AgentGrade
EnglishEspañol日本語中文
← Knowledge Base

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 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:

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

AspectAPI keys + subscriptionx402
SignupAccount creation requiredNone
AuthenticationPer-account API keyPer-request payment
Billing modelMonthly subscriptionPay-per-request
DiscoveryOut-of-band (docs, sales)In-protocol (402 header)
SettlementInvoice cycle (~30 days)Sub-second (on-chain)
Failure modeQuota exceeded → 429Payment insufficient → 402
Agent compatibilityHard (account management)Native
Geographic limitsCommon (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

Who's using x402

The x402 ecosystem has formed around two anchors:

Beyond those anchors, individual API providers, agent runtimes, and 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

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', // 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:

{
  "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

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

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

Related

Related: What is AI agent readiness?