Documentation

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.

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 "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": 4987
}

{
  "ip":                "185.220.101.5",
  "asn":               "60729",
  "country_code":      "DE",
  "as_name":           "TORSERVERS-NET",
  "credits_remaining": 87
}

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

Response fields

Error codes

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. Available on Pro, VIP, and Business plans.

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 and rate limit as /api/check, but draws from its own separate credit pool — one BIN-lookup credit per successful lookup, sized to the same allocation as your plan's IP-check credits.

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",
  "credits_remaining": 4986
}

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

A bin_not_found or upstream failure never consumes a credit — you're only charged for a successful lookup.

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. Uses the same API key, rate limit and BIN credit pool as /api/bin: one BIN credit per successful call. Failed lookups are never charged.

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": 4985
}

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.

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