What is HTTP 402 Payment Required?

HTTP 402 Payment Required is an HTTP status code reserved in the HTTP specification since 1997 for machine-to-machine payment. For decades it went unused because no open protocol existed for how a client should pay a 402 response. x402 is that protocol. Xenarch implements it for AI agents via signed USDC micropayments on Base L2.

History of HTTP 402

The 402 status code appeared in the HTTP/1.1 working-group drafts in 1997 (RFC 2068) and was carried into the published HTTP/1.1 standard in 1999 (RFC 2616) and later re-described in 2014 (RFC 7231 §6.5.2). The specification marked the code as "reserved for future use," with the intended semantics of indicating that payment is required to proceed.

It went unused for almost three decades because digital-cash systems (Digicash, Millicent, early Bitcoin) never reached the adoption needed to become an open HTTP-native payment protocol. Client software didn't know how to respond to a 402. Servers had no canonical format for the payment challenge. So 402 stayed reserved — everyone knew it existed, nobody could ship it.

402 Payment Required vs related status codes

402 is the only HTTP status code that encodes a commercial relationship rather than an identity, permission, or rate-limiting one. It tells the client: "I will serve you — on payment."

How x402 uses HTTP 402

x402 is the open protocol that finally activates the 1997 reservation. It was originated by the Coinbase Developer Platform team and works as follows:

1. Client sends GET /resource
2. Server returns 402 Payment Required with headers:
     X-Payment: {price, receiver, network, asset, nonce, …}
3. Client signs a USDC transfer authorization (EIP-712)
4. Client retries GET /resource with X-Payment-Proof: <signed>
5. Server verifies the signature, settles on-chain, returns 200

Because the payment is a signed stablecoin transfer, any server that speaks USDC on a supported chain can verify it without trusting a middleman. Settlement is on-chain. No API keys, no subscriptions, no invoicing.

How to return HTTP 402 from your API

FastAPI (Python):

from fastapi import FastAPI
from xenarch import require_payment

app = FastAPI()

@app.get("/premium/article")
@require_payment(price_usd="0.003")
async def article():
    return {"content": "…"}

Express (Node.js):

import express from 'express';
import { requirePayment } from '@xenarch/express';

const app = express();
app.get('/premium/article', requirePayment({ priceUsd: '0.003' }), (req, res) => {
  res.json({ content: '…' });
});

Both set the 402 status, emit the X-Payment challenge header, and — after the client retries with a signed payment — verify and serve the resource.

How AI agents pay an HTTP 402 (with Xenarch)

An AI agent — Claude, Cursor, LangChain, CrewAI, or any Model Context Protocol client — installs the Xenarch MCP server and handles the handshake automatically:

claude mcp add xenarch -- npx @xenarch/agent-mcp

When the agent hits an x402-gated URL, the Xenarch MCP reads the 402 challenge, signs a USDC micropayment (up to $1 per call) on Base L2 via the immutable Xenarch splitter contract, and retries the request with proof of payment. Publishers get paid directly on-chain — no platform holds the funds. 0% fee today, hard-capped at 0.99% on-chain forever.

HTTP 402 FAQ

HTTP 402 Payment Required is an HTTP status code reserved in the HTTP/1.1 specification since 1997 (RFC 2068 → RFC 2616 → RFC 7231) for machine-to-machine payment. For decades it was unused because no open protocol standardized how a client should actually pay a 402 response. x402 is that protocol — a signed USDC micropayment on Base L2 any server can verify.

The HTTP spec reserved 402 in 1997 specifically for digital-cash and micropayment systems. The intent was always payment — but no payment protocol reached standardization, so the code sat unused until x402.

Return a 402 status with an X-Payment challenge header describing price, receiver, network, and asset. Python/FastAPI publishers use Xenarch's @require_payment decorator; Express and Cloudflare Worker adapters are also available.

Install the Xenarch MCP server. When the agent's HTTP client gets a 402 with an x402 challenge, the MCP signs a USDC payment on Base L2 via the Xenarch splitter contract and retries the request with proof. Fully automatic — no keys, no human approval.

403 Forbidden is a policy denial — the server understood the request but refuses it. No remediation path. 402 Payment Required is a commercial signal — the server will serve the request if you pay. Remediation: pay, then retry.

401 Unauthorized is about authentication — proving who you are. 402 is about payment — proving you've paid. In x402, the signed payment can be both — the signing wallet is the identity, and the payment covers the resource in one step.

claude mcp add xenarch -- npx @xenarch/agent-mcp