x402 payment flow
HTTP-native · stablecoin · human or agent client · no account-for-access required
Client layer
App or AI agent
Requests a paid resource
Payment wallet
USDC on supported network (e.g. Base)
Retry with proof
Attaches payment credentials after 402
HTTP + x402 protocol
GET /resource
First request unpaid
402 Payment Required
PAYMENT-REQUIRED instructions in headers
Paid retry
Server verifies, then serves payload
Settlement infrastructure
Seller API / middleware
Declares price, network, asset
Facilitator
Verify + settle (CDP or self-hosted / alt)
L2 settlement
Low fees make micropayments viable
What x402 is
x402 is an open payment standard that revives the HTTP 402 Payment Requiredstatus code for internet-native payments. Instead of accounts, API keys, and card rails for every call, a server can say "pay this amount in stablecoin on this network," a client (human app or agent) pays, retries, and receives the resource. Coinbase and the broader ecosystem publish the protocol and facilitator patterns; the interesting part for operators is SOTA setup - reliable, observable, and OpSec-clean.
- Seller: monetize an API or content without inventing a billing stack.
- Buyer / agent: pay-per-call for data, inference, or automation with a hot wallet policy.
- Network: L2s (commonly Base + USDC) keep fees low enough for true micropayments.
SOTA architecture (what "good" looks like)
| Layer | SOTA choice | Why |
|---|---|---|
| Protocol | x402 open standard | HTTP-native; works for agents and scripts |
| Asset / chain | USDC on a low-fee L2 (e.g. Base) | Predictable unit of account; cheap retries |
| Facilitator | Managed (e.g. CDP) for prod; public testnet for labs | Verification + settlement without DIY consensus edge cases |
| Seller keys | Dedicated receive address; no shared treasury hot wallet | Blast-radius control |
| Buyer / agent keys | Spend-capped wallet; daily limits; separate from custody | Compromise does not drain main capital |
| Identity of operators | YubiKey on admin SSH / deploy / cloud console | Humans stay phishing-resistant while machines pay |
| Observability | Structured logs for 402 / pay / 200; on-chain receipts | Dispute, debug, and incident response |
01
Lab
Testnet facilitator
02
Seller
402 middleware
03
Buyer
Pay + retry client
04
Prod
Limits + OpSec
Setup Tutorial
01 - Clarify roles
- Resource server (seller): owns the endpoint and pricing.
- Client (buyer): browser, backend job, or AI agent that can sign payments.
- Facilitator: verifies payment payloads and helps settle (or you use a documented alternative).
Do not mix the seller treasury, the agent spend wallet, and personal custody on one seed. Treat x402 balances as operational float.
02 - Lab environment
- Use the public / test facilitator only for experiments (confirm current network support in official docs).
- Fund a disposable test wallet with test USDC on the documented test network.
- Run seller and client on localhost first; bind to loopback until you intentionally expose the API.
# Example shape only - check current x402 / CDP docs for exact packages
# Seller: Node or Python HTTP service with x402 payment middleware
# Client: HTTP client that handles 402 + payment header retry03 - Seller: payment-gated endpoint
- Declare path, price, asset, and network in middleware config.
- Return
402with machine-readable payment requirements when unpaid. - On valid payment, serve the payload (JSON, binary, stream).
- Keep pricing idempotent per resource where possible; log correlation IDs.
// Conceptual middleware config (pseudo)
// GET /v1/signal -> requires USDC amount N on chosen network
// unpaid -> 402 + PAYMENT-REQUIRED
// paid -> 200 + body04 - Buyer: pay-and-retry client
- On
402, parse payment requirements. - Construct and authorize the stablecoin payment via the scheme the server accepts.
- Retry the original request with the payment proof / headers the protocol expects.
- Agents: enforce max spend per call and per day in code - not only in your head.
# Conceptual client loop
# 1) GET resource
# 2) if status == 402: pay(requirements) -> retry with proof
# 3) else: handle body / error05 - Production facilitator & network choice
- Production typically uses a managed facilitator (e.g. Coinbase Developer Platform x402) with credentials and supported networks.
- Confirm gas / fee sponsorship assumptions in current docs - do not market "free forever" without reading the fine print.
- Pin versions of SDKs; record which chain and USDC contract you accept.
06 - OpSec hardening (SOTA)
- YubiKey: protect human admin paths (SSH, cloud IAM, GitHub, deploy CI) with hardware 2FA / FIDO2.
- Agent wallet: dedicated key; hard spend caps; no seed on the same disk as long-term cold storage.
- Seller receive: dedicated address or smart-account policy; sweep to cold / multisig on a schedule.
- Facilitator trust: treat facilitator outages and policy changes as production dependencies; have a kill switch.
- Network: TLS everywhere; no mixed-content clients; verify you are not logging payment secrets.
- Institutional ceiling: if you custody customer funds at scale under regulation, evaluate banking-grade stacks (e.g. Taurus) rather than hot-wallet DIY - that is a different product class.
07 - Observability & verification
- Metrics: 402 rate, paid success rate, average settlement latency, failed payments by reason.
- Store tx hashes / facilitator receipts for reconciling revenue.
- Alert on spend spikes from agent wallets.
Verification checklist
- Unpaid request always returns 402 with parseable requirements
- Paid retry returns 200 and the correct body
- Replay of an old payment proof does not double-serve incorrectly (per your scheme rules)
- Agent wallet cannot exceed configured daily cap
- Admin access requires YubiKey (or equivalent hardware-backed factor)
- No production secrets in client-side bundles
- Runbook exists for facilitator downtime and chain congestion
Official references to keep open while building: x402.org · CDP x402 docs. Always re-check network support and facilitator endpoints before mainnet.