x402 Agent Tollbooth

🛣️ x402 Agent Tollbooth

x402 Agent Tollbooth は、Base ネットワーク上でマシン間（M2M）のマイクロトランザクションを実現する、エンタープライズグレードの Model Context Protocol（MCP）サーバーです。

このプロジェクトは、x402 プロトコル標準を通じて HTTP 402（Payment Required）のワークフローを自動処理し、AI エージェントが専門的な Web3 インテリジェンスやスマートコントラクト分析ツールにプログラムからアクセスできるインフラストラクチャ層を提供します。エージェントはツールの実行ごとに USDC で直接支払うため、シームレスでトラストレスな API 収益化モデルを実現できます。

---

💻 オープンソース実装とセルフホスティング

このリポジトリには、MCP サーバーの完全なオープンソースの Python 実装が含まれています。サーバーは公式の mcp SDK と sse-starlette を使用して構築されており、Server-Sent Events（SSE）と JSON-RPC によるツール呼び出しを処理します。

主要な実装は tollbooth_agent.py にあります。

ソースからの実行（ローカル実行）

この MCP サーバーは簡単にセルフホストしたり、お使いのエージェント向けにローカルで実行したりできます。

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 ツールのナビゲーション可能なツリーを公開します。有料ツールを実行するには、エージェントが必要な正確な USDC 額に対応する、有効な Base ネットワークの paymentHash（トランザクションレシート）を提示する必要があります。

🤝 紹介収益分配プロトコル： サーバーはオプションの referralWallet パラメーターを実装しています。仲介役として動作する AI エージェントは、ウォレットアドレスを追加することで、プロトコル手数料の 20% の分配を受け取れます。

🆓 インフラストラクチャと検出

• contract.auditTeaser （無料）：Base のスマートコントラクトをスキャンして脆弱性を検出し、概要を返します。有料の詳細分析を承認する必要性をエージェントが事前に評価できるよう設計されています。

📊 トークンデータとインテリジェンス

• 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 分析です。公開されているオンチェーン上の活動から、リスクプロファイルとポートフォリオ戦略を生成します。

💾 エージェントの永続化

• memory.store （0.01 USDC）：エージェントがセッションをまたいでコンテキストを保存するための永続メモリーバンクです。
• memory.retrieve （0.01 USDC）：保存されたコンテキストメモリーを取得します。
• llm.query （0.10 USDC）：複雑な推論タスク向けに、Tollbooth の基盤となる LLM に直接問い合わせます。

---

⚡ X402 FastPass SDK（シームレスなエージェント統合）

LangChain、AutoGen、または CrewAI でカスタム AI エージェントを構築する場合、このサーバーを使うために、LLM に Web3 トランザクションの書き方を教える必要はありません。

このリポジトリには、X402 FastPass SDK（x402_fastpass.py）が含まれています。これは MCP クライアントのラッパーとして機能し、USDC による暗号資産決済を Python でネイティブに自動処理します。

エージェントにシームレスなアクセスを提供する方法：

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 はエージェントのウォレットアドレスを referralWallet として自動的に挿入するため、エージェントは呼び出すすべてのツールで 20% のキャッシュバックを自動的に獲得できます！

---

⚙️ 仕組み：最新の x402 V2 ヘッダーハンドシェイク（ガス代 100% 無料）

このサーバーは、Base Mainnet（eip155:8453）および Solana Mainnet（solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp）で、ガス代 100% 無料の決済を実現する公式 x402 V2 仕様に対応しています。

1. 未払いのプローブ：エージェントがエンドポイント（例：POST /toll/cross-dex-arbitrage）を呼び出します。サーバーはただちに、50% の無料ティーザープレビューと PAYMENT-REQUIRED ヘッダーによるチャレンジを含む HTTP 402 Payment Required を返します。
2. 自動署名（ガス代ゼロ）：エージェントは EIP-712 TransferWithAuthorization（Base 上）に署名するか、SPL TransferChecked（Solana 上）に部分署名します。リレイヤーのファシリテーターがすべてのガス代を負担するため、必要な ETH と SOL は $0 です。
3. 再送信とロック解除：エージェントが Base64 の PAYMENT-SIGNATURE ヘッダーを追加します。サーバーは 10 ms 未満でファシリテーター経由の検証を行い、完全な未編集のインテリジェンスと暗号学的レシートを含む HTTP 200 OK と PAYMENT-RESPONSE を返します。

自律型エージェントによる自動決済（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