x402 Protocol Development#

x402 is an open standard (Apache-2.0) that activates the HTTP 402 Payment Required status code for programmatic, on-chain payments. Originally created by Coinbase, now maintained by the x402 Foundation. No accounts, sessions, or API keys required - clients pay with signed crypto transactions directly over HTTP.

When to Use#

• Building a paid API that accepts crypto micropayments
• Adding paywall to web content or endpoints
• Enabling AI agents to autonomously pay for resources
• Integrating MCP tools that require payment
• Building agent-to-agent (A2A) payment flows
• Working with EVM (Base, Ethereum, MegaETH, Monad, Polygon, Stable, Arbitrum), Solana, Stellar, Aptos, NEAR, or XRPL payment settlement
• Implementing usage-based billing with the upto scheme (LLM tokens, bandwidth, compute)
• Running an in-process facilitator (self-facilitation) without external facilitator dependency

Core Architecture#

Three roles in every x402 payment:

1. Resource Server - protects endpoints, returns 402 with payment requirements
2. Client - signs payment authorization, retries request with payment header
3. Facilitator - verifies signatures, settles transactions on-chain

Payment flow (HTTP transport):

text

Client -> GET /resource -> Server returns 402 + PAYMENT-REQUIRED header
Client -> signs payment -> retries with PAYMENT-SIGNATURE header
Server -> POST /verify to Facilitator -> POST /settle to Facilitator
Server -> returns 200 + PAYMENT-RESPONSE header + resource data

Quick Start: Seller (TypeScript + Express)#

typescript

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();
const payTo = "0xYourWalletAddress";

const facilitator = new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" });
const server = new x402ResourceServer(facilitator)
  .register("eip155:84532", new ExactEvmScheme());

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [
          { scheme: "exact", price: "$0.001", network: "eip155:84532", payTo },
        ],
        description: "Weather data",
        mimeType: "application/json",
      },
    },
    server,
  ),
);

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

app.listen(4021);

Install: npm install @x402/express @x402/core @x402/evm

Quick Start: Buyer (TypeScript + Axios)#

typescript

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

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
registerExactEvmScheme(client, { signer });

const api = wrapAxiosWithPayment(axios.create(), client);
const response = await api.get("http://localhost:4021/weather");
// Payment handled automatically on 402 response

Install: npm install @x402/axios @x402/evm viem

Quick Start: Seller (Python + FastAPI)#

python

from fastapi import FastAPI
from x402.http import FacilitatorConfig, HTTPFacilitatorClient, PaymentOption
from x402.http.middleware.fastapi import PaymentMiddlewareASGI
from x402.http.types import RouteConfig
from x402.mechanisms.evm.exact import ExactEvmServerScheme
from x402.server import x402ResourceServer

app = FastAPI()

facilitator = HTTPFacilitatorClient(FacilitatorConfig(url="https://x402.org/facilitator"))
server = x402ResourceServer(facilitator)
server.register("eip155:84532", ExactEvmServerScheme())

routes = {
    "GET /weather": RouteConfig(
        accepts=[PaymentOption(scheme="exact", pay_to="0xYourAddress", price="$0.001", network="eip155:84532")],
        mime_type="application/json",
        description="Weather data",
    ),
}
app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)

@app.get("/weather")
async def get_weather():
    return {"weather": "sunny", "temperature": 70}

Install: pip install "x402[fastapi,evm]"

Quick Start: Seller (Go + Gin)#

go

import (
    x402http "github.com/x402-foundation/x402/go/v2/http"
    ginmw "github.com/x402-foundation/x402/go/v2/http/gin"
    evm "github.com/x402-foundation/x402/go/v2/mechanisms/evm/exact/server"
)

facilitator := x402http.NewHTTPFacilitatorClient(&x402http.FacilitatorConfig{URL: facilitatorURL})

routes := x402http.RoutesConfig{
    "GET /weather": {
        Accepts: x402http.PaymentOptions{
            {Scheme: "exact", Price: "$0.001", Network: "eip155:84532", PayTo: evmAddress},
        },
        Description: "Weather data",
        MimeType:    "application/json",
    },
}

