x402

https://docs.x402.org/
Admin
x402 is an open payment standard that enables services to charge for access to their APIs and...
Tokens:47,977
Snippets:400
Trust Score:7.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Clone and Build x402 Example

Source: https://docs.x402.org/guides/mcp-server-with-x402

Clone the x402 repository, install dependencies, and build the packages. Navigate to the MCP client example directory.

```bash
# Clone the x402 repository
git clone https://github.com/coinbase/x402.git
cd x402/examples/typescript

# Install dependencies and build packages
pnpm install && pnpm build

# Navigate to the MCP client example
cd clients/mcp
```

--------------------------------

### Install Go Dependency for x402

Source: https://docs.x402.org/getting-started/quickstart-for-buyers

Add the x402 Go module to your project using the go get command.

```bash
go get github.com/coinbase/x402/go
```

--------------------------------

### Install x402 Dependencies

Source: https://docs.x402.org/getting-started/quickstart-for-sellers

Install the required x402 middleware and core packages for your specific web framework.

```bash
npm install @x402/express @x402/core @x402/evm @x402/svm
```

```bash
npm install @x402/next @x402/core @x402/evm @x402/svm
```

```bash
npm install @x402/hono @x402/core @x402/evm @x402/svm
```

```bash
npm install @x402/fastify @x402/core @x402/evm @x402/svm
```

```bash
go get github.com/coinbase/x402/go
```

```bash
pip install "x402[fastapi]"

# For Solana support, also add:
pip install "x402[svm]"
```

```bash
pip install "x402[flask]"

# For Solana support, also add:
pip install "x402[svm]"
```

--------------------------------

### Install x402 Packages

Source: https://docs.x402.org/extensions/offer-receipt

Install the necessary x402 packages using npm. Ensure Node.js 18+ is installed.

```bash
npm install @x402/express @x402/extensions @x402/evm @x402/core viem
```

--------------------------------

### Install x402 V2 with extras

Source: https://docs.x402.org/guides/migration-v1-to-v2

Use pip to install the x402 package with specific extras required for your environment, such as async/sync HTTP clients or framework support.

```bash
# V1
pip install x402

# V2 - install with specific extras
pip install "x402[httpx]"      # For async HTTP clients
pip install "x402[requests]"   # For sync HTTP clients
pip install "x402[fastapi]"    # For FastAPI servers
pip install "x402[flask]"      # For Flask servers
pip install "x402[svm]"        # For Solana support
```

--------------------------------

### Install X402 TypeScript Packages

Source: https://docs.x402.org/guides/migration-v1-to-v2

Use these commands to install the necessary V2 packages for buyer or seller implementations.

```bash
# For buyers
npm install @x402/axios @x402/evm

# For sellers (Express)
npm install @x402/express @x402/core @x402/evm
```

--------------------------------

### Initialize FastAPI Application

Source: https://docs.x402.org/getting-started/quickstart-for-sellers

Setup boilerplate for a FastAPI application with x402 dependencies.

```python
from typing import Any

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.mechanisms.svm.exact import ExactSvmServerScheme
from x402.schemas import Network
from x402.server import x402ResourceServer

app = FastAPI()

# Your receiving wallet addresses
```

--------------------------------

### Install X402 Python Packages

Source: https://docs.x402.org/guides/migration-v1-to-v2

Install the x402 package with specific extras based on your HTTP client, server framework, or network requirements.

```bash
# For async HTTP clients (httpx)
pip install "x402[httpx]"

# For sync HTTP clients (requests)
pip install "x402[requests]"

# For FastAPI servers
pip install "x402[fastapi]"

# For Flask servers
pip install "x402[flask]"

# For Solana support
pip install "x402[svm]"
```

--------------------------------

### Install Python Dependencies for x402

Source: https://docs.x402.org/getting-started/quickstart-for-buyers

Install the x402 Python package. Use the [httpx] extra for asynchronous HTTP requests (recommended) or [requests] for synchronous requests. Add [svm] for Solana support.

```bash
# For httpx (async) - recommended
pip install "x402[httpx]"

# For requests (sync)
pip install "x402[requests]"

# For Solana support, also add:
pip install "x402[svm]"
```

--------------------------------

### Start the x402 Express Server

Source: https://docs.x402.org/guides/mcp-server-with-x402

Run the x402-compatible Express server. Ensure it is accessible at the URL specified in `RESOURCE_SERVER_URL`.

```bash
# In another terminal, from the examples/typescript directory
cd servers/express
pnpm dev
```

--------------------------------

### Manual Usage (Advanced)

Source: https://docs.x402.org/extensions/sign-in-with-x

Provides a TypeScript example for custom SIWx implementations, including steps to get extension and network details, build complete info, create a signed payload, and encode the header for sending.

