x402-agent-mcp

x402-agent-mcp

Universal x402 MCP for AI agents — discover and pay for any x402 endpoint on Base or Solana.

Agents discover services, pay per call in USDC, and consume data — all autonomously. No API keys, no subscriptions, no signup. Just a wallet.

What It Does

Agent: "I need news data"
  → x402_search("news") → finds Tavily, 2s.io, glim.sh
  → x402_describe("Tavily") → gets endpoint schema + price
  → x402_fetch("https://api.tavily.com/search", "POST", body) → pays $0.001 USDC → gets results

The agent never sees wallets, private keys, or x402 protocol details. Just search, describe, fetch.

Tools

Multi-Chain Support

Chain is auto-detected from the 402 response. Override with chain parameter.

Quick Start

1. Install

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

2. Configure

# .env
SOLANA_PRIVATE_KEY=your-base58-solana-key
EVM_PRIVATE_KEY=your-hex-base-key
SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=your-key
BASE_RPC_URL=https://mainnet.base.org

You only need the key for chains you want to pay on. Solana-only? Just set SOLANA_PRIVATE_KEY.

3. Connect to Your Agent

Hermes Agent

hermes config set mcp_servers.x402.command "node"
hermes config set mcp_servers.x402.args '["/path/to/x402-agent-mcp/dist/index.js"]'
hermes config set mcp_servers.x402.enabled true

# Set env vars
python3 -c "
import yaml
with open('$HOME/.hermes/config.yaml') as f:
    config = yaml.safe_load(f)
config['mcp_servers']['x402']['env'] = {
    'SOLANA_PRIVATE_KEY': 'your-base58-key',
    'EVM_PRIVATE_KEY': 'your-hex-key',
}
with open('$HOME/.hermes/config.yaml', 'w') as f:
    yaml.dump(config, f, default_flow_style=False, allow_unicode=True)
"

hermes gateway restart
hermes mcp test x402

Claude Desktop

{
  "mcpServers": {
    "x402": {
      "command": "node",
      "args": ["/path/to/x402-agent-mcp/dist/index.js"],
      "env": {
        "SOLANA_PRIVATE_KEY": "your-base58-key",
        "EVM_PRIVATE_KEY": "your-hex-key"
      }
    }
  }
}

Usage Examples

Search for endpoints

x402_search({ query: "news" })
x402_search({ category: "social" })
x402_search({ chain: "solana" })

Describe a service

x402_describe({ name: "svm402" })

Fetch an x402 endpoint

x402_fetch({
  url: "https://svm402.com/analyze",
  method: "POST",
  body: '{"address": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}'
})

x402_fetch({
  url: "https://api.tavily.com/search",
  method: "POST",
  body: '{"query": "latest AI news"}',
  chain: "base"
})

Endpoint Directory

The endpoints.json file contains known x402 endpoints. To add a new service:

1. Edit endpoints.json
2. Add your service with name, description, base_url, chain, category, tags, and endpoints
3. Submit a PR

Safety

• Spending limits via env vars: MAX_PAYMENT_PER_CALL (default: $0.50), MAX_DAILY_SPEND (default: $10.00)
• Payment logging to x402-payments.jsonl
• Private keys never exposed to the agent — MCP handles payment internally

Disclaimer

This software is experimental and provided "as is", without warranty of any kind. Use at your own risk.

This software initiates real cryptocurrency transactions that are irreversible.

Tech Stack

• MCP SDK
• @x402/fetch — x402 payment handling
• @x402/svm — Solana x402 scheme
• @x402/evm — Base/EVM x402 scheme
• @solana/web3.js — Solana SDK
• ethers — EVM SDK

License

MIT

Links

• x402 Protocol — Payment standard
• x402scan — Endpoint explorer
• MCP Protocol — Agent tool protocol