Geospatial primitives your agent can pay for

What this is

GeoPrimitives answers geospatial questions one request at a time. Reproject a coordinate between EPSG codes, repair a GeoJSON file into RFC 7946, buffer a polygon on the ellipsoid, ask which timezone or which US county a point falls in, ask how high the ground is or what a NOAA chart says about the water. The caller needs the URL and a wallet holding USDC. There is no account to create and no API key to hold. The billing relationship is the request: a priced route answers an unpaid call with 402 and its terms, and the retry carrying a signed USDC authorization gets served.

What makes an answer worth buying is where it was checked. This domain fails quietly. proj4 answers a coordinate outside a projection's valid domain with Infinity sitting in an otherwise ordinary array. h3-js takes a latitude of 950 degrees and hands back a valid cell index for a place somewhere else on Earth. So every route here is measured against a reference somebody else built. Reprojection is compared with PROJ 9.5.1 through pyproj across 7881 cases, three points inside the area of use for each of 1380 EPSG codes, and the largest disagreement is 1.01e-8 m. Elevation is compared with gdallocationinfo reading the same USGS blocks and agrees to 6.12e-4 m on the bilinear default. The marine routes are compared with GDAL reading the untouched S-57 exchange sets: at 1,260 charted positions the depth range, the zone of confidence and the nearest charted sounding all matched 1,260 times out of 1,260.

Where a route is wrong, it says so before you pay. The timezone index was checked against all 312 principal locations in IANA's zone1970.tab and answers 293 of them with the identifier IANA gives. Of the 19 left, 7 are Antarctic stations the source map does not cover, 7 name a different zone whose clock is identical every day of the year, and 4 are regions that split after the map was drawn in 2016. Those 4 are named in the route description a buyer reads before paying. The US geography lookup was checked against the Census Bureau's geocoder on 650 coordinates, 250 of them drawn within 1500 m of a county line to put a floor under the claim, and it carries a boundaryUncertain flag per tier. Across all 650 it never returned a wrong code with that flag clear.

The data underneath is public domain and only public domain: USGS 3DEP elevation, Census TIGER boundaries, NOAA electronic navigational charts, and efele.net's CC0 tz_world for the timezone map. The last of those cost something real. The current, accurate timezone dataset is ODbL, and reindexing its polygons into an H3 grid is a reshaping that triggers share-alike, so this API took the eight-year-old CC0 map instead and publishes what the age costs.

One call, from request to answer

The three steps below were recorded from the live API while this page was built. The first request carries no credentials at all. The second is what came back to it, a 402 with an empty body and the terms in a header. The third is the same request sent again with a signature on it, and it gets the answer.

You can watch step three happen instead of reading it. Open the worked example and GeoPrimitives buys one call for you, from a wallet it funds itself, and hands back the answer with the transaction hash. Open the hash on the block explorer; the money moved. To check the terms without involving us at all, send the same request yourself and read the 402 that comes back.

1. 1 Ask

   POST https://api.geoprimitives.dev/v1/hello
   content-type: application/json
   
   {"name":"world"}

   The request carries no credentials. Anyone can send it.

2. 2 402 Payment Required

   HTTP/2 402
   content-type: application/json
   payment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXlt…
   
   {}

   The body is {}. The terms are the header, base64 JSON, recorded from the live API when this page was built:

   {
     "x402Version": 2,
     "resource": {
       "url": "https://api.geoprimitives.dev/v1/hello",
       "mimeType": "application/json"
     },
     "accepts": [
       {
         "scheme": "exact",
         "network": "eip155:8453",
         "amount": "1000",
         "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
         "payTo": "0x76A51b5Dd3729950B3b60c17f19252d221968FCe",
         "maxTimeoutSeconds": 300
       }
     ]
   }

   1000 atomic 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 is $0.001. The 402 and the catalog are generated from one price table, and this build checked that they agree. Omitted above for length: resource.description, which is the same prose the docs carry, and extensions.bazaar, the Bazaar discovery block that tells an agent what to send.

3. 3 Pay, retry, served

   POST https://api.geoprimitives.dev/v1/hello
   payment-signature: <EIP-3009 transferWithAuthorization, signed>
   
   HTTP/2 200
   payment-response: {"success":true,"transaction":"0x…","network":"eip155:8453"}
   
   {"hello":"world", …}

   The facilitator submits the transaction, so the buyer holds USDC and needs no gas. Each authorization nonce is single-use at the token contract, so a replayed signature is rejected there. First settlement on this route, read off the chain: 0xf9e26c83…0199c0.

Reading the terms costs nothing, so the first step is a plain curl:

curl -X POST https://api.geoprimitives.dev/v1/hello \
  -H 'content-type: application/json' \
  -d '{"name":"world"}' -i

