Whatoblock.com
Login Register

API Documentation

Documentation for Whatoblock.com API v3 system. Integrate threat intelligence into your applications with endpoints, filtering, and token-based billing.

RESTful API
Token-Based Billing
Secure Access

API v3 System

Access comprehensive threat intelligence through our RESTful API with flexible filtering, real-time data retrieval, and direct file downloads.

Key Features

  • Token-Based Billing: Pay only for what you use with transparent cost calculation
  • Real-Time Data: Access to live threat intelligence and scanning results
  • Filtering: Data filtering with mutual exclusivity validation
  • Direct Downloads: Stream files directly
  • Cost Preview Mode: Preview costs and results before actual queries
  • Pretty-Printed JSON: Human-readable responses for better debugging

Base URL & Authentication

Base URL: https://whatoblock.com/apiv3/
Authentication: ?apiKey=7eae00f2-d740-4756-9658-ca2d62b05c73

API Key Format

API keys must be valid UUIDv4 format: 7eae00f2-d740-4756-9658-ca2d62b05c73

Status Endpoint

Check your account status, token balance, and API costs. This endpoint does not consume any tokens. 

GET https://whatoblock.com/apiv3/status?apiKey=7eae00f2-d740-4756-9658-ca2d62b05c73

Status Response

{
  "success": true,
  "timestamp": "January 15, 2024, 10:30:00 AM",
  "account": {
    "username": "your_username",
    "available_tokens": 87585.8,
    "used_tokens": 12414.2,
    "total_tokens_ever": 100000,
    "last_api_reset": "January 1, 2024, 12:00:00 AM",
    "api_key_reset_tries": 0
  },
  "token_costs": {
    "HEARTBEAT_API": 0.1,
    "BOTNET_API": 1,
    "SCANNER_API": 1,
    "OPENDATA_API": 10
  }
}

Token Cost Breakdown

All API endpoints use token-based billing. See the Token-Based Billing section for detailed pricing information, including cost per record and minimum costs for each endpoint.

Common Features

Response Format Options

The Heartbeat, Botnet, and Scanner endpoints support flexible response formats:

Format Parameter
  • format=json (required) - Returns JSON response
  • format=text (required) - Returns plain text, one IP per line
  • format=csv (required) - Returns CSV format, one IP per line
  • Perfect for importing IPs into firewall rules or other programs
Info Parameter
  • info=false (default) - Returns IPs only
  • info=true - Includes metadata (tokens charged, filters, etc.)
  • For text format, metadata appears as # comments
Example Combinations
/apiv3/heartbeat?apiKey=KEY&time=24h&format=json - JSON with IPs only (info=false)
/apiv3/heartbeat?apiKey=KEY&time=24h&format=json&info=false - JSON with IPs only
/apiv3/heartbeat?apiKey=KEY&time=24h&format=text - Plain text, IPs only
/apiv3/heartbeat?apiKey=KEY&time=24h&format=text&info=true - Plain text with metadata comments
/apiv3/heartbeat?apiKey=KEY&time=24h&format=csv - CSV format, one IP per line

Cost Preview Mode

All endpoints support cost preview mode to preview costs and results without consuming tokens. Use cost=true:

Add &cost=true to any endpoint to preview the operation
Cost Preview Response Format
{
  "success": true,
  "cost_preview": true,
  "query_details": {
    "endpoint": "/apiv3/heartbeat",
    "records_found": 150,
    "filters_applied": {
      "time": "24h",
      "country": "US"
    },
    "operation_type": "HEARTBEAT_API",
    "response_format": "IP addresses only",
    "pricing_info": {
      "OpenProxy": "0.1 tokens per unique IP",
      "Tor_Exit_Node": "0.1 tokens per unique IP",
      "Scanner": "1 token per unique IP",
      "C2": "1 token per unique IP",
      "note": "If an IP appears with multiple categories, you are charged for the highest-cost category only."
    }
  },
  "account_impact": {
    "current_balance": 1000.0,
    "tokens_to_charge": 25.5,
    "balance_after_query": 974.5,
    "sufficient_balance": true
  },
  "timestamp": "January 15, 2024, 10:30:00 AM",
  "note": "This is a cost preview query. No tokens have been charged and no data has been returned.",
  "category_breakdown": {
    "Scanner": {"count": 50, "cost": 50},
    "OpenProxy": {"count": 100, "cost": 10}
    }
}