```APIDOC
## Manual Usage (Advanced)

For custom implementations:

### TypeScript Example

```typescript
import {
  createSIWxPayload,
  encodeSIWxHeader,
} from '@x402/extensions/sign-in-with-x';

// 1. Get extension and network from 402 response
const paymentRequired = await response.json();
const extension = paymentRequired.extensions['sign-in-with-x'];
const paymentNetwork = paymentRequired.accepts[0].network; // e.g., "eip155:8453"

// 2. Find matching chain in supportedChains
const matchingChain = extension.supportedChains.find(
  chain => chain.chainId === paymentNetwork
);

if (!matchingChain) {
  throw new Error('Chain not supported');
}

// 3. Build complete info with selected chain
const completeInfo = {
  ...extension.info,
  chainId: matchingChain.chainId,
  type: matchingChain.type,
};

// 4. Create signed payload
const payload = await createSIWxPayload(completeInfo, signer);

// 5. Encode and send
const header = encodeSIWxHeader(payload);
const response = await fetch(url, {
  headers: { 'SIGN-IN-WITH-X': header }
});
```
```

--------------------------------

### Registering an Extension (Server)

Source: https://docs.x402.org/extensions/overview

Example of how to register a ResourceServerExtension with the x402 resource server.

```APIDOC
## Registering an Extension (Server)

Extensions implement the `ResourceServerExtension` interface and are registered via `registerExtension`:

```typescript
import { x402ResourceServer } from "@x402/express";

const resourceServer = new x402ResourceServer(facilitatorClient)
  .register("eip155:84532", new ExactEvmScheme())
  .registerExtension(myExtension)       // Add one extension
  .registerExtension(anotherExtension); // Stack another
```

Each extension has a unique `key` that identifies it in route declarations and response payloads.
```

--------------------------------

### Create Python EVM Wallet Signer with eth-account

Source: https://docs.x402.org/getting-started/quickstart-for-buyers

Install the eth_account package. Then, instantiate an EVM wallet signer using a private key from an environment variable.

```bash
pip install eth_account
```

```python
import os
from eth_account import Account
from x402.mechanisms.evm import EthAccountSigner

account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
signer = EthAccountSigner(account)
```

--------------------------------

### Install Node.js Dependencies for x402

Source: https://docs.x402.org/getting-started/quickstart-for-buyers

Install the x402 client packages for Node.js. Choose packages based on your HTTP client (fetch or Axios) and add SVM, Aptos, or Stellar support as needed.

```bash
# For fetch-based clients
npm install @x402/fetch @x402/evm

# For axios-based clients
npm install @x402/axios @x402/evm

# For Solana support, also add:
npm install @x402/svm

# For Aptos support, also add:
npm install @x402/aptos

# For Stellar support, also add:
npm install @x402/stellar
```

--------------------------------

### Create Node.js EVM Wallet Signer with viem

Source: https://docs.x402.org/getting-started/quickstart-for-buyers

Install the viem package and then instantiate an EVM wallet signer from a private key stored in an environment variable.

```bash
npm install viem
```

```typescript
import { privateKeyToAccount } from "viem/accounts";

// Create a signer from private key (use environment variable)
const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
```

--------------------------------

### MakeRequest Function Example

Source: https://docs.x402.org/extensions/payment-identifier

This Go code demonstrates making a request and then retrying with the same payment ID, showing how a cached response might be returned on the second attempt.

```Go
response1, err := client.MakeRequest(url)

    // Retry with same payment ID - cached response returned (no payment)
    response2, err := client.MakeRequest(url)
```

--------------------------------

### Register Server Hook for Post-Settlement Actions (Go)

Source: https://docs.x402.org/advanced-concepts/lifecycle-hooks

Use `OnAfterSettle` to hook into the post-settlement event. This Go example demonstrates recording payment details using a closure.

```go
import x402 "github.com/coinbase/x402/go"

server := x402.Newx402ResourceServer(facilitatorClient)

server.OnAfterSettle(func(ctx x402.SettleResultContext) error {
    return db.RecordPayment(Payment{
        Payer:       ctx.Result.Payer,
        Transaction: ctx.Result.Transaction,
        Amount:      ctx.Requirements.Amount,
        Network:     ctx.Requirements.Network,
    })
})
```

--------------------------------

### Express Server Setup with EIP-712

Source: https://docs.x402.org/extensions/offer-receipt

Sets up an Express server with the x402 payment middleware and EIP-712 offer-receipt extension. Ensure environment variables like EVM_ADDRESS, SIGNING_PRIVATE_KEY, and FACILITATOR_URL are configured.

