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.

Free accounts get 100 IP lookups and 50 BIN lookups a month on /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.

  1. You send the visitor's IP to GET /api/check
  2. Fraudex resolves the IP to its ASN via in-memory binary search
  3. ASN is matched against 741+ flagged networks
  4. The IP is also checked against the Tor Project's live list of exit relays, refreshed every 6 hours
  5. Country code is extracted from the ASN record
  6. 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 — check an IP
curl "https://fraudex.xyz/api/check?ip=185.220.101.5" \
     -H "X-API-Key: fx_your_key_here"
Response — bot detected
{
  "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.

Header (recommended)
X-API-Key: fx_your_api_key_here
Query parameter (alternative)
GET /api/check?ip=1.2.3.4&key=fx_your_api_key_here

Endpoint

GET https://fraudex.xyz/api/check
ParameterWhereRequiredDescription
ipQueryYesIPv4 or IPv6 address to check
keyQueryIf no headerYour API key
X-API-KeyHeaderIf no ?key=Your API key (recommended)

Response fields

FieldTypePlansDescription
ipstringAllThe IP address checked
asnstring | nullAllAutonomous System Number
country_codestring | nullAllISO 3166-1 alpha-2 country code (e.g. "US", "NL")
as_namestring | nullAllOrganization name owning the ASN
is_botbooleanAlltrue if VPN, proxy, bot, or datacenter IP
statusstringAll"bot" or "clean"
credits_remainingnumber | stringAllLookups left this month on the Free plan; "unlimited" on paid plans

Error codes

HTTPcode fieldMeaning
400missing_ipNo ip parameter provided
400invalid_ipValue is not a valid IP address
400not_public_ipPrivate, loopback or reserved address (e.g. 10.0.0.1, 127.0.0.1). Not charged.
405method_not_allowedUse GET
401missing_keyNo API key provided
401invalid_keyAPI key not recognized
429rate_limitedPer-user rate limit exceeded — check retry_after
402payment_requiredThe account's email isn't verified yet. Finish sign-up first.
429free_limit_reachedFree plan: this month's lookups are used up. resets_on gives the refill date.
403plan_upgrade_requiredYour 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.

Python — block VPN at checkout
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.

Python — deny specific countries
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.

Scraper detection works at the network layer — it catches scrapers that run on known datacenter and proxy ASNs. Combine with user-agent checking and behavioral rate limiting for maximum coverage.

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.

Fraudex is a strong first layer. Combine it with your payment processor's 3DS authentication and velocity checks for maximum fraud coverage.

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.

Only send the first 6-8 digits of a card number. Never send, log, or store a full card number (PAN) — the BIN alone identifies the issuer and doesn't identify an individual card.
GET https://fraudex.xyz/api/bin
ParameterWhereRequiredDescription
binQueryYes6-8 digit card prefix
keyQueryIf no headerYour API key
X-API-KeyHeaderIf no ?key=Your API key (recommended)
cURL
curl "https://fraudex.xyz/api/bin?bin=424242" \
     -H "X-API-Key: fx_your_key_here"
Response
{
  "bin":               "424242",
  "brand":             "VISA",
  "type":              "CREDIT",
  "issuer":            "Visa",
  "country":           "United States",
  "country_code":      "US",
  "level":             "CLASSIC",
  "prepaid":           false,
  "credits_remaining": "unlimited"
}
FieldTypeDescription
binstringThe BIN that was looked up
brandstring | nullCard network, e.g. "VISA", "MASTERCARD"
typestring | null"CREDIT", "DEBIT", or "PREPAID"
issuerstring | nullIssuing bank name (may be "UNKNOWN")
countrystring | nullIssuing country, full name
country_codestring | nullISO 3166-1 alpha-2 country code
levelstring | nullCard product level, e.g. "CLASSIC", "PLATINUM", "BUSINESS", "PREPAID", when known
prepaidboolean | nulltrue for prepaid and gift cards, null when unknown
credits_remainingnumber | stringLookups 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

HTTPcode fieldMeaning
400missing_binNo bin parameter, or fewer than 6 digits
401missing_keyNo API key provided
401invalid_keyAPI key not recognized
404bin_not_foundBIN not found in the registry — try fewer digits
429rate_limitedPer-user rate limit exceeded — check retry_after
402payment_requiredThe account's email isn't verified yet. Finish sign-up first.
429free_limit_reachedFree plan: this month's lookups are used up. resets_on gives the refill date.
403plan_upgrade_requiredYour 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.

GET https://fraudex.xyz/api/risk
ParameterRequiredDescription
ipYesThe shopper's IP address (IPv4 or IPv6)
binRecommendedFirst 6-8 digits of the card. Never send the full number.
billing_countryNo2-letter ISO code of the billing address, e.g. US
emailNoOnly the domain is checked, against common throwaway inbox services
cURL
curl "https://fraudex.xyz/api/risk?ip=185.220.101.5&bin=414720&billing_country=US" \
     -H "X-API-Key: fx_your_key_here"
Response
{
  "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.

codePointsWhen it fires
tor_exit45The IP is a current Tor exit relay
vpn_proxy_hosting30The IP is on a VPN, proxy, hosting or bot network
card_ip_country_mismatch20Card issued in one country, shopper connecting from another (not counted when the IP is already a VPN or Tor)
billing_card_country_mismatch15Billing country differs from the card's country
billing_ip_country_mismatch10Billing country differs from the IP's country
prepaid_card15The BIN belongs to a prepaid or gift card
disposable_email20The email uses a throwaway inbox service
many_cards_one_ip403 to 5 different BINs from this IP on your checkout in 15 minutes
card_testing_burst606 or more different BINs from this IP in 15 minutes
bin_attack45The same BIN tried 8+ times from 5+ different IPs in 15 minutes (generated card numbers)

Python example

Flask middleware — block bots before any route
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

Express middleware
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

Procedural PHP
$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.");
}