Skip to content
API Guides

IP Fraud Detection API: Score Signups, Logins and Checkouts in Node and Python

Add an IP fraud detection API to signup, login and checkout: Node and Python code we ran on six public IPs, with real output, caching and the rate limits.

ByGeoIPHub TeamPublishedUpdatedReading time15 min read
An app window with a glowing cable plugged in from a bright node, representing adding IP fraud detection with one API call

Two signups arrive a second apart, and both hide the person's home address. One comes from a Tor exit in Hamburg. The other comes from iCloud Private Relay, which Apple describes as "part of an iCloud+ subscription" that protects you "when you browse the web in Safari" (Apple Support). A rule that blocks "anything hidden" rejects both, and one of them is a paying Apple customer.

Telling those two apart is the job. It is one slice of what IP intelligence covers, and it fits in one file of under 50 lines. Below you get the request, one real response, a Node and a Python version with caching and failure handling, what they printed for six addresses, and where the check falls short.

A stopwatch beside an app window filling with a response card, representing integration in minutes
One request, one response, every field.

The one request an IP fraud detection API needs

The whole integration is a single GET with the IP in the path and your key in the x-api-key header. The API reference documents the same shape:

Terminal
curl https://api.geoiphub.com/v1/lookup/45.83.220.7 \ -H "x-api-key: YOUR_API_KEY"

Three details catch people on the first try:

  • The IP goes in the path. /v1/lookup/{ip} is the only form. A query-string version redirects instead of returning data.
  • Don't send the placeholder. We sent the literal string YOUR_API_KEY and got 401 with {"message":"Invalid API key"}. Leave the header out until you have a real key; anonymous calls work at 30 a minute.
  • One IP per call. Each request takes one address, so a script that screens a list makes one request per address and counts each against your limit.

Create a free key in the dashboard when you move past testing. The free plan gives that key 1,500 lookups a day, with every field included.

What came back for a Mullvad address, and which fields to branch on

The response is about 2.7 KB of nested JSON in ten groups, and a fraud check needs two of them: detection and scoring. Here is the lookup for 45.83.220.7 from 16 October 2026, trimmed but with values untouched:

JSON
{ "ip": "45.83.220.7", "asn": { "asn": 39351, "org": "ESAB-AS - 31173 Services AB", "asn_type": "hosting", "connection_type": "datacenter" }, "geo": { "country_code": "SE", "city": "Malmö" }, "detection": { "is_vpn": true, "is_proxy": false, "is_tor": false, "is_hosting": true, "is_relay": false, "vpn_provider": "Mullvad (31173 Services)", "vpn_confidence": 85 }, "scoring": { "fraud_score": 46, "confidence": 0.56, "recommended_action": "review", "detection_methods": [ "known_vpn_server", "datacenter_ip" ] }, "meta": { "last_classified_at": "2026-10-16T07:40:17.524Z" } }

This address is on 31173 Services, the network Mullvad VPN runs its servers on, in Malmö. When we checked on 13 October it was not on Mullvad's own published server list. Two signals fired. known_vpn_server came from our table of known VPN hosting networks, which is why vpn_confidence was 85 and not the 95 a match on Mullvad's own server list gives. datacenter_ip said it is hosting, not a home connection. Together they scored 46, which landed in review: a VPN on its own is not fraud. Since our 10 November 2026 scoring change, a VPN on a hosting network gets datacenter_with_vpn_proxy instead of datacenter_ip, and a VPN with no abuse, proxy or Tor evidence stops at 70, so on 11 November this address returned 70, step_up.

Three fields carry the decision:

scoring.recommended_action

  • What it holds: allow (score up to 25), review (up to 50), step_up (up to 75), block (above 75)
  • How the code uses it: The branch

scoring.fraud_score

  • What it holds: The 0 to 100 composite behind that action
  • How the code uses it: Logging and later tuning

scoring.detection_methods

  • What it holds: The signals that fired, such as tor_exit or openvpn_open
  • How the code uses it: The reason you store and show reviewers

The detection flags (is_vpn, is_proxy, is_tor, is_hosting, is_relay) are the raw facts behind the score. Use them for the few rules where your business differs from the default bands. The score also has exonerating signals: a residential ISP subtracts 20 points and a verified crawler 30, so a flag alone doesn't push an address into block. The IP fraud score guide explains what moves the number.

The Node version: fetch, a one-hour cache and four branches

This is the exact file we ran, on Node 24 with no dependencies. It needs Node 18 or later for the built-in fetch:

