Core Concepts
A deliberately brief overview. Each concept gets one paragraph; follow the links for depth.
x402 in 60 seconds
HTTP 402 Payment Required is a status code reserved in the HTTP/1.1 spec but never widely implemented. The x402 protocol revives it: a paywalled endpoint returns 402 with payment parameters in the response body, the client signs an off-chain authorization, and the server verifies and settles it on-chain. Any HTTP client — including an autonomous AI agent — can participate without knowing anything about wallets, chains, or token standards ahead of time.
Why BSC + USDC
BNB Smart Chain offers ~2-second block times, predictable gas costs around $0.01, and native USDC at a well-known contract address. For per-request micropayments, those properties matter more than any single feature of a larger chain — the payment needs to confirm fast enough that a synchronous HTTP handler can wait on it, cheap enough that a 5¢ API call is worth settling, and in a currency the merchant can keep on the books without volatility.
Permit2 off-chain signing
Uniswap’s Permit2 lets users authorize token transfers via EIP-712 signatures without a preceding approve() transaction. The x402 facilitator uses Permit2 so payers sign once, off-chain, and the facilitator handles all on-chain execution (and pays the gas). Zero gas for the payer, zero wallet popups past the first signature, and the authorization is scoped to a single transferFrom — it can’t be replayed.
EIP-7702 gasless approval (optional)
For wallets that haven’t approved Permit2 yet, EIP-7702 lets the payer sign an authorization alongside the payment that temporarily grants the facilitator approval capability. This compresses the first-time-user flow from two transactions (approve + transfer) to one signature. The SDK handles the 7702 authorization format transparently — you only see it if you dig into EIP7702Authorization in the types.
The payment flow
That’s the whole protocol. Everything else — session management, error handling, refunds, dashboards — is built on top.
Where each piece lives in the SDK
| Concept | File | Notes |
|---|---|---|
| Wire-format types | src/x402/types.ts | PaymentDetails, CreateOrderBody, CreateOrderResponse |
| Facilitator HTTP client | src/x402/facilitator.ts | Thin typed wrapper around the facilitator REST API |
| Session lifecycle | src/checkout/session.ts | CheckoutSessionManager + InMemorySessionStore |
| Self-contained payment page | src/checkout/payment-page.ts | HTML/JS that handles wallet + signing in-browser |
| Express routes | src/middleware/express.ts | Mounts /aiot-pay/* in one call |
For a tour of each subsystem, start with the SDK client guide.