The 402 response

An unpaid request to any Superspice endpoint returns HTTP 402 Payment Required. The JSON body is empty ({}) — the terms travel in the payment-required response header as base64-encoded JSON (x402 version 2).

A real example

This is the decoded payment-required header from the live demo endpoint (https://gw.superspice.xyz/g/superspice-demo/api/data/price-feed — curl it yourself):

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://gw.superspice.xyz/g/superspice-demo/api/data/price-feed",
    "description": "BTC-USD spot price (demo)",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "1029973",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x18263d6158C775d795E8F0C60A999A0cD1612a22",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "extensions": {
    "superspice/session": {
      "tokenHeader": "x-superspice-access",
      "includedCalls": 100,
      "note": "paying this quote funds 100 calls at the advertised per-call rate; …"
    }
  }
}

Fields

Field	Meaning
x402Version	Always 2.
resource	What you’re buying: the URL, the seller’s description, and the response mimeType.
accepts[]	The payable option(s). Superspice quotes one option per 402.
accepts[].scheme	exact — a signed USDC authorization for the exact amount.
accepts[].network	eip155:8453 — Base mainnet.
accepts[].amount	The total to sign, in USDC base units (6 decimals; 1029973 = $1.029973). Fee-inclusive: sign it, done.
accepts[].asset	The USDC contract on Base.
accepts[].payTo	Where the payment settles — the seller’s on-chain destination.
accepts[].maxTimeoutSeconds	Validity window for the quote.
accepts[].extra	EIP-712 domain hints for the signature (name, version).
extensions	Optional machine-readable notices (below).

Extensions you may see

superspice/session — appears when the quoted payment funds prepaid credit (an explicit pack, or the automatic sub-$1 bundle). It names the token header (x-superspice-access), how many calls the payment includes, and a plain-language note. If you see this, pay once, keep the token, and stop paying per call — details in Prepaid credit & sessions.

When you see a 402

• First contact — the normal case: these are the terms; pay and retry.
• After a payment attempt — the payment didn’t verify or settle (wrong amount, expired quote, bad signature). Read the fresh terms and sign again; Errors lists the cases.
• Balance exhausted — on prepaid endpoints, the re-fund quote. Your session token keeps working after you top up.