# API overview

All responses are JSON: `{ data, meta, attribution }`.

## Payment (x402)

Paid endpoints return HTTP 402 with a `PAYMENT-REQUIRED` header describing the price,
network and recipient. Pay with an x402 client (e.g. `@x402/fetch`) and retry with the
`PAYMENT-SIGNATURE` header. Settlement details come back in `PAYMENT-RESPONSE`.

The unpaid 402 body may include a free `preview`: how many records the call would
return, or an input error to fix before paying (`valid: false`). Check it before paying.

## MCP

`POST /mcp` is a stateless Streamable HTTP MCP server. Each endpoint below is also a tool.
Each client gets 3 free paid-tool calls per day (marked in `meta.free_call`), while a
shared allowance of 25 free calls per tool per day lasts.
After that, paid tools return the x402 payment requirements as an error result; x402-capable
MCP clients (e.g. `@x402/mcp`) pay and retry automatically.

## Datasets

- [Solana validator stats](/docs/solana-validators.md) — base path `/v1/solana-validators`