Prepaid credit & sessions
Prepaid is how sub-cent, machine-speed pricing works: one on-chain payment funds a balance, then every call draws against it instantly — no blockchain round-trip, no new 402, sub-second responses.
Funding a balance
Section titled “Funding a balance”When an endpoint offers a bundle, pass, or tier (or auto-bundles a sub-$1 per-call price), the bare 402 quotes that pack. Pay it like any x402 payment (Paying for a call) and the funding response:
- delivers your first call’s data (the payment wasn’t a separate “top-up step” — you’re already being served),
- issues an access token in the
x-superspice-accessresponse header (and as a cookie), and - carries your opening balance in the response headers.
When the pack was auto-synthesized from a sub-$1 per-call price, the 402 carries a
superspice/session extension spelling out exactly what the payment funds — e.g.
“100 calls at the advertised per-call rate” — and which header returns your token.
Nothing about the bundle is a surprise.
Drawing against it
Section titled “Drawing against it”Re-send the token on each subsequent request:
x-superspice-access: <token from the funding response>Each call draws your balance off-chain and responds immediately. Every response tells you where you stand:
| Header | Meaning |
|---|---|
X-Superspice-Balance |
Remaining balance, in USDC |
X-Superspice-Calls-Remaining |
Calls left at the current per-call price |
X-Superspice-Low-Balance |
true when you’re near empty |
X-Superspice-Topup |
Where/how to top up when the flag is on |
Running out (and other edges)
Section titled “Running out (and other edges)”- Balance exhausted — the next request gets a fresh 402 quoting a re-fund. Pay it and continue; your token keeps working.
- Lost the token — sign a normal per-call payment with the same wallet: the gateway recognizes your funded balance, serves the call from it (the signed call is drawn from your balance, not settled on-chain), and issues a fresh token.
- Failed calls — a draw whose delivery fails is automatically re-credited. You never pay for a failed call, prepaid or not.
- Stock clients — even a client that ignores the token entirely still works: signed per-call payments from a funded wallet draw the balance off-chain instead of paying on-chain each time.
Why this model
Section titled “Why this model”Approval friction is the practical ceiling on agent payments — a wallet signature per sub-cent call wastes most of its time on ceremony. One settle plus off-chain draws keeps the cryptographic payment guarantee where it matters (funding) and makes the per-call hot path pure speed. It’s the model the x402 ecosystem is converging on; Superspice ships it today.