x402

The x402 plugin enables tool monetization through the HTTP 402 payment protocol using USDC on Base.

Overview

The x402 plugin integrates the x402 payment protocol with your xmcp server, enabling you to charge USDC micropayments for tool usage on the Base blockchain.

Installation

Install the x402 plugin:

pnpm add @xmcp-dev/x402

Set up your wallet

Before integrating the plugin, you need a wallet address to receive payments:

Create or use an existing Ethereum-compatible wallet (e.g., Coinbase Wallet, MetaMask)
Get your wallet's public address (starts with 0x)
For testing, use Base Sepolia testnet and get test USDC from the Coinbase Developer Platform under Wallets > Faucet

The x402 protocol uses USDC stablecoin for payments. On Base mainnet, 1 USDC = 1 USD.

Environment Variables

Create a .env file in the root of your project and configure the following environment variables:

X402_WALLET=0x...

# Optional: Custom facilitator URL (defaults to https://x402.org/facilitator)
X402_FACILITATOR=https://x402.org/facilitator

Set up the Provider

Create a middleware.ts file in your xmcp app's src directory and import the provider from the package:

src/middleware.ts

import { x402Provider } from "@xmcp-dev/x402";

export default x402Provider({
  wallet: process.env.X402_WALLET!,
  defaults: {
    price: 0.01,
    network: "base-sepolia",
  },
});

Configuration Options

wallet: Your wallet address that receives payments
facilitator: (Optional) Facilitator URL (defaults to https://x402.org/facilitator)
debug: (Optional) Enable debug logging
defaults: (Optional) Default values for all paid tools
- price: Price in USDC (default: 0.01)
- currency: Currency code (default: "USDC")
- network: Blockchain network - "base" or "base-sepolia" (default: "base")
- maxPaymentAge: Maximum payment age in seconds (default: 300)

Monetize a Tool

Wrap your tool functions with paid() to require payment:

src/tools/analyze.ts

import { paid } from "@xmcp-dev/x402";

export default paid(
  { price: 0.05 },
  async function analyze({ data }) {
    // Tool logic here
    return `Analysis complete for: ${data}`;
  }
);

You can set a custom price for each tool by passing a price option to paid(). If not specified, the tool will use the default price from your provider configuration. If the provider doesn't specify a default price either, the tool will cost 0.01 USDC per call.

src/tools/premium-analysis.ts

import { paid } from "@xmcp-dev/x402";

// This tool costs 0.10 USDC per call
export default paid(
  { price: 0.10 },
  async function premiumAnalysis({ data }) {
    // Premium tool logic
    return `Premium analysis complete for: ${data}`;
  }
);

src/tools/basic-tool.ts

import { paid } from "@xmcp-dev/x402";

// This tool uses the provider's default price,
// or 0.01 USDC if no default is configured
export default paid(async function basicTool({ input }) {
  return `Processed: ${input}`;
});

Tool Options

price: Price in USDC for this tool (falls back to provider default, then 0.01 USDC)
network: Override default network
maxPaymentAge: Override maximum payment age
description: Description used in payment requirements

Get Payment Details

Access payment details inside your tool using the payment() function:

src/tools/paid-greet.ts

import { paid, payment } from "@xmcp-dev/x402";

export default paid(async function paidGreet({ name }) {
  const { payer, amount, network, transactionHash } = payment();

  return `Hello, ${name}! Payment received from ${payer}. Transaction: ${transactionHash}`;
});