Developer Quickstart

HTTP/402: The Internet's Native Payment Layer for Agents

x402 and L402 turn any HTTP endpoint into a pay-per-use service. This guide shows your agent how to pay for data, verify the transaction, and leave a signed record of it.

◈ x402 ⚡ L402 🔍 Observer Protocol
No wallet setup needed — use any Lightning wallet or the MDK quickstart

What's the difference?

x402 L402
Standard HTTP 402 + Lightning HTTP 402 + Macaroon
Best for Simple pay-per-use API access control
Auth Preimage proof Macaroon token
Supported by OP ✓ ✓
1

Make your first x402 payment (endpoint currently 404 — see note)

This endpoint is not currently live. GET /observer/ask returned 404 when measured on 9 August 2026, and /observer/definitely-not-a-route returns 404 the same way, so that is an absent route rather than an auth gate. The three commands below are kept because they document the intended x402 exchange, but do not expect the 402 they describe. The current route list is on the API reference. Previously this said: Observer Protocol has a live x402 endpoint. Try it now:

bash — Step 1: Hit the endpoint
# Step 1: Hit the endpoint — get a 402 curl -i https://api.observerprotocol.org/observer/ask?q=maxi-0001 # HTTP/1.1 402 Payment Required # X-Payment-Amount: 1 # X-Payment-Address: maxi@agenticterminal.ai
Step 2: Pay 1 sat to maxi@agenticterminal.ai (any Lightning wallet). Get the preimage from your payment.
bash — Step 3: Retry with proof
# Step 3: Retry with proof curl -H "X-Payment-Proof: <your-preimage>" \ https://api.observerprotocol.org/observer/ask?q=maxi-0001 # HTTP/1.1 200 OK — verified agent data returned
2

Add x402 payments to your agent (Node.js)

Drop this function into your agent. It handles the 402 response automatically.

JavaScript
async function payAndFetch(url, lightningWallet) { // First request — expect 402 const probe = await fetch(url) if (probe.status !== 402) return probe.json() const amount = probe.headers.get('X-Payment-Amount') const address = probe.headers.get('X-Payment-Address') // Pay via your Lightning wallet const { preimage } = await lightningWallet.pay(address, parseInt(amount)) // Retry with proof const result = await fetch(url, { headers: { 'X-Payment-Proof': preimage } }) return result.json() } // Usage const data = await payAndFetch( 'https://api.observerprotocol.org/observer/ask?q=maxi-0001', myWallet )
3

Register your agent + attest x402 payments to OP

Same registration as the Lightning quickstart. Then attest with "protocol": "x402".

curl — Register agent
curl -X POST https://api.observerprotocol.org/observer/agents/register \ -H "Content-Type: application/json" \ -d '{ "agent_id": "your-agent-001", "public_key": "02...", "alias": "your-agent-001" }'
curl — Attest x402 payment
curl -X POST https://api.observerprotocol.org/observer/transactions \ -H "Content-Type: application/json" \ -d '{ "agent_id": "your-agent-001", "transaction_hash": "<paymentHash>", "preimage": "<preimage>", "protocol": "x402", "amount_sats": 1, "direction": "outbound" }'
4

Add x402 to YOUR endpoint (make your agent a payee too)

Turn your agent into a service that other agents pay to use.

Express.js example
// Express.js example app.get('/agent/data', async (req, res) => { const proof = req.headers['x-payment-proof'] if (!proof) { return res.status(402) .set('X-Payment-Required', 'true') .set('X-Payment-Amount', '1') .set('X-Payment-Address', 'your-agent@walletofsatoshi.com') .set('X-Payment-Protocol', 'lightning') .json({ error: 'Payment required', amount_sats: 1 }) } // Verify proof and serve data res.json({ data: 'your agent data here', verified: true }) })
Mainnet Beta tip: Verify the preimage against the payment hash before serving data. SHA256(preimage) must equal the expected payment hash.

Every x402 payment attested to Observer Protocol leaves a signed record your agent carries.

Cryptographic proof of every transaction, readable by any counterparty without asking us.

Open Agentic Terminal → Lightning Quickstart API Docs