X402 Agent Tollbooth MCP Server

🛣️ x402 Agent Tollbooth

The x402 Agent Tollbooth is an enterprise-grade Model Context Protocol (MCP) server that demonstrates machine-to-machine (M2M) micro-transactions on the Base network.

This project provides an infrastructure layer allowing AI agents to programmatically access specialized Web3 intelligence and smart contract analysis tools by fulfilling automated HTTP 402 (Payment Required) workflows via the x402 protocol standard. Agents pay per tool execution directly in USDC, enabling a seamless, trustless API monetization model.

---

💻 Open Source Implementation & Self-Hosting

This repository contains the full, open-source Python implementation of the MCP server. The server is built using the official mcp SDK and sse-starlette to handle Server-Sent Events (SSE) and JSON-RPC tool calling.

The core implementation is located in tollbooth_agent.py.

Running from Source (Local Execution)

You can easily self-host this MCP server or run it locally for your own agents.

Using Docker:

docker build -t x402-tollbooth .
docker run -p 8000:8000 -e GEMINI_API_KEY="your_api_key" x402-tollbooth

Using Python:

pip install -r requirements.txt
uvicorn tollbooth_agent:mcp_app --host 0.0.0.0 --port 8000

---

🛠️ Server Capabilities

This server exposes a navigable tree of specialized Web3 tools. AI agents must provide a valid Base network paymentHash (transaction receipt) for the exact USDC amount required to execute the paid tools.

🤝 Referral Revenue Sharing Protocol: The server implements an optional referralWallet parameter. AI agents acting as intermediaries can append their wallet address to receive a 20% protocol fee distribution.

🆓 Infrastructure & Discovery

• contract.auditTeaser (FREE): Scans a Base smart contract for vulnerabilities and returns a high-level summary. Designed to allow agents to assess necessity before authorizing paid deep-dives.

📊 Token Data & Intelligence

• token.analyze (0.50 USDC): Real-time liquidity, volume, and analytics for any Base token. Aggregates data for high-frequency algorithmic usage.

🔐 Smart Contract Security

• contract.audit (1.00 USDC): Full AI-driven smart contract vulnerability audit. Returns exact lines of code, risk severity, and attack vectors.
• contract.patch (5.00 USDC): Premium service. Audits the contract and generates production-ready, secure Solidity code to patch the vulnerabilities.

🧠 Market Intelligence

• market.alpha (10.00 USDC): High-level metadata brokering. Aggregates metadata to reveal which smart contracts are currently experiencing high automated analysis volume on the network.
• wallet.profile (2.00 USDC): Behavioral finance AI analysis of a specific wallet address. Generates risk profiles and portfolio strategies based on public on-chain actions.

💾 Agent Persistence

• memory.store (0.01 USDC): Persistent memory bank for agents to store context across sessions.
• memory.retrieve (0.01 USDC): Retrieve stored contextual memory.
• llm.query (0.10 USDC): Query the Tollbooth's underlying LLM directly for complex reasoning tasks.

---

⚡ The X402 FastPass SDK (Seamless Agent Integration)

If you are building custom AI agents in LangChain, AutoGen, or CrewAI, you do not need to teach your LLMs how to write Web3 transactions to use this server.

We have included the X402 FastPass SDK (x402_fastpass.py) directly in this repository. It acts as a wrapper around the MCP client and automatically handles the USDC crypto payments natively in Python.

How to give your agent seamless access:

from x402_fastpass import X402FastPass
import asyncio

# 1. Give the FastPass Client your agent's Base wallet private key
client = X402FastPass(private_key="0xYOUR_PRIVATE_KEY")

# 2. Give this Python function to your agent as a standard tool.
# The SDK automatically handles the on-chain USDC transfer and passes the payment hash to the MCP server!
async def run_audit():
    result = await client.audit_contract("0xTargetSmartContractAddress")
    print(result)

asyncio.run(run_audit())

