x402 Protocol

Overview

The x402 protocol enables machine-to-machine API payments using HTTP 402 status codes.

Implementation Guide

Step 1: Return 402 for Unpaid Requests

When an agent calls your API without payment:

HTTP/1.1 402 Payment Required
Content-Type: application/json
x-payment-required: eyJwYXlUbyI6IjB4Li4uIiwibmV0d29yayI6ImVpcDE1NTo4NDUzIn0=

{
  "error": "Payment Required",
  "payTo": "0xYourAddress",
  "network": "eip155:8453",
  "maxAmountRequired": "0.001",
  "asset": "USDC",
  "facilitatorUrl": "https://api.x402relay.com/api/v1/facilitator"
}

Step 2: Verify Payment and Serve

When the agent retries with a payment proof:

GET /api/data
x-payment: <base64-encoded-payment-proof>

Your server should:

1. Decode the payment proof
2. Verify the on-chain transaction
3. Return the requested data

Libraries

Use the official x402 libraries to handle payment verification:

npm install @x402/core @x402/evm

import { verifyPayment } from '@x402/core';

app.use(async (req, res, next) => {
  const paymentHeader = req.headers['x-payment'];

  if (!paymentHeader) {
    return res.status(402).json({
      payTo: process.env.WALLET_ADDRESS,
      network: 'eip155:8453',
      maxAmountRequired: '0.001',
      asset: 'USDC',
    });
  }

  const verified = await verifyPayment(paymentHeader);
  if (!verified) {
    return res.status(402).json({ error: 'Invalid payment' });
  }

  next();
});

Supported Networks

Network	Chain ID	Asset	Status
Base	eip155:8453	USDC	✅ Supported
Ethereum	eip155:1	USDC	🔄 Planned
Solana	—	USDC (SPL)	🔄 Planned