// Last updated 2026-04-30

x402 payment flow

The REST API charges a micropayment per request via the x402 protocol. This page walks through one full request: hit the endpoint without payment, read the challenge, sign a payment, replay.

Step 1 — Hit the endpoint without payment

curl -i https://erc-8004.quicknode.com/v1/agents

You get back HTTP/1.1 402 Payment Required with a JSON body:

{
  "x402Version": 1,
  "error": "Payment required to access this resource",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x...",
      "maxAmountRequired": "1000",
      "resource": "https://erc-8004.quicknode.com/v1/agents",
      "description": "Payment required for /v1/agents",
      "maxTimeoutSeconds": 600,
      "mimeType": "application/json",
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

Key fields:

• network — base is Base mainnet.
• asset — the Base USDC contract address.
• payTo — the wallet address that will receive your payment.
• maxAmountRequired — 1000 means 1000 USDC base units (USDC has 6 decimals → $0.001).
• extra — EIP-712 domain hints (name, version) needed to construct a valid signature.

Step 2 — Sign a payment

Use any x402 client library to build and sign the payload. The reference Python and TypeScript clients are documented at x402.org. The signed payload is a base64-encoded EIP-712 signature authorizing a USDC transfer of maxAmountRequired to payTo.

Step 3 — Replay with the payment header

curl -i \
  -H "X-PAYMENT: <base64-signed-payload>" \
  https://erc-8004.quicknode.com/v1/agents

Server-side, the request is routed through the x402 facilitator for verification and settlement. On success you get HTTP/1.1 200 OK with the JSON response. The settlement transaction hash is returned in the X-PAYMENT-RESPONSE header (base64-encoded).

Settlement modes

The Explorer runs in non-optimistic mode by default: settlement completes before the response is sent, so a 200 is a guarantee that the transaction landed. Latency is ~1–2 seconds on Base.

Errors