r.Use(ginmw.X402Payment(ginmw.Config{
    Routes:      routes,
    Facilitator: facilitator,
    Schemes:     []ginmw.SchemeConfig{{Network: "eip155:84532", Server: evm.NewExactEvmScheme()}},
}))

Install: go get github.com/x402-foundation/x402/go/v2

Multi-Network Support (EVM + Solana)#

Servers can accept payment on multiple networks simultaneously:

typescript

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

const server = new x402ResourceServer(facilitator)
  .register("eip155:84532", new ExactEvmScheme())
  .register("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", new ExactSvmScheme());

// Route config with both networks
"GET /weather": {
  accepts: [
    { scheme: "exact", price: "$0.001", network: "eip155:84532", payTo: evmAddress },
    { scheme: "exact", price: "$0.001", network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", payTo: svmAddress },
  ],
}

Clients register both schemes and auto-select based on server requirements:

typescript

const client = new x402Client();
registerExactEvmScheme(client, { signer: evmSigner });
registerExactSvmScheme(client, { signer: svmSigner });

Supported Networks#

NetworkCAIP-2 IDStatusBase Mainneteip155:8453MainnetBase Sepoliaeip155:84532TestnetMegaETH Mainneteip155:4326Mainnet (MegaUSD default, 18 decimals)Solana Mainnetsolana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpMainnetSolana Devnetsolana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1TestnetStellar Mainnetstellar:pubnetMainnet (TypeScript SDK only)Stellar Testnetstellar:testnetTestnet (TypeScript SDK only)Aptos Mainnetaptos:1Mainnet (TypeScript SDK only)Aptos Testnetaptos:2Testnet (TypeScript SDK only)Monad Mainneteip155:143MainnetPolygon Mainneteip155:137MainnetPolygon Amoyeip155:80002TestnetStable Mainneteip155:988MainnetStable Testneteip155:2201TestnetArbitrum Oneeip155:42161MainnetArbitrum Sepoliaeip155:421614TestnetXDC Network Mainneteip155:50Mainnet (USDC)XDC Apothem Testneteip155:51Testnet (USDC)Mezo Mainneteip155:31612Mainnet (mUSD, 18 decimals, Permit2 + EIP-2612)Mezo Testneteip155:31611Testnet (mUSD, Permit2 + EIP-2612)Avalancheeip155:43114Runtime registration only (no default asset; community facilitators)Radius Mainneteip155:723487Mainnet (SBC default)Radius Testneteip155:72344Testnet (SBC default)ADI Chaineip155:36900Mainnet (USDC.e default)HPP Mainneteip155:190415Mainnet (Bridged USDC default)HPP Sepoliaeip155:181228Testnet (Bridged USDC default)TON Mainnettvm:-239Mainnet (jetton transfers; Python + TypeScript SDK)TON Testnettvm:-3TestnetHedera Mainnethedera:mainnetMainnet (HBAR + HTS tokens)Hedera Testnethedera:testnetTestnetAlgorand Mainnetalgorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73kMainnet (USDC ASA)Algorand Testnetalgorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDeTestnet (USDC ASA)Keeta Mainnetkeeta:21378Mainnet (TypeScript SDK)Keeta Testnetkeeta:1413829460Testnet (TypeScript SDK)Concordium Mainnetccd:9dd9ca4d19e9393877d2c44b70f89acbMainnet (native CCD, 6 decimals; TypeScript SDK)Concordium Testnetccd:4221332d34e1694168c2a0c0b3fd0f27Testnet (native CCD; TypeScript SDK)Igra Mainneteip155:38833Mainnet (USDC, Permit2 only - no EIP-3009, no EIP-2612)NEAR Mainnetnear:mainnetMainnet (NEP-141 USDC, relayer-sponsored; TypeScript SDK)NEAR Testnetnear:testnetTestnet (TypeScript SDK)XRPL Mainnetxrpl:0Mainnet (XRP + IOUs, no fee sponsorship; TypeScript SDK)XRPL Testnetxrpl:1TestnetXRPL Devnetxrpl:2Devnet

Algorand CAIP-2 ids changed. The reference is the URL-safe base64 genesis hash truncated to the first 32 characters. The older padded full-hash form ( algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=) no longer matches; SDKs normalize legacy ids on input, but emit the truncated form.

Default facilitator ( https://x402.org/facilitator) supports Base Sepolia, Solana Devnet, Algorand Testnet, Stellar Testnet, Aptos Testnet, Hedera Testnet, and XRPL Testnet. On Base Sepolia it advertises exact, upto, and batch-settlement, plus the builder-code, eip2612GasSponsoring, and erc20ApprovalGasSponsoring extensions.

Not a production default. Upstream now states explicitly that the public x402.org facilitator is intended for development and testnet workflows - do not assume it is the default path for production mainnet routes. See the facilitator directory for production options.

SDK Packages#

TypeScript v2.20.0 ( npm, GitHub)#

PackagePurpose@x402/coreCore types, client, server, facilitator@x402/evmEVM exact + upto schemes (EIP-3009, Permit2). Upto via @x402/evm/upto/* subpaths@x402/svmSolana scheme (SPL TransferChecked)@x402/stellarStellar scheme (SEP-41 Soroban token transfers)@x402/aptosAptos scheme (Fungible Asset transfers)@x402/avmAlgorand (AVM) scheme@x402/hederaHedera scheme (HBAR + HTS fungible-asset transfers)@x402/tvmTON scheme (jetton transfers)@x402/keetaKeeta scheme (exact)@x402/concordiumConcordium scheme (native CCD, exact)@x402/nearNEAR scheme (NEP-366 SignedDelegate + NEP-141 ft_transfer, relayer-sponsored)@x402/xrplXRPL scheme (payer-signed Payment, no fee sponsorship). Tagged 2.20.0 but not yet on npm - build from source@x402/expressExpress middleware@x402/fastifyFastify middleware@x402/honoHono edge middleware@x402/nextNext.js middleware@x402/axiosAxios interceptor@x402/fetchFetch wrapper@x402/paywallBrowser paywall UI@x402/mcpMCP client + server@x402/extensionsBazaar, offer-receipt, payment-identifier, sign-in-with-x, gas sponsoring

Python v2.17.0 ( PyPI, GitHub)#

bash

pip install "x402[httpx]"      # Async HTTP client
pip install "x402[requests]"   # Sync HTTP client
pip install "x402[fastapi]"    # FastAPI server
pip install "x402[flask]"      # Flask server
pip install "x402[evm]"        # EVM support
pip install "x402[svm]"        # Solana support
pip install "x402[tvm]"        # TON support
pip install "x402[mcp]"        # MCP integration
pip install "x402[extensions]" # Extensions (bazaar, gas sponsoring, etc.)
pip install "x402[all]"        # Everything

Convenience bundles: clients (httpx + requests), servers (flask + fastapi), mechanisms (evm + svm + tvm).

Go v2.20.0 ( GitHub)#

The Go module path carries a /v2 suffix - the bare .../x402/go path no longer resolves tagged releases.

bash

go get github.com/x402-foundation/x402/go/v2

Java (Java 17+, GitHub)#

A fourth official binding is in the repo ( PaymentFilter, FacilitatorClient, X402HttpClient). Not published to a package registry yet - build from source.

Key Concepts#

• Client/Server/Facilitator: The three roles in every payment. Client signs, server enforces, facilitator settles on-chain. See references/core-concepts.md
• Wallet: Both payment mechanism and identity for buyers/sellers. See references/core-concepts.md
• Networks & Tokens: CAIP-2 identifiers, EIP-3009 tokens on EVM, SPL on Solana, custom token config. See references/core-concepts.md
• Scheme: Payment method. exact = transfer exact amount; upto = authorize max, settle actual usage (shipping SDKs are EVM Permit2 only; a draft SVM binding via Solana payment channels is spec-stage); batch-settlement = commit at request time, settle asynchronously; auth-capture = escrow / authorize-then-capture with void, refund, reclaim. See references/evm-scheme.md, references/svm-scheme.md, references/stellar-scheme.md, references/upto-scheme.md, references/aptos-scheme.md, references/near-scheme.md, references/xrpl-scheme.md, references/protocol-spec.md
• Self-facilitation: Run an in-process facilitator instead of calling an external URL. See references/typescript-sdk.md, references/go-sdk.md
• Transport: How payment data is transmitted (HTTP headers, MCP _meta, A2A metadata). See references/transports.md
• Extensions: Optional features (bazaar discovery, offer-receipt attestations, payment-identifier idempotency, sign-in-with-x auth, gas sponsoring, builder-code attribution, http-message-signatures, auth-hints). See references/extensions.md
• Hooks: Lifecycle callbacks on client/server/facilitator (TS, Python, Go). See references/lifecycle-hooks.md
• Protocol types: PaymentRequired, PaymentPayload, SettlementResponse. See references/protocol-spec.md
• Custom tokens: Use registerMoneyParser for non-USDC tokens, Permit2 for non-EIP-3009 tokens. See references/evm-scheme.md
• Mainnet deployment: Switch facilitator URL, network IDs, and wallet addresses. See references/core-concepts.md

References#

FileContentreferences/core-concepts.mdHTTP 402 foundation, client/server/facilitator roles, wallet identity, networks, tokens, custom token config, dynamic registration, self-hosted facilitator, mainnet deploymentreferences/protocol-spec.mdv2 protocol types, payment flow, facilitator API, error codesreferences/typescript-sdk.mdTypeScript SDK patterns for server, client, MCP, paywall, facilitatorreferences/python-sdk.mdPython SDK patterns for server, client, MCP (server + client), facilitatorreferences/go-sdk.mdGo SDK patterns for server, client, MCP, facilitator, signers, custom money parserreferences/evm-scheme.mdEVM exact scheme: EIP-3009, Permit2, default asset resolution, registerMoneyParser, custom tokensreferences/svm-scheme.mdSolana exact scheme: SPL TransferChecked, verification rules, duplicate settlement mitigationreferences/stellar-scheme.mdStellar exact scheme: SEP-41 Soroban token transfers, ledger-based expiration, fee sponsorship, TypeScript SDK onlyreferences/upto-scheme.mdUpto (usage-based) scheme: authorize max amount, settle actual usage. EVM via Permit2 onlyreferences/aptos-scheme.mdAptos exact scheme: fungible asset transfers, fee payer sponsorship, TypeScript SDK onlyreferences/near-scheme.mdNEAR exact scheme: NEP-366 SignedDelegate, NEP-141 ft_transfer, relayer gas sponsorship, full-access-key requirement, NEP-145 storage registrationreferences/xrpl-scheme.mdXRPL exact scheme: payer-signed Payment, no fee sponsorship, explicit AssetAmount pricing, sequence vs ticketSequencereferences/transports.mdHTTP, MCP, A2A transport implementationsreferences/extensions.mdBazaar, payment-identifier, sign-in-with-x, gas sponsoring (eip2612 + erc20) extensionsreferences/lifecycle-hooks.mdClient/server/facilitator hooks (TypeScript, Python, Go), hook chaining, MCP hooks

Official Resources#

• GitHub: https://github.com/x402-foundation/x402
• Spec: https://github.com/x402-foundation/x402/tree/main/specs
• Docs: https://docs.x402.org
• Website: https://x402.org
• Facilitator directory - named production and community facilitators
• Third-party SDKs - Rust ( x402-rs), Java (Mogami), Ruby (x402-rails), and others beyond the three official bindings
• Third-party extensions - ecosystem extension packages
• Community: Slack at http://slack.x402.org/ (the project moved off Discord)
• Foundation Charter: https://github.com/x402-foundation/x402/tree/main/foundation