Base Mainnet ยท x402 V2

Geocoding API for AI Agents

Forward and reverse geocoding for $0.001 USDC per request. No API key or subscription. Developers and AI agents can pay automatically with USDC on Base using x402.

Try Geocoding View Documentation OpenAPI Spec x402 Integration

Quick Start

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

Price$0.001 USDC
NetworkBase mainnet (eip155:8453)
Paymentx402 V2
AuthenticationNo API key
GET /api/geocode?q=1600 Pennsylvania Ave NW, Washington, DC 20500

{
  "lat": 38.8976763,
  "lon": -77.0365298,
  "display_name": "1600 Pennsylvania Ave NW, Washington, DC 20500, USA"
}

Forward Geocoding

Reverse Geocoding



    


    
Pay-Per-Request Geocoding API

    
Convert street addresses, cities, landmarks, and other locations into geographic coordinates. Reverse geocoding converts latitude and longitude back into readable addresses. Each standard operation costs $0.001 USDC, handled through the x402 protocol on Base mainnet. No subscription is needed. No traditional API key is needed.

    
The geocoding API returns structured JSON for easy integration into applications, scripts, and autonomous agents.


    
Forward Geocoding API

    
Convert an address or place name to latitude and longitude coordinates. Pass a location string as the q parameter and receive coordinates in the response.

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

{
  "lat": 38.8976763,
  "lon": -77.0365298,
  "display_name": "1600 Pennsylvania Ave NW, Washington, DC 20500, USA"
}

    
See the full forward geocoding guide and the API documentation for parameters, error codes, and examples.


    
Reverse Geocoding API

    
Convert latitude and longitude coordinates into a human-readable address. Pass lat and lon parameters to resolve coordinates into a street address, city, and country.

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

{
  "address": "New York, NY, USA",
  "place": "New York"
}

    
See the full reverse geocoding guide for use cases and examples.


    
Built for AI Agents

    
This API is designed for autonomous agents and programmatic consumers. No permanent API credential is required. Payment is handled per-request via x402 V2. All responses are structured JSON. Machine-readable documentation is available for automated discovery.

    

    
How x402 Payments Work

    
x402 embeds payments directly into HTTP using the 402 status code. Here is the request flow:

    
    
      
  1. Client requests the geocoding resource without payment.
    2. 
      
  2. Server responds with HTTP 402 and x402 V2 payment requirements in the PAYMENT-REQUIRED header.
    3. 
      
  3. An x402-compatible client signs the USDC transfer authorization and sends it using the PAYMENT-SIGNATURE header.
    4. 
      
  4. Server verifies and settles the payment, then returns the geocoding response with PAYMENT-RESPONSE.
    5. 
    

    
Protocol details: x402Version: 2, network eip155:8453, asset USDC, price $0.001 (1000 base units). See the x402 integration guide for complete client examples.


    
Simple Pay-Per-Call Pricing

    

      
Price
$0.001 USDC

      
Subscription
None

      
API key
None

      
Network
Base mainnet

      
Asset
USDC

      
Protocol
x402 V2

    


    
Geocoding API Use Cases

    
AI travel agents
An agent can translate hotel, venue, or destination names into coordinates for itinerary building.

    
Delivery and logistics software
Convert customer addresses into locations for routing and distance calculations.

    
Lead and CRM enrichment
Turn business or customer address data into geographic coordinates for territory mapping.

    
Real estate applications
Resolve property addresses into map coordinates for listing displays and proximity searches.

    
Location-aware AI workflows
Allow autonomous agents to translate natural-language location references into structured coordinates.

    
Reverse location lookup
Translate GPS coordinates into readable place information for dashboards and reports.


    
Developer Resources

    

      Documentation
      OpenAPI Spec
      llms.txt
      x402 Descriptor
      Forward Geocoding Guide
      Reverse Geocoding Guide
      x402 Integration Guide
    


    


    
Frequently Asked Questions

    

      
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 using USDC on Base mainnet. There is no traditional API key to manage.

      
What blockchain does the API use?
Base mainnet (chain ID 8453). CAIP-2 identifier: eip155:8453. Payments are in USDC.

      
What is x402?
x402 is an open payment protocol that embeds payments directly into HTTP using the 402 status code. It enables per-request micropayments without API keys or subscriptions.

      
Can AI agents use the API?
Yes. The API is designed for autonomous 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 is the payment asset?
USDC (USD Coin), a stablecoin pegged to the US dollar, on Base mainnet.