Build a server that responds to HTTP 402 and accepts x402 stablecoin payments so AI agents can pay per API call without accounts or sessions
domain: docs.cdp.coinbase.com/x402/welcome · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Review the x402 specification and v2 network/asset identification standard at the x402 Foundation (formalized April 2026 under the Linux Foundation); understand the client-server flow: client requests resource, server returns 402 with a payment-details header, client sends a signed payment payload in a standard HTTP header
Configure your server to return a 402 status with a structured JSON body describing the accepted token (e.g., USDC on Base), the amount, and your receiving address or Circle Gateway balance endpoint
On the client side, provision a Coinbase Agentic Wallet (launched February 2026) or a CDP Server Wallet v2 (GA July 2025) so the agent has a funded, key-managed wallet capable of signing and broadcasting stablecoin transactions without exposing raw keys
After the client submits the signed payment payload in the designated request header, verify the on-chain settlement or Circle Gateway receipt before serving the protected resource
Implement idempotency by tying each payment payload to a nonce; reject replays using the nonce even if the underlying transaction confirms twice due to agent retry logic
Test with Circle Gateway's nanopayments endpoint, which supports gas-free USDC transfers as small as $0.000001, making it suitable for high-frequency agent API calls
Known gotchas
x402 v2 changed how networks and assets are identified in the payment header, breaking v1 clients; ensure your server advertises the version it expects and returns a descriptive error to v1 clients rather than silently accepting an unverifiable payload
On-chain settlement finality times differ across supported chains; serving the resource before settlement is confirmed can enable a replay-without-payment attack if your nonce store has not been updated atomically
Circle Gateway balances are not immediately spendable on-chain; factor in the withdrawal latency to a Payout Wallet when designing your revenue reconciliation pipeline
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?