```typescript
import { config } from "dotenv";
import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";
import {
  createOfferReceiptExtension,
  createEIP712OfferReceiptIssuer,
  declareOfferReceiptExtension,
} from "@x402/extensions/offer-receipt";
import { privateKeyToAccount } from "viem/accounts";

config();

const evmAddress = process.env.EVM_ADDRESS as `0x${string}`;
const signingPrivateKey = process.env.SIGNING_PRIVATE_KEY as `0x${string}`;
const facilitatorUrl = process.env.FACILITATOR_URL!;

const signingAccount = privateKeyToAccount(signingPrivateKey);
const kid = `did:pkh:eip155:1:${signingAccount.address}#key-1`;

const offerReceiptIssuer = createEIP712OfferReceiptIssuer(
  kid,
  signingAccount.signTypedData.bind(signingAccount)
);

const facilitatorClient = new HTTPFacilitatorClient({ url: facilitatorUrl });
const resourceServer = new x402ResourceServer(facilitatorClient)
  .register("eip155:84532", new ExactEvmScheme())
  .registerExtension(createOfferReceiptExtension(offerReceiptIssuer));

const app = express();

app.use(
  paymentMiddleware(
    {
      "GET /api/data": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.001",
            network: "eip155:84532",
            payTo: evmAddress,
          },
        ],
        description: "Premium data endpoint",
        mimeType: "application/json",
        extensions: {
          ...declareOfferReceiptExtension({ includeTxHash: false }),
        },
      },
    },
    resourceServer,
  )
);

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

app.listen(4021, () => {
  console.log("Server listening on http://localhost:4021");
  console.log("Offer-receipt extension enabled (EIP-712)");
});

```

--------------------------------

### Python V2 Payment Middleware Setup

Source: https://docs.x402.org/guides/migration-v1-to-v2

V2 Python utilizes `x402ResourceServer` and `PaymentMiddlewareASGI` with `RouteConfig` for payment options, including CAIP-2 network identifiers.

```python
from typing import Any

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

# V2 pattern: Create facilitator client and resource server
facilitator = HTTPFacilitatorClient(
    FacilitatorConfig(url="https://x402.org/facilitator")
)

server = x402ResourceServer(facilitator)
server.register("eip155:84532", ExactEvmServerScheme())

# V2: Route config uses accepts array with explicit scheme, network, and pay_to
routes: dict[str, RouteConfig] = {
    "GET /weather": RouteConfig(
        accepts=[
            PaymentOption(
                scheme="exact",
                pay_to="0xYourAddress",
                price="$0.001",
                network="eip155:84532",  # V2 CAIP-2 format
            ),
        ],
        mime_type="application/json",
        description="Get weather data",
    ),
}

app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)


@app.get("/weather")
async def get_weather() -> dict[str, Any]:
    return {"report": {"weather": "sunny", "temperature": 70}}
```

--------------------------------

### Multi-Chain Support Configuration

Source: https://docs.x402.org/extensions/sign-in-with-x

Demonstrates how to configure servers to support multiple blockchain networks for SIWx authentication, including example routes and the structure of the `accepts` and `extensions` fields.

```APIDOC
## Multi-Chain Support

Servers can support multiple chains (e.g., both EVM and Solana) by including multiple entries in `supportedChains`:

### TypeScript Example

```typescript
const routes = {
  'GET /data': {
    accepts: [
      {
        scheme: 'exact',
        price: '$0.01',
        network: 'eip155:8453', // Base
        payTo: '0xYourAddress'
      },
      {
        scheme: 'exact',
        price: '$0.01',
        network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', // Solana mainnet
        payTo: 'YourSolanaAddress'
      }
    ],
    extensions: declareSIWxExtension({
      network: ['eip155:8453', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'],
      statement: 'Sign in to access your purchased content',
    }),
  },
};
```

Clients match their wallet's `chainId` against `supportedChains` and use the first matching entry. The same `nonce` is shared across all chains, preventing replay attacks when authenticating with different wallets.
```

--------------------------------

### Call Discovered Service with Python

Source: https://docs.x402.org/extensions/bazaar

Utilize the x402 client in Python to interact with discovered services. This example shows how to register an EVM exact client and make an HTTP request using the httpx client.

```python
import asyncio

from eth_account import Account

from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


async def main() -> None:
    account = Account.from_key("0xYourPrivateKey")
    client = x402Client()
    register_exact_evm_client(client, EthAccountSigner(account))

    # Select a service from discovery (from Step 1)
    selected_service = affordable_services[0]

    # Select the payment method of your choice
    selected_payment_requirements = selected_service.accepts[0]
    input_schema = selected_payment_requirements.output_schema.input

    # Make the request using httpx client
    async with x402HttpxClient(client) as http:
        response = await http.request(
            method=input_schema.method,
            url=input_schema.resource,
            params={"location": "San Francisco"}  # Based on input_schema
        )
        await response.aread()
        print(f"Response data: {response.json()}")


