Pay per request

The pay per request API serves captures that are already attested on Base. Each call is paid on the spot in USDC through x402, an open payment standard built on HTTP status 402. There is no sign up, no API key and no invoice: the caller holds a wallet with USDC on Base, the client library signs a transfer for the quoted price, and the response comes back in the same request. The API is built for software that acts on its own: agents, pipelines, MCP tools. A person can use it too, with the same client.

Base URL

https://data.vangrid.io/api/v1

How a paid call works

The client sends the request without payment.
The server answers 402 Payment Required with a PAYMENT-REQUIRED header: price, asset (USDC), network (Base) and the receiving address.
The client signs a USDC transfer authorization for that amount and repeats the request with a PAYMENT-SIGNATURE header.
The server verifies the signature, returns the data, and the transfer settles on Base. The PAYMENT-RESPONSE header carries the transaction.

x402 client libraries do steps 2 to 4 automatically. The wallet needs USDC only; gas is covered by the settlement service.

Endpoints

Method and path	Price	Returns
`POST /spatial/query`	$0.01	Observations inside an area of interest and time window
`GET /observations/{id}`	$0.005	One observation by its sha256
`GET /provenance/{hash}`	free	Whether a sha256 is an attested capture, and where it is anchored

Prices are quoted by the server on every request and can change. A client library reads the quote and never pays more than the cap you configure.

Observation object

Every paid endpoint returns observations in this shape.

string

The sha256 of the capture, hex. Also the id for GET /observations/{id}.

string

sha256: followed by the observation id.

string

Coarse location as attested: a geohash of six characters, a cell of about 1.2 km by 0.6 km. Nothing finer is served.

string

ISO 8601 UTC time of capture.

object

The Merkle tree that contains this capture and its attestation on Base.

Show Anchor fields

integer

8453, Base.

integer

Tree number in the explorer.

string

Hash of this capture’s leaf in the tree.

string

Merkle root that was attested.

string

EAS attestation uid on Base.

string

Transaction that wrote the attestation.

string

The attestation on base.easscan.org.

string

The tree on explorer.vangrid.io.

Responses contain no wallet addresses, no media and no network wide counts.

Spatial query

POST https://data.vangrid.io/api/v1/spatial/query

object

required

GeoJSON geometry. Point with radius_m, or Polygon whose bounding box is at most 100 km².

number

For a Point: radius in metres, 1 to 5000. Defaults to 500.

string

ISO 8601 start of the time window. Defaults to seven days before to.

string

ISO 8601 end of the time window. Defaults to now.

integer

Maximum observations to return, 1 to 1000. Defaults to 100. Results are ordered newest first.

Example

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

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
  spendControls: { maxAmountPerPayment: "$0.05" },
});

const res = await fetchWithPayment("https://data.vangrid.io/api/v1/spatial/query", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    aoi: { type: "Point", coordinates: [139.7671, 35.6812] },
    radius_m: 1000,
    from: "2026-09-17T00:00:00Z",
    to: "2026-09-24T00:00:00Z",
  }),
});
const { observations } = await res.json();

{
  "window": { "from": "2026-09-17T00:00:00.000Z", "to": "2026-09-24T00:00:00.000Z" },
  "observations": [
    {
      "observation_id": "cf9642dae244a213bc9c0e6d325a84be44fe8fd1f57d9b362c64493769b74a48",
      "provenance_hash": "sha256:cf9642dae244a213bc9c0e6d325a84be44fe8fd1f57d9b362c64493769b74a48",
      "geohash": "xn76e4",
      "captured_at": "2026-09-24T06:31:34.000Z",
      "anchor": {
        "chain_id": 8453,
        "tree_id": 4145,
        "leaf_hash": "0x25b77cf9b580c39dd49561efb23bf6903755df5d02330f10eb09d6f9aa79596e",
        "root": "0x6deec66f4ef88662b3c784782bce696e99dc9ff518363eeefe76c0760d69f221",
        "attest_uid": "0x1b0a4d4221b2721f6386abf40787dc06690ad781e877e64db98db9e49ddbd9df",
        "attest_tx": "0xd41521271ac64fe72db3cf3a667b4cd7e05c47429b46e2d145f3d8ce63e6e706",
        "eas_url": "https://base.easscan.org/attestation/view/0x1b0a4d4221b2721f6386abf40787dc06690ad781e877e64db98db9e49ddbd9df",
        "viewer_url": "https://explorer.vangrid.io/tree/4145"
      }
    }
  ]
}

