## 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 response with a `Payment-Required` header containing structured payment instructions. The agent (or its wallet) inspects the header, decides whether the price is acceptable, pays on-chain, attaches the receipt to a retry, and receives the response.

Conceptually, x402 finally completes the HTTP 402 status code that has sat unused in the HTTP spec since 1996 — the spec reserved the code for "Payment Required" but never specified *how* a client should pay. x402 specifies the mechanism: USDC on Base, signed payment intents, facilitator-mediated settlement, and a discovery format so agents can find paid endpoints before calling them.

## Why x402 matters

Traditional API monetization is built for humans: sign up, generate an API key, manage a credit card on file, get a monthly invoice. Every step requires a UI, an account, and an out-of-band relationship between the API provider and the developer.

Autonomous agents don't have those things. An agent calling a paid API for the first time needs to:

- Discover the price *before* committing
- Pay programmatically, without human approval
- Settle the transaction in seconds, not days
- Receive a receipt the API provider can verify

x402 addresses all four with a single mechanism. The price is in the 402 header. The payment is a signed transaction on Base. Settlement is sub-second. The receipt is the on-chain confirmation.

This makes x402 the foundational payment primitive for the agentic web — analogous to what TLS was for the commercial web, or OAuth for delegated authorization: a protocol that turns something previously human-mediated into something machines can negotiate end-to-end.

## How it works

1. Agent sends a request to a paid endpoint
2. Server returns **HTTP 402** with a base64-encoded `Payment-Required` header
3. The header contains: amount, asset (USDC), network (Base), recipient wallet, and facilitator
4. Agent pays via the facilitator (e.g., Coinbase)
5. Agent retries the request with a `Payment` header containing the receipt
6. Server verifies the payment through the facilitator and serves the response

The whole flow takes a few seconds end-to-end. No API keys. No subscriptions. No human in the loop.

## x402 vs traditional API monetization

| Aspect | API keys + subscription | x402 |
|---|---|---|
| Signup | Account creation required | None |
| Authentication | Per-account API key | Per-request payment |
| Billing model | Monthly subscription | Pay-per-request |
| Discovery | Out-of-band (docs, sales) | In-protocol (402 header) |
| Settlement | Invoice cycle (~30 days) | Sub-second (on-chain) |
| Failure mode | Quota exceeded → 429 | Payment insufficient → 402 |
| Agent compatibility | Hard (account management) | Native |
| Geographic limits | Common (Stripe restrictions) | Minimal (on-chain) |

The key shift: x402 puts pricing into the protocol itself, where any agent can read it. With API keys, the price exists only in a contract negotiated between humans. With x402, the price is in the HTTP response, the same way the status code is — first-class transport metadata, not paperwork.

## Key concepts

- **Facilitator**: A service that verifies and settles payments. Set `"facilitator": "coinbase"` in your x402.json to use Coinbase's facilitator on Base mainnet. Other facilitators can support different networks and assets.
- **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 USDC contract on Base is `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`. Multi-network support is on the roadmap.
- **Per-request pricing**: Each API call has its own price — no subscriptions, no tiered plans, no API keys.
- **Discoverable services**: Mark services with `"discoverable": true` to appear in the [x402 Bazaar](/kb/bazaar) — a catalog of paid endpoints that agents browse to find capabilities.

## Who's using x402

The x402 ecosystem has formed around two anchors:

- **Coinbase Developer Platform** — the protocol originator. Ships official SDKs in TypeScript, Go, and Python; runs the canonical facilitator on Base mainnet.
- **Tempo [MPP](/kb/mpp)** — the Paradigm and Stripe-backed payment proxy. Tempo runs `*.mpp.tempo.xyz` proxies that translate between x402 and traditional payment rails for sites that haven't natively implemented x402.

Beyond those anchors, individual API providers, agent runtimes, and [MCP](/kb/mcp) server operators are integrating x402 for per-call billing — paid MCP tools, metered data APIs, AI inference endpoints, and agent marketplaces. agentgrade's x402 Bazaar discovery catalogs paid endpoints across the agentic web as they go live.

