402tools402 docs
docs · live

x402 protocol

x402 is the open wire protocol for HTTP-native payments in USDC. It was specified by Coinbase in 2025 and contributed to the Linux Foundation in 2026. tools402 is one implementation of x402 — the spec is public, anyone can stand up their own marketplace or facilitator.

#Why x402 is the right protocol layer

Before x402, "pay per API call" required custom integration with each provider (Stripe webhooks, API keys, OAuth, custom JWT, etc.). x402 collapses that to a 3-step HTTP exchange with on-chain settlement :

  1. Client requests resource → server responds 402 Payment Required with a signed price quote
  2. Client sends payment on-chain (USDC transfer, EIP-3009, or spl-transfer depending on chain)
  3. Client retries with the tx hash in X-Payment header → server resolves

No platform account, no API key, no OAuth dance. The wallet is the identity ; the on-chain tx is the receipt. The protocol is symmetric : the same client talks to any x402 server, the same server is callable by any x402 client.

#Invariants tools402 implements

These are spec-mandated and tools402 inherits them as-is. If you read x402.org you'll find the same set.

| Invariant | Detail | |--------------------------|-----------------------------------------------------------------------------------| | 402 with accepts[] | The 402 response body contains an array of payment options (multi-chain support) | | Atomic units | All amounts are integers in token atomic units (USDC has 6 decimals) | | X-Payment is base64url | The retry header is a base64url-encoded JSON, NOT base64 standard | | maxTimeoutSeconds | The quote expires after this many seconds (typically 60 on EVM, 30 on Solana) | | Replay-once | The same tx hash cannot resolve two endpoint calls | | No off-chain refund | Payment is verified on the request, not the response. Dispute via on-chain proof. | | Idempotent retries | Same X-Payment header to same endpoint within the window = same response |

#Schemes supported by tools402

| Scheme | Chain(s) | Mechanism | |--------------------------------|------------------|----------------------------------------------------------------------| | exact | Base, Polygon | Standard ERC-20 transfer() ; tx hash is the receipt | | transfer-with-authorization | Base, Polygon | EIP-3009 off-chain signed authorization ; facilitator broadcasts | | spl-transfer | Solana | SPL token transfer, partial-signed by buyer, facilitator broadcasts |

A single 402 quote returns accepts[] with one entry per supported scheme × chain combination — the client picks one and pays.

#Extensions tools402 adds (not in core spec)

  • Multi-chain auto-routing : a single endpoint declares accepted_chains: ["base", "polygon", "solana"] in /v1/_meta ; the 402 quote returns all matching schemes
  • Cross-chain settlement : if buyer pays on a chain ≠ seller's declared settlement chain, marketplace bridges via Mayan (~30 s–2 min). V1 Mayan-only ; V2 will subsume into CCTP V2 native
  • Facilitator stack : 3 levels per chain (2 external + 1 local-key fallback) — see /reference/facilitators
  • Audit endpoint : every settled tx is queryable at /v1/_audit/<tx_hash> with the facilitator that broadcast it, the seller, the amount, and the timestamp

#Self-hosting an x402 marketplace

Since the protocol is open, you can stand up your own. The Coinbase CDP SDK gives you a starting facilitator, and any HTTPS server can speak the 402-quote-retry dance. The value tools402 adds beyond a self-host is :

  • 9 facilitators × 3 chains with measured failover (uptime engineering)
  • A live catalog at /v1/_meta already populated with 157 first-party endpoints + community sell-side
  • Daily settlement cron + dust threshold logic
  • On-chain audit endpoint + replay protection storage

If you only need a private x402 server (e.g. paying your own internal agents), self-host is fine. If you want discoverability + 99.99 %+ uptime + multi-chain by default, you'd reimplement most of what tools402 already runs.

#Reading the spec