DOCS / X402 V1 + V2
x402, v1 and v2
x402 is HTTP 402 Payment Required, reborn: the server quotes a price, the client signs a USDC authorization, a facilitator settles on-chain. The SDK speaks both protocol versions and picks per-challenge — you never branch on it.
The flow
- Your agent calls an endpoint; the server answers
402with a discovery document: accepted networks, asset, recipient, price. - The SDK checks your grant against the quoted price, then signs an EIP-3009
TransferWithAuthorization— gasless for the payer. - The request retries with the payment header; the server's facilitator settles on-chain and responds
200plus a settlement header with the tx hash.
v1 vs v2 — what the SDK absorbs
| x402 v1 | x402 v2 | |
|---|---|---|
| Price field | maxAmountRequired | amount |
| Network id | "base" | CAIP-2 — "eip155:8453" |
| Payment header | X-PAYMENT (flat payload) | PAYMENT-SIGNATURE (envelope echoing the accepted requirement) |
| Settle header | X-PAYMENT-RESPONSE | PAYMENT-RESPONSE |
Real gateways are mid-migration — TripAdvisor's moved to v2 while others still serve v1 — so a single agent routinely meets both in one session. Selection also skips requirements the client can't sign (non-EVM networks such as solana:…, entries with no parseable amount): an unpayable challenge is a clean PaymentError, receipted as payment-failed, never a crash.
Networks
USDC on Base is the default everywhere on Yeetful; the client also resolves Base Sepolia, Ethereum, Optimism, Arbitrum, and Polygon, plus any eip155:* id a v2 challenge presents. Restrict with allowedNetworks if your agent should only ever pay on specific chains.
Using the primitives directly
The agent wrapper sits on a plain x402 toolkit you can use without grants: createPaymentClient({ wallet }) from yeetful/client for auto-paying fetch, and withPayment() from yeetful/next (or gate()/ the Express middleware) to charge for your own routes — that's how you sell to agents rather than buy.