asyncio.run(main())
```

--------------------------------

### Discover Resources Endpoint

Source: https://docs.x402.org/extensions/bazaar

Use this GET endpoint to discover available resources. It is recommended to use the `useFacilitator` hook for integration.

```bash
GET https://facilitator.payai.network/discovery/resources
```

--------------------------------

### EIP-712 Setup with Server Wallet

Source: https://docs.x402.org/extensions/offer-receipt

Use this pattern when your wallet provider manages private keys and offers a signTypedData API. The private key never leaves the provider's infrastructure.

```typescript
import {
  createOfferReceiptExtension,
  createEIP712OfferReceiptIssuer,
} from "@x402/extensions/offer-receipt";

// The provider's SDK gives you a signTypedData function
// that calls their API — the private key never leaves their infrastructure
const signerAddress = "0xYourServerWalletAddress";
const kid = `did:pkh:eip155:1:${signerAddress}#key-1`;

const offerReceiptIssuer = createEIP712OfferReceiptIssuer(kid, async (params) => {
  // Call your wallet provider's signing API
  return await yourWalletProvider.signTypedData({
    domain: params.domain,
    types: params.types,
    primaryType: params.primaryType,
    message: params.message,
  });
});

// Register as usual
resourceServer.registerExtension(createOfferReceiptExtension(offerReceiptIssuer));
```

--------------------------------

### Register Server Hook for Post-Settlement Actions (Python)

Source: https://docs.x402.org/advanced-concepts/lifecycle-hooks

Use `on_after_settle` to perform actions after successful settlement. This example shows how to record payment information asynchronously.

```python
from x402 import x402ResourceServer

server = x402ResourceServer(facilitator_client)

async def record_payment(context):
    await db.record_payment(
        payer=context.result.payer,
        transaction=context.result.transaction,
        amount=context.requirements.amount,
        network=context.requirements.network,
    )

server.on_after_settle(record_payment)
```

--------------------------------

### FastAPI Server with x402 Payment Middleware

Source: https://docs.x402.org/getting-started/quickstart-for-sellers

Set up a FastAPI application to handle protected routes with payment requirements. Ensure the facilitator URL and network configurations are correct. This example uses the HTTPFacilitatorClient for asynchronous operations.

```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.mechanisms.svm.exact import ExactSvmServerScheme
from x402.schemas import Network
from x402.server import x402ResourceServer

app = FastAPI()

# Your receiving wallet addresses
ev_address = "0xYourEvmAddress"
svm_address = "YourSolanaAddress"
EVM_NETWORK: Network = "eip155:84532"  # Base Sepolia
SVM_NETWORK: Network = "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"  # Solana Devnet

# Create facilitator client (testnet)
facilitator = HTTPFacilitatorClient(
    FacilitatorConfig(url="https://x402.org/facilitator")
)

# Create resource server and register schemes
server = x402ResourceServer(facilitator)
server.register(EVM_NETWORK, ExactEvmServerScheme())
server.register(SVM_NETWORK, ExactSvmServerScheme())

# Define protected routes
routes: dict[str, RouteConfig] = {
    "GET /weather": RouteConfig(
        accepts=[
            PaymentOption(
                scheme="exact",
                pay_to=evm_address,
                price="$0.001",
                network=EVM_NETWORK,
            ),
            PaymentOption(
                scheme="exact",
                pay_to=svm_address,
                price="$0.001",
                network=SVM_NETWORK,
            ),
        ],
        mime_type="application/json",
        description="Weather report",
    ),
}

# Add payment middleware
app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)


@app.get("/weather")
async def get_weather() -> dict[str, Any]:
    return {
        "report": {
            "weather": "sunny",
            "temperature": 70,
        }
    }


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=4021)

```

--------------------------------

### TypeScript V1 Payment Middleware Setup

Source: https://docs.x402.org/guides/migration-v1-to-v2

Before V2, payment middleware in TypeScript required direct string network identifiers and a simpler configuration object.

```typescript
import { paymentMiddleware, FacilitatorConfig } from "x402-express";
import express from "express";

const app = express();

const facilitatorConfig: FacilitatorConfig = {
  url: "https://x402.org/facilitator",
};

app.use(
  paymentMiddleware(facilitatorConfig, {
    "GET /weather": {
      price: "$0.001",
      network: "base-sepolia", // V1 string format
      config: {
        description: "Get weather data",
      },
    },
  }),
);
```

--------------------------------

### Flask Server with x402 Payment Middleware

Source: https://docs.x402.org/getting-started/quickstart-for-sellers

Implement a Flask application to enforce payments for specific routes using x402. This example utilizes the synchronous HTTPFacilitatorClientSync. Ensure your wallet addresses and network configurations are correctly set.

```python
from flask import Flask, jsonify

