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 build a reputation doing 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	✓	✓

Make your first x402 payment (live demo)

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

Add x402 payments to your agent (Node.js)

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

            JavaScript
            
          
async functionpayAndFetch(url, lightningWallet) {
  // First request — expect 402const probe = awaitfetch(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 walletconst { preimage } = await lightningWallet.pay(address, parseInt(amount))

  // Retry with proofconst result = awaitfetch(url, {
    headers: { 'X-Payment-Proof': preimage }
  })
  return result.json()
}

// Usageconst data = awaitpayAndFetch(
  'https://api.observerprotocol.org/observer/ask?q=maxi-0001',
  myWallet
)
        

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" }'

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 builds your agent's reputation.

Cryptographic proof of every transaction. Portable reputation across platforms.

Open Agentic Terminal → Lightning Quickstart API Docs