An empty area returns 200 with an empty observations array.

Observation by id

GET https://data.vangrid.io/api/v1/observations/{id}

id is the sha256 of the capture, with or without the 0x prefix. Returns one observation object, or 404 when no attested capture has this id.

Provenance check

GET https://data.vangrid.io/api/v1/provenance/{hash}

Free. Answers whether a sha256 is a capture attested by Vangrid on Base.

curl https://data.vangrid.io/api/v1/provenance/cf9642dae244a213bc9c0e6d325a84be44fe8fd1f57d9b362c64493769b74a48

{
  "provenance_hash": "sha256:cf9642dae244a213bc9c0e6d325a84be44fe8fd1f57d9b362c64493769b74a48",
  "verified": true,
  "captured_at": "2026-09-24T06:31:34.000Z",
  "geohash": "xn76e4",
  "anchor": { "chain_id": 8453, "tree_id": 4145, "attest_uid": "0x1b0a…d9df", "attest_tx": "0xd415…e706" }
}

An unknown hash returns 200 with "verified": false. To check independently, open anchor.eas_url: the attestation is written by Vangrid’s attester and references the tree at viewer_url, where the leaf and its Merkle path are listed.

Use it from an agent

The endpoints declare x402 discovery metadata, so agent frameworks that browse the x402 catalogue find them without configuration. For Claude, Cursor and other MCP clients, Vangrid ships an MCP server that exposes the three calls as tools and pays from the agent’s own wallet, with a per call spending cap:

{
  "mcpServers": {
    "vangrid": {
      "command": "node",
      "args": ["/path/to/vangrid-mcp/src/index.js"],
      "env": {
        "VANGRID_API_URL": "https://data.vangrid.io",
        "X402_NETWORK": "eip155:8453",
        "EVM_PRIVATE_KEY": "0x...",
        "MAX_USD_PER_CALL": "0.05"
      }
    }
  }
}

Tools: vangrid_coverage_query, vangrid_observation, vangrid_verify_provenance. Without a key the server runs in read only mode and the free tool still works.

Errors

Status	Error code	Description
`400`	`invalid_geometry`	`aoi` is not a supported GeoJSON geometry
`400`	`aoi_too_large`	Bounding box of the polygon exceeds 100 km²
`400`	`invalid_request`	A date, limit or id is malformed
`402`	`payment_required`	No payment, or the payment could not be verified
`404`	`not_found`	No attested capture with this id

Need a place captured that is not in the index yet? Bounties for agents lets software commission a capture the same way: pay the bounty in USDC, a person films it, accept the result. The Enterprise Spatial API covers commissioned capture, ingestion, streaming and region scoped access under an agreement. Pay per request is the open door: the same anchored data, one call at a time.

Start

Contribute

For agents

Protocol

Concepts

Data

Use cases

Legal

Pay per request

Base URL

How a paid call works

Endpoints

Observation object

Spatial query

Example

Observation by id

Provenance check

Use it from an agent

Errors

​Base URL

​How a paid call works

​Endpoints

​Observation object

​Spatial query

​Example

​Observation by id

​Provenance check

​Use it from an agent

​Errors

​Related

Base URL

How a paid call works

Endpoints

Observation object

Spatial query

Example

Observation by id

Provenance check

Use it from an agent

Errors

Related