Note: The FastPass SDK automatically injects your agent's wallet address as the referralWallet, meaning your agent automatically earns a 20% cashback on all tools it calls!

---

⚙️ How it Works: Modern x402 V2 Header Handshake (100% Gasless)

The server supports the official x402 V2 specification with 100% gasless settlement on Base Mainnet (eip155:8453) and Solana Mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp):

1. Unpaid Probe: Agent calls endpoint (e.g. POST /toll/cross-dex-arbitrage). Server immediately returns HTTP 402 Payment Required with a 50% Free Teaser Preview and PAYMENT-REQUIRED header challenge.
2. Auto-Sign (Zero Gas): Agent signs an EIP-712 TransferWithAuthorization (on Base) or partially-signs an SPL TransferChecked (on Solana). The relayer facilitator sponsors all gas fees ($0 ETH / $0 SOL required).
3. Replay & Unlock: Agent attaches Base64 PAYMENT-SIGNATURE header. Server verifies via facilitator in <10ms and returns HTTP 200 OK with full unredacted intel and PAYMENT-RESPONSE cryptographic receipt.

Autonomous Agent Auto-Pay (Python)

import base64, json, secrets, time, requests
from eth_account import Account
from eth_account.messages import encode_typed_data

def paid_toll_call(endpoint: str, payload: dict, private_key: str):
    account = Account.from_key(private_key)
    url = f"https://x402-agent-tollbooth.onrender.com{endpoint}"

    # 1. Probe endpoint
    res = requests.post(url, json=payload)
    if res.status_code == 200:
        return res.json()

    # 2. Decode 402 challenge & sign EIP-712 authorization
    raw_pr = res.headers.get("PAYMENT-REQUIRED") or res.headers.get("X-Payment-Required")
    pr_json = json.loads(base64.b64decode(raw_pr).decode("utf-8"))
    accepted = next(a for a in pr_json["accepts"] if "8453" in str(a.get("network", "")))

    now = int(time.time())
    nonce = secrets.token_bytes(32)
    types = {"TransferWithAuthorization": [
        {"name": "from", "type": "address"}, {"name": "to", "type": "address"},
        {"name": "value", "type": "uint256"}, {"name": "validAfter", "type": "uint256"},
        {"name": "validBefore", "type": "uint256"}, {"name": "nonce", "type": "bytes32"},
    ]}
    domain = {"name": "USD Coin", "version": "2", "chainId": 8453, "verifyingContract": accepted["asset"]}
    msg = {"from": account.address, "to": accepted["payTo"], "value": int(accepted["amount"]), "validAfter": 0, "validBefore": now + 300, "nonce": nonce}
    sig = account.sign_message(encode_typed_data(domain_data=domain, message_types=types, message_data=msg)).signature.hex()

    payment_b64 = base64.b64encode(json.dumps({
        "x402Version": 2, "resource": pr_json.get("resource"), "accepted": accepted,
        "payload": {"signature": "0x" + sig.lstrip("0x"), "authorization": {
            "from": account.address, "to": accepted["payTo"], "value": str(accepted["amount"]),
            "validAfter": "0", "validBefore": str(now + 300), "nonce": "0x" + nonce.hex()
        }}
    }).encode()).decode()

    # 3. Settle & unlock premium response
    paid_res = requests.post(url, json=payload, headers={"PAYMENT-SIGNATURE": payment_b64})
    return paid_res.json()

---

🚀 Connecting to the Hosted Endpoint

If you do not want to run the server from source, connect directly to our public hosted endpoint:

• Remote MCP URL: https://x402-agent-tollbooth.onrender.com/mcp
• Discovery Manifest: https://x402-agent-tollbooth.onrender.com/.well-known/mcp/server-card.json
• x402 Manifest: https://x402-agent-tollbooth.onrender.com/.well-known/x402.json
• Smithery CLI Install:

npx @smithery/cli mcp install x402-agent-tollbooth