from x402.http import FacilitatorConfig, HTTPFacilitatorClientSync, PaymentOption
from x402.http.middleware.flask import payment_middleware
from x402.http.types import RouteConfig
from x402.mechanisms.evm.exact import ExactEvmServerScheme
from x402.mechanisms.svm.exact import ExactSvmServerScheme
from x402.schemas import Network
from x402.server import x402ResourceServerSync

app = Flask(__name__)

# Your receiving wallet addresses
ev_address = "0xYourEvmAddress"
svm_address = "YourSolanaAddress"
EVM_NETWORK: Network = "eip155:84532"  # Base Sepolia
SVM_NETWORK: Network = "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"  # Solana Devnet

facilitator = HTTPFacilitatorClientSync(
    FacilitatorConfig(url="https://x402.org/facilitator")
)

server = x402ResourceServerSync(facilitator)
server.register(EVM_NETWORK, ExactEvmServerScheme())
server.register(SVM_NETWORK, ExactSvmServerScheme())

routes: dict[str, RouteConfig] = {
    "GET /weather": RouteConfig(
        accepts=[
            PaymentOption(
                scheme="exact",
                pay_to=evm_address,
                price="$0.001",
                network=EVM_NETWORK,
            ),
            PaymentOption(
                scheme="exact",
                pay_to=svm_address,
                price="$0.001",
                network=SVM_NETWORK,
            ),
        ],
        mime_type="application/json",
        description="Weather report",
    ),
}

payment_middleware(app, routes=routes, server=server)


@app.route("/weather")
def get_weather():
    return jsonify({
        "report": {
            "weather": "sunny",
            "temperature": 70,
        }
    })


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=4021)

```

--------------------------------

### Environment Variables for Server Configuration

Source: https://docs.x402.org/extensions/offer-receipt

Defines necessary environment variables for server setup, including payment wallet address, facilitator URL, signing private key, and server domain for did:web.

```bash
EVM_ADDRESS=0xYourPaymentWalletAddress
FACILITATOR_URL=https://facilitator.x402.org

# Base64-encoded PKCS#8 private key (EC P-256)
# For production deployments, do not store private keys in an environment variable
SIGNING_PRIVATE_KEY=base64EncodedPrivateKey

# Your server's domain (URL-encoded for did:web)
# e.g., "api.example.com" or "localhost%3A4021" for local dev
SERVER_DOMAIN=api.example.com
```

--------------------------------

### List Available x402 Services (Coinbase)

Source: https://docs.x402.org/extensions/bazaar

Use this GET request to retrieve all x402-compatible endpoints and MCP tools registered through the Coinbase facilitator. This endpoint is part of the Bazaar's discovery mechanism.

```bash
GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources
```

--------------------------------

### Implement x402 with net/http

Source: https://docs.x402.org/getting-started/quickstart-for-sellers

Full server implementation using the standard library net/http ServeMux and x402 middleware.

```go
package main

import (
    "encoding/json"
    "net/http"
    "time"

    x402 "github.com/coinbase/x402/go"
    x402http "github.com/coinbase/x402/go/http"
    nethttpmw "github.com/coinbase/x402/go/http/nethttp"
    evm "github.com/coinbase/x402/go/mechanisms/evm/exact/server"
    svm "github.com/coinbase/x402/go/mechanisms/svm/exact/server"
)

func main() {
    evmAddress := "0xYourEvmAddress"
    svmAddress := "YourSolanaAddress"
    evmNetwork := x402.Network("eip155:84532")                              // Base Sepolia
    svmNetwork := x402.Network("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1")  // Solana Devnet

    // Create facilitator client
    facilitatorClient := x402http.NewHTTPFacilitatorClient(&x402http.FacilitatorConfig{
        URL: "https://x402.org/facilitator",
    })

    // Configure routes
    routes := x402http.RoutesConfig{
        "GET /weather": {
            Accepts: x402http.PaymentOptions{
                {
                    Scheme:  "exact",
                    Price:   "$0.001",
                    Network: "eip155:84532",
                    PayTo:   evmAddress,
                },
                {
                    Scheme:  "exact",
                    Price:   "$0.001",
                    Network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
                    PayTo:   svmAddress,
                },
            },
            Description: "Get weather data for a city",
            MimeType:    "application/json",
        },
    }

    // Create ServeMux and register handlers
    mux := http.NewServeMux()

    // Protected endpoint
    mux.HandleFunc("GET /weather", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusOK)
        json.NewEncoder(w).Encode(map[string]interface{}{
            "weather":     "sunny",
            "temperature": 70,
        })
    })

    // Apply x402 payment middleware
    handler := nethttpmw.X402Payment(nethttpmw.Config{
        Routes:      routes,
        Facilitator: facilitatorClient,
        Schemes: []nethttpmw.SchemeConfig{
            {Network: evmNetwork, Server: evm.NewExactEvmScheme()},
            {Network: svmNetwork, Server: svm.NewExactSvmScheme()},
        },
        Timeout: 30 * time.Second,
    })(mux)

    http.ListenAndServe(":4021", handler)
}
```

--------------------------------

### Declaring Extensions on Routes

Source: https://docs.x402.org/extensions/overview

Example of how to declare extensions for a specific route using the payment middleware configuration.

```APIDOC
## Declaring Extensions on Routes

