x402-agent-mcp

Universal x402 agent MCP — discover and pay for any x402 endpoint on Base, Polygon, Arbitrum, Solana or Casper

What it does

An agent searches the directory, describes a service, then fetches its URL: the server pays the seller's 402 price with the operator's wallet and hands back the data. The agent never sees wallets, private keys or x402 protocol details — no API keys, no subscriptions, just a wallet.

Related MCP server: obolpay-x402-mcp

Quick start

git clone https://github.com/dchu3/x402-agent-mcp.git
cd x402-agent-mcp
npm install
npm run build

Point your MCP client config at the built server, passing the server's keys through env (only keys that exist in .env.example):

{
  "mcpServers": {
    "x402": {
      "command": "node",
      "args": ["/path/to/x402-agent-mcp/dist/index.js"],
      "env": {
        "X402_NETWORK_MODE": "mainnet",
        "SOLANA_PRIVATE_KEY": "<YOUR_SOLANA_PRIVATE_KEY>",
        "EVM_PRIVATE_KEY": "<YOUR_EVM_PRIVATE_KEY>",
        "CASPER_PRIVATE_KEY": "<YOUR_CASPER_PRIVATE_KEY>",
        "MAX_PAYMENT_PER_CALL": "0.50",
        "MAX_DAILY_SPEND": "10.00"
      }
    }
  }
}

Replace every <PLACEHOLDER> with your own value — never commit real key material. Only the chains you want to pay on need a key. The full annotated key set (RPC URLs with their public fallbacks, devnet mode, the optional cross-chain ceiling, the policy config) is .env.example; copy it to a .env your client loads, or inline the keys in the config block.

Before your first paid call: there is no default network — with a payment key loaded and X402_NETWORK_MODE unset, every paid call is refused with NETWORK_NOT_CONFIGURED before anything is fetched or signed. Set MAX_PAYMENT_PER_CALL and MAX_DAILY_SPEND to what you can afford, and make your first paid calls with a throwaway key.

Paid routes and prices rotate — confirm the route and price on the seller's GET /.well-known/x402 manifest before fetching.

Tools

Safety and network defaults

• The default payment policy is permissive — any x402 endpoint is payable up to the global caps — and every cap fails closed on a malformed value (it disables payments rather than widening them). Tighten via a config file pointed at by POLICY_CONFIG_PATH, or opt into a shipped profile with X402_POLICY_PROFILE=strict|standard — unset stays permissive (the behavior-compat default; see the policy engine reference for the three profiles).

• Polygon and Arbitrum are opt-in (add them to the policy's networks.allowed); the Ethereum mainnet (eip155:1) is always refused.

• Payment receipts come from the seller and are not verified on-chain (receipt_verified: false).

• There is no default network: X402_NETWORK_MODE must be set explicitly before any paid call.

Documentation

• Policy engine — decisions, reason codes, rule order, trust levels, the recipients and anomaly gates

• Payments and budgets — spend accounting, the ledger and reservations, the payment-intent boundary, trust in receipts

• Networks and network mode — the chain matrix, the no-default network mode, devnet, Casper, assets and USD pricing

• Operations — usage examples, directory refresh recipes, CI, the security scan, tech stack

Disclaimer and licence

This software is experimental and provided "as is", without warranty of any kind. Use at your own risk. It initiates real cryptocurrency transactions that are irreversible. License: MIT.