# IP Lookup

Geolocation, ASN, proxy and threat intelligence for any IP address. Every request is paid per call over x402 — no API key, no account, no
subscription. Use the OpenAPI schema at https://ipx402.com/openapi.json for exact request fields.

## Routes

- `POST https://ipx402.com/v1/ip` — resolve an IP address. Body: `{ "ip": "8.8.8.8" }`. Accepts
  IPv4 or IPv6. Returns country, region, city, latitude/longitude, postal code, timezone,
  ISP, ASN, and proxy/VPN detection with proxy type and usage where known.

The route also accepts `GET` with the same field as a query parameter, so
`GET https://ipx402.com/v1/ip?ip=8.8.8.8` is equivalent.

## Payment Flow

Call the route with no payment and it answers `402 Payment Required` with the terms in a
`PAYMENT-REQUIRED` header. Sign the payment with an x402 client and retry the same
request with the `X-PAYMENT` header; the response is the live data. Any x402 v2 client
works — for example `wrapFetchWithPayment` from `@x402/fetch`.

Price is **$0.01 per call**, quoted on:

  - Base (EVM), chain `eip155:8453`, USDC, paid to `0x1C2Eb89273135175Ae7F24A7C93f0bF5D61Eb793`
  - Solana, chain `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`, USDC, paid to `H6YQh5EHWdmu56j8KUWjVvR7M6yvUhHM2ekydPHEs9sR`

Pick whichever chain your wallet holds USDC on; both are offered on every paid route and
cost the same.

## Billing Semantics

This is the part worth reading. Settlement is cancelled whenever a request fails, so:

- A missing or malformed parameter returns `400` and is **not charged**.
- An upstream provider failure returns `502` or `503` and is **not charged**.
- A timeout returns `504` and is **not charged**.
- Only a `2xx` response is billed.

An address that cannot be resolved returns a non-2xx status, so it is not billed.
Check the HTTP status, not a `found` field.

Because of this, retrying a failed call costs nothing. Do not implement balance guards
around error responses.

## Free Endpoints

- `GET https://ipx402.com/` — human-readable overview
- `GET https://ipx402.com/openapi.json` — machine-readable contract
- `GET https://ipx402.com/llms.txt` — this document
- `GET https://ipx402.com/pricing` — current price and accepted chains as JSON
- `GET https://ipx402.com/health` — liveness

## Practical Agent Rule

Send one paid request per lookup with all known fields in the JSON body. Read the HTTP
status first: `2xx` means billed and valid, anything else means free and safe to retry.
Do not poll — every route answers synchronously.