x402

What this skill does

# 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**, or **Aptos** 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 |
| Mezo Testnet | `eip155:31611` | Testnet (mUSD, Permit2 + EIP-2612) |
| Avalanche | `eip155:43114` | Via 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 SDK) |
| TON Testnet | `tvm:-3` | Testnet |
| Hedera Mainnet | `hedera:mainnet` | Mainnet (HBAR + HTS tokens) |
| Hedera Testnet | `hedera:testnet` | Testnet |
| Algorand Mainnet | `algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=` | Mainnet (USDC ASA) |

Default facilitator (`https://x402.org/facilitator`) supports Base Sepolia, Solana Devnet, Stellar Testnet, and Aptos Testnet.

## SDK Package