# Block402 API

> Blockchain intelligence for AI agents.

Query blockchain data through a read-only, pay-per-request API with x402.

## Current Availability

Currently advertised chains: Bitcoin. Only the operations listed in OpenAPI and MCP are
available through these interfaces; planned chains are not advertised as supported.

Payments use USDC on Base mainnet, independently of the blockchain being queried.
Payment network: eip155:8453. Asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.
Recipient: 0x5b5cE945b2Cda4446fC4899496A85dBBEd626c63. Data networks are listed per operation in OpenAPI.

## Discovery

- OpenAPI: https://api.block402.xyz/openapi.json
- Compatibility discovery: https://api.block402.xyz/.well-known/x402
- MCP Streamable HTTP: https://api.block402.xyz/mcp
- MCP registry metadata (not proof of registration): https://api.block402.xyz/mcp/server.json
- Wallet example: https://block402.xyz/example/

Only configured, discoverable methods appear below. No wallets, signing, broadcasting,
administration, arbitrary URLs, notifications, or batch requests are available.

| Chain | Method | Price (USDC) | POST route |
| --- | --- | --- | --- |
| Bitcoin | getblockcount | 0.002500 | /rpc/bitcoin |
| Bitcoin | getbestblockhash | 0.002500 | /rpc/bitcoin |
| Bitcoin | getblockhash | 0.002500 | /rpc/bitcoin |
| Bitcoin | getblockheader | 0.002500 | /rpc/bitcoin |
| Bitcoin | getblock | 0.005000 | /rpc/bitcoin |
| Bitcoin | getrawtransaction | 0.005000 | /rpc/bitcoin |
| Bitcoin | gettxout | 0.005000 | /rpc/bitcoin |

## Ethereum limits and history

Ethereum provides historical blocks, transactions, receipts and bounded logs. Historical
state and proofs depend on retained node data; no archive-state guarantee is made.
Pending, latest, safe, finalized and explicit block selectors are supported where the
method permits. Calls simulate state changes without broadcasting.

Limits: 64 KiB request, 4 MiB response, 10-second upstream timeout; 1000000 simulation
gas and 5-second EVM timeout; 16 KiB calldata; 64 access-list addresses and 256 total
storage keys; 16 authorizations; 64 proof slots; 1024 fee-history blocks and 20 ordered
percentiles; 1000 log-query blocks and 10000 returned logs, 64 filter addresses and four
topic positions with 64 alternatives each. Oversized output is rejected, not truncated.
No tracing, persistent filters, subscriptions, state overrides, blob sidecars or batches.

## Pay and Recover

1. Generate a cryptographically random 32-byte lowercase hex Idempotency-Key.
   Save it durably and privately before any request. It is also a bearer recovery
   credential. Do not put it in URLs, logs, discovery documents, or shared examples.
2. POST the JSON-RPC body with Content-Type: application/json and that key.
3. Read the 402 PAYMENT-REQUIRED header using the official x402 SDK. Check the
   exact resource URL, payment network, USDC asset, recipient, amount and expiry.
   Set per-payment and total spending limits on the client.
4. Only sign a challenge with extensions.block402.info.quote and
   discoveryOnly=false. Echo all extensions unchanged. The quote is bound to
   your request and private key. The server verifies its signature and expiry.
5. Retry the identical method and params with the same key and PAYMENT-SIGNATURE.
   The x402 facilitator settles USDC; RPC nodes never handle payment keys.
6. On 202, timeout, disconnect, or any uncertain outcome, retry WITHOUT a payment
   signature using the SAME key and params. Never automatically create a new
   payment. A 402 during recovery is not permission to sign again after uncertainty.

Use POST /rpc/:chainId exclusively. Method-specific URLs are not supported.
Request IDs may change on retries; the method, params and recovery key may not.
Successful retries return the stored result, not a second charge or fresh query.

Example body for POST /rpc/bitcoin:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getblockcount",
  "params": []
}
```

Empty POST requests, or POST requests with a valid JSON-RPC
body, return discovery metadata when both PAYMENT-SIGNATURE and Idempotency-Key
are absent. These network-level discoveryOnly=true challenges have no bound
quote. Do not sign them. Request a fresh quote with a valid body and private key.
Examples in schemas are illustrative, not current chain data.

200 plus PAYMENT-RESPONSE means settled. Ethereum execution errors return a JSON-RPC error with X-Block402-Payment-Status: not-settled and are not billed. Valid empty/null results are billed. 202 means pending, 409 requires inspecting
the error, and 410 means a settled result expired. Results are retained for
168 hours. Recovery keys and authorization tombstones
are not reset when results expire. Receipts can also be recovered at
GET /receipts/:id with Authorization: Bearer ORIGINAL_IDEMPOTENCY_KEY.

## MCP

Connect an MCP Streamable HTTP client to https://api.block402.xyz/mcp. Initialization,
tools/list and resources/read are free; connecting never signs or pays. Each
enabled method has a tool named CHAINID_METHOD.
For example, bitcoin_getblockcount takes {"params":[],"idempotencyKey":"YOUR_PRIVATE_SAVED_KEY"}.
Use the exact positional params from the HTTP schema. Unknown fields are rejected.

An unpaid tool returns isError=true with the x402 PaymentRequired object in
structuredContent and JSON text. An x402-aware client authorizes that quote and
repeats the tool with the same arguments and params._meta["x402/payment"] carrying
the official PaymentPayload. The quote names the canonical network-level HTTP
resource; MCP is an adapter over the same paid operation, not a second payment.
Successful settlement is in result._meta["x402/payment-response"].
result._meta["block402/http-status"] preserves the payment status (including 202).
Successful result text preserves the original JSON numbers without precision loss.
The official x402 MCP wrapper exposes paymentResponse separately and omits raw
_meta in its convenience return value; inspect its onAfterPayment result or use
the raw MCP client. paymentMade means an attempt, not proof of settlement.

Do not give the server wallet keys. Clients own signing, approval, budgets and
durable recovery storage. Ordinary MCP clients cannot pay without x402 support.
During recovery, use a non-paying MCP call with the same arguments. Do not use
an auto-paying wrapper after an ambiguous payment attempt.