Pay-per-call geospatial API · x402 · USDC on Base Sepolia

Geometry,
sold by the call.

17 small, compute-shaped endpoints for agents. A request gets a 402 with terms, the caller pays in USDC, retries with proof, and gets the answer. No account, no API key, no subscription. A call costs $0.001 to $0.01.

Read the catalog See the 402

paid routes: 17
a call: $0.001–$0.01
EPSG codes: 1,236
free routes: 2

This map is the index behind GET /v1/timezone, drawn directly. 2,398 hexagons at H3 resolution 2, walked up from the 304,906 compacted cells the Worker searches, each coloured by its zone's UTC offset on 2026-08-20. The bright meridian marks solar noon right now.

Testnet. Every route currently settles on Base Sepolia in testnet USDC. Real money arrives with the mainnet cutover; the sandbox stays at sandbox.geoprimitives.dev afterwards.

The whole protocol

Three round trips, recorded live.

Payment terms travel in a response header. Everything below was captured from the live API when this page was built, then decoded.

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 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:84532",
      "amount": "1000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x42b5882F9Fb35bC1014416F1637F351421151cb5",
      "maxTimeoutSeconds": 300
    }
  ]
}

1000 atomic 0x036CbD53842c5426634e7929541eC2318f3dCF7e 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 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:84532"}

{"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.

The ledger

Every route, and what it costs.

Prices are read from /openapi.json at build time, which the Worker generates from the table it charges from. Every figure on this page came from that file, so it matches what the 402 quotes.

Route	What it does	Price
HandshakeProve a client can pay before it spends anything real.
POST `/v1/hello`	Echo a string back. The cheapest way to test your payment client.	$0.001
GeoJSONValidate against RFC 7946, or repair into it.
POST `/v1/geojson/validate`	Check GeoJSON against RFC 7946 and say exactly what is wrong and where.	$0.005
POST `/v1/geojson/repair`	Rewrite broken GeoJSON into RFC 7946 form and log every change.	$0.01
ReprojectionCoordinates between EPSG codes, PROJ-checked.
POST `/v1/transform`	Reproject coordinates or GeoJSON between 1236 EPSG codes.	$0.005
GeometryPolygon operations computed on the WGS 84 ellipsoid.
POST `/v1/geometry/buffer`	Offset a geometry by a distance in metres, corrected for the ellipsoid.	$0.01
POST `/v1/geometry/simplify`	Thin out vertices with Douglas-Peucker, in metres or in degrees.	$0.01
POST `/v1/geometry/union`	Merge two or more polygons into one shape.	$0.01
POST `/v1/geometry/intersect`	Return the area two or more polygons have in common.	$0.01
POST `/v1/geometry/difference`	Subtract later polygons from the first one. Order matters.	$0.01
POST `/v1/geometry/area`	Ellipsoidal area of a polygon in square metres, holes subtracted.	$0.01
POST `/v1/geometry/centroid`	True area centroid of a polygon, weighted correctly at high latitude.	$0.01
POST `/v1/geometry/bbox`	Extent of any geometry as [minLon, minLat, maxLon, maxLat].	$0.01
H3 gridPoints to cells, polygons to cell sets.
POST `/v1/h3/index`	Index positions to their containing H3 cell, at one or more resolutions.	$0.005
POST `/v1/h3/polyfill`	Cover a polygon with the set of H3 cells that tile it.	$0.01
ContainmentMany points against many polygons, the whole matrix.
POST `/v1/pip`	Test many points against many polygons and get the full matrix.	$0.01
LookupA coordinate in, a fact about that place out.
GET `/v1/timezone`	IANA timezone, current UTC offset and DST flag for a coordinate.	$0.005
GET `/v1/us/geographies`	US Census FIPS codes for a coordinate: state, county and congressional district.	$0.01
CatalogFree, always, so an agent can read before it decides to pay.
GET `/`	Service catalog: every route, its price, and what it does.	free
GET `/openapi.json`	This OpenAPI 3.1 document. Free, and generated from the price table.	free

There are two prices across 17 routes. Routes are priced by class: per-position work costs $0.005, and anything that returns a geometry-shaped answer with a megabyte-scale tail costs $0.01. Compute is a rounding error next to the fee to settle one transaction, so pricing each route by its own millisecond count would price noise. /v1/hello costs exactly the settlement fee, because its product is the payment.

How to call it

One URL. The server explains the rest.

From a shell

Ask without paying and read the terms out of the header.

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

From an agent

With @x402/fetch and a wallet holding USDC. The facilitator pays the gas.

import { wrapFetchWithPayment } from "@x402/fetch";

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

Discover

GET / the catalog, free
GET /openapi.json OpenAPI 3.1 with a request, a response and a real answer on every route
MCP server coming; until then the OpenAPI document is the tool definition
Every 402 carries the x402 Bazaar discovery extension, so an agent that has only the URL learns the schema from the refusal

What is under it

Checked against independent references.

Independent references

Reprojection is verified against PROJ 9.5. Area and buffer against GeographicLib. Timezones against IANA's own zone1970.tab. Census codes against the Census Bureau's geocoder on 650 coordinates. The misses are listed by name in the route descriptions, where a buyer reads before paying.

Public-domain data only

The boundaries behind the lookups are US government works and CC0 sources. It costs something: the timezone map dates from 2016, and the four regions that split since then are named in the route. That staleness was the price of the licence, paid deliberately. Every source, on one page.

Caps you can read

Every limit a handler enforces is published on its route as prose and as data; the published number and the enforced number are the same constant read twice. A request that can never be served is refused before it is priced, so there is nothing to sign and nothing to settle.

Geometry,sold by the call.