diegosouzapw X402 Agent Payments
Let your agent pay (and get paid by) other agents. HTTP 402 + on-chain escrow.
How It Works
Agent A Agent B
│ │
│ GET /api/data │
│ ─────────────────────► │
│ │
│ 402 Payment Required │
│ X-Price: 0.01 USDC │
│ ◄───────────────────── │
│ │
│ Lock funds in escrow │
│ ══════════════════════► │ (on-chain)
│ │
│ GET /api/data │
│ X-Payment-Proof: 0x... │
│ ─────────────────────► │
│ │
│ 200 OK + data │
│ ◄───────────────────── │
│ │
│ Release escrow │
│ ◄══════════════════════ │ (on-chain)
Quick Start
As a Buyer (Paying Agent)
import { X402Client } from './x402-client';
const client = new X402Client({
wallet: '0x...',
privateKey: process.env.PRIVATE_KEY,
facilitatorUrl: 'http://localhost:8403'
});
// Call a paid API - payment handled automatically
const response = await client.fetch('http://agent-b.local/api/sensor-data');
console.log(response.data);
console.log(`Paid: ${response.paymentAmount} USDC`);
As a Seller (Paid Agent)
import { X402Server } from './x402-server';
import { Hono } from 'hono';
const app = new Hono();
const x402 = new X402Server({
wallet: '0x...',
facilitatorUrl: 'http://localhost:8403'
});
// Protect an endpoint with payment requirement
app.get('/api/sensor-data', x402.protect({ price: 0.01 }), (c) => {
return c.json({ temperature: 23.5, humidity: 45 });
});
// Free endpoint
app.get('/api/status', (c) => {
return c.json({ online: true });
});
Run the Facilitator
The facilitator coordinates payments and monitors escrow:
cd apps/x402-facilitator
bun run start
🔷 X402 Facilitator Started
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📍 HTTP: http://0.0.0.0:8403
🔌 WebSocket: ws://0.0.0.0:8403
⛓️ Escrow: 0x5FbDB2315678afecb367f032d93F642f64180aa3
🌐 Provider: http://localhost:8545
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Local Development
# Start local blockchain
anvil
# Deploy escrow contract
cd contracts && forge script script/Deploy.s.sol --broadcast
# Start facilitator
cd apps/x402-facilitator && bun run start
# Run example agents
bun run dev:alice # Seller on :3001
bun run dev:bob # Buyer on :3002
Payment Flow
- Request — Buyer calls seller API
- Challenge — Seller returns 402 with price
- Lock — Buyer locks funds in escrow contract
- Proof — Buyer retries with payment proof header
- Deliver — Seller returns data
- Release — Escrow releases funds to seller
If seller doesn't deliver, buyer can dispute and get refund.
Headers
| Header | Direction | Description |
|---|---|---|
X-Price |
Response | Required payment amount |
X-Payment-Address |
Response | Seller's wallet |
X-Payment-Proof |
Request | Transaction hash proving payment |
X-Escrow-Id |
Both | Escrow transaction ID |
Chains Supported
- Local (Anvil)
- Base
- Arbitrum
- Any EVM chain
Why Escrow?
- Trustless — No reputation needed
- Atomic — Payment and delivery linked
- Reversible — Dispute mechanism for non-delivery
- Cheap — L2s make this practical