x402 Protocol: The Complete Developer Guide

The HTTP 402 status code has been "reserved for future use" since 1999. Twenty-seven years later, that future arrived.

x402 transforms this dormant status code into a payment layer for the web. No OAuth flows. No API keys. No monthly invoices. Payments embedded directly into HTTP request/response cycles.

Why x402 Exists

Traditional payment infrastructure was designed for humans. Credit cards require fraud detection because humans commit fraud. Payment forms exist because humans need to enter information. Chargebacks exist because humans change their minds.

AI agents don't have these problems. They're deterministic, cryptographically authenticated, and operate at machine speed. But they're stuck using payment infrastructure optimized for human limitations.

Look at the overhead of a typical API monetization setup:

1. User creates account
2. User provides credit card
3. Platform stores payment method
4. API tracks usage
5. Platform batches usage
6. Monthly invoice generated
7. Payment processed (2-3% fees)
8. Potential chargebacks handled
9. Reconciliation completed

This exists because processing individual transactions was historically expensive. Stripe charges $0.30 + 2.9% per transaction. For a $0.01 API call, that's a 3,000% fee.

x402 inverts this model. With Base L2 transaction costs around $0.0016 and payment verification in ~200ms (on-chain finality in ~2s), every request can carry its own payment. No accounts. No batching. No invoices.

The Protocol Specification

x402 extends HTTP with payment semantics. Server requires payment, responds with 402 and instructions. Client pays, retries.

The request-response flow

Response headers (402)

Amount is specified in atomic units. For USDC (6 decimals), 1000 units = $0.001.

Request headers (retry with proof)

The x402-hono Package

For production, x402-hono handles the heavy lifting:

import { Hono } from 'hono';
import { paymentMiddleware } from 'x402-hono';
import type { RoutesConfig } from 'x402-hono';

const app = new Hono();

const routes: RoutesConfig = {
  '/api/translate': {
    price: '$0.001', // $0.001 USDC
    network: 'base',
    config: { description: 'Translation service' }
  }
};

app.use('/api/*', paymentMiddleware(process.env.WALLET_ADDRESS!, routes));

app.post('/api/translate', async (c) => {
  const { text, target } = await c.req.json();
  const translation = await translate(text, target);
  return c.json({ translation });
});

export default app;

Network Selection

x402 works across EVM networks. Base is the current standard for production.

Why Base?

1. Transaction costs: ~$0.0016 per transaction
2. Settlement time: ~2 seconds
3. Native USDC: Circle-issued, not bridged
4. Coinbase backing: Enterprise-grade infrastructure
5. x402 ecosystem: Most x402 tooling targets Base first

What's Next

You now have everything needed to implement x402 in production. The protocol is simple by design—HTTP plus blockchain verification.

Key takeaways:

1. 402 response = payment requirements
2. X-Payment-Proof header = payment verification
3. Base network = optimal cost/speed tradeoff
4. USDC = stable pricing for services

For hands-on implementation, check out x402 Tutorial: Your First Micropayment in 5 Minutes where we build a working payment flow from scratch.

The machine economy runs on x402. Time to build.