What is the x402 Protocol? A Complete Guide
Everything you need to know about HTTP 402 Payment Required and how the x402 protocol enables machine-to-machine payments for AI agents.
The HTTP 402 status code has been "reserved for future use" since 1999. For over two decades, it sat dormant in the HTTP specification, waiting for a use case. That use case has arrived: autonomous AI agents that need to pay for services.
Quick Definition
x402 is an open protocol that uses HTTP 402 to enable machine-to-machine payments. When a client requests a paid resource, the server responds with payment requirements. The client automatically signs a payment and retries.
How x402 Works
The x402 protocol is elegantly simple. It adds payment negotiation to standard HTTP requests:
Client (AI Agent) Server (API Provider)
│ │
│ 1. GET /api/weather │
│───────────────────────────────────────────▶│
│ │
│ 2. 402 Payment Required │
│ X-Payment-Amount: 0.001 │
│ X-Payment-Asset: USDC │
│ X-Payment-Network: base │
│◀───────────────────────────────────────────│
│ │
│ [Client signs payment with wallet] │
│ │
│ 3. GET /api/weather │
│ X-Payment: <signed-payment-token> │
│───────────────────────────────────────────▶│
│ │
│ 4. 200 OK │
│ X-Payment-Status: paid │
│ {"temp": 72, "condition": "sunny"} │
│◀───────────────────────────────────────────│
│ │
This entire exchange happens in milliseconds. The AI agent doesn't need human approval— it has its own wallet and can sign payments autonomously.
x402 Protocol Headers
X-Payment-AmountResponseThe amount required to access the resource (e.g., "0.001" for $0.001).
X-Payment-AssetResponseThe accepted payment asset (e.g., "USDC", "USDT", "ETH").
X-Payment-NetworkResponseThe blockchain network for payment (e.g., "base", "ethereum").
X-PaymentRequestThe signed payment token from the client wallet.
X-Payment-StatusResponseConfirmation that payment was accepted (e.g., "paid").
Why x402 for AI Agents?
HTTP-Native
No separate payment API or checkout flow. Payments happen in the same HTTP request/response cycle.
Autonomous
AI agents can pay without human intervention. They see 402, sign payment, and retry automatically.
Micropayment-Ready
Built on crypto rails, supporting payments as small as $0.0001 with minimal fees.
Open Standard
Not proprietary. Any client or server can implement x402. Growing ecosystem of compatible tools.
Implementing x402
For API Providers (Server-Side)
// Middleware to handle x402 payments
app.use('/api/*', async (req, res, next) => {
const payment = req.headers['x-payment']
if (!payment) {
// No payment token - return 402
return res.status(402).json({
error: 'Payment Required'
}).set({
'X-Payment-Amount': '0.001',
'X-Payment-Asset': 'USDC',
'X-Payment-Network': 'base',
'X-Payment-Recipient': '0x...'
})
}
// Validate payment token
const isValid = await validatePayment(payment)
if (!isValid) {
return res.status(402).json({ error: 'Invalid payment' })
}
// Payment valid - continue to handler
res.set('X-Payment-Status', 'paid')
next()
})For AI Agents (Client-Side)
import { createAgent } from 'apiosk-client'
const agent = createAgent({
privateKey: process.env.AGENT_PRIVATE_KEY,
network: 'base'
})
// The agent handles 402 automatically
const response = await agent.callApi('/provider/api/endpoint', {
method: 'POST',
body: { query: 'What is the weather?' }
})
console.log(response.data) // API response
console.log(response.paymentInfo.amount) // Amount paidStart Using x402 Today
Apiosk implements x402 out of the box. List your API and start accepting payments from AI agents instantly.