MCP server for PayToll — 27 tools for DeFi, swaps, bridging, social, on-chain data, and AI, powered by x402 micro-payments on Base. No API keys, no subscriptions. Your AI agent pays per call in USDC.

# Works without PRIVATE_KEY while API free tier is available
npx -y paytoll-mcp
# Add PRIVATE_KEY (or keychain/secret-service source) for paid/unlimited access
PRIVATE_KEY=0xYourKey npx -y paytoll-mcp

The server connects to the PayToll API, discovers all available tools, and registers them over stdio. Your agent can immediately start querying DeFi data, swapping tokens, searching Twitter, prompting LLMs, and more.

Security: Use a dedicated wallet with minimal funds. Do not use your main wallet. The private key is used only to sign x402 micro-payments (fractions of a cent per call) — it never leaves your machine and is never sent to any server.

• Node.js 20+
• Wallet key is optional for free-tier calls
• A wallet private key with USDC on Base (+ a small amount of ETH for gas) is required for paid calls

A few dollars of USDC is enough for thousands of API calls.

For paid flow, the server needs one key source:

• PRIVATE_KEY
• PRIVATE_KEY_KEYCHAIN_SERVICE (macOS)
• PRIVATE_KEY_SECRET_SERVICE (Linux / Ubuntu)
• PRIVATE_KEY_COMMAND

If no key source is set, the MCP server starts in free-tier mode and will return a clear error when:

• the free tier is exhausted, or
• the called endpoint is paid-only (for example social/X or AI paths on default API config).

Store key once:

security add-generic-password -a "$USER" -s paytoll-mcp -w '0xYOUR_PRIVATE_KEY'

Then run:

PRIVATE_KEY_KEYCHAIN_SERVICE=paytoll-mcp npx -y paytoll-mcp

Install CLI:

sudo apt-get update && sudo apt-get install -y libsecret-tools

Store key once:

printf '0xYOUR_PRIVATE_KEY' | secret-tool store --label='PayToll MCP Wallet' service paytoll-mcp account "$USER"

Then run:

PRIVATE_KEY_SECRET_SERVICE=paytoll-mcp npx -y paytoll-mcp

For macOS examples below, use PRIVATE_KEY_KEYCHAIN_SERVICE. On Ubuntu/Linux, use PRIVATE_KEY_SECRET_SERVICE with the same value.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "paytoll": {
      "command": "npx",
      "args": ["-y", "paytoll-mcp"],
      "env": {
        "PRIVATE_KEY_KEYCHAIN_SERVICE": "paytoll-mcp"
      }
    }
  }
}

Restart Claude Desktop. You'll see PayToll tools in the tools menu.

Add to .claude/settings.json:

{
  "mcpServers": {
    "paytoll": {
      "command": "npx",
      "args": ["-y", "paytoll-mcp"],
      "env": {
        "PRIVATE_KEY_KEYCHAIN_SERVICE": "paytoll-mcp"
      }
    }
  }
}

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "paytoll": {
      "command": "npx",
      "args": ["-y", "paytoll-mcp"],
      "env": {
        "PRIVATE_KEY_KEYCHAIN_SERVICE": "paytoll-mcp"
      }
    }
  }
}

/install paytoll

Do not set raw PRIVATE_KEY in OpenClaw env settings.

Set one non-secret selector instead:

• macOS: PRIVATE_KEY_KEYCHAIN_SERVICE=paytoll-mcp
• Ubuntu: PRIVATE_KEY_SECRET_SERVICE=paytoll-mcp

Optional if not using $USER:

• macOS: PRIVATE_KEY_KEYCHAIN_ACCOUNT=your-account
• Ubuntu: PRIVATE_KEY_SECRET_ACCOUNT=your-account

Build unsigned transaction data for Aave operations. Returns transaction payloads for your wallet to sign — does not broadcast or execute transactions.

Powered by Li.Fi aggregator. Supports same-chain swaps and cross-chain bridges across 12 networks (Ethereum, Base, Arbitrum, Optimism, Polygon, Avalanche, BSC, zkSync, Linea, Scroll, Fantom, Gnosis).

To bridge, set fromChain and toChain to different chain IDs. Li.Fi routes through optimal bridge protocols (Stargate, Across, Hop, etc.) automatically.

All tools are discovered automatically from the API at startup.

AI Agent (Claude, Cursor, etc.)
  |  stdio JSON-RPC
  v
paytoll-mcp
  |  1. Startup: GET /v1/meta -> discover all endpoints -> register MCP tools
  |  2. Tool call: POST endpoint -> 402 -> auto-sign USDC payment -> retry -> result
  v
PayToll API (api.paytoll.io)

Payment is invisible to the agent. The MCP server handles the full x402 payment protocol flow automatically:

1. Agent calls a tool (e.g., aave-best-yield)
2. MCP server sends request to PayToll API
3. API responds with 402 Payment Required and payment details
4. MCP server signs a USDC payment using your wallet's private key
5. MCP server retries with the signed payment
6. API verifies payment, executes the request, settles on Base
7. Result is returned to the agent

When no wallet key is configured, the MCP server sends plain requests first (free-tier mode). If the API returns 402, MCP reports that a wallet key is required for paid access.

Your private key never leaves your machine. It is only used locally to sign EIP-712 typed data for x402 payments. The PayToll API and MCP server communicate over HTTPS — the key itself is never transmitted.

• Use a dedicated wallet. Create a new wallet with only the USDC/ETH you need. Do not reuse your main wallet.
• Private key stays local. The key is used only to sign payment authorizations on your machine. It is never sent to any server.
• No transaction execution. Transaction-building tools (aave-supply, swap-build, etc.) return unsigned transaction data. They do not broadcast anything on-chain.
• Payments are micro-amounts. Most calls cost $0.001–$0.08 in USDC. A few dollars funds thousands of calls.
• Open source. This entire MCP server is open source — audit it yourself.

git clone https://github.com/foodaka/paytoll-mcp.git
cd paytoll-mcp
npm install
npm run build
PRIVATE_KEY_KEYCHAIN_SERVICE=paytoll-mcp npm start

MIT