Extensions are declared per-route in the payment middleware configuration. Each extension's declaration goes under `extensions` keyed by the extension's `key`:

```typescript
app.use(
  paymentMiddleware(
    {
      "GET /api/data": {
        accepts: [{ scheme: "exact", price: "$0.01", network: "eip155:84532", payTo: address }],
        description: "Premium data",
        mimeType: "application/json",
        extensions: {
          // Each key matches a registered extension
          "offer-receipt": { includeTxHash: false },
          "bazaar": { /* bazaar config */ },
        },
      },
    },
    resourceServer,
  ),
);
```

If an extension is declared on a route but not registered on the server, it is silently ignored.
```

--------------------------------

### Integrate X402 with Go Gin

Source: https://docs.x402.org/getting-started/quickstart-for-sellers

Initializes the X402 facilitator client for a Gin web server.

```go
package main

import (
    "net/http"
    "time"

    x402 "github.com/coinbase/x402/go"
    x402http "github.com/coinbase/x402/go/http"
    ginmw "github.com/coinbase/x402/go/http/gin"
    evm "github.com/coinbase/x402/go/mechanisms/evm/exact/server"
    svm "github.com/coinbase/x402/go/mechanisms/svm/exact/server"
    "github.com/gin-gonic/gin"
)

func main() {
    evmAddress := "0xYourEvmAddress"
    svmAddress := "YourSolanaAddress"
    evmNetwork := x402.Network("eip155:84532")                              // Base Sepolia
    svmNetwork := x402.Network("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1")  // Solana Devnet

    r := gin.Default()

    // Create facilitator client
    facilitatorClient := x402http.NewHTTPFacilitatorClient(&x402http.FacilitatorConfig{
        URL: "https://x402.org/facilitator",
    })
```

--------------------------------

### Buyer Implementation V1 (Python)

Source: https://docs.x402.org/guides/migration-v1-to-v2

Uses the legacy x402.clients.httpx client for V1 payment handling.

```python
import os

from eth_account import Account

from x402.clients.httpx import x402HttpxClient

# V1 pattern
account = Account.from_key(os.getenv("PRIVATE_KEY"))

async with x402HttpxClient(account=account, base_url="https://api.example.com") as client:
    response = await client.get("/protected-endpoint")
    print(await response.aread())
```

--------------------------------

### Bazaar Settlement Response Header Example (Success)

Source: https://docs.x402.org/extensions/bazaar

This header indicates that discovery information was validated and successfully cataloged by the Bazaar extension. It is base64 encoded.

```http
EXTENSION-RESPONSES: eyJiYXphYXIiOnsic3RhdHVzIjoic3VjY2VzcyJ9fQ==
```

--------------------------------

### Successful Response from MCP Server

Source: https://docs.x402.org/guides/mcp-server-with-x402

Example of a successful response from the MCP server after payment has been processed. The content includes a JSON object with weather data.

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"report\":{\"weather\":\"sunny\",\"temperature\":70}}"
    }
  ]
}

```

--------------------------------

### TypeScript V2 Payment Middleware Setup

Source: https://docs.x402.org/guides/migration-v1-to-v2

V2 TypeScript payment middleware uses a `x402ResourceServer` and CAIP-2 network identifiers for more robust network configuration.

```typescript
import express from "express";
import { paymentMiddleware } from "@x402/express";
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";

const app = express();
const payTo = "0xYourAddress";

// V2 pattern: Create facilitator client and resource server
const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://x402.org/facilitator"
});

const server = new x402ResourceServer(facilitatorClient);
server.register("eip155:*", new ExactEvmScheme());

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

--------------------------------

### Create Go EVM Wallet Signer

Source: https://docs.x402.org/getting-started/quickstart-for-buyers

Import the necessary package and load an EVM private key from the environment to create a client signer.

```go
import (
    evmsigners "github.com/coinbase/x402/go/signers/evm"
)

// Load private key from environment
evmSigner, err := evmsigners.NewClientSignerFromPrivateKey(os.Getenv("EVM_PRIVATE_KEY"))
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Create MCP Server with x402 Axios Client

Source: https://docs.x402.org/guides/mcp-server-with-x402

Sets up an MCP server and configures an axios client with x402 payment support for EVM and/or SVM. Requires environment variables for private keys and server URL.

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import axios from "axios";
import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";
import { config } from "dotenv";

config();

const evmPrivateKey = process.env.EVM_PRIVATE_KEY as `0x${string}`;
const svmPrivateKey = process.env.SVM_PRIVATE_KEY as string;
const baseURL = process.env.RESOURCE_SERVER_URL || "http://localhost:4021";
const endpointPath = process.env.ENDPOINT_PATH || "/weather";

if (!evmPrivateKey && !svmPrivateKey) {
  throw new Error("At least one of EVM_PRIVATE_KEY or SVM_PRIVATE_KEY must be provided");
}

/**
 * Creates an axios client configured with x402 payment support for EVM and/or SVM.
 */
async function createClient() {
  const client = new x402Client();

  // Register EVM scheme if private key is provided
  if (evmPrivateKey) {
    const evmSigner = privateKeyToAccount(evmPrivateKey);
    client.register("eip155:*", new ExactEvmScheme(evmSigner));
  }

  // Register SVM scheme if private key is provided
  if (svmPrivateKey) {
    const svmSigner = await createKeyPairSignerFromBytes(base58.decode(svmPrivateKey));
    client.register("solana:*", new ExactSvmScheme(svmSigner));
  }

  return wrapAxiosWithPayment(axios.create({ baseURL }), client);
}

async function main() {
  const api = await createClient();

  // Create an MCP server
  const server = new McpServer({
    name: "x402 MCP Client Demo",
    version: "2.0.0",
  });

  // Add a tool that calls the paid API
  server.tool(
    "get-data-from-resource-server",
    "Get data from the resource server (in this example, the weather)",
    {},
    async () => {
      const res = await api.get(endpointPath);
      return {
        content: [{ type: "text", text: JSON.stringify(res.data) }],
      };
    },
  );

  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(error => {
  console.error(error);
  process.exit(1);
});

```

--------------------------------

### Buyer Implementation V2 (Python)

Source: https://docs.x402.org/guides/migration-v1-to-v2

Uses the modular x402 client architecture to register schemes and handle payment settlement.

```python
import asyncio
import os

from eth_account import Account

from x402 import x402Client
from x402.http import x402HTTPClient
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client


async def main() -> None:
    # V2 pattern: Create client and register scheme separately
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    http_client = x402HTTPClient(client)

    async with x402HttpxClient(client) as http:
        response = await http.get("https://api.example.com/paid-endpoint")
        await response.aread()

        print(f"Response: {response.text}")

        if response.is_success:
            settle_response = http_client.get_payment_settle_response(
                lambda name: response.headers.get(name)
            )
            print(f"Payment settled: {settle_response}")


asyncio.run(main())
```

--------------------------------

### Next.js Payment Proxy Configuration

Source: https://docs.x402.org/getting-started/quickstart-for-sellers

Configures the payment proxy for Next.js applications to protect page routes. This setup uses a central proxy configuration file.

```typescript
// proxy.ts
import { paymentProxy } from "@x402/next";
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { ExactSvmScheme } from "@x402/svm/exact/server";

export const evmAddress = "0xYourEvmAddress";
export const svmAddress = "YourSolanaAddress";

const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://x402.org/facilitator"
});

