Skip to main content
Glama

🛣️ 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.

Smithery Quality Score: 100/100 Network Currency Glama


💻 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

Related MCP server: x402-json-repair-mcp

🛠️ 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

Available Tools

9 tools
contract.auditA
Read-onlyIdempotent
Inspect

Live Smart Contract AI Auditor. Analyzes Base contracts for vulnerabilities. Requires 1.00 USDC payment via x402 protocol.

Inputs: contractAddress (required), paymentHash, referralWallet. Returns: error, score, vulnerabilities

contract.auditTeaserA
Read-only
Inspect

Free teaser for the smart contract auditor. Returns vulnerability counts but obscures details to upsell the paid audit. Free to use.

Inputs: contractAddress (required). Returns: teaser, upsell

contract.patchA
Read-onlyIdempotent
Inspect

Premium Smart Contract Patcher. Not only audits but rewrites vulnerable Solidity code into production-ready safe code. Requires 5.00 USDC payment via x402 protocol.

Inputs: contractAddress (required), paymentHash, referralWallet. Returns: error, changelog, patchedCode

llm.queryA
Read-only
Inspect

Agent-to-Agent Compute Arbitrage. Route raw LLM prompts to our Gemini instance. Requires 0.10 USDC micro-transaction via x402 protocol.

Inputs: prompt (required), paymentHash. Returns: error, response

market.alphaA
Read-only
Inspect

Purchase aggregated intelligence on which contracts and wallets other AI agents are analyzing right now. Requires 10.00 USDC.

Inputs: paymentHash (required). Returns: mostProfiledWallets, mostAuditedContracts

memory.retrieveB
Read-only
Inspect

Agent Memory Bank: Retrieve stored context or data. Requires 0.01 USDC micro-transaction.

Inputs: memoryKey (required), paymentHash. Returns: memoryKey, memoryValue

memory.storeBInspect

Agent Memory Bank: Store arbitrary context, snippets, or vectors persistently. Requires 0.01 USDC micro-transaction.

Inputs: memoryKey (required), memoryValue (required), paymentHash. Returns: status

token.analyzeA
Read-only
Inspect

Premium real-time liquidity, volume, and smart-money analytics for any token on Base. Required payment: 0.50 USDC.

Inputs: paymentHash (required), tokenAddress (required), referralWallet. Returns: priceUsd, liquidity, volume24h, protocolLoyaltyPoints

wallet.profileA
Read-only
Inspect

Smart Money Oracle. Analyzes a wallet's on-chain behavior and assigns a psychological risk profile. Requires 2.00 USDC payment via x402 protocol.

Inputs: targetWallet (required), paymentHash. Returns: error, profile

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 9 tools

    Disambiguation3/5

    Most tools target distinct resources (llm, wallet, memory, market, token), but the contract.audit / contract.patch / contract.auditTeaser cluster overlaps heavily: patch includes auditing, and auditTeaser is an explicitly degraded version of audit, so an agent may struggle to pick between them.

    Naming Consistency4/5

    Nearly all tools follow a clean namespace.action pattern (llm.query, contract.audit, wallet.profile, memory.store), with only contract.auditTeaser breaking the convention by cramming a modifier into the verb slot instead of using a separate action.

    Tool Count5/5

    Nine tools is well within the ideal 3-15 range, and each represents a discrete paid service rather than a redundant wrapper, so the set feels appropriately scoped.

    Completeness3/5

    Memory has store/retrieve but no update/delete, and there is no discovery, pricing, or payment/balance tool despite the whole server being an x402 tollbooth, leaving notable lifecycle gaps agents must work around.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers