// 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.
// API v3beta — Connection classification BETA
GET
/api/v3beta/:ip
Classifies an IP by the type of connection behind it — mobile carrier, residential broadband, hosting/datacenter, VPN, Tor, iCloud Private Relay, business, bogon, or unknown when no signal fires at all. Where v2 answers “should I block this IP?”, v3beta answers “what kind of user is this?”. Responses are cached for one day. Reuses every v2 detection module and adds mobile/residential ASN lists plus a reverse-DNS pattern classifier.
Beta.
No API key required during beta — open to any caller. Response shape, category names, and
internal weights may change before GA. Once promoted out of beta, this endpoint will move behind
RapidAPI with an
X-RapidAPI-Key header like v2. Pin against the v3beta URL only for
experimentation; do not depend on field stability yet.
Response fields
| Field | Type | Description |
|---|---|---|
| ip | string | The queried IP address (cleaned — ::ffff: prefix stripped). |
| error | null|string | Null on success. Error message on failure (400 for invalid IP). |
| asn | object|false | { number, name, network, cidr } — from the routing registry, or false for unrouted IPs. |
| classification | string | argmax(categories) — the single most-likely connection type. |
| confidence | number | [0..1] — the probability mass on the winning category. |
| categories | object | Full probability distribution — one entry per category (all 9, sums to 1). When no positive signal fires, all mass goes to unknown. |
| signals | object | Raw boolean detection flags (v2-compatible superset — lets callers apply custom logic). v3beta adds sfs_listed and sfs_toxic for StopForumSpam reputation. |
| evidence | string[] | Names of the rules that fired — useful for auditing and weight tuning. |
| suspicious | bool | Orthogonal axis — true if Spamhaus-listed, SFS-listed (90-day or toxic), OR ≥ 5 raw signals fired. Does not change the classification. |
| rdns | object|null | { hostname, category, match, apex, ispApex, autoGeneratedPtr, hasMX, hasSPF, mxMatch, spfAuthorizes } — the PTR lookup result plus apex-domain enrichment. Null if no rDNS. hasMX/hasSPF describe the apex (does the domain have mail infra anywhere?) and are retained for v2-compat consumers. mxMatch/spfAuthorizes (v1.16.0+) describe this specific IP — mxMatch is true only when the PTR hostname is itself one of the apex's MX targets; spfAuthorizes is true only when the apex's SPF record explicitly authorizes this IP via ip4/ip6/a/mx mechanisms (no include: recursion). The classifier gates rdns_corp_mx/rdns_corp_spf on the tight fields, not the loose ones. |
Categories
bogon
Non-routable address (reserved / private / multicast). Exclusive — short-circuits with confidence 1.0.
tor
Active Tor exit node. Exclusive — short-circuits with confidence 1.0.
privacy_relay
Trusted relay fronting real users (iCloud Private Relay, Zscaler CENR). Exclusive override — datacenter-egressing but legitimate.
vpn
Commercial VPN exit (not iCloud / Zscaler — those are privacy_relay). Exclusive short-circuit with confidence 1.0: any ASN on the curated vpn-asns list bypasses the weighted scorer, since commercial VPNs universally run on hosting infrastructure and the "vpn + hosting" split tells the caller nothing actionable.
hosting
Datacenter / cloud / server infrastructure. Rarely a real end user directly, unless it's a privacy relay.
mobile
Mobile carrier cellular connection. Matched via curated mobile-ASN list or mobile-pattern rDNS.
residential
Consumer broadband / fiber / cable. Matched via residential-ASN list or residential-pattern rDNS — never as a fallback. When no signal fires, the classifier returns unknown instead of guessing residential.
business
Corporate network. Detected via rDNS pattern matching and apex-domain enrichment: if the PTR's apex is not a consumer-ISP brand and has MX/SPF records, it almost certainly belongs to a business.
unknown
Fallback bucket — no positive signal fired (unrouted IPs, allocations not yet announced in BGP, prefixes we simply have no data on). Preferred over silently defaulting to residential, which is a misread on e.g. a hosting-provider allocation not yet announced.
Evidence signals
Each signal contributes weight toward one or more categories; the distribution is the normalised sum. Weights are a defensible starting point, not a calibrated model — expect tuning as v3beta sees production load.
| Signal | Category weights | Meaning |
|---|---|---|
| mobile_asn | mobile +5 | ASN is in the curated mobile-carrier list (e.g. T-Mobile USA, AS21928). |
| residential_asn | residential +5 | ASN is in the curated consumer-ISP list (e.g. Comcast, AS7922). |
| vpn_asn | vpn 1.0 (short-circuit) | ASN is on the curated vpn-asns list. Bypasses the weighted scorer entirely — the classification returns vpn: 1.0 directly, same exclusive-match path as bogon and tor_exit. |
| proxy_cidr | vpn +4, hosting −2 | IP is inside a known proxy/VPN CIDR block. |
| hosting_asn | hosting +4 | ASN is in the hosting/datacenter list. |
| cloud_cidr | hosting +3 | IP is inside a major cloud provider CIDR (aliased into hosting). |
| rdns_hosting | hosting +3 | PTR hostname matches a provider-owned TLD / pattern. |
| rdns_residential | residential +4 | PTR hostname matches a consumer-ISP pattern (dynamic pools, etc). |
| rdns_mobile | mobile +2 | PTR hostname matches a mobile-carrier pattern. |
| rdns_business | business +3 | PTR hostname matches a corporate-network pattern (.corp., .office., etc.). |
| rdns_corp_mx | business +6, residential −3 | PTR hostname is itself one of the apex's MX targets — i.e. this specific IP is literally a mail server for the apex (v1.16.0 tightened from the loose "apex has any MX" check). Gated on: non-ISP apex, non-auto-generated PTR, and no hosting/cloud signal already firing. The residential penalty lets a self-hosted mail server on a consumer-broadband ASN flip the classification from residential to business. |
| rdns_corp_spf | business +4, residential −2 | Apex's v=spf1 record explicitly authorizes this IP via ip4/ip6/a/mx mechanisms (include: is not recursed — scope-limited to bound DNS cost). Same gates as rdns_corp_mx. Weighted lower than MX because "authorized to send" is a slightly weaker organisational signal than "receives mail here". |
| sfs_listed | (suspicion only) | IP appears in StopForumSpam's 90-day reported-spammer feed (listed_ip_90.zip). Does not change the classification on its own — a listed residential IP is legitimately a compromised home machine / botnet node, i.e. still residential, just suspicious: true. Feeds the compound amplifier rules below. |
| sfs_toxic | vpn +5, hosting −2 | IP is inside a CIDR from SFS's hand-curated toxic list (~50 ranges, updated daily). Treated as a strong proxy/anonymizer indicator regardless of ASN or rDNS context — "very likely proxy". |
| sfs_proxy_amplify | vpn +2 | Compound signal — fires when sfs_listed AND proxy_cidr both hit. Boosts the vpn confidence of an IP we already know is a proxy and that has recent spam history. Suppressed when sfs_toxic also fires (toxic alone is strong enough). |
| sfs_hosting_proxy_hint | vpn +3, hosting −1 | Compound signal — fires when sfs_listed on a hosting/cloud IP with NO other anonymizer signal (proxy, tor, vpnasn all quiet). The "undetected proxy on a VPS" heuristic: hosting + abuse history strongly suggests anonymizer infrastructure we haven't indexed yet. Suppressed when sfs_toxic or sfs_proxy_amplify fires. |
| no_other_signal | unknown +1 | Fallback when no positive signal fires — routes all mass to the unknown bucket rather than guessing residential. Triggered for unrouted IPs, un-announced allocations, and anything else the classifier has nothing to say about. |
Example request
curl https://blackbox.ipinfo.app/api/v3beta/8.8.8.8
Example response — hosting IP (Google DNS)
{
"ip": "8.8.8.8",
"error": null,
"asn": {
"number": 15169,
"name": "GOOGLE",
"network": "8.8.8.0",
"cidr": 24
},
"classification": "hosting",
"confidence": 1.0,
"categories": {
"bogon": 0,
"tor": 0,
"vpn": 0,
"privacy_relay": 0,
"hosting": 1.0,
"mobile": 0,
"residential": 0,
"business": 0
},
"signals": {
"hosting": true,
"cloud": true
// ...plus other v2-compatible flags
},
"evidence": ["hosting_asn", "cloud_cidr"],
"suspicious": false,
"rdns": {
"hostname": "dns.google",
"category": null,
"match": null
}
}
Example response — residential broadband
{
"ip": "72.49.1.1",
"error": null,
"asn": {
"number": 6181,
"name": "FUSE-NET",
"network": "72.49.0.0",
"cidr": 16
},
"classification": "residential",
"confidence": 1.0,
"categories": {
"residential": 1.0
// ...zeros elided for brevity
},
"evidence": ["residential_asn"],
"suspicious": false,
"rdns": null
}
No bulk endpoint. v1 and v2 accepted comma-separated IPs and POST bodies;
v3beta dropped those because the response is an object, not an array — there's no
sensible shape to batch. Callers that need multiple IPs should issue parallel GETs;
Cloudflare caching makes repeats effectively free.
// 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