Note: category_breakdown is only included for Heartbeat API responses.

Filter Validation

Parameter Validation
  • Unknown Parameters: All endpoints validate query parameters and reject unknown parameters with a 400 error.
  • Allowed Parameters: Each endpoint has a specific set of allowed parameters. See the endpoint-specific sections for details.
  • Error Response: When unknown parameters are detected, the API returns a list of allowed parameters for that endpoint.
Mutual Exclusivity Rules
  • Time Filter: The time parameter is required for Heartbeat, Scanner, and Botnet endpoints. Not required for Open Data endpoint.
  • Open Data - MD5 vs Service Mode: Cannot use md5 filter together with service, protocol, or port filters. Choose ONE filtering mode:
    • MD5 Mode: Use md5 alone to get a specific file by hash (e.g., ?md5=9f3a7b2c4d1e8a0b6c5f2d9e3a1b0c4d)
    • Service Mode: Use service, protocol, and port together (e.g., ?service=DNS&protocol=tcp&port=53)
Required Filter Combinations
  • Open Data - Service Mode: When using service mode, service, protocol, and port are all required together:
    • ✅ Valid: ?service=DNS&protocol=tcp&port=53
    • ❌ Invalid: ?service=DNS&protocol=tcp (missing port)
    • ❌ Invalid: ?service=DNS&port=53 (missing protocol)
    • ❌ Invalid: ?protocol=tcp&port=53 (missing service)

Error Handling

The API returns standardized error responses with appropriate HTTP status codes:

401 - Authentication Errors
{
  "success": false,
  "error": "API key is required. Please include ?apiKey=YOUR_API_KEY in your request.",
  "note": "Make sure to include the ? before apiKey= in your URL"
}

// Invalid API key format
{
  "success": false,
  "error": "Invalid API key format. API key must be a valid UUIDv4.",
  "format": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (where x is any hexadecimal digit and y is one of 8, 9, A, or B)"
}

// Invalid API key
{
  "success": false,
  "error": "Invalid API key. Please check your API key and try again."
}
402 - Insufficient Tokens
// Preliminary validation (before processing)
{
  "success": false,
  "error": "Insufficient token balance for this operation.",
  "required_operation": "HEARTBEAT_API",
  "cost_per_record": "Dynamic (0.1-1.0 tokens per record based on category)",
  "available_tokens": 5.2,
  "message": "Please top up your account to use this endpoint."
}

// Final validation (after processing)
{
  "success": false,
  "error": "Insufficient token balance. Please top up your account.",
  "required_tokens": 125.5,
  "available_tokens": 100.0
}
403 - Banned Account
{
  "success": false,
  "error": "Your account has been banned. Please contact support at [email protected] for assistance."
}
400 - Invalid Request
// Missing time filter
{
  "success": false,
  "error": "Missing required parameter",
  "message": "The \"time\" parameter is required.",
  "required_parameters": ["time", "format"],
  "optional_parameters": ["country", "category", "ip", "hideUnknown", "info", "cost"],
  "supported_time_values": ["24h", "30d"],
  "examples": {
    "minimal": "/apiv3/heartbeat?apiKey=KEY&time=24h&format=json",
    "with_filters": "/apiv3/heartbeat?apiKey=KEY&time=24h&format=json&country=US&category=OpenProxy",
    "text_format": "/apiv3/heartbeat?apiKey=KEY&time=24h&format=text&info=false"
  }
}

// Invalid filter parameter
{
  "success": false,
  "error": "Invalid filter parameter",
  "message": "Invalid country code: \"XX\". Please use valid 2-letter ISO country codes (e.g., US, DE, GB).",
  "required_parameters": ["time", "format"],
  "optional_parameters": ["country", "category", "ip", "hideUnknown", "info", "cost"],
  "example": "/apiv3/heartbeat?apiKey=KEY&time=24h&format=json&country=US"
}

// Unknown query parameters
{
  "success": false,
  "error": "Invalid query parameters",
  "message": "Unknown parameter provided by the user.",
  "required_parameters": ["time", "format"],
  "optional_parameters": ["country", "category", "ip", "hideUnknown", "info", "cost"],
  "example": "/apiv3/heartbeat?apiKey=KEY&time=24h&format=json&country=US"
}
503 - Service Unavailable
{
  "success": false,
  "error": "Data is being generated.",
  "message": "Data not yet available. Please wait a few seconds and retry."
}

// Maintenance mode
{
  "success": false,
  "error": "System is under maintenance. Please check back later.",
  "maintenance": true
}
500 - Server Error
{
  "success": false,
  "error": "Failed to retrieve heartbeat data. Please try again later."
}

Best Practices

  • Always use cost preview mode first to estimate costs for large queries
  • Use time=30d for broader analysis or time=24h for recent data
  • Combine filters to get precisely the data you need
  • Monitor your token balance regularly using the status endpoint
  • Use case-insensitive parameters where supported (protocol, etc.)
  • Only use documented parameters - unknown parameters will be rejected with a 400 error

Scanners

The Scanner API provides access to IP addresses from network scanning activity data.

API Endpoint

Access IP addresses from network scanning activity through the API v3 endpoint:

GET https://whatoblock.com/apiv3/scanner?apiKey=7eae00f2-d740-4756-9658-ca2d62b05c73&time=24h&hideBots=true

Response Format

The Scanner API supports three response formats: JSON, plain text, and CSV. The format parameter is required. Use format=json, format=text, or format=csv to control the output format. Use info=true to include metadata in the response (only for JSON and text formats).

JSON Format (format=json)

JSON response with IPs only when info=false (minimal format - just the array):

["203.0.113.45", "198.51.100.10"]
JSON Format with Info (info=true)

JSON response with full metadata when info=true:

{
  "success": true,
  "ips": ["203.0.113.45", "198.51.100.10"],
  "records": 2,
  "tokens_charged": 2,
  "filters_applied": {
    "time": "24h",
    "hideBots": "true"
  }
}
JSON Format IPs Only (info=false)

JSON response with IPs only when info=false (minimal format - just the array):

["203.0.113.45", "198.51.100.10"]
Plain Text Format (format=text)

Plain text response with one IP per line - perfect for importing into other programs:

203.0.113.45
198.51.100.10
Plain Text Format with Info (format=text&info=true)

Plain text response with metadata as comments:

# Records: 2
# Tokens Charged: 2
# Filters: time=24h, hideBots=true

203.0.113.45
198.51.100.10
CSV Format (format=csv)

CSV response with one IP per line - perfect for importing into spreadsheet applications:

203.0.113.45
198.51.100.10
No Data Found Response

When no data matches your filters, the API returns an empty array:

{
  "success": true,
  "ips": [],
  "records": 0,
  "tokens_charged": 0,
  "filters_applied": {
    "time": "24h",
    "country": "US"
  },
  "message": "No data found for your query.",
  "suggestion": "Try adjusting your filters (time period, country, protocol, ASN) to get results. You can use time=30d for a broader range, or remove some filters to see more data.",
    "supported_filters": {
      "time": ["24h", "30d"],
      "country": "Use 2-letter codes like US, DE, GB",
      "protocol": "Use exact protocol names like TCP, UDP",
      "asn": "Use format like AS1234 or AS1234,AS5678"
    }
}
Cost Preview Response

Use cost=true to preview costs without consuming tokens:

GET https://whatoblock.com/apiv3/scanner?apiKey=KEY&time=24h&country=US&cost=true
{
  "success": true,
  "cost_preview": true,
  "query_details": {
    "endpoint": "/apiv3/scanner",
    "records_found": 150,
    "filters_applied": {
      "time": "24h",
      "country": "US"
    },
    "operation_type": "SCANNER_API",
    "response_format": "IP addresses only"
  },
  "account_impact": {
    "current_balance": 1000.0,
    "tokens_to_charge": 150,
    "balance_after_query": 850.0,
    "sufficient_balance": true
  },
  "timestamp": "January 15, 2024, 10:30:00 AM",
  "note": "This is a cost preview query. No tokens have been charged and no data has been returned."
}

Available Filters

Time Filters
  • time: Required - 24h, 30d
Technical Filters
  • country: 2-letter ISO codes (US, UK, DE, etc.) - comma-separated for multiple
  • protocol: tcp or udp (case-insensitive)
  • asn: AS1234 format (comma-separated for multiple, e.g., AS1234,AS5678)
Behavior Filters
  • hideUnknown: true/false (exclude unknown locations)
  • hideBots: Scanner endpoint only - true/false (exclude automated bot traffic)
  • format: Required - json, text, or csv - controls response format
  • info: true/false (default: false) - include metadata in response
  • cost: true/false (cost preview mode - no tokens charged)

Pricing

See the Token-Based Billing section for detailed pricing information.

Error Responses

400 - Missing Time Filter
{
  "success": false,
  "error": "Missing required parameter",
  "message": "The \"time\" parameter is required.",
  "required_parameters": ["time", "format"],
  "optional_parameters": ["country", "protocol", "asn", "hideUnknown", "hideBots", "info", "cost"],
  "supported_time_values": ["24h", "30d"],
  "examples": {
    "minimal": "/apiv3/scanner?apiKey=KEY&time=24h&format=json",
    "with_filters": "/apiv3/scanner?apiKey=KEY&time=24h&format=json&protocol=tcp&country=US",
    "text_format": "/apiv3/scanner?apiKey=KEY&time=24h&format=text&info=false"
  }
}
400 - Invalid Country Code
{
  "success": false,
  "error": "Invalid filter parameter",
  "message": "Invalid country code: \"XYZ\". Please use valid 2-letter ISO country codes (e.g., US, DE, GB).",
  "example": "/apiv3/scanner?apiKey=KEY&time=24h&country=US"
}
400 - Invalid Query Parameters
{
  "success": false,
  "error": "Invalid query parameters",
  "message": "Unknown parameter provided by the user.",
  "required_parameters": ["time", "format"],
  "optional_parameters": ["country", "protocol", "asn", "hideUnknown", "hideBots", "info", "cost"],
  "example": "/apiv3/scanner?apiKey=KEY&time=24h&format=json&country=US"
}
402 - Insufficient Tokens
{
  "success": false,
  "error": "Insufficient token balance. Please top up your account.",
  "required_tokens": 150,
  "available_tokens": 50
}

Example Use Cases

Block Human-Operated Scans
/apiv3/scanner?apiKey=KEY&time=24h&hideBots=true&hideUnknown=true

Get IP addresses of human-operated scanners to block in your firewall

Monitor Specific Country
/apiv3/scanner?apiKey=KEY&time=24h&country=CN

Track scanning activity from China over 24 hours

Track Cloud Provider Activity
/apiv3/scanner?apiKey=KEY&time=30d&asn=AS13335,AS15169

Monitor scanning activity from major cloud providers (Cloudflare, Google)

Export IPs as Text
/apiv3/scanner?apiKey=KEY&time=24h&format=text

Get IP addresses in plain text format for easy import into firewall rules

Text Format with Metadata
/apiv3/scanner?apiKey=KEY&time=24h&format=text&info=true

Get IP addresses in text format with metadata comments for documentation

Heartbeat

The Heartbeat API provides access to IP threat intelligence data, categorizing IP addresses by threat type.

API Endpoint

Access Heartbeat data through the API v3 endpoint:

GET https://whatoblock.com/apiv3/heartbeat?apiKey=7eae00f2-d740-4756-9658-ca2d62b05c73&time=24h&country=US

Response Format

The Heartbeat API supports three response formats: JSON, plain text, and CSV. The format parameter is required. Use format=json, format=text, or format=csv to control the output format. Use info=true to include metadata in the response (only for JSON and text formats).

JSON Format (format=json)

JSON response with IPs only when info=false (minimal format - just the array):

["185.220.101.45", "198.51.100.23"]
JSON Format with Info (info=true)

JSON response with full metadata when info=true:

{
  "success": true,
  "ips": ["185.220.101.45", "198.51.100.23"],
  "records": 2,
  "tokens_charged": 1.1,
  "category_breakdown": {
    "Scanner": {"count": 1, "cost": 1},
    "OpenProxy": {"count": 1, "cost": 0.1}
  },
  "filters_applied": {
    "time": "24h",
    "country": "US"
  }
}
JSON Format IPs Only (info=false)

JSON response with IPs only when info=false (minimal format - just the array):

["185.220.101.45", "198.51.100.23"]
Plain Text Format (format=text)

Plain text response with one IP per line - perfect for importing into firewall rules:

185.220.101.45
198.51.100.23
Plain Text Format with Info (format=text&info=true)

Plain text response with metadata as comments:

# Records: 2
# Tokens Charged: 1.1
# Filters: time=24h, country=US
# Category Breakdown:
#   Scanner: 1 (1 tokens)
#   OpenProxy: 1 (0.1 tokens)

185.220.101.45
198.51.100.23
CSV Format (format=csv)

CSV response with one IP per line - perfect for importing into spreadsheet applications:

185.220.101.45
198.51.100.23

Available Filters

Time Filters
  • time: Required - 24h, 30d
Location Filters
  • country: 2-letter ISO codes (US, UK, DE, etc.) - comma-separated for multiple
  • ip: Heartbeat endpoint only - Specific IP or prefix (e.g., 185.220.101 or 185.220.101.45)
Threat Filters
  • category: Heartbeat endpoint only - OpenProxy, Tor_Exit_Node, Scanner, C2 (comma-separated, use underscores for spaces like Tor_Exit_Node)
  • hideUnknown: true/false (exclude unknown locations)
  • format: Required - json, text, or csv - controls response format
  • info: true/false (default: false) - include metadata in response
  • cost: true/false (cost preview mode - no tokens charged)

Pricing

See the Token-Based Billing section for detailed pricing information, including dynamic pricing based on threat category.

Example Use Cases

Block High-Risk Threats
/apiv3/heartbeat?apiKey=KEY&time=24h&category=C2,Scanner

Get IP addresses of C2 servers and scanners to block in your firewall

Monitor Geographic Threats
/apiv3/heartbeat?apiKey=KEY&time=30d&country=RU,CN,IR

Track threat activity from specific countries over 30 days

Investigate Specific IP
/apiv3/heartbeat?apiKey=KEY&time=30d&ip=185.220.101.45

Check if a specific IP address appears in threat intelligence data

Export IPs as Text
/apiv3/heartbeat?apiKey=KEY&time=24h&format=text

Get IP addresses in plain text format for easy import into firewall rules

Text Format with Metadata
/apiv3/heartbeat?apiKey=KEY&time=24h&format=text&info=true

Get IP addresses in text format with metadata comments for documentation

Botnets

The Botnet API provides access to Command & Control (C2) server intelligence and downloadable malware samples for security research.

API Endpoint

Access Botnet data through the API v3 endpoint:

GET https://whatoblock.com/apiv3/botnet?apiKey=7eae00f2-d740-4756-9658-ca2d62b05c73&time=24h&downloadableOnly=true

Response Format

The Botnet API supports three response formats: JSON, plain text, and CSV. The format parameter is required. Use format=json, format=text, or format=csv to control the output format. Use info=true to include metadata in the response (only for JSON and text formats).

JSON Format (format=json)

JSON response with C2 IPs only when info=false (minimal format - just the array):

["185.220.101.45", "198.51.100.23"]
JSON Format with Info (info=true)

JSON response with full metadata when info=true:

{
  "success": true,
  "c2_ips": ["185.220.101.45", "198.51.100.23"],
  "records": 2,
  "tokens_charged": 2,
  "filters_applied": {
    "time": "24h",
    "downloadableOnly": "true"
  }
}
JSON Format IPs Only (info=false)

JSON response with IPs only when info=false (minimal format - just the array):

["185.220.101.45", "198.51.100.23"]
Plain Text Format (format=text)

Plain text response with one IP per line - perfect for importing into firewall rules:

185.220.101.45
198.51.100.23
Plain Text Format with Info (format=text&info=true)

Plain text response with metadata as comments:

# Records: 2
# Tokens Charged: 2
# Filters: time=24h, downloadableOnly=true

185.220.101.45
198.51.100.23
CSV Format (format=csv)

CSV response with one IP per line - perfect for importing into spreadsheet applications:

185.220.101.45
198.51.100.23

Available Filters

Time Filters
  • time: Required - 24h, 30d
Location Filters
  • country: 2-letter ISO codes (US, UK, DE, etc.) - comma-separated for multiple
  • asn: AS1234 format (comma-separated for multiple, e.g., AS1234,AS5678)
