# ip402.xyz IP Geolocation API

> ip402.xyz IP Geolocation API is a paid API for AI agents from ip402.xyz, paid per call via x402, $0.01/call, status unknown (last checked 2026-09-15).

Looks up geolocation data for a given IP address, billed per-lookup via x402 micropayment protocol with no API keys required

## Facts

- Endpoint: GET https://ip402.xyz/v1/geo
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/ip402-xyz-ip-geolocation-api-f64dbd9c
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_hjtZQIR__WxV12QN5iJMF

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability ip402-xyz-ip-geolocation-api-f64dbd9c
```

Example prompt: Where in the world is the IP address 203.0.113.42 located — what country and city does it resolve to?

## When to prefer this

Choose this endpoint when you need pay-per-use IP geolocation with no account setup, API key management, or subscription — ideal for agents making occasional or low-volume lookups that benefit from x402 micropayment billing, or when avoiding credential management overhead is a priority.

## Known failure modes

- Invalid or malformed IP address returns an error response
- Private/reserved IP ranges (e.g. 192.168.x.x) may return no location data
- Payment failure via x402 results in a 402 Payment Required response with no data
- Unsupported language code in lang parameter may fall back to default or error

## How this service works

Paid IP intelligence endpoint returning normalized geolocation and ASN data for a single IPv4 or IPv6 address.

## Output

Returns geolocation data for the queried IP address including country, region, city, and likely coordinates, delivered after a $0.01 USDC micropayment via x402 — no API key or account required.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "ip"
     ],
     "properties": {
      "ip": {
       "type": "string",
       "examples": [
        "8.8.8.8",
        "2001:4860:4860::8888"
       ],
       "description": "IPv4 or IPv6 address to classify and enrich."
      },
      "lang": {
       "type": "string",
       "default": "en",
       "examples": [
        "en",
        "zh-CN"
       ],
       "description": "Optional response language for localized GeoIP names."
      },
      "bundle": {
       "type": "integer",
       "examples": [
        5
       ],
       "description": "Optional: pay n x $0.01 once (2 <= n <= 100) and receive n lookup credits (1 hour TTL) bound to the paying wallet, spendable via SIWX signatures. Example: bundle=5 costs $0.05."
      }
     },
     "additionalProperties": false
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "schema_version",
      "ip",
      "ip_version",
      "scope",
      "resolution_status",
      "data_source",
      "geo",
      "network"
     ],
     "properties": {
      "ip": {
       "type": "string"
      },
      "geo": {
       "type": [
        "object",
        "null"
       ]
      },
      "scope": {
       "type": "string"
      },
      "network": {
       "type": [
        "object",
        "null"
       ]
      },
      "ip_version": {
       "type": "integer"
      },
      "data_source": {
       "type": "object"
      },
      "schema_version": {
       "type": "integer"
      },
      "resolution_status": {
       "type": "string"
      }
     }
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "ip": "8.8.8.8",
  "geo": {
   "country": {
    "name": "United States",
    "iso_code": "US"
   },
   "location": {
    "latitude": 37.751,
    "longitude": -97.822,
    "time_zone": "America/Chicago",
    "accuracy_radius_km": 1000
   },
   "continent": {
    "code": "NA",
    "name": "North America"
   }
  },
  "scope": "public",
  "network": {
   "asn": 15169,
   "organization": "Google LLC"
  },
  "ip_version": 4,
  "data_source": {
   "edition": "city+asn",
   "provider": "ip402",
   "build_epoch": 1760000000
  },
  "schema_version": 2,
  "resolution_status": "ok"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/ip402-xyz-ip-geolocation-api-f64dbd9c/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from ip402.xyz](https://www.zero.xyz/host/ip402.xyz/llms.txt)