base-facts-mcp

An MCP server for AI agents that trade or move money on Base. Each tool calls Base Token Facts and pays for the call itself in USDC over x402, from a small wallet you control. Every answer is read at one block and says which.

Facts and heuristics, not financial advice. API docs and live revenue counter: https://base-facts.yankii.fr and https://base-facts.yankii.fr/stats

Setup

1. Make a dedicated wallet and put a little USDC on it, on the Base network (1 USDC pays for 100 verdicts). No ETH is needed: the x402 facilitator pays the gas. Never use your main wallet.

2. Add the server to your MCP client, for example claude_desktop_config.json:

{
  "mcpServers": {
    "base-facts": {
      "command": "npx",
      "args": ["-y", "base-facts-mcp"],
      "env": {
        "X402_PAYER_FILE": "/path/to/payer.json",
        "MAX_PRICE_USD": "0.02",
        "SESSION_BUDGET_USD": "1"
      }
    }
  }
}

payer.json is { "privateKey": "0x..." }; X402_PRIVATE_KEY works too. Without either, the server uses ~/.base-facts-mcp/payer.json when it exists.

Every setting also exists as an option, for hosts that pass only command and args (Preste): --payer-file <path>, --max-price <usd>, --budget <usd>, --api <url>. See preste/ for the Preste config and skill.

Related MCP server: Grey Ridge x402 MCP

Spending safety

• MAX_PRICE_USD (default 0.02): the client refuses to sign any single payment above it.

• SESSION_BUDGET_USD (default 1): once reached, the client stops signing until restarted.

• Only USDC on Base (eip155:8453) is ever signed.

• A refused or failed call (4xx/5xx) cancels the settlement: you are not charged, and the tool says charged: false with the reason (for example not enough USDC).

• Paid calls run one at a time so the budget count stays exact.

Development

npm test drives the server over stdio like a real client, with empty wallets: no USDC is spent.