x402 Agent Tollbooth

🛣️ x402 Agent 收费站

x402 Agent 收费站是一个企业级模型上下文协议（MCP）服务，用于演示 Base 网络上的机器对机器（M2M）微交易。

本项目提供了一个基础设施层，让 AI Agent 能够通过 x402 协议标准自动完成 HTTP 402（需要付款）工作流，以编程方式访问专业 Web3 情报和智能合约分析工具。Agent 直接使用 USDC 按工具调用次数付费，实现无缝、无需信任的 API 变现模式。

---

💻 开源实现与自托管

此代码库包含 MCP 服务的完整开源 Python 实现。该服务使用官方 mcp SDK 和 sse-starlette 构建，用于处理服务器发送事件（SSE）和 JSON-RPC 工具调用。

核心实现位于 tollbooth_agent.py。

从源代码运行（本地执行）

你可以轻松自托管此 MCP 服务，或在本地运行它来服务自己的 Agent。

使用 Docker：

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

使用 Python：

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

---

🛠️ 服务功能

此服务提供一组可导航的专业 Web3 工具。AI Agent 必须提供有效的 Base 网络 paymentHash（交易收据），且金额必须与执行付费工具所需的 USDC 金额完全一致。

🤝 推荐收入分成协议： 服务支持可选的 referralWallet 参数。作为中介的 AI Agent 可以附加其钱包地址，以获得 20% 的协议费用分成。

🆓 基础设施与发现

• contract.auditTeaser （免费）：扫描 Base 智能合约中的漏洞并返回概要。旨在让 Agent 在授权付费深度分析前评估其必要性。

📊 代币数据与情报

• token.analyze （0.50 USDC）：提供任意 Base 代币的实时流动性、交易量和分析数据。汇总的数据适用于高频算法使用场景。

🔐 智能合约安全

• contract.audit （1.00 USDC）：由 AI 驱动的完整智能合约漏洞审计。返回具体代码行、风险严重程度和攻击向量。
• contract.patch （5.00 USDC）：高级服务。审计合约并生成可用于生产环境的安全 Solidity 代码，以修补漏洞。

🧠 市场情报

• market.alpha （10.00 USDC）：高级元数据经纪服务。汇总元数据，揭示网络上当前正受到大量自动化分析的智能合约。
• wallet.profile （2.00 USDC）：对特定钱包地址进行行为金融 AI 分析。根据公开的链上活动生成风险画像和投资组合策略。

💾 Agent 持久化

• memory.store （0.01 USDC）：持久化记忆库，供 Agent 跨会话存储上下文。
• memory.retrieve （0.01 USDC）：检索已存储的上下文记忆。
• llm.query （0.10 USDC）：直接向收费站底层大模型发送查询，以完成复杂推理任务。

---

⚡ X402 FastPass SDK（无缝集成 Agent）

如果你正在使用 LangChain、AutoGen 或 CrewAI 构建自定义 AI Agent，则无需教会大模型如何编写 Web3 交易即可使用此服务。

我们已在此仓库中直接加入 X402 FastPass SDK（x402_fastpass.py）。它充当 MCP 客户端的封装器，可在 Python 中原生自动处理 USDC 加密货币支付。

如何让 Agent 无缝访问：

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())

注意：FastPass SDK 会自动将 Agent 的钱包地址注入为 referralWallet，这意味着 Agent 调用的所有工具都能自动获得 20% 的现金返还！

---

⚙️ 工作原理：现代 x402 V2 标头握手（100% 免 Gas）

此服务支持官方 x402 V2 规范，可在 Base 主网（eip155:8453）和 Solana 主网（solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp）上实现 100% 免 Gas 结算：

1. 未付款探测：Agent 调用端点（例如 POST /toll/cross-dex-arbitrage）。服务立即返回包含 50% 免费预览的 HTTP 402 Payment Required，以及 PAYMENT-REQUIRED 标头挑战。
2. 自动签名（零 Gas）：Agent 对 EIP-712 TransferWithAuthorization（在 Base 上）签名，或对 SPL TransferChecked（在 Solana 上）进行部分签名。中继器服务商会承担所有 Gas 费用（无需支付 $0 ETH / $0 SOL）。
3. 重放并解锁：Agent 附加 Base64 PAYMENT-SIGNATURE 标头。服务会在 <10ms 内通过服务商验证，并返回包含完整未删减情报和 PAYMENT-RESPONSE 加密收据的 HTTP 200 OK。

自主 Agent 自动支付（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()

---

🚀 连接到托管端点

如果你不想从源代码运行服务，可以直接连接到我们的公共托管端点：

• 远程 MCP URL：https://x402-agent-tollbooth.onrender.com/mcp
• 发现清单：https://x402-agent-tollbooth.onrender.com/.well-known/mcp/server-card.json
• x402 清单：https://x402-agent-tollbooth.onrender.com/.well-known/x402.json
• Smithery CLI 安装：

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