JavaScript
// screen.mjs: score an IP before a signup, login or checkout. Node 18+, no dependencies. const API = "https://api.geoiphub.com/v1/lookup/"; const KEY = process.env.GEOIPHUB_API_KEY; // without a key: 30 lookups a minute, for testing only const TTL_MS = 60 * 60 * 1000; // reuse a verdict for an hour const cache = new Map(); // ip -> { at, data } async function lookup(ip) { const hit = cache.get(ip); if (hit && Date.now() - hit.at < TTL_MS) return hit.data; const headers = KEY ? { "x-api-key": KEY } : {}; const res = await fetch(API + encodeURIComponent(ip), { headers, signal: AbortSignal.timeout(3000), }); if (res.status === 429) throw new Error(`rate limited, retry after ${res.headers.get("retry-after")}s`); if (!res.ok) throw new Error(`HTTP ${res.status}`); const data = await res.json(); cache.set(ip, { at: Date.now(), data }); return data; } export async function screen(ip, flow) { let data; try { data = await lookup(ip); } catch (err) { return { action: "review", reason: `lookup failed: ${err.message}` }; // fail soft, never block on our outage } const { scoring, detection } = data; let action = scoring.recommended_action; // "allow" | "review" | "step_up" | "block" if (detection.is_tor) action = "block"; // no step-up through a Tor exit if (flow === "checkout" && action === "review") action = "step_up"; // stricter where money moves const flags = ["is_vpn", "is_proxy", "is_tor", "is_hosting", "is_relay"].filter((f) => detection[f]); return { action, score: scoring.fraud_score, flags, methods: scoring.detection_methods }; } // Try it: node screen.mjs signup 45.33.32.156 104.28.46.99 const [flow, ...ips] = process.argv.slice(2); for (const ip of ips) { const v = await screen(ip, flow); console.log(ip.padEnd(15), v.action.padEnd(8), v.score ?? "-", v.flags?.join(",") || "-", v.methods?.join(",") || v.reason); }

Four decisions in it are deliberate:

  • It starts from recommended_action and overrides it in only two places. A Tor exit always blocks, and at checkout review becomes step_up, because that is where money leaves.
  • It fails soft. A timeout, a 5xx or a 429 returns review, not block. If our API is unreachable, your signups keep working and get logged for a second look.
  • The timeout is 3 seconds. On our side, a known IP is answered from a memory-mapped database in under a millisecond, so the network round trip is most of the wait. An IP we have never seen is classified live in under 2.5 seconds, and 3 seconds covers that case.
  • The key stays on your server. Call the API from your backend, never from browser code, where anyone can read the key.

The Python version needs a User-Agent, or it gets a 403

Our API answers Python urllib's default User-Agent, Python-urllib/3.x, with 403 Forbidden. We reproduced it on 16 October at 05:36 UTC with a bare urllib.request.urlopen call: HTTP Error 403: Forbidden. Curl and requests don't hit it, because they send different User-Agents. So the Python file sets its own, with a comment saying why:

Python
# screen.py: score an IP before a signup, login or checkout. Python 3.8+, standard library only. import json, os, sys, time, urllib.error, urllib.request API = "https://api.geoiphub.com/v1/lookup/" KEY = os.environ.get("GEOIPHUB_API_KEY") # without a key: 30 lookups a minute, for testing only TTL = 3600 # reuse a verdict for an hour _cache = {} # ip -> (time, data) def lookup(ip): hit = _cache.get(ip) if hit and time.time() - hit[0] < TTL: return hit[1] # Set a User-Agent: our API answers urllib's default "Python-urllib/3.x" with 403 Forbidden. headers = {"User-Agent": "signup-screen/1.0"} if KEY: headers["x-api-key"] = KEY req = urllib.request.Request(API + ip, headers=headers) with urllib.request.urlopen(req, timeout=3) as resp: data = json.load(resp) _cache[ip] = (time.time(), data) return data def screen(ip, flow): try: data = lookup(ip) except urllib.error.HTTPError as e: wait = e.headers.get("Retry-After") if e.code == 429 else None return {"action": "review", "reason": f"HTTP {e.code}" + (f", retry after {wait}s" if wait else "")} except (OSError, ValueError) as e: # network error, timeout, bad JSON return {"action": "review", "reason": f"lookup failed: {e}"} # fail soft scoring, detection = data["scoring"], data["detection"] action = scoring["recommended_action"] # "allow" | "review" | "step_up" | "block" if detection["is_tor"]: action = "block" # no step-up through a Tor exit if flow == "checkout" and action == "review": action = "step_up" # stricter where money moves flags = [f for f in ("is_vpn", "is_proxy", "is_tor", "is_hosting", "is_relay") if detection[f]] return {"action": action, "score": scoring["fraud_score"], "flags": flags, "methods": scoring["detection_methods"]} if __name__ == "__main__": flow, ips = sys.argv[1], sys.argv[2:] for ip in ips: v = screen(ip, flow) print(f"{ip:<15} {v['action']:<8}", v.get("score", "-"), ",".join(v.get("flags", [])) or "-", ",".join(v.get("methods", [])) or v.get("reason", ""))

