Blackbox — IP Reputation API

// API v1 — Free & unlimited

GET /api/v1/:ip

Returns a single character indicating whether the IP is detected as malicious or suspicious. This is a direct drop-in replacement for the legacy proxycheck.php API. Free and unlimited — no API key required. Responses cached up to 30 days. Also accessible at /lookup/:ip.

Response values

Value	Meaning	Notes
Y	Listed	IP found on one or more detection lists.
N	Clean	IP not found on any detection list.
E	Error	Invalid IP or lookup failure.

Example request

curl https://blackbox.ipinfo.app/api/v1/8.8.8.8 Y

Always check explicitly for Y — do not check for "not N". An error response (E) would incorrectly be treated as a positive detection if you use != 'N'.

Implementation example

// Correct if (response === 'Y') { // Handle proxy / malicious IP } // Incorrect — E (error) would trigger this branch if (response !== 'N') { // Do not use this pattern }

// API v2 — Detailed JSON (RapidAPI)

GET /api/v2/:ip

Returns a detailed JSON object with ASN information and per-category detection flags. Responses are cached for one day. API v2 is a subscription service available via RapidAPI — a valid X-RapidAPI-Key header is required.

Response fields

Field	Type	Description
ip	string	The queried IP address.
error	null\|string	Null on success. Error message on failure.
asn.name	string	Organisation name from the routing registry.
asn.number	number	Autonomous System Number as an integer.
asn.network	string	Network base address for this ASN block.
asn.cidr	number	Prefix length of the ASN block.
detection.*	bool	Per-category detection flags — see Detections below.
suggestion	string	`"block"` if any detection flag is true, otherwise `"allow"`.

Example request

curl -H "X-RapidAPI-Key: YOUR_KEY" https://blackbox.ipinfo.app/api/v2/8.8.8.8

Example response — listed IP

{ "ip": "8.8.8.8", "error": null, "asn": { "name": "GOOGLE", "number": 15169, "network": "8.8.8.0", "cidr": 24 }, "detection": { "bogon": false, "cloud": true, "hosting": true, "proxy": false, "spamhaus": false, "tor": false }, "suggestion": "block" }

Example response — clean IP

{ "ip": "72.49.1.1", "error": null, "asn": { "name": "FUSE-NET", "number": 6181, "network": "72.49.0.0", "cidr": 16 }, "detection": { "bogon": false, "cloud": false, "hosting": false, "proxy": false, "spamhaus": false, "tor": false }, "suggestion": "allow" }

// Detections explained

The detection object contains six boolean flags. suggestion is "block" when any flag is true — use the individual flags to build your own logic.

bogon

Non-internet-routable address (e.g. 192.168.x.x). May indicate spoofing — block unconditionally.

cloud

IP belongs to a major cloud provider (AWS, GCP, Azure, etc). Unlikely to be a real end user.

hosting

IP is in a hosting / datacenter network (DigitalOcean, Vultr, etc). May be a proxy, scraper, or bot.

proxy

Known proxy provider, open proxy, or compromised device acting as a proxy.

spamhaus

Listed by Spamhaus as a continuous threat source. Strongly recommended to block all traffic.

tor

Active Tor exit node. Commonly used to anonymise traffic and circumvent access controls.

// Project history

Blackbox is a modern replacement for the now-discontinued proxy checking APIs proxy.mind-media.com/block/ and shroomery.org/ythan/proxycheck.php. The free v1 API is a direct continuation of the Shroomery.org project — a simple Y/N flag for whether an IP is a likely proxy.

The rewrite added ASN-based detection (identifying entire hosting networks rather than individual IPs), Tor exit node data, cloud provider classification, Spamhaus integration, full IPv6 support, and the detailed v2 JSON format.

// Projects using Blackbox

my.ipinfo.app — Client IP detail page; uses Blackbox for VPN/proxy detection.
IP-Lookup.org Proxy Checker — Web tool to check proxies, VPNs, and Tor nodes.
SourceMod Blacklist/Whitelist Plugin — Game server plugin to block players by country or proxy status.
FoxGate — Minecraft server proxy and firewall using Blackbox for connection filtering.
XenForo Proxy Check Add-on — Blocks forum registrations from proxies and VPNs.
IMC '21 Research Paper — "Residential Proxies: A Deep Dive into the Growing Anonymity Service."

// Health check

GET /ping also /api/ping

Returns uptime, status, and server timestamp. No auth required.

Example response

{ "uptime": 3600.42, "message": "OK", "timestamp": 1743724800000 }

// Support This Project

The v1 API is free and unlimited. If it saves you time or keeps your service safer, consider supporting continued development.

♥ Donate