Instant digital payments via HTTP 402. Zero fees, ~2 second settlement, blockchain-agnostic. Pay-per-API-call, pay-per-GB, micropayments as low as $0.001.
X402 is a web protocol that uses HTTP 402 Payment Required to enable instant micropayments for API calls, data transfers, and usage-based billing. It’s built on blockchain technology for instant settlement and zero platform fees.
The protocol is named after HTTP status code 402 (Payment Required), which was defined in RFC 7231 but rarely used until X402 revived it for practical payments.
Client Server
│ │
├─ GET /api/data ──────────────────────→ │
│ │
│ ← 402 Payment Required ─────────────── │
│ (price: $0.001, paymentAddress: ...) │
│ │
├─ Send payment to blockchain ──────────→ ⟳
│ │
├─ GET /api/data ──────────────────────→ │
│ (X-Payment-Hash: 0x123...) ────────→ │
│ │
│ ← 200 OK ──────────────────────────── │
│ (data content) ←────────────────────┤
X402 integrates with the 6-dimension ontology for payment tracking:
API Provider: $0.0001 per API call
User makes 10,000 calls = $1.00
Instant payment via X402
Download Provider: $0.001 per GB
User downloads 5 GB = $0.005
Streaming payments as data transfers
AI Service: $0.001 per 1,000 tokens
User uses 2M tokens = $2.00
Fine-grained metering and billing
Model API: $0.0001 per cycle
User runs 100 cycles = $0.01
Real-time payment per request
Choose blockchain based on needs:
| Blockchain | Settlement | Cost | Best For |
|---|---|---|---|
| Base | 2-5 seconds | $0.0001-0.001 | Small micropayments |
| Polygon | 2-5 seconds | $0.0001-0.001 | Higher volume |
| Ethereum | 12 seconds | $0.10-1.00 | Large payments |
| Solana | 400ms | $0.00025 | Ultra-fast |
X402 typically uses stablecoins for stability:
X402 enables new pricing models:
| Aspect | X402 | AP2 | ACP |
|---|---|---|---|
| Primary Use | Micropayments | Agent payments | Messaging |
| Settlement | Seconds | Minutes/hours | N/A |
| Fees | Zero | Variable | N/A |
| Blockchain | Required | Optional | N/A |
X402 supports accounting via things:
// Payment ledger entry
{
type: "payment_ledger",
properties: {
protocols: {
x402: {
from: "user_wallet",
to: "service_wallet",
amount: "0.001",
asset: "USDC",
network: "base",
txHash: "0x123...",
timestamp: 1698765432,
description: "API call"
}
}
}
}
How this protocol maps to the 6-dimension ontology
X402 payments scoped to groups for payment isolation
Payment permission determined by agent role
Payment ledger entries stored as things
Payment flows between agents and services tracked
Every payment creates a payment_verified event with blockchain proof
Payment history and ledger state stored for accounting
No platform fees - payment goes directly to recipient
Transactions settle in seconds, not days
Works on any blockchain or payment rail
Enable payments as small as $0.001
Users only pay for API calls they make, per millisecond of compute
Bandwidth metering with instant micro-payments
Platform A bills user for exact usage (tokens, requests, storage)
Pay for every cycle call to AI models in real-time
// HTTP 402 endpoint that requires payment
import { HttpPaymentRequired } from "@x402/sdk";
export const protectedEndpoint = mutation({
args: { userId: v.string() },
handler: async (ctx, args) => {
// Check for X402 payment header
const paymentHeader = ctx.headers?.get("x-payment-required");
if (!paymentHeader) {
// Return 402 Payment Required
throw new HttpPaymentRequired({
amount: "0.001", // $0.001 = 1 cent
currency: "USD",
asset: "USDC",
paymentAddress: "0x1234...5678",
timeout: 30 // seconds
});
}
// Payment received, process request
const result = await processRequest(args);
// Log payment event
await ctx.db.insert("events", {
type: "payment_verified",
groupId: ctx.auth?.getOrganizationId?.(),
metadata: {
protocol: "x402",
network: paymentHeader.network,
txHash: paymentHeader.txHash,
amount: "0.001"
},
timestamp: Date.now()
});
return result;
}
});
// Client making X402 payment for API call
import { X402Client } from "@x402/sdk";
const x402 = new X402Client({
wallet: "user_wallet_address",
network: "base", // Optimized for speed
asset: "USDC"
});
// Make API call with payment
const response = await x402.fetch("https://api.example.com/search", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({ query: "find documents" })
});
// X402 automatically:
// 1. Gets payment quote from server
// 2. Sends payment on blockchain
// 3. Resends request with payment proof
// 4. Gets response
const results = await response.json();
console.log(`Paid $0.001, got ${results.length} results`);
// Track usage and bill via X402
const startTime = Date.now();
const startStorage = await getStorageUsage();
// User makes requests
for await (const request of requestStream) {
const result = await processRequest(request);
// Calculate usage
const elapsedMs = Date.now() - startTime;
const bytesUsed = getStorageUsage() - startStorage;
const computeCost = (elapsedMs / 1000) * 0.0001; // $0.0001 per second
const storageCost = (bytesUsed / 1024 / 1024 / 1024) * 0.00001; // $0.00001 per GB
const totalCost = computeCost + storageCost;
// Send X402 payment for usage
const paymentResult = await x402.pay({
amount: totalCost.toString(),
recipient: "service_wallet",
metadata: {
computeMs: elapsedMs,
storageBytes: bytesUsed,
requestId: request.id
}
});
// Log to ledger thing
await ctx.db.insert("things", {
type: "payment_ledger",
name: `Usage charge for ${request.id}`,
groupId: ctx.auth?.getOrganizationId?.(),
properties: {
protocols: {
x402: {
computeCost,
storageCost,
totalCost,
txHash: paymentResult.txHash,
network: "base",
asset: "USDC"
}
}
},
status: "active",
createdAt: Date.now(),
updatedAt: Date.now()
});
}