It is the same logic as the Node file, using only the standard library, tested on Python 3.9.6. urllib raises HTTPError for any non-2xx status, so the 429 and its Retry-After header are read from the exception.

What both scripts printed for six public addresses

Both scripts gave the same verdict for every address. We ran the Node file at 07:39 UTC and the Python file at 07:40 UTC on 16 October 2026, with no key, against six public addresses. The last command re-runs the Mullvad address as a checkout:

Terminal
node screen.mjs signup 45.33.32.156 104.28.46.99 45.83.220.7 91.90.122.25 102.129.235.17 185.220.101.1 node screen.mjs checkout 45.83.220.7
Output
45.33.32.156 allow 10 is_hosting datacenter_ip 104.28.46.99 allow 9 is_relay relay_ip 45.83.220.7 review 46 is_vpn,is_hosting known_vpn_server,datacenter_ip 91.90.122.25 step_up 64 is_hosting datacenter_blocklisted,no_ptr_datacenter,known_spammer 102.129.235.17 block 92 is_vpn known_vpn_server,openvpn_open,ipsec_open 185.220.101.1 block 100 is_tor,is_hosting tor_exit,datacenter_blocklisted,no_ptr_datacenter,known_spammer 45.83.220.7 step_up 46 is_vpn,is_hosting known_vpn_server,datacenter_ip

python3 screen.py with the same arguments printed the same seven lines, character for character. Here is what each address is and why it landed where it did:

45.33.32.156

  • What it is: scanme.nmap.org, Nmap's public test host on Linode
  • Action: allow, 10
  • Signals that fired: datacenter_ip only. Hosting alone isn't fraud

104.28.46.99

  • What it is: iCloud Private Relay egress on Cloudflare
  • Action: allow, 9
  • Signals that fired: relay_ip. The score caps relay addresses at 60, so they can never reach block

45.83.220.7

  • What it is: Mullvad's network in Malmö
  • Action: review, 46; step_up at checkout
  • Signals that fired: known_vpn_server, datacenter_ip

91.90.122.25

  • What it is: PIA VPN server in Schaan, Liechtenstein, on M247
  • Action: step_up, 64
  • Signals that fired: datacenter_blocklisted, no_ptr_datacenter, known_spammer. Not flagged as a VPN

102.129.235.17

  • What it is: Commercial VPN server in Washington, D.C.
  • Action: block, 92
  • Signals that fired: known_vpn_server, plus openvpn_open and ipsec_open: our probes completed OpenVPN and IPsec handshakes

185.220.101.1

  • What it is: Tor exit in Hamburg
  • Action: block, 100
  • Signals that fired: tor_exit, datacenter_blocklisted, no_ptr_datacenter, known_spammer

The two signups from the opening landed at opposite ends: the Tor exit at 100 and the Private Relay user at 9. That spread is the reason to score instead of blocking every hidden address.

Results move as our data changes. Until this rewrite, this post showed 45.83.220.7 as plain hosting with a score of 10 and allow. By 8 October our scanner had tied it to Mullvad, and on 16 October it scored 46. On 11 November 2026, after our scoring change, it scored 70, step_up. Log the action and the methods with each decision, so a change like that shows up in your data instead of surprising you.

Where to call it: every signup, login and checkout

Score every signup, every login and every checkout, on the server, before you commit the action. Those are the three moments where a fraudster gains something, and they are rare enough per user to fit a daily budget. Don't call it on every page view.

What each action means in practice:

allow

  • Signup: Create the account
  • Login: Sign in
  • Checkout: Take the payment

review

  • Signup: Create it, flag for review
  • Login: Sign in, log the reason
  • Checkout: Our code promotes it to step_up

step_up

  • Signup: Verify email or phone first
  • Login: Ask for the second factor
  • Checkout: Run 3-D Secure

block

  • Signup: Refuse with a neutral message
  • Login: Refuse, and count it toward lockout
  • Checkout: Decline the order

