x402-development

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):

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)

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)

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)

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)

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:

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:

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

Supported Networks

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)

Python v2.17.0 (PyPI, GitHub)

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.

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

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