x402 · v0.11.3 · 2026-09-09 · sha256 967260b3296c97b2
x402 v0.11.3A
Immutable. This exact content is served forever at /api/v1/blob/967260b3296c97b2.
---
name: x402
description: Build internet-native payments with x402 - HTTP 402 for on-chain micropayments, no accounts or API keys. Use for paid APIs, paywalled content, agent payment flows, or per-call MCP tools. TypeScript, Python, and Go SDKs across EVM and Solana.
metadata:
version: "0.11.3"
categories: "finance, development"
topics: "x402, payments, http-402, micropayments, stablecoins"
upstream: "@x402/core@2.20.0, @x402/evm@2.20.0, x402@2.17.0, github.com/x402-foundation/x402/go/v2@v2.20.0"
openclaw:
homepage: https://github.com/tenequm/skills/tree/main/skills/x402
emoji: "💰"
primaryEnv: EVM_PRIVATE_KEY
envVars:
- name: EVM_PRIVATE_KEY
required: false
description: EVM signer key for x402 client/server.
- name: SVM_PRIVATE_KEY
required: false
description: Solana signer key for x402 client/server.
- name: APTOS_PRIVATE_KEY
required: false
description: Aptos signer for x402 on Aptos.
- name: API_KEY
required: false
description: Example upstream bearer token used in lifecycle hook examples.
- name: FACILITATOR_KEY
required: false
description: Self-hosted facilitator signing key.
- name: FACILITATOR_URL
required: false
description: Facilitator endpoint URL override.
---
# 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](https://github.com/x402-foundation/x402). 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)
```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
| Network | CAIP-2 ID | Status |
|---------|-----------|--------|
| Base Mainnet | `eip155:8453` | Mainnet |
| Base Sepolia | `eip155:84532` | Testnet |
| MegaETH Mainnet | `eip155:4326` | Mainnet (MegaUSD default, 18 decimals) |
| Solana Mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | Mainnet |
| Solana Devnet | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` | Testnet |
| Stellar Mainnet | `stellar:pubnet` | Mainnet (TypeScript SDK only) |
| Stellar Testnet | `stellar:testnet` | Testnet (TypeScript SDK only) |
| Aptos Mainnet | `aptos:1` | Mainnet (TypeScript SDK only) |
| Aptos Testnet | `aptos:2` | Testnet (TypeScript SDK only) |
| Monad Mainnet | `eip155:143` | Mainnet |
| Polygon Mainnet | `eip155:137` | Mainnet |
| Polygon Amoy | `eip155:80002` | Testnet |
| Stable Mainnet | `eip155:988` | Mainnet |
| Stable Testnet | `eip155:2201` | Testnet |
| Arbitrum One | `eip155:42161` | Mainnet |
| Arbitrum Sepolia | `eip155:421614` | Testnet |
| XDC Network Mainnet | `eip155:50` | Mainnet (USDC) |
| XDC Apothem Testnet | `eip155:51` | Testnet (USDC) |
| Mezo Mainnet | `eip155:31612` | Mainnet (mUSD, 18 decimals, Permit2 + EIP-2612) |
| Mezo Testnet | `eip155:31611` | Testnet (mUSD, Permit2 + EIP-2612) |
| Avalanche | `eip155:43114` | Runtime registration only (no default asset; community facilitators) |
| Radius Mainnet | `eip155:723487` | Mainnet (SBC default) |
| Radius Testnet | `eip155:72344` | Testnet (SBC default) |
| ADI Chain | `eip155:36900` | Mainnet (USDC.e default) |
| HPP Mainnet | `eip155:190415` | Mainnet (Bridged USDC default) |
| HPP Sepolia | `eip155:181228` | Testnet (Bridged USDC default) |
| TON Mainnet | `tvm:-239` | Mainnet (jetton transfers; Python + TypeScript SDK) |
| TON Testnet | `tvm:-3` | Testnet |
| Hedera Mainnet | `hedera:mainnet` | Mainnet (HBAR + HTS tokens) |
| Hedera Testnet | `hedera:testnet` | Testnet |
| Algorand Mainnet | `algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k` | Mainnet (USDC ASA) |
| Algorand Testnet | `algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDe` | Testnet (USDC ASA) |
| Keeta Mainnet | `keeta:21378` | Mainnet (TypeScript SDK) |
| Keeta Testnet | `keeta:1413829460` | Testnet (TypeScript SDK) |
| Concordium Mainnet | `ccd:9dd9ca4d19e9393877d2c44b70f89acb` | Mainnet (native CCD, 6 decimals; TypeScript SDK) |
| Concordium Testnet | `ccd:4221332d34e1694168c2a0c0b3fd0f27` | Testnet (native CCD; TypeScript SDK) |
| Igra Mainnet | `eip155:38833` | Mainnet (USDC, Permit2 only - no EIP-3009, no EIP-2612) |
| NEAR Mainnet | `near:mainnet` | Mainnet (NEP-141 USDC, relayer-sponsored; TypeScript SDK) |
| NEAR Testnet | `near:testnet` | Testnet (TypeScript SDK) |
| XRPL Mainnet | `xrpl:0` | Mainnet (XRP + IOUs, no fee sponsorship; TypeScript SDK) |
| XRPL Testnet | `xrpl:1` | Testnet |
| XRPL Devnet | `xrpl:2` | Devnet |
> **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](https://docs.x402.org/dev-tools/facilitators) for production options.
## SDK Packages
### TypeScript v2.20.0 ([npm](https://www.npmjs.com/org/x402), [GitHub](https://github.com/x402-foundation/x402/tree/main/typescript))
| Package | Purpose |
|---------|---------|
| `@x402/core` | Core types, client, server, facilitator |
| `@x402/evm` | EVM exact + upto schemes (EIP-3009, Permit2). Upto via `@x402/evm/upto/*` subpaths |
| `@x402/svm` | Solana scheme (SPL TransferChecked) |
| `@x402/stellar` | Stellar scheme (SEP-41 Soroban token transfers) |
| `@x402/aptos` | Aptos scheme (Fungible Asset transfers) |
| `@x402/avm` | Algorand (AVM) scheme |
| `@x402/hedera` | Hedera scheme (HBAR + HTS fungible-asset transfers) |
| `@x402/tvm` | TON scheme (jetton transfers) |
| `@x402/keeta` | Keeta scheme (exact) |
| `@x402/concordium` | Concordium scheme (native CCD, exact) |
| `@x402/near` | NEAR scheme (NEP-366 SignedDelegate + NEP-141 `ft_transfer`, relayer-sponsored) |
| `@x402/xrpl` | XRPL scheme (payer-signed `Payment`, no fee sponsorship). Tagged 2.20.0 but **not yet on npm** - build from source |
| `@x402/express` | Express middleware |
| `@x402/fastify` | Fastify middleware |
| `@x402/hono` | Hono edge middleware |
| `@x402/next` | Next.js middleware |
| `@x402/axios` | Axios interceptor |
| `@x402/fetch` | Fetch wrapper |
| `@x402/paywall` | Browser paywall UI |
| `@x402/mcp` | MCP client + server |
| `@x402/extensions` | Bazaar, offer-receipt, payment-identifier, sign-in-with-x, gas sponsoring |
### Python v2.17.0 ([PyPI](https://pypi.org/project/x402/), [GitHub](https://github.com/x402-foundation/x402/tree/main/python))
```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](https://github.com/x402-foundation/x402/tree/main/go))
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](https://github.com/x402-foundation/x402/tree/main/java))
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
| File | Content |
|------|---------|
| `references/core-concepts.md` | HTTP 402 foundation, client/server/facilitator roles, wallet identity, networks, tokens, custom token config, dynamic registration, self-hosted facilitator, mainnet deployment |
| `references/protocol-spec.md` | v2 protocol types, payment flow, facilitator API, error codes |
| `references/typescript-sdk.md` | TypeScript SDK patterns for server, client, MCP, paywall, facilitator |
| `references/python-sdk.md` | Python SDK patterns for server, client, MCP (server + client), facilitator |
| `references/go-sdk.md` | Go SDK patterns for server, client, MCP, facilitator, signers, custom money parser |
| `references/evm-scheme.md` | EVM exact scheme: EIP-3009, Permit2, default asset resolution, registerMoneyParser, custom tokens |
| `references/svm-scheme.md` | Solana exact scheme: SPL TransferChecked, verification rules, duplicate settlement mitigation |
| `references/stellar-scheme.md` | Stellar exact scheme: SEP-41 Soroban token transfers, ledger-based expiration, fee sponsorship, TypeScript SDK only |
| `references/upto-scheme.md` | Upto (usage-based) scheme: authorize max amount, settle actual usage. EVM via Permit2 only |
| `references/aptos-scheme.md` | Aptos exact scheme: fungible asset transfers, fee payer sponsorship, TypeScript SDK only |
| `references/near-scheme.md` | NEAR exact scheme: NEP-366 SignedDelegate, NEP-141 `ft_transfer`, relayer gas sponsorship, full-access-key requirement, NEP-145 storage registration |
| `references/xrpl-scheme.md` | XRPL exact scheme: payer-signed `Payment`, no fee sponsorship, explicit `AssetAmount` pricing, sequence vs ticketSequence |
| `references/transports.md` | HTTP, MCP, A2A transport implementations |
| `references/extensions.md` | Bazaar, payment-identifier, sign-in-with-x, gas sponsoring (eip2612 + erc20) extensions |
| `references/lifecycle-hooks.md` | Client/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](https://docs.x402.org/dev-tools/facilitators) - named production and community facilitators
- [Third-party SDKs](https://docs.x402.org/dev-tools/third-party-sdks) - Rust (`x402-rs`), Java (Mogami), Ruby (x402-rails), and others beyond the three official bindings
- [Third-party extensions](https://docs.x402.org/dev-tools/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