An agent holding only the URL can learn the rest from the refusal. Every 402 carries the x402 Bazaar discovery extension, which names the method, the fields the route requires and their types, so a client can build a valid request straight from the header. A request that could never be served is turned away before any of that. Over the size cap, unparseable, a Content-Type that cannot carry JSON, or missing a required top-level field is answered 400 with a machine-readable code and no terms at all, so there is nothing to sign. Checks that have to read a coordinate run after payment, and settlement happens only on a 2xx.

Every endpoint, and what it costs

Two prices cover the whole table, and the class of the answer picks which one applies. A route that does per-position work and returns a bounded answer sits in the lower tier. A route that can hand back a geometry with a megabyte-scale tail sits in the higher one. Millisecond counts stay out of it: the most expensive 200 ms this API can spend costs around 0.4% of the fee charged to settle a single onchain transaction, so a price set from a stopwatch would be a price set on noise. The handshake route at the top of the table is the one deliberate exception, priced at the settlement fee, because what it sells is the payment. An agent buys it to find out whether its client can discover terms, sign and be served.

Prices, request schemas, limits and a real answer for every route are in the reference, which is rendered from /openapi.json.

From your own code

An x402 client library runs the whole exchange for you. It sends the request, reads the terms out of the 402, signs an authorization for the amount quoted there and sends the request a second time, so the call site reads like ordinary HTTP with a wallet attached. Both clients below need a funded key and a URL.

fetch

The client this project's own buyer and MCP server use.

npm install @x402/fetch @x402/core @x402/evm viem

import { privateKeyToAccount } from "viem/accounts";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";

const client = new x402Client();
registerExactEvmScheme(client, {
  signer: privateKeyToAccount(process.env.BUYER_PRIVATE_KEY),
});

const fetchPaid = wrapFetchWithPayment(fetch, client);

const res = await fetchPaid(
  "https://api.geoprimitives.dev/v1/timezone?lat=40.7128&lon=-74.006",
);
const { timezone, utcOffset, isDST } = await res.json();

axios

The same exchange as an interceptor, for a codebase already built on axios.

npm install @x402/axios @x402/evm axios viem

import axios from "axios";
import { privateKeyToAccount } from "viem/accounts";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapAxiosWithPaymentFromConfig } from "@x402/axios";

const account = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY);

const api = wrapAxiosWithPaymentFromConfig(axios.create(), {
  // eip155:* registers the signer for every EVM chain, so one client works
  // against the mainnet API and against the testnet sandbox.
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(account) }],
});

const { data } = await api.get("https://api.geoprimitives.dev/v1/timezone", {
  params: { lat: 40.7128, lon: -74.006 },
});

Both clients hand back the response to the retry, with the settlement riding on a PAYMENT-RESPONSE header. Read that header's success field, because a settlement that failed sends the header too, carrying false and a reason. If a process needs a spending ceiling, the place to check it is between reading the 402 and signing, where the quote is already known and no authorization exists yet. The MCP server below does exactly that.

As MCP tools

The MCP server runs on the same machine as the agent, because the buyer signs the authorization and so the process making the call has to hold the key. A hosted server would have to hold every caller's key, or else rely on an MCP client that can carry a payment through tools/call, which the mainstream clients cannot do today. So mcp/server.ts is a stdio server started with a wallet key and a base URL. It reads /openapi.json from that URL at startup and builds one tool per operation, so the tool list, the schemas, the descriptions and the prices all come from the server that will charge for them. Pointing it at the testnet sandbox instead of the production host changes the URL and leaves everything else alone.

{
  "mcpServers": {
    "geoprimitives": {
      "command": "node",
      "args": ["/path/to/geoprimitives/mcp/server.ts"],
      "env": {
        "GEOPRIMITIVES_URL": "https://api.geoprimitives.dev",
        "BUYER_PRIVATE_KEY": "0x…",
        "GEOPRIMITIVES_BUDGET_USD": "1"
      }
    }
  }
}

GEOPRIMITIVES_BUDGET_USD is the most the process may spend in total, checked against the quote in the 402 before anything is signed. Without BUYER_PRIVATE_KEY the paid tools return the terms and stop, so the server still reads the catalog.

A paid tool result carries the answer, the settlement for that call and the running total for the session, so an agent can account for what it has spent. The path was driven from a real MCP client against the testnet sandbox before any of this was written: the paid timezone call moved the receiving balance by exactly the amount its 402 quoted, the same call with a parameter missing came back refused with no terms issued, and a session opened with a budget below the quote stopped before signing.

Where to go next

Both free routes answer without a wallet, so the cheapest way to start is to read the catalog and send the curl above. The terms come back in a header and cost nothing to look at.