Documentation
Fraudex API — real-time VPN, proxy, bot & fraud detection. One endpoint. Instant JSON.
Introduction
Fraudex checks any IP address against 741+ known bad ASNs — VPN providers, proxy networks,
Tor exit nodes, datacenters, and scraping infrastructure — and returns the visitor's country code,
ASN info, and a clean is_bot flag in a single JSON call.
/api/check and /api/bin, refilled on the 1st (UTC), at up to 30 requests a minute.
Paid plans are unlimited within a per-minute speed limit: IP ($40, 120/min) covers /api/check; IP + BIN ($70, 300/min) adds /api/bin; Complete ($99, 600/min) adds /api/bin-logo. See pricing.
How it works
Fraudex maintains two in-memory IP-to-ASN databases (IPv4 and IPv6). When you send a visitor IP, it performs a binary range search to find the owning ASN, then checks that ASN against the blocklist.
- You send the visitor's IP to
GET /api/check - Fraudex resolves the IP to its ASN via in-memory binary search
- ASN is matched against 741+ flagged networks
- The IP is also checked against the Tor Project's live list of exit relays, refreshed every 6 hours
- Country code is extracted from the ASN record
- JSON returned with
is_bot,country_code, ASN name, and credits remaining
Quick start
Sign up, verify your email, and copy your API key from the dashboard. Then make your first call:
curl "https://fraudex.xyz/api/check?ip=185.220.101.5" \
-H "X-API-Key: fx_your_key_here"
{
"ip": "185.220.101.5",
"asn": "60729",
"country_code": "DE",
"as_name": "TORSERVERS-NET",
"is_bot": true,
"status": "bot",
"credits_remaining": "unlimited"
}
Authentication
Pass your API key via the X-API-Key header (recommended — keeps the key out of server logs) or the ?key= query parameter.
X-API-Key: fx_your_api_key_here
GET /api/check?ip=1.2.3.4&key=fx_your_api_key_here
Endpoint
https://fraudex.xyz/api/check
| Parameter | Where | Required | Description |
|---|---|---|---|
ip | Query | Yes | IPv4 or IPv6 address to check |
key | Query | If no header | Your API key |
X-API-Key | Header | If no ?key= | Your API key (recommended) |
Response fields
| Field | Type | Plans | Description |
|---|---|---|---|
ip | string | All | The IP address checked |
asn | string | null | All | Autonomous System Number |
country_code | string | null | All | ISO 3166-1 alpha-2 country code (e.g. "US", "NL") |
as_name | string | null | All | Organization name owning the ASN |
is_bot | boolean | All | true if VPN, proxy, bot, or datacenter IP |
status | string | All | "bot" or "clean" |
credits_remaining | number | string | All | Lookups left this month on the Free plan; "unlimited" on paid plans |
Error codes
| HTTP | code field | Meaning |
|---|---|---|
400 | missing_ip | No ip parameter provided |
400 | invalid_ip | Value is not a valid IP address |
400 | not_public_ip | Private, loopback or reserved address (e.g. 10.0.0.1, 127.0.0.1). Not charged. |
405 | method_not_allowed | Use GET |
401 | missing_key | No API key provided |
401 | invalid_key | API key not recognized |
429 | rate_limited | Per-user rate limit exceeded — check retry_after |
402 | payment_required | The account's email isn't verified yet. Finish sign-up first. |
429 | free_limit_reached | Free plan: this month's lookups are used up. resets_on gives the refill date. |
403 | plan_upgrade_required | Your plan doesn't include this endpoint. required_plan names the cheapest plan that does. |
Rejected requests (bad key, invalid IP) do not consume credits.
VPN & proxy detection
Check is_bot to detect visitors using commercial VPNs, SOCKS proxies, residential proxy networks, and Tor exit nodes. Included in every plan.
r = requests.get("https://fraudex.xyz/api/check",
params={"ip": visitor_ip},
headers={"X-API-Key": KEY})
data = r.json()
if data.get("is_bot"):
abort(403, "VPN or proxy detected.")
Country blocking
Every response includes country_code — a two-letter ISO code based on the IP's registered ASN location. Use it to block or restrict access by region. Available on all plans.
BLOCKED = {"CN", "RU", "KP", "IR"}
data = requests.get("https://fraudex.xyz/api/check",
params={"ip": visitor_ip}, headers={"X-API-Key": KEY}).json()
if data.get("country_code") in BLOCKED:
abort(403, "Not available in your region.")
Scraper detection
Fraudex flags 741+ ASNs used by known scraping services, headless browser farms, and datacenter ranges. When is_bot is true for a content request, you can block it, serve honeypot data, or apply strict rate limits.
Anti-carding & fraud
Carders use VPNs to spoof locations and bypass geo-fraud rules. Integrate Fraudex at checkout: if is_bot: true, block or require additional verification before processing payment.
For higher accuracy, combine the country_code from Fraudex with the billing address country. A mismatch plus is_bot: true is a strong fraud signal.
BIN / card issuer lookup
Look up the brand, type, issuing bank, and country behind any 6-8 digit card prefix (the BIN / IIN).
Uses the same API key as /api/check. Included in the IP + BIN ($70) and Complete ($99) plans, unlimited within your plan's per-minute speed limit.
https://fraudex.xyz/api/bin
| Parameter | Where | Required | Description |
|---|---|---|---|
bin | Query | Yes | 6-8 digit card prefix |
key | Query | If no header | Your API key |
X-API-Key | Header | If no ?key= | Your API key (recommended) |
curl "https://fraudex.xyz/api/bin?bin=424242" \
-H "X-API-Key: fx_your_key_here"
{
"bin": "424242",
"brand": "VISA",
"type": "CREDIT",
"issuer": "Visa",
"country": "United States",
"country_code": "US",
"level": "CLASSIC",
"prepaid": false,
"credits_remaining": "unlimited"
}
| Field | Type | Description |
|---|---|---|
bin | string | The BIN that was looked up |
brand | string | null | Card network, e.g. "VISA", "MASTERCARD" |
type | string | null | "CREDIT", "DEBIT", or "PREPAID" |
issuer | string | null | Issuing bank name (may be "UNKNOWN") |
country | string | null | Issuing country, full name |
country_code | string | null | ISO 3166-1 alpha-2 country code |
level | string | null | Card product level, e.g. "CLASSIC", "PLATINUM", "BUSINESS", "PREPAID", when known |
prepaid | boolean | null | true for prepaid and gift cards, null when unknown |
credits_remaining | number | string | Lookups left this month on the Free plan; "unlimited" on paid plans |
Anti-fraud tip: combine country_code here with the visitor's IP country_code from /api/check. A mismatch between card-issuing country and visitor/billing country is a strong carding signal.
BIN lookup error codes
| HTTP | code field | Meaning |
|---|---|---|
400 | missing_bin | No bin parameter, or fewer than 6 digits |
401 | missing_key | No API key provided |
401 | invalid_key | API key not recognized |
404 | bin_not_found | BIN not found in the registry — try fewer digits |
429 | rate_limited | Per-user rate limit exceeded — check retry_after |
402 | payment_required | The account's email isn't verified yet. Finish sign-up first. |
429 | free_limit_reached | Free plan: this month's lookups are used up. resets_on gives the refill date. |
403 | plan_upgrade_required | Your plan doesn't include this endpoint. required_plan names the cheapest plan that does. |
A bin_not_found or upstream failure never consumes a credit — you're only charged for a successful lookup.
Checkout risk check
One call per payment attempt. Send the shopper's IP and the card's BIN (plus the billing country and email if you have them) and get back
allow, review or block, a score from 0 to 100, and every reason behind it in plain English.
Fraudex also remembers your recent attempts (BIN and IP only, for 15 minutes) so it can spot card testing as it happens.
https://fraudex.xyz/api/risk
| Parameter | Required | Description |
|---|---|---|
ip | Yes | The shopper's IP address (IPv4 or IPv6) |
bin | Recommended | First 6-8 digits of the card. Never send the full number. |
billing_country | No | 2-letter ISO code of the billing address, e.g. US |
email | No | Only the domain is checked, against common throwaway inbox services |
curl "https://fraudex.xyz/api/risk?ip=185.220.101.5&bin=414720&billing_country=US" \
-H "X-API-Key: fx_your_key_here"
{
"decision": "block",
"score": 85,
"reasons": [
{ "code": "tor_exit", "points": 45,
"detail": "185.220.101.5 is a Tor exit relay, so the buyer's real location is hidden." },
{ "code": "many_cards_one_ip", "points": 40,
"detail": "185.220.101.5 has tried 4 different cards on your checkout in the last 15 minutes." }
],
"ip": { "ip": "185.220.101.5", "asn": "60729", "country_code": "DE", "is_bot": true, "tor": true, ... },
"card": { "bin": "414720", "brand": "Visa", "type": "Credit", "prepaid": false, "country_code": "US", ... },
"billing_country": "US",
"velocity": { "window_minutes": 15, "attempts_from_ip": 5, "distinct_cards_from_ip": 4, "attempts_on_bin": 1, "distinct_ips_on_bin": 1 },
"credits_remaining": { "ip": "unlimited", "bin": "unlimited" }
}
A check uses one IP credit, plus one BIN credit when you send a BIN, so it is included in the IP + BIN ($70) and Complete ($99) plans and works on the Free plan. Error codes are the same as for /api/check and /api/bin, plus invalid_bin and invalid_country (400).
Call it on every attempt, including declined ones. Card testing shows up as many attempts, so the velocity signals only work if Fraudex sees them all.
Signals and points
The score is the sum of the signals that fired, capped at 100. Under 30 is allow, 30 to 59 is review, 60 and up is block. You can ignore decision and set your own thresholds from score or individual reasons.
| code | Points | When it fires |
|---|---|---|
tor_exit | 45 | The IP is a current Tor exit relay |
vpn_proxy_hosting | 30 | The IP is on a VPN, proxy, hosting or bot network |
card_ip_country_mismatch | 20 | Card issued in one country, shopper connecting from another (not counted when the IP is already a VPN or Tor) |
billing_card_country_mismatch | 15 | Billing country differs from the card's country |
billing_ip_country_mismatch | 10 | Billing country differs from the IP's country |
prepaid_card | 15 | The BIN belongs to a prepaid or gift card |
disposable_email | 20 | The email uses a throwaway inbox service |
many_cards_one_ip | 40 | 3 to 5 different BINs from this IP on your checkout in 15 minutes |
card_testing_burst | 60 | 6 or more different BINs from this IP in 15 minutes |
bin_attack | 45 | The same BIN tried 8+ times from 5+ different IPs in 15 minutes (generated card numbers) |
BIN to bank logo
Get the logo of the bank that issued a card, from its first 6-8 digits. Useful for showing customers a familiar card-issuer badge at checkout, or for making card lists easier to scan in your admin tools. Included in the Complete plan ($99) only, unlimited within its per-minute speed limit. Same API key as the other endpoints.
https://fraudex.xyz/api/bin-logo
| Parameter | Where | Required | Description |
|---|---|---|---|
bin | Query | Yes | 6-8 digit card prefix |
format | Query | No | Leave out to get the image itself (image/jpeg). Set to json to get the bank details plus a logo_url. |
X-API-Key | Header | If no ?key= | Your API key (recommended) |
curl "https://fraudex.xyz/api/bin-logo?bin=545454" \
-H "X-API-Key: fx_your_key_here" -o logo.jpg
{
"bin": "545454",
"brand": "MASTERCARD",
"type": "CREDIT",
"issuer": "BANK HANDLOWY W WARSZAWIE, S.A.",
"country": "Poland",
"country_code": "PL",
"logo_url": "https://fraudex.xyz/logos/dfb4ccc34fcb5d9146697585.jpg",
"credits_remaining": "unlimited"
}
logo_url is public and needs no key, so you can put it straight into an <img> tag without exposing your API key. Image responses also include the bank name in an X-Issuer header.
Logos are found automatically by bank name. Well-known banks come back accurate; for small or obscure issuers the image is a best match and may occasionally be wrong, so treat it as a visual aid, not as proof of who issued a card.
| HTTP | code field | Meaning |
|---|---|---|
404 | bin_not_found | BIN not found in the registry |
404 | no_issuer | The BIN exists but has no issuing bank on record, so there is no logo to find |
502 | logo_unavailable | The logo source didn't return an image. Try again later; you were not charged. |
All errors from BIN lookup (missing key, invalid key, rate limits, credits) apply here too.
Python example
import requests, os
from flask import request, abort
FX_KEY = os.environ["FRAUDEX_KEY"]
def check_visitor(ip):
try:
r = requests.get(
"https://fraudex.xyz/api/check",
params={"ip": ip},
headers={"X-API-Key": FX_KEY},
timeout=2
)
return r.json()
except Exception:
return {} # fail open on network error
@app.before_request
def guard():
data = check_visitor(request.remote_addr)
if data.get("is_bot"):
abort(403)
Node.js example
const FX_KEY = process.env.FRAUDEX_KEY;
async function fraudex(req, res, next) {
const ip = req.ip;
try {
const r = await fetch(
`https://fraudex.xyz/api/check?ip=${ip}`,
{ headers: { "X-API-Key": FX_KEY } }
);
const data = await r.json();
if (data.is_bot) return res.status(403).json({ error: "Blocked." });
} catch (_) { /* fail open */ }
next();
}
app.use(fraudex);
PHP example
$ip = $_SERVER["REMOTE_ADDR"];
$key = getenv("FRAUDEX_KEY");
$url = "https://fraudex.xyz/api/check?ip=" . urlencode($ip);
$ctx = stream_context_create(["http" => [
"header" => "X-API-Key: $key\r\n"
]]);
$res = @file_get_contents($url, false, $ctx);
$data = $res ? json_decode($res, true) : [];
if (!empty($data["is_bot"])) {
http_response_code(403);
exit("Access denied.");
}