Content Filters
  • downloadableOnly: Botnet endpoint only - true/false (only samples with downloadable malware files)
  • hideUnknown: true/false (exclude unknown locations)
  • format: Required - json, text, or csv - controls response format
  • info: true/false (default: false) - include metadata in response
  • cost: true/false (cost preview mode - no tokens charged)

Botnet Sample Download

Download malware samples directly from botnet C2 servers. Each downloadable sample is identified by a unique botnet ID.

Obtaining Botnet IDs

Botnet IDs are obtained from the web interface. Visit the Botnet page to view C2 servers and their associated botnet ID values. Only botnets with downloadable samples will have available files. Botnet IDs must contain only alphanumeric characters, hyphens, and underscores. 

GET https://whatoblock.com/apiv3/botnet/download/YOUR_BOTNET_ID?apiKey=YOUR_API_KEY

Response Format

The Botnet download endpoint returns a binary ZIP file containing the malware sample. The filename is automatically constructed as {botnet_id}-binaries.zip. Tokens are consumed after successful download (5 tokens per file).

Content-Type: application/zip
Content-Disposition: attachment; filename="YOUR_BOTNET_ID-binaries.zip"
Content-Length: [file_size]

[Binary ZIP file content]

Error Responses

400 - Invalid Botnet ID
{
  "success": false,
  "error": "Botnet ID is required"
}
401 - Authentication Error
{
  "success": false,
  "error": "Download failed - authentication error"
}
404 - File Not Found
{
  "success": false,
  "error": "Payload file not found for ID: YOUR_BOTNET_ID",
  "id": "YOUR_BOTNET_ID"
}
402 - Insufficient Tokens
{
  "success": false,
  "error": "Insufficient token balance. Please top up your account.",
  "required_tokens": 5,
  "available_tokens": 2.5
}
504 - Connection Timeout
{
  "success": false,
  "error": "Download failed - connection timeout. Please try again later."
}
500 - Server Error
{
  "success": false,
  "error": "Download failed: [error message]"
}
Security Warning

Malware samples are live and dangerous! Only download if you have proper isolation, analysis tools, and security expertise. These files can damage systems and compromise networks.

Pricing

See the Token-Based Billing section for detailed pricing information, including costs for C2 IP addresses and malware sample downloads.

Example Use Cases

Block C2 Servers
/apiv3/botnet?apiKey=KEY&time=24h&country=US

Get C2 server IP addresses from the US to block in your firewall

Find Downloadable Samples
/apiv3/botnet?apiKey=KEY&time=30d&downloadableOnly=true

Get botnet IDs with downloadable malware samples for analysis

Download Malware Sample
/apiv3/botnet/download/YOUR_BOTNET_ID?apiKey=KEY

Download a specific malware sample for security research (requires proper isolation)

Export C2 IPs as Text
/apiv3/botnet?apiKey=KEY&time=24h&format=text

Get C2 server IP addresses in plain text format for easy import into firewall rules

Text Format with Metadata
/apiv3/botnet?apiKey=KEY&time=24h&format=text&info=true

Get C2 server IP addresses in text format with metadata comments for documentation

Open Data

The Open Data API provides access to binary file downloads from scanner result files. Returns binary file streams, not IP addresses or JSON.

API Endpoint

Access Open Data files through the API v3 endpoint:

GET https://whatoblock.com/apiv3/opendata?apiKey=YOUR_API_KEY&service=DNS&protocol=tcp&port=53

Response Format

The Open Data API returns direct file downloads (binary stream) for single file matches:

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="dns-tcp-53-20240101.tar.gz"
X-API-Success: File download initiated successfully
X-API-Message: Downloading file: dns-tcp-53-20240101.tar.gz
X-API-Tokens-Charged: 10
X-API-Filter-Type: service+protocol+port
X-API-Service-Protocol: DNS (tcp:53)

[Binary file content]
Note

Open Data API always returns a single file as a binary stream. The API returns the most recent file for the specified service, protocol, and port combination, or the file matching the MD5 hash. Multiple files are not supported - each query returns exactly one file. One active download per user at a time.

Filter Modes & Combinations

Important: Mutually Exclusive Filter Modes

Open Data API supports two mutually exclusive filtering modes. You must choose ONE mode per request:

  • • MD5 Mode: Use md5 filter alone to get a specific file by hash
  • • Service Mode: Use service, protocol, and port together (all three required)
  • • Cannot combine: You cannot use md5 with service/protocol/port filters

