HTTP 402 Payment Required
The internet's native payment protocol. Enable sub-cent micropayments for APIs, content, and agent-to-agent transactions without API keys.
Native protocol support for machine-to-machine payments on the open web.
๐What is x402?
HTTP status code 402 "Payment Required" was reserved in the original HTTP specification for future use with digital payments. The x402 protocol finally implements this vision, enabling any HTTP endpoint to request payment before serving content.
Unlike traditional payment APIs that require API keys, OAuth tokens, and complex integration, x402 works at the HTTP protocol level. When a server returns a 402 response, it includes payment instructions in the headers. The client makes a payment and retries the request with proof of payment. It's that simple.
Sub-Cent Payments
Minimum payment of $0.001 enables true micropayments
No API Keys
Payment is the authentication - no signup required
Instant Settlement
Payments settle on Base L2 in seconds
โ๏ธHow It Works
Request
Client makes HTTP request to protected endpoint
402 Response
Server returns 402 with payment instructions
Payment
Client sends stablecoin to specified address
Access
Retry with payment proof, receive content
import requests
from web3 import Web3
# Step 1: Make initial request
response = requests.get("https://api.example.com/premium-data")
# Step 2: Handle 402 Payment Required
if response.status_code == 402:
payment_info = {
"amount": response.headers["X-402-Amount"],
"receiver": response.headers["X-402-Receiver"],
"network": response.headers["X-402-Network"],
"token": response.headers["X-402-Token"]
}
# Step 3: Send payment on Base network
w3 = Web3(Web3.HTTPProvider("https://mainnet.base.org"))
usdc = w3.eth.contract(address=USDC_ADDRESS, abi=ERC20_ABI)
tx = usdc.functions.transfer(
payment_info["receiver"],
int(float(payment_info["amount"]) * 1e6) # USDC has 6 decimals
).transact()
tx_hash = w3.eth.wait_for_transaction_receipt(tx)
# Step 4: Retry with payment proof
response = requests.get(
"https://api.example.com/premium-data",
headers={
"X-402-Payment-Proof": json.dumps({
"txHash": tx_hash.hex(),
"network": "base",
"token": "USDC",
"amount": payment_info["amount"]
})
}
)
# Success! Access granted
data = response.json()๐Supported Networks & Tokens
Networks
Stablecoins
๐ตx402 Pricing
| Resource | Price | Example |
|---|---|---|
| Tokens (LLM) | $0.01 / 1,000 tokens | 1,000 word response = $0.01 |
| API Requests | $0.10 / 1,000 requests | Single API call = $0.0001 |
| Compute Time | $0.001 / 1,000ms | 5 second task = $0.005 |
| Minimum Payment | $0.001 | One tenth of a cent |
๐ฏUse Cases
Agent-to-Agent Payments
AI agents can autonomously pay for services from other agents without human intervention. A research agent can pay a data analysis agent per query.
Agent A โ $0.05 โ Agent B (per analysis)Content Micropayments
Pay-per-article instead of subscriptions. Readers pay only for what they read, creators get paid instantly.
Reader โ $0.10 โ Publisher (per article)API Monetization
Monetize your API without managing API keys, rate limits, or billing. Every request pays automatically.
Developer โ $0.001 โ API Provider (per call)Gaming & Virtual Goods
In-game purchases without app store fees. Players pay directly for items, power-ups, or access.
Player โ $0.25 โ Game (per item)๐งIntegration Guide
Server-Side: Protecting an Endpoint
import { handleX402, createPaymentRequest, createX402Headers } from '@/lib/x402';
export async function GET(request: Request) {
// Check for payment proof in headers
const paymentProof = request.headers.get('X-402-Payment-Proof');
if (!paymentProof) {
// Return 402 Payment Required
const paymentRequest = createPaymentRequest({
amountUSD: 0.01,
resource: '/api/premium-data',
description: 'Access to premium data endpoint',
});
return new Response(
JSON.stringify({
error: 'Payment required',
paymentRequest,
}),
{
status: 402,
headers: {
'Content-Type': 'application/json',
...createX402Headers(paymentRequest),
},
}
);
}
// Verify payment proof
const isValid = await verifyPayment(JSON.parse(paymentProof));
if (!isValid) {
return new Response(
JSON.stringify({ error: 'Invalid payment proof' }),
{ status: 402 }
);
}
// Payment verified - serve content
return Response.json({
data: 'Premium content here',
payment: { verified: true }
});
}Client-Side: Making Paid Requests
import { MNNR } from '@mnnr/sdk';
const client = new MNNR({ apiKey: 'your-api-key' });
// The SDK handles x402 automatically
async function fetchPremiumData() {
try {
// SDK automatically handles 402 responses
const response = await client.x402.request({
url: 'https://api.example.com/premium-data',
method: 'GET',
// Optional: set spending limits
maxPayment: 1.00, // Max $1.00 per request
});
return response.data;
} catch (error) {
if (error.code === 'PAYMENT_LIMIT_EXCEEDED') {
console.log('Request would exceed payment limit');
}
throw error;
}
}
// Or handle manually
async function manualX402Flow() {
const response = await fetch('https://api.example.com/premium-data');
if (response.status === 402) {
const paymentInfo = {
amount: response.headers.get('X-402-Amount'),
receiver: response.headers.get('X-402-Receiver'),
network: response.headers.get('X-402-Network'),
};
// Make payment through MNNR
const payment = await client.payments.create({
amount: paymentInfo.amount,
to: paymentInfo.receiver,
network: paymentInfo.network,
});
// Retry with payment proof
return fetch('https://api.example.com/premium-data', {
headers: {
'X-402-Payment-Proof': JSON.stringify({
txHash: payment.txHash,
network: payment.network,
token: payment.token,
amount: payment.amount,
}),
},
});
}
return response;
}๐HTTP Headers Reference
| Header | Direction | Description | Example |
|---|---|---|---|
X-402-Version | Response | Protocol version | 1.0 |
X-402-Amount | Response | Payment amount in USD | 0.001 |
X-402-Currency | Response | Currency code | USD |
X-402-Network | Response | Blockchain network | base |
X-402-Token | Response | Token to pay with | USDC |
X-402-Receiver | Response | Payment address | 0x1234...abcd |
X-402-Expires | Response | Payment deadline | 2025-12-28T12:00:00Z |
X-402-Payment-Proof | Request | JSON proof of payment | {"txHash":"0x..."} |
๐Try x402 Now
Test the x402 protocol with our demo endpoint. Send a request and see the 402 response in action.
curl -i https://mnnr.app/api/x402?demo=true
Learn More
Explore the x402 specification and community resources.