IP Geolocation API

A paid Lucid Agent API providing IP geolocation lookup with x402 micropayments.

Features

• IP Geolocation: Look up location data for any public IP address
• Batch Lookup: Query up to 10 IPs in a single request
• Private IP Detection: Automatically rejects private/reserved IP ranges
• IPv6 Support: Handles both IPv4 and IPv6 addresses
• Caching: 1-hour TTL cache to reduce API calls
• x402 Payments: Built-in micropayment support

Endpoints

Health Check (Free)

GET /health

Single IP Lookup ($0.001)

GET /v1/geo?ip=8.8.8.8

Batch IP Lookup ($0.005)

POST /v1/geo/batch
Content-Type: application/json

{
  "ips": ["8.8.8.8", "1.1.1.1"]
}

Response Format

{
  "ip": "8.8.8.8",
  "country": "United States",
  "countryCode": "US",
  "region": "California",
  "city": "Mountain View",
  "latitude": 37.405991,
  "longitude": -122.078514,
  "timezone": "America/Los_Angeles",
  "utcOffset": "-08:00",
  "asn": {
    "number": 15169,
    "org": "Google LLC",
    "isp": "Google LLC"
  },
  "threat": {
    "isVpn": false,
    "isTor": false,
    "isProxy": false,
    "isDatacenter": false,
    "threatScore": 0
  },
  "freshness": {
    "fetchedAt": "2026-03-03T12:00:00.000Z",
    "staleness": 0,
    "confidence": 0.9
  }
}

Tech Stack

• Runtime: Bun
• Framework: Hono
• Data Source: ip-api.com (free tier)
• Validation: Zod
• Deployment: Railway
• Payments: x402

Development

# Install dependencies
bun install

# Run development server
bun dev

# Run tests
bun test

# Type check
bun run typecheck

Deployment

Railway

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
railway init
railway up

Environment Variables

PORT=3000

Test Coverage

• ✅ Health endpoint
• ✅ Single IP lookup (public IPs)
• ✅ Private IP detection (192.168.x.x, 10.x.x.x, 172.16.x.x)
• ✅ Invalid IP format handling
• ✅ Batch lookup (max 10 IPs)
• ✅ Batch limit enforcement
• ✅ IPv6 support
• ✅ Response schema validation
• ✅ Cache functionality
• ✅ Error handling

Total: 15+ tests

License

MIT