export const server = new x402ResourceServer(facilitatorClient);
server.register("eip155:*", new ExactEvmScheme());
server.register("solana:*", new ExactSvmScheme());

export const proxy = paymentProxy(
  {
    "/protected": {
      accepts: [
        {
          scheme: "exact",
          price: "$0.001",
          network: "eip155:84532", // Base Sepolia
          payTo: evmAddress,
        },
        {
          scheme: "exact",
          price: "$0.001",
          network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", // Solana Devnet
          payTo: svmAddress,
        },
      ],
      description: "Premium content",
      mimeType: "text/html",
    },
  },
  server,
);

export const config = {
  matcher: ["/protected/:path*"],
};

```

--------------------------------

### Configure Multi-Chain Support

Source: https://docs.x402.org/extensions/sign-in-with-x

Shows how to define multiple networks in the server routes to support diverse wallet types like EVM and Solana.

```typescript
const routes = {
  'GET /data': {
    accepts: [
      {
        scheme: 'exact',
        price: '$0.01',
        network: 'eip155:8453', // Base
        payTo: '0xYourAddress'
      },
      {
        scheme: 'exact',
        price: '$0.01',
        network: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', // Solana mainnet
        payTo: 'YourSolanaAddress'
      }
    ],
    extensions: declareSIWxExtension({
      network: ['eip155:8453', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'],
      statement: 'Sign in to access your purchased content',
    }),
  },
};
```

--------------------------------

### Python V1 Payment Middleware Setup

Source: https://docs.x402.org/guides/migration-v1-to-v2

In V1 Python, payment requirements were configured directly within the `require_payment` decorator or middleware, using string network identifiers.

```python
from typing import Any, Dict

from fastapi import FastAPI

from x402.fastapi.middleware import require_payment

app = FastAPI()

# V1 pattern
app.middleware("http")(
    require_payment(
        path="/weather",
        price="$0.001",
        pay_to_address="0xYourAddress",
        network="base-sepolia",  # V1 string identifier
    )
)

@app.get("/weather")
async def get_weather() -> Dict[str, Any]:
    return {"report": {"weather": "sunny", "temperature": 70}}
```

--------------------------------

### Configure x402 Middleware with Metadata

Source: https://docs.x402.org/extensions/bazaar

Define routes with Bazaar discovery metadata to enable agent interaction. Ensure descriptions are provided for all parameters.

```typescript
import { paymentMiddleware } from "@x402/express";
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { bazaarResourceServerExtension } from "@x402/extensions";

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

const routes = {
  "GET /weather": {
    price: "$0.001",
    network: "eip155:8453",
    resource: "0xYourAddress",
    description: "Get current weather data for any location",
    extensions: {
      bazaar: {
        discoverable: true,
        inputSchema: {
          queryParams: {
            location: {
              type: "string",
              description: "City name or coordinates",
              required: true
            }
          }
        },
        outputSchema: {
          type: "object",
          properties: {
            temperature: { type: "number" },
            conditions: { type: "string" },
            humidity: { type: "number" }
          }
        }
      }
    }
  }
};

app.use(paymentMiddleware(routes, server));
```

```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()

# Create facilitator client (CDP mainnet)
facilitator = HTTPFacilitatorClient(
    FacilitatorConfig(url="https://x402.org/facilitator")
)

# Create resource server and register EVM scheme
server = x402ResourceServer(facilitator)
server.register("eip155:8453", ExactEvmServerScheme())

# Define routes with Bazaar discovery metadata
routes: dict[str, RouteConfig] = {
    "GET /weather": RouteConfig(
        accepts=[
            PaymentOption(
                scheme="exact",
                pay_to="0xYourAddress",
                price="$0.001",
                network="eip155:8453",
            ),
        ],
        mime_type="application/json",
        description="Get current weather data for any location",
        extensions={
            "bazaar": {
                "discoverable": True,
                "inputSchema": {
                    "queryParams": {
                        "location": {
                            "type": "string",
                            "description": "City name or coordinates",
                            "required": True,
                        }
                    }
                },
                "outputSchema": {
                    "type": "object",
                    "properties": {
                        "temperature": {"type": "number"},
                        "conditions": {"type": "string"},
                        "humidity": {"type": "number"},
                    },
                },
            }
        },
    ),
}

app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)
```

```go
package main

