Threat IP lookup — per-IP automation reputation via x402 upto

TL;DR

One paid endpoint: GET /api/v1/threat-ips/lookup?ip=… returns whether an address appears on War-Tracker's internal automation-abuse ledger, with opaque class labels and coarse timing metadata.
x402 upto billing (EVM only): the 402 advertises a maximum authorization of $0.02 USDC; settlement is $0.02 when the IP matches the ledger, $0.002 on a miss or invalid input. Invalid IPs are billed as misses — there is no free 400.
No IP list sales. Buyers query one IP at a time. We do not publish bulk dumps, CSV exports, or facet browsers.
Free buyer docs: class-label glossary at /threat-ips and a scale narrative at /threat-ips/history. Neither page documents collection pipelines or internal scoring.
Buyer SDK requirement: EVM offers use the upto scheme — your x402 client must implement UptoEvmScheme (not just exact).

What's live

Path	Scheme	Max auth	Settle (hit)	Settle (miss / invalid)
`/api/v1/threat-ips/lookup?ip=`	`upto`	$0.02	$0.02	$0.002

Per-route prices are env-tunable (X402_PRICE_THREAT_IP_LOOKUP_MAX and X402_PRICE_THREAT_IP_LOOKUP_MISS). The defaults above are what's in production today.

The route sits alongside the events corpus and maritime APIs on the same multi-facilitator x402 gate (xpay, CDP, PayAI, Dexter on Base and selected L2s). Discovery is in /api/v1/openapi.json and /.well-known/x402.

Why one lookup endpoint (and no lists)

War-Tracker runs one of the few large-scale, x402-metered public OSINT APIs on the open web. That visibility attracts sustained automated pressure — share walkers, non-interactive farm clients, UA-spoofing automation, and other scripted abuse against our paid and free surfaces.

We maintain an internal ledger of addresses tied to that activity. Selling per-IP lookup lets integrators ask "is this address one you've seen before, and what coarse class does it fall into?" without us publishing a downloadable reputation feed that would immediately become a free mirror.

You supply one IP; we return a sanitized JSON dossier. That's the product boundary.

Billing contract (`upto`, not `exact`)

Most War-Tracker paid routes use x402 exact — the 402 amount is the amount you settle. Threat IP lookup is different: it uses upto because the price depends on whether the address is on the ledger.

First call (no payment): gated clients receive HTTP 402 with accepts[] entries advertising a maximum of $0.02 USDC (EVM only). There is no pre-payment oracle — you authorize up to the cap.
Retry with X-PAYMENT: after settlement, you get HTTP 200 with the JSON body.
Settlement tier is chosen server-side after the lookup runs: - matched: true → $0.02 settles. - matched: false (valid IP, not on ledger) → $0.002 settles. - invalid: true (error: "invalid_ip") → $0.002 settles. Malformed or missing ip is not a free validation error.

The miss tier was set at $0.002 (not zero) to stay above facilitator settlement floors while keeping negative lookups cheap enough to use in pre-flight checks.

Every successful 200 includes coarse network flags (mobile, proxy, hosting) and a licensing field, even on misses.

Response shapes

Ledger hit

{
  "matched": true,
  "ip": "185.142.40.229",
  "classes": ["farm_walker", "noj_farm"],
  "confidence": "high",
  "country": "LB",
  "mobile": false,
  "proxy": false,
  "hosting": false,
  "first_seen": "2026-05-01T12:00:00Z",
  "last_seen": "2026-09-01T08:30:00Z",
  "hit_count": 48,
  "licensing": "…"
}

classes[] entries are opaque product vocabulary — they group observed automation patterns without explaining how the label was assigned. The full glossary (with buyer-facing blurbs for each label) lives at /threat-ips.

Miss (valid IP, not on ledger)

{
  "matched": false,
  "ip": "8.8.8.8",
  "country": "US",
  "mobile": false,
  "proxy": true,
  "hosting": false,
  "licensing": "…"
}

No classes[] on a miss. Network flags still populate from our ip-geo cache when available.

Invalid input

{
  "matched": false,
  "invalid": true,
  "error": "invalid_ip",
  "licensing": "…"
}

Still HTTP 200 after payment; still settles at the miss tier.

What we deliberately do not return

Lookup responses are sanitized for redistribution. You will not see internal reason codes, detection channels, response-playbook metadata, user-agent samples, or evidence blobs. If you need operational detail beyond the opaque classes[] labels, that's a commercial conversation — not something this endpoint exposes.

Integrating as a buyer

Read the free glossary first — /threat-ips for pricing, example JSON, and class-label meanings; /threat-ips/history for why we charge per lookup instead of publishing lists.
Confirm your SDK speaks upto on EVM. The x402 Python/TS buyer SDKs expose UptoEvmScheme for routes whose scheme is upto. Clients that only implement exact will fail to settle this route.
Use the same payment flow as other paid routes — fetch the 402, pick an accepts[] entry for your chain/facilitator, sign, retry with X-PAYMENT. See /x402 for the full policy and /developers for a worked integration guide.
LLM agents: /skill.md lists the lookup tool alongside the events and maritime catalog.

# After x402 settlement (same flow as /api/v1/events, /api/v1/vessels/*, …):
curl -H "X-PAYMENT: …" \
  'https://war-tracker.com/api/v1/threat-ips/lookup?ip=185.142.40.229'

Licensing

Paid lookup data carries the same redistribution terms as the rest of the War-Tracker paid surface: no third-party sharing without written consent from war-tracker.com; $1 USDC per infraction for unauthorized redistribution. The licensing field on every response echoes the canonical text. See /pricing and /terms.

Per-lookup purchase covers your own use of the returned dossier. Building a competing IP-reputation feed or republishing lookup results to third parties is not covered — contact

sales@war-tracker.com.