name: x402 description: x402 payment protocol for HTTP-native payments. Use when building paid APIs, monetizing endpoints, or integrating crypto payments into web services. Triggers on "x402", "paid API", "monetize endpoint", "HTTP 402", "payment middleware", "pay per request", or "API paywall". license: MIT metadata: author: Ember (emberdragonc) version: "1.0.0" source: https://github.com/coinbase/x402

x402 Payment Protocol

x402 is an open standard by Coinbase for HTTP-native payments. It uses HTTP status code 402 (Payment Required) to enable pay-per-request APIs.

Key Concepts

• HTTP 402: Standard response when payment is required
• Facilitator: Service that verifies and settles payments on-chain
• Resource Server: Your API server with paid endpoints
• Client: Makes requests and handles automatic payments

Installation

# Server (Express)
npm install @x402/core @x402/evm @x402/svm @x402/express

# Server (Hono)
npm install @x402/core @x402/evm @x402/svm @x402/hono

# Client (Fetch)
npm install @x402/core @x402/evm @x402/svm @x402/fetch

# Client (Axios)
npm install @x402/core @x402/evm @x402/svm @x402/axios

Server Setup (Seller)

Express Example

import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

const app = express();

// Your wallet address to receive payments
const payToAddress = "0xYourWalletAddress";

// Facilitator URL (see https://www.x402.org/ecosystem?category=facilitators)
const facilitatorClient = new HTTPFacilitatorClient({ 
  url: "https://facilitator.x402.org" 
});

// Configure payment requirements
app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: {
          scheme: "exact",
          price: "$0.001",           // Price in USD
          network: "eip155:8453",    // Base Mainnet
          payTo: payToAddress,
        },
        description: "Weather data",
        mimeType: "application/json",
      },
      "POST /ai/generate": {
        accepts: {
          scheme: "exact",
          price: "$0.01",
          network: "eip155:8453",
          payTo: payToAddress,
        },
        description: "AI text generation",
        mimeType: "application/json",
      },
    },
    new x402ResourceServer(facilitatorClient)
      .register("eip155:*", new ExactEvmScheme()),  // All EVM chains
  ),
);

// Define your endpoints as normal
app.get("/weather", (req, res) => {
  res.json({ weather: "sunny", temperature: 70 });
});

app.post("/ai/generate", (req, res) => {
  res.json({ text: "Generated content here" });
});

app.listen(3000);

Multi-Network Support

import { ExactEvmScheme } from "@x402/evm/exact/server";
import { ExactSvmScheme } from "@x402/svm/exact/server";

app.use(
  paymentMiddleware(
    {
      "GET /data": {
        accepts: [
          // Accept EVM payment
          {
            scheme: "exact",
            price: "$0.001",
            network: "eip155:8453",      // Base Mainnet
            payTo: evmAddress,
          },
          // Also accept Solana payment
          {
            scheme: "exact",
            price: "$0.001",
            network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",  // Solana Mainnet
            payTo: solanaAddress,
          },
        ],
        description: "Data endpoint",
      },
    },
    new x402ResourceServer(facilitatorClient)
      .register("eip155:*", new ExactEvmScheme())
      .register("solana:*", new ExactSvmScheme()),
  ),
);

Client Setup (Buyer)

Fetch Client

import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// Create signer from private key
const signer = privateKeyToAccount("0xYourPrivateKey");

// Create x402 client and register payment scheme
const client = new x402Client();
registerExactEvmScheme(client, { signer });

// Wrap fetch to auto-handle payments
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Use like normal fetch - payments handled automatically!
const response = await fetchWithPayment("https://api.example.com/weather");
const data = await response.json();

Axios Client

import { wrapAxiosWithPayment, x402Client } from "@x402/axios";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import axios from "axios";

const client = new x402Client();
registerExactEvmScheme(client, { signer });

const axiosWithPayment = wrapAxiosWithPayment(axios, client);

// Use like normal axios
const response = await axiosWithPayment.get("https://api.example.com/weather");

Network Identifiers (CAIP-2)

| Network | Identifier | |---------|-----------| | Ethereum Mainnet | eip155:1 | | Base Mainnet | eip155:8453 | | Base Sepolia | eip155:84532 | | Arbitrum One | eip155:42161 | | Optimism | eip155:10 | | Polygon | eip155:137 | | Solana Mainnet | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp | | Solana Devnet | solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 |

Payment Flow

1. Client makes request to protected endpoint
2. Server returns HTTP 402 with PAYMENT-REQUIRED header
3. Client parses requirements, signs payment
4. Client re-sends request with X-PAYMENT header
5. Server forwards to Facilitator to verify
6. Facilitator settles payment on-chain
7. Server returns response with PAYMENT-RESPONSE header

Environment Variables

Server

FACILITATOR_URL=https://facilitator.x402.org
EVM_ADDRESS=0xYourReceivingAddress
SVM_ADDRESS=YourSolanaAddress  # Optional

Client

EVM_PRIVATE_KEY=0xYourPrivateKey
SVM_PRIVATE_KEY=YourBase58PrivateKey  # Optional

Facilitators

Public facilitators that verify and settle payments:

• See https://www.x402.org/ecosystem?category=facilitators

Advanced Patterns

Dynamic Pricing

{
  "GET /ai/:model": {
    accepts: (req) => ({
      scheme: "exact",
      price: req.params.model === "gpt4" ? "$0.10" : "$0.01",
      network: "eip155:8453",
      payTo: address,
    }),
  },
}

Lifecycle Hooks

new x402ResourceServer(facilitatorClient)
  .register("eip155:*", new ExactEvmScheme())
  .onVerify(async (payment) => {
    console.log("Payment verified:", payment);
  })
  .onSettle(async (result) => {
    console.log("Payment settled:", result.transaction);
  });

Resources

• Docs: https://docs.x402.org
• GitHub: https://github.com/coinbase/x402
• Ecosystem: https://www.x402.org/ecosystem
• Spec: https://github.com/coinbase/x402/tree/main/specs