import (
    x402 "github.com/coinbase/x402/go"
    "github.com/coinbase/x402/go/extensions/bazaar"
    "github.com/coinbase/x402/go/extensions/types"
    x402http "github.com/coinbase/x402/go/http"
    ginmw "github.com/coinbase/x402/go/http/gin"
    evm "github.com/coinbase/x402/go/mechanisms/evm/exact/server"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    facilitatorClient := x402http.NewHTTPFacilitatorClient(&x402http.FacilitatorConfig{
        URL: "https://x402.org/facilitator",
    })

    // Create Bazaar Discovery Extension with input/output schemas
    discoveryExtension, _ := bazaar.DeclareDiscoveryExtension(
        bazaar.MethodGET,
        map[string]interface{}{"location": "San Francisco"},
        types.JSONSchema{
            "properties": map[string]interface{}{
                "location": map[string]interface{}{
                    "type":        "string",
```

--------------------------------

### Bazaar Settlement Response Header Example (Rejected)

Source: https://docs.x402.org/extensions/bazaar

This header indicates that discovery information was rejected, likely due to failed schema validation. The `rejectedReason` field provides details. It is base64 encoded.

```http
EXTENSION-RESPONSES: eyJiYXphYXIiOnsic3RhdHVzIjoicmVqZWN0ZWQiLCJyZWplY3RlZFJlYXNvbiI6ImluZm8gZmFpbGVkIHNjaGVtYSB2YWxpZGF0aW9uIn19
```
Tokens:
Raw