## How to add x402 to your service

### 1. Install the SDK

```bash
npm install @coinbase/x402-express
```

### 2. Add middleware to your Express app

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

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

### 3. Publish discovery file

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

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

### 4. Test the flow

```bash
curl -i https://your-domain.com/api/paid-endpoint
# Expect: HTTP/1.1 402 Payment Required
# Expect: Payment-Required: <base64-encoded payment instructions>
```

Decode the `Payment-Required` header (base64 → JSON) and confirm amount, asset, recipient, and facilitator match your middleware configuration.

## Common errors and debugging

- **402 with no Payment-Required header**: Middleware not configured. Confirm `payTo` and `amount` are set on the middleware call.
- **Payment header rejected**: Receipt is for the wrong amount, wrong asset, or expired. Most facilitators reject receipts older than a few minutes.
- **Wallet address mismatch**: `payTo` in middleware doesn't match the receipt's recipient. Must match exactly.
- **Network mismatch**: Receipt is on a different chain than declared. Confirm `network` is `base` in both middleware and x402.json.
- **Facilitator unreachable**: The facilitator service is down. Use a fallback facilitator or fail open during outages.

agentgrade's scanner probes these directly — its x402 check verifies live 402 responses parse cleanly and that the discovery file matches what endpoints actually return.

## Frequently asked questions

### Is x402 a blockchain protocol or an HTTP protocol?

Both. The transport is HTTP (a 402 status with structured headers). The settlement is on-chain (USDC on Base). x402 is the bridge — the protocol that lets HTTP servers and HTTP clients negotiate a payment that gets settled by a blockchain.

### Do I need a crypto wallet to accept x402 payments?

Yes. You need a Base wallet to receive USDC. Coinbase's CDP makes this manageable for non-crypto-native teams — you can provision a custodied wallet via API and never touch keys yourself.

### What's the difference between x402 and Stripe?

Stripe is the dominant traditional rail: per-account API keys, monthly subscriptions, fraud detection trained on human buyers. x402 is per-request, agent-native, and settles on-chain. They're complementary — Stripe for human checkout, x402 for agent metered access. Tempo MPP bridges between them for sites that want both.

### Is x402 production-ready?

Yes. x402 v2 is supported by Coinbase with official SDKs in TypeScript, Go, and Python. The canonical facilitator runs in production and the ecosystem of paid services is growing.

### Can agents pay each other with x402, not just API providers?

Yes. x402 doesn't care whether the "server" is a human-run API, an agent, or an MCP tool. Any HTTP responder can return a 402 and any HTTP requester can pay. Agent-to-agent metered work is one of the most active use cases.

### Why USDC and not ETH?

Stable. Predictable price. Most API providers price in dollars and want a dollar-stable asset for settlement; volatile assets create accounting friction that defeats the per-request model.

### What happens if the agent doesn't have funds?

The wallet returns insufficient-funds and the call fails. There's no retry-buy-credits flow in the protocol itself — funding is the wallet's concern, not the API's.

### How discoverable are x402 endpoints?

Endpoints marked `"discoverable": true` in your x402.json appear in the x402 Bazaar — the public catalog of paid services. Agents browse the Bazaar the way developers browse npm. agentgrade's scanner walks the Bazaar to surface paid endpoints across the agentic web.

## Spec maturity

**Production-ready.** x402 v2 is the current envelope, supported by Coinbase with official SDKs in TypeScript, Go, and Python. The protocol is stable, the canonical facilitator runs in production, and the ecosystem is expanding across MCP tool providers, data APIs, and agent marketplaces.

## Learn more

- [x402.org](https://www.x402.org/) — Protocol specification and whitepaper
- [Coinbase x402 docs](https://docs.cdp.coinbase.com/x402/docs/welcome) — SDK and integration guide
- [x402 npm package](https://www.npmjs.com/package/@coinbase/x402-express) — Express middleware
- [Agent Readiness](/agent-readiness) — How x402 fits in the broader agent-readiness landscape

## Related

- [OpenAPI](/kb/openapi)
- [A2A](/kb/a2a)