The default bands are a starting point, and your own fraud data should move them. Our fraud score thresholds for login, signup and checkout gives per-action starting cutoffs and the reasoning for each.

Score the right address, too. Behind a load balancer or CDN, the socket address is your proxy, and the client's IP sits in a forwarding header that any client can also forge. Take it from the hop your own trusted proxy added, never from the leftmost value a client sent.

Staying under 1,500 lookups a day: caching and the rate limit

The free plan allows 1,500 lookups a day. Cache by IP in your own code and the budget stretches much further, because one person usually signs up, logs in and pays from the same address within an hour.

The API itself won't help with caching: every response carries Cache-Control: private, no-store, so no shared HTTP cache will keep it. Both scripts keep a verdict for an hour in process memory. Use Redis or your existing cache if you run more than one server. Don't keep a verdict longer than a day, because our threat feeds and the lookup database refresh daily.

The two limits behave differently, and we hit one of them while testing this post:

No key

  • Limit: 30 lookups a minute per caller IP
  • What happens past it: The 30th request inside a minute returns 429 and blocks that IP for two hours

Free key

  • Limit: 1,500 lookups a day
  • What happens past it: 429 with a Retry-After header until the daily counter resets

At 05:37 UTC on 16 October we fired a burst of anonymous requests to see the 429. Within twenty seconds the API returned 429 with Retry-After: 7199, and every anonymous call from our IP stayed blocked for two hours, including our own scripts. Their fail-soft path is the first real output we got:

Output
45.33.32.156 review - - lookup failed: rate limited, retry after 6971s 45.33.32.156 review - - HTTP 429, retry after 6970s

So treat the anonymous limit as a testing allowance, and use a key in production. Branch on the status code and Retry-After, not on the 429's message text.

Where this check falls short

An IP verdict is one signal, and it misses things. Four cases came up while we wrote this post:

  • A listed VPN server can come back clean. PIA's server 91.90.122.25 was in PIA's own published list on 4 October, yet our API returns is_vpn: false. It reached step_up only because it is on a DNS blocklist. Without that history it would have passed as plain hosting.
  • Residential proxies are mostly invisible to IP data. Traffic routed through real home connections looks like a home user. The is_residential_proxy field is a coarse inference from the network, not a detection, so don't build a rule on it.
  • Shared addresses carry other people's history. Mobile carriers and CGNAT put many users behind one IP, which is why the score caps CGNAT ranges and why block should stay rare there.
  • Relay locations are approximate. For 104.28.46.99 our geolocation says Luanda, Angola, while Apple's own egress list puts that range in Lusaka, Zambia. Use the relay flag, not the city, for decisions, as our guide to letting Private Relay through explains.

Pair the IP check with what you know about the account: email age, device, payment history and velocity. The payment fraud stack guide shows where IP signals sit among them.

Run it against your own traffic first

Before you wire it into a live flow, run either script over a day of past signup IPs with a free key, and compare its actions with what you already know about those accounts. If block would have caught accounts you later banned, and allow covers the customers you kept, put it in front of signup first, then login, then checkout. To check one address by hand, the IP fraud score checker shows the same score and reasons without any code.

Frequently Asked Questions

Is the GeoIPHub API free to start?

Yes. The free plan includes 1,500 lookups a day with every data field, one API key and no credit card. Without a key you can make 30 lookups a minute for testing.

Which field should my code branch on?

scoring.recommended_action. It is allow up to a score of 25, review up to 50, step_up up to 75 and block above 75. Read scoring.detection_methods to log why.

Why does my Python script get a 403?

Our API answers urllib's default User-Agent, Python-urllib/3.x, with 403 Forbidden. Set your own User-Agent header and the same request returns 200.

Can I cache the response?

Yes, in your own code. The API sends Cache-Control: private, no-store, so shared HTTP caches will not keep it. We reuse a verdict for an hour per IP.

Will it block my real customers?

Not if you use the four actions as designed. An iCloud Private Relay address came back allow with a score of 9 in our run, and a plain cloud server came back allow at 10. Only the Tor exit and a probe-verified VPN reached block.

Do I need to send personal data?

No. You send an IP address and get intelligence about that address. Names, emails and card details stay in your system.

Written by

GeoIPHub Team

The team behind the GeoIPHub API

Written by the GeoIPHub team, the people who build the GeoIPHub IP intelligence API and its scanner. Drafts are prepared with AI assistance and edited by the team; API examples are real lookups against the live API unless labelled illustrative.

Share this article
More articles

Related posts