Base Mainnet · x402 V2

Geocoding API Documentation

Pay-per-request forward and reverse geocoding for developers and AI agents. $0.001 USDC per request via x402 V2. No API key or subscription required.

Quick Start

Make a geocoding request. The server returns HTTP 402 with a payment challenge in the PAYMENT-REQUIRED header. Sign the payment and retry with the PAYMENT-SIGNATURE header.

curl "https://geocoding-x402.royaldemocracy.workers.dev/api/geocode?q=1600 Pennsylvania Ave NW, Washington, DC 20500"

Without payment, you receive HTTP 402 with V2 payment requirements:

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://geocoding-x402.royaldemocracy.workers.dev/api/geocode?q=1600 Pennsylvania Ave NW, Washington, DC 20500",
    "description": "Forward geocoding: convert address to coordinates",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "1000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x26377E6B37A2eaDFD18d52f76e85ca59182cF6B9",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USDC", "version": "2" }
  }]
}

Forward Geocoding

Convert a street address, city, landmark, or location string into latitude and longitude coordinates.

Method	`GET`
Endpoint	`/api/geocode`
Parameter	`q` (required) — The address or location to geocode
Price	$0.001 USDC
Network	Base mainnet (eip155:8453)

Request

GET /api/geocode?q=1600+Pennsylvania+Avenue+NW,+Washington,+DC

Response (after payment)

{
  "lat": 38.8976763,
  "lon": -77.0365298,
  "display_name": "1600 Pennsylvania Ave NW, Washington, DC 20500, USA",
  "payer": "0x1234...",
  "settlement": {
    "success": true,
    "transaction": "0xabcdef...",
    "network": "eip155:8453",
    "payer": "0x1234..."
  }
}

Reverse Geocoding

Convert latitude and longitude coordinates into a human-readable address.

Method	`GET`
Endpoint	`/api/reverse`
Parameters	`lat` (required), `lon` (required)
Price	$0.001 USDC
Network	Base mainnet (eip155:8453)

Request

GET /api/reverse?lat=40.7128&lon=-74.006

Response (after payment)

{
  "address": "New York, NY, USA",
  "place": "New York",
  "payer": "0x1234...",
  "settlement": {
    "success": true,
    "transaction": "0xabcdef...",
    "network": "eip155:8453",
    "payer": "0x1234..."
  }
}

x402 V2 Payments

This API uses the x402 V2 payment protocol for per-request micropayments on Base mainnet.

How it works

Client requests a paid endpoint without payment.
Server responds with HTTP 402 and a payment challenge in the PAYMENT-REQUIRED header (base64-encoded JSON).
Client signs a USDC transfer authorization (EIP-3009) and encodes it as base64 in the PAYMENT-SIGNATURE header.
Server verifies the payment via the facilitator, performs the geocoding lookup, then settles the payment on-chain.
Server returns the geocoding result in the HTTP 200 response with a PAYMENT-RESPONSE header.

Payment details

Amount	$0.001 USDC (1000 raw units, 6 decimals)
Asset	USDC
Network	Base mainnet (chain ID 8453, CAIP-2: eip155:8453)
USDC Contract	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
Facilitator	`https://pay.openfacilitator.io`
Payment scheme	exact (EIP-3009 transferWithAuthorization)
x402 version	2
Request header	`PAYMENT-SIGNATURE`
Response header	`PAYMENT-RESPONSE`

Complete TypeScript x402 V2 Client Example

// geocode-client.ts
// Install: npm install @x402/fetch @x402/evm viem

import { wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { createWalletClient, http, privateKeyToAccount } from "viem";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(),
});

const paidFetch = wrapFetchWithPayment(
  fetch,
  walletClient,
  new ExactEvmScheme()
);

async function geocode(address: string) {
  const url = `https://geocoding-x402.royaldemocracy.workers.dev/api/geocode?q=${encodeURIComponent(address)}`;
  const response = await paidFetch(url);
  const data = await response.json();
  console.log(JSON.stringify(data, null, 2));
}

geocode("1600 Pennsylvania Ave NW, Washington DC");

The PRIVATE_KEY environment variable should contain the private key of a wallet funded with USDC on Base mainnet.

Pricing

$0.001 USDC per request.

No API key. No subscription. No monthly fees. You pay only for what you use. Payment is handled on-chain via x402 V2 using USDC on Base mainnet.

Errors

HTTP Status	Meaning
`200`	Request succeeded. Geocoding result returned with `PAYMENT-RESPONSE` header.
`400`	Missing or invalid query parameters (e.g., missing `q`, `lat`, or `lon`).
`402`	Payment required. The `PAYMENT-REQUIRED` header and JSON body contain the x402 V2 payment challenge. Sign the payment and retry with the `PAYMENT-SIGNATURE` header.
`404`	Location not found. The address could not be geocoded or the coordinates could not be reverse-geocoded.

AI Agent Usage

Autonomous agents can discover this API via machine-readable endpoints:

/openapi.json — Full OpenAPI 3.1 specification
/llms.txt — LLM-friendly plain text description
/.well-known/x402 — x402 service descriptor for payment-aware crawlers

These endpoints make it easy to programmatically discover and integrate the geocoding API without human intervention.

FAQ

How much does the geocoding API cost?

$0.001 USDC per successful request. No subscriptions, no API keys, no hidden fees.

Does the geocoding API require an API key?

No. Payment is handled via x402 V2 using USDC on Base mainnet. There is no traditional API key to manage.

What blockchain is used?

Base mainnet (chain ID 8453). CAIP-2 identifier: eip155:8453. Payments are in USDC.

What is x402?

x402 is an open payment protocol that enables per-request micropayments over HTTP. It uses the HTTP 402 status code to signal payment required, and allows clients to pay with cryptocurrency (USDC) directly in the request flow.

Can AI agents use this API automatically?

Yes. The API is designed for AI agents. Machine-readable documentation is available at /openapi.json, /llms.txt, and /.well-known/x402.

What is forward geocoding?

Forward geocoding converts a street address, city name, or location string into geographic coordinates (latitude and longitude).

What is reverse geocoding?

Reverse geocoding converts latitude and longitude coordinates into a human-readable address.

What cryptocurrency is used for payment?

USDC (USD Coin), a stablecoin pegged to the US dollar, on Base mainnet.

Homepage OpenAPI llms.txt x402 Descriptor Forward Geocoding Reverse Geocoding x402 Integration