x402 — HTTP Payment Protocol

What is x402?

x402 turns the HTTP 402 "Payment Required" status code into a real payment protocol. When an agent hits a paid endpoint, the server returns a 402 with a Payment-Required header containing payment instructions. The agent pays on-chain, attaches the receipt, and retries.

How it works

Agent sends a request to a paid endpoint

Server returns HTTP 402 with a base64-encoded Payment-Required header

The header contains: amount, asset (USDC), network (Base), recipient wallet, and facilitator

Agent pays via the facilitator (e.g., Coinbase)

Agent retries the request with a Payment header containing the receipt

Server verifies the payment through the facilitator and serves the response

Key concepts

Facilitator: A service that verifies and settles payments. Set "facilitator": "coinbase" in your x402.json for Coinbase's facilitator on Base mainnet.
Envelope v2: The current header format. Adds structured service catalogs, Bazaar discovery, and richer payment options. Always use v2.
Network: Payments happen on Base (eip155:8453) using USDC. The asset contract is 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.
Per-request pricing: Each API call has its own price — no subscriptions, no API keys.

How to add x402 to your service

1. Install the SDK

npm install @coinbase/x402-express

2. Add middleware to your Express app

import { paymentMiddleware } from '@coinbase/x402-express';

app.use('/api/paid-endpoint', paymentMiddleware({
  payTo: '0xYourWalletAddress',
  amount: '100000', // in smallest unit (0.10 USDC)
  network: 'base',
  facilitator: 'coinbase',
}));

3. Publish discovery file

Serve /.well-known/x402.json so agents can find your paid endpoints:

{
  "x402Version": 2,
  "name": "Your Service",
  "network": "base",
  "facilitator": "coinbase",
  "payTo": "0xYourWalletAddress",
  "services": [{
    "method": "POST",
    "path": "/api/paid-endpoint",
    "amount": "100000",
    "discoverable": true
  }]
}

Spec maturity

Production-ready. x402 v2 launched December 2025. Supported by Coinbase with official SDKs in TypeScript, Go, and Python.

Learn more

x402.org — Protocol specification and whitepaper
Coinbase x402 docs — SDK and integration guide
x402 npm package — Express middleware

agentgrade