x402 Protocol Guide

x402 is an open internet-native payment standard that revives the dormant HTTP 402 'Payment Required' status code, enabling direct blockchain-based transactions over HTTP.

Integration Examples

Learn how to integrate the x402 protocol into your application, covering both server-side (seller) and client-side (buyer) implementations.

SDK Ecosystem

TypeScript

@x402/core@x402/evm@x402/svm@x402/fetch@x402/axios@x402/next@x402/express@x402/hono@x402/paywall

Other Languages

Python: x402Rust: x402-rsGo: x402-go

Server-Side (Seller)

Add x402 middleware to your API endpoints to enable per-request billing.

Express.js

import express from "express";
import { paymentMiddleware } from "@x402/express";

const app = express();
const facilitatorUrl = "https://x402.org/facilitator";
const payTo = "0xYourWalletAddress";

app.use(
  "/api/data",
  paymentMiddleware(payTo, {
    scheme: "exact",
    network: "base",
    maxAmountRequired: 1000,
  }, { url: facilitatorUrl })
);

app.get("/api/data", (req, res) => {
  res.json({ data: "Premium content" });
});

app.listen(3000);

Next.js (App Router)

import { withPayment } from "@x402/next";
import { NextResponse } from "next/server";

const facilitatorUrl = "https://x402.org/facilitator";
const payTo = "0xYourWalletAddress";

async function handler() {
  return NextResponse.json({ data: "Premium content" });
}

export const GET = withPayment(handler, payTo, {
  scheme: "exact",
  network: "base",
  maxAmountRequired: 1000,
}, { url: facilitatorUrl });

Hono

import { Hono } from "hono";
import { paymentMiddleware } from "@x402/hono";

const app = new Hono();
const facilitatorUrl = "https://x402.org/facilitator";
const payTo = "0xYourWalletAddress";

app.use(
  "/api/data",
  paymentMiddleware(payTo, {
    scheme: "exact",
    network: "base",
    maxAmountRequired: 1000,
  }, { url: facilitatorUrl })
);

app.get("/api/data", (c) => {
  return c.json({ data: "Premium content" });
});

export default app;

Client-Side (Buyer)

Use x402-enabled HTTP clients to automatically handle payment flows.

Fetch API

import { wrapFetch } from "@x402/fetch";
import { createWalletClient } from "viem";

const walletClient = createWalletClient({ /* config */ });
const fetchWithPayment = wrapFetch(walletClient);

// 402 responses are automatically handled
const response = await fetchWithPayment(
  "https://api.example.com/data"
);
const data = await response.json();

Axios

import { wrapAxios } from "@x402/axios";
import axios from "axios";
import { createWalletClient } from "viem";

const walletClient = createWalletClient({ /* config */ });
const client = wrapAxios(axios, walletClient);

const { data } = await client.get(
  "https://api.example.com/data"
);

Setup Steps

Choose a facilitator (Coinbase CDP / PayAI Network, etc.)

Install x402 SDKs (npm install @x402/express @x402/fetch)

Configure your wallet address (for receiving payments)

Add x402 middleware to your API endpoints

Test on Base Sepolia testnet

Official Resources

Coinbase CDP x402 Docs→GitHub: coinbase/x402→x402.org→

Browse Facilitators→Back to Overview