Available Filters

Service + Protocol + Port Mode
  • service: Required - DNS, NTP, SSH, HTTPS_ALT, etc. (both hyphens and underscores accepted)
  • protocol: Required - Must be tcp or udp (case-insensitive)
  • port: Required - Port number (1-65535)
  • All three required: service, protocol, and port must all be provided
  • Returns: Most recent file matching all three criteria
MD5 Hash Mode
  • md5: Required - 32 hexadecimal characters (0-9, a-f, A-F)
  • Standalone mode: Use md5 filter alone (no other filters allowed)
  • Returns: Specific file matching MD5 hash exactly
  • Note: Cannot combine with service/protocol filters

Supported Services & Ports

Complete list of supported services organized by protocol:

TCP Services
DNS 53
FTP 21
HTTP 80
HTTP_ALT 8080

(HTTP-ALT)

HTTPS 443
HTTPS_ALT 8443

(HTTPS-ALT)

IMAP 143
IMAPS 993
MSSQL 1433
MYSQL 3306
POP3 110
POP3S 995
POSTGRESQL 5432
RDP 3389
SMB 445
SMTP 25, 587
SMTPS 465
SSH 22
TELNET 23
UDP Services
ARD 3283
CHARGEN 19
DNS 53
IPMI 623
LDAP 389
MDNS 5353
MEMCACHED 11211
MSSQL 1434
NAT_PMP 5351

(NAT-PMP)

NETBIOS_NS 137

(NETBIOS-NS)

NTP 123
QOTD 17
RIP 520
SIP 5060
SSDP 1900
STUN 3478
UBIQUITI 10001
WSD 3702
Important Note

Services with hyphens in their names (HTTP-ALT, HTTPS-ALT, NAT-PMP, NETBIOS-NS) must use underscores in the API query parameter (HTTP_ALT, HTTPS_ALT, NAT_PMP, NETBIOS_NS). Example: Use service=HTTP_ALT to access HTTP-ALT service data.

Error Responses

400 - Invalid Filter Combination
{
  "success": false,
  "error": "Invalid filter combination",
  "message": "You cannot use MD5 filter together with service/protocol/port filters. Choose ONE filtering mode.",
  "provided_filters": {
    "md5": "9f3a7b2c4d1e8a0b6c5f2d9e3a1b0c4d",
    "conflicting_filters": ["service", "protocol", "port"]
  },
  "supported_modes": {
    "md5_mode": "Use MD5 hash only: ?md5=hash",
    "service_mode": "Use service+protocol+port: ?service=DNS&protocol=tcp&port=53"
  },
  "examples": {
    "md5_single": "/apiv3/opendata?apiKey=KEY&md5=9f3a7b2c4d1e8a0b6c5f2d9e3a1b0c4d",
    "service_mode": "/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53"
  }
}
400 - Missing Service Parameter
{
  "success": false,
  "error": "Missing required filter parameter",
  "message": "You must specify service, protocol, and port parameters.",
  "supported_filters": {
    "service": "Service name (e.g., DNS, NTP, SSH, HTTPS_ALT)",
    "protocol": "Required: tcp or udp (case-insensitive)",
    "port": "Required: port number (1-65535)"
  },
  "examples": {
    "dns_tcp": "/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53",
    "ntp_udp": "/apiv3/opendata?apiKey=KEY&service=NTP&protocol=udp&port=123"
  },
  "alternative": {
    "md5_mode": "Or use MD5 hash: /apiv3/opendata?apiKey=KEY&md5=9f3a7b2c4d1e8a0b6c5f2d9e3a1b0c4d"
  }
}
400 - Missing Protocol Parameter
{
  "success": false,
  "error": "Missing required protocol parameter",
  "message": "You must specify a protocol parameter when using service filter.",
  "provided_service": "DNS",
  "supported_protocols": ["tcp", "udp"],
  "examples": {
    "with_tcp": "/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53",
    "with_udp": "/apiv3/opendata?apiKey=KEY&service=NTP&protocol=udp&port=123"
  }
}
400 - Invalid Protocol Parameter
{
  "success": false,
  "error": "Invalid protocol parameter",
  "message": "Protocol must be either \"tcp\" or \"udp\" (case-insensitive).",
  "provided_protocol": "http",
  "supported_protocols": ["tcp", "udp"],
  "examples": {
    "tcp_example": "/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53",
    "udp_example": "/apiv3/opendata?apiKey=KEY&service=NTP&protocol=udp&port=123"
  }
}
400 - Invalid MD5 Hash Format
{
  "success": false,
  "error": "Invalid MD5 hash format",
  "message": "MD5 hash must be exactly 32 hexadecimal characters.",
  "provided_hash": "abc123",
  "valid_format": "32 hexadecimal characters (0-9, a-f, A-F)",
  "examples": {
    "valid": "/apiv3/opendata?apiKey=KEY&md5=a1b2c3d4e5f6789012345678901234ab"
  }
}
429 - Download In Progress
{
  "success": false,
  "error": "You already have a download in progress. Please wait for it to complete."
}
200 - No Data Found
{
  "success": true,
  "files": [],
  "records": 0,
  "tokens_charged": 0,
  "filters_applied": {
    "service": "DNS",
    "protocol": "tcp",
    "port": 53
  },
  "message": "No data found for your service+protocol+port query.",
  "suggestion": "No files found for service \"DNS\" with protocol \"tcp\" on port 53. Verify the combination is correct.",
  "supported_filters": {
    "service": "Service name (e.g., DNS, NTP, SSH, HTTPS_ALT)",
    "protocol": "Required: tcp or udp (case-insensitive)",
    "port": "Required: port number (1-65535)",
    "md5": "Single MD5 hash - alternative to service mode"
  },
  "examples": {
    "dns_tcp": "/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53",
    "ntp_udp": "/apiv3/opendata?apiKey=KEY&service=NTP&protocol=udp&port=123",
    "https_alt": "/apiv3/opendata?apiKey=KEY&service=HTTPS_ALT&protocol=tcp&port=8443",
    "md5_hash": "/apiv3/opendata?apiKey=KEY&md5=9f3a7b2c4d1e8a0b6c5f2d9e3a1b0c4d"
  }
}

Pricing

See the Token-Based Billing section for detailed pricing information.

Example Use Cases

Get Most Recent DNS Scan (TCP)
/apiv3/opendata?apiKey=KEY&service=DNS&protocol=tcp&port=53

Download the most recent DNS TCP port 53 scanning result file

Download Specific File by MD5
/apiv3/opendata?apiKey=KEY&md5=a1b2c3d4e5f6789012345678901234ab

Download a specific file by its MD5 hash

Get Most Recent NTP UDP Scan
/apiv3/opendata?apiKey=KEY&service=NTP&protocol=udp&port=123

Download the most recent NTP UDP port 123 scanning result file

Token-Based Billing

Pay-per-use access to API endpoints with transparent pricing based on data volume.

How Token Billing Works

Cost Structure

  • • Tokens consumed per API request
  • • Variable costs by endpoint type
  • • Scales with data volume returned
  • • Cost preview mode available

Protections

  • • Early validation prevents overspend
  • • Insufficient balance blocks queries
  • • Real-time balance checking
  • • Automatic cost calculations

Token Costs by Endpoint

/apiv3/heartbeat 0.1 token

  • • IP intelligence and geolocation data
  • • Dynamic pricing (0.1-1.0 tokens based on category)

/apiv3/scanner 1.0 token

  • • Network scanning activity data
  • • 1 token per IP address

/apiv3/botnet 1.0 token

  • • Botnet C2 server intelligence
  • • 1 token per IP address

/apiv3/botnet/download/:id 5.0 tokens

  • • Malware sample file download
  • • 5 tokens per download

/apiv3/opendata 10.0 tokens

  • • File downloads and data access
  • • 10 tokens per file download

/apiv3/status Free

  • • Account status and token balance
  • • No tokens consumed

Managing Your Token Balance

Check Balance

  • • Use /apiv3/status endpoint
  • • View available and used tokens
  • • Monitor token cost breakdown

Estimate Costs

  • • Use cost=true parameter
  • • Get cost estimates without charges
  • • Plan large queries effectively

Best Practices

  • • Monitor balance before large queries
  • • Use specific filters to reduce costs
  • • Cache responses when appropriate