x402dispatcher

AIエージェント向けのローカル x402 Bazaar Aggregator：Coinbase x402 Bazaar から有料APIを発見し、Model Context Protocol (MCP) ツールとしてラップし、CDP トレジャリーウォレットからマイクロペイメントを決済し、アップストリームのデータをエージェントに返します。

このリポジトリは現在 V4 です。

なぜこれが存在するのか

AIエージェントは推論とツール使用は得意ですが、APIへの支払いは苦手です。x402 プロトコルは、HTTP 402 Payment Required をプログラム可能なステーブルコインのマイクロペイメントレール（通常は USDC）に変換します。

x402dispatcher は、ソロオペレーターに優しいアグリゲーターとして中間に位置します：

資金はウォレット → マーチャントと移動します。プラットフォームは購入者資金をカストディしません。

Related MCP server: JMT x402 MCP Server

ロードマップ

V4 の機能

V3 のルーティングに加えて、V4 は有料コールごとの成功とレイテンシを data/api-stats.json に記録し、2つのティアを提供します：

しきい値（環境変数）：VERIFIED_MIN_SAMPLES（デフォルト 2）、VERIFIED_MIN_SUCCESS_RATE（デフォルト 0.8）。

新しいツール：get_api_stats、list_verified_apis。quote_route / route_and_call はオプションの tier を受け付けます。

V3 の機能

V2 の発見と支払いに加えて、V3 はルーターを追加します：

1. quote_route — Bazaar で自然言語タスクを検索し、合計価格（アップストリーム + マークアップ）で候補をランク付けし、支払いなしでプランを返す

2. route_and_call — 同じランク付けで、最安に支払い・呼び出し；失敗した場合は次に安いものを試す（最大 max_attempts 回）

すべての支出は MAX_PRICE_USD で制限されます。

V2 の機能

起動時に MCP サーバーは：

1. .env から認証情報を読み込む

2. CDP Treasury 支払いウォレットを解決する

3. Coinbase Bazaar で Base Sepolia (eip155:84532) の HTTP リソースを MAX_PRICE_USD 以下の価格で検索/一覧表示する

4. 各一致を MCP ツールとして登録する

5. ヘルパーツールも登録：search_bazaar、list_discovered_apis、call_x402_api

6. V1 デモツール get_mbta_predictions を保持する

エージェントが発見されたツール（または call_x402_api）を呼び出すと：

1. アップストリーム価格 + マークアップ に MAX_PRICE_USD を適用する

2. CdpX402Client + @x402/fetch の wrapFetchWithPayment で実際の x402 エンドポイントに支払う

3. マークアップスプレッドを回収する（可能な場合、Treasury → Merchant USDC 転送）

4. { payment, data } をエージェントに返す

V1 の get_mbta_predictions は、固定 $0.01 USDC Base Sepolia 転送を行い、その後無料の公開 MBTA 予測データを取得します。

アーキテクチャ

Agent / Cursor
    │  MCP (stdio)
    ▼
x402dispatcher MCP server (src/index.ts)
    │
    ├─ Discovery  → listX402DiscoveryResources / searchX402Resources (@coinbase/cdp-sdk)
    ├─ Payment    → CdpX402Client + wrapFetchWithPayment (@coinbase/cdp-sdk/x402, @x402/fetch)
    ├─ Routing    → economy (price) / verified (stats score) with failover
    ├─ Stats      → data/api-stats.json success + latency history
    ├─ Guardrails → MAX_PRICE_USD (+ SDK spend controls)
    └─ Markup     → MARKUP_BPS applied; optional USDC transfer to Merchant account
    │
    ▼
Upstream x402 HTTP API (Bazaar listing)

主要パッケージ

• @coinbase/cdp-sdk — ウォレット、Bazaar 発見、CdpX402Client

• @x402/fetch / @x402/core / @x402/evm — HTTP 402 支払いループ

• @modelcontextprotocol/sdk — MCP サーバー + ツール

• dotenv、zod、viem

要件

• Node.js 19+（CDP SDK の要件；22 LTS 推奨）

• Coinbase Developer Platform の認証情報：

  • CDP_API_KEY_ID

  • CDP_API_KEY_SECRET

  • CDP_WALLET_SECRET（CDP ポータル → 非カストディアルウォレット → セキュリティ の Wallet Secret — MetaMask の秘密鍵ではありません）

• Treasury アドレスに Base Sepolia USDC（+ ガス用の少量の ETH）

セットアップ

git clone https://github.com/jegamboafuentes/x402dispatcher.git
cd x402dispatcher
npm install
cp .env.example .env
# edit .env with your CDP credentials

環境変数

.env をコミットしないでください。追跡されるのは .env.example のみです。

トレジャリーに資金を供給

npx tsx -e "import 'dotenv/config'; import { CdpX402Client } from '@coinbase/cdp-sdk/x402'; const c = new CdpX402Client({ environment: 'development', walletConfig: { type: 'eoa', accountName: 'Treasury' } }); console.log(await c.getAddresses());"

表示された evmAddress に Base Sepolia USDC（および少量の ETH）を送信します。

実行

MCP サーバー（stdio）

npm start

Cursor MCP 設定

プロジェクトファイル：.cursor/mcp.json（同梱済み）。Cursor は以下を起動するはずです：

{
  "mcpServers": {
    "x402dispatcher": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "${workspaceFolder}"
    }
  }
}

クローン/インストール後に Cursor で MCP をリロードします。お使いの Cursor ビルドで ${workspaceFolder} が展開されない場合は、cwd をこのリポジトリの絶対パスに設定し、必要に応じて command を Node 22 バイナリに指定します。

MCP ツール

コア

動的ツール

起動時に、x402dispatcher は発見された Bazaar リソースごとに 1 つの MCP ツールも登録します（x402_<host>_<path>_<n> のような名前）。それぞれがオプションの query / body を受け付け、アップストリーム URL に支払います。

テスト

V4 エンドツーエンド（推奨）

2 つのエコノミー天気コールをシードし、勝者を Verified に昇格させ、tier=verified でクォート/ルーティングします：

npm run test:v4

期待：V4 SMOKE TEST PASSED

以前のバージョン

npm run test:v3
npm run test:v2

Cursor での手動チェック

1. x402dispatcher MCP サーバーをリロード

2. エコノミールーティングで天気を数回尋ねる（統計を構築）

3. 「List verified APIs」/「Get API stats」と尋ねる

4. 「Use the verified tier to get weather for Boston」と尋ねる

5. chosen.verified が true で、data/api-stats.json が増えたことを確認

ガードレールチェック

MAX_PRICE_USD をリストの合計より低く設定し、クォート/ルートが拒否するか、候補がゼロになることを確認します。

プロジェクト構成

x402dispatcher/
├── src/
│   ├── index.ts       # MCP server, tool registration
│   ├── discovery.ts   # Bazaar list/search → DiscoveredApi
│   ├── payment.ts     # CdpX402Client, markup, MBTA settle
│   ├── routing.ts     # quote + economy/verified route + failover
│   ├── stats.ts       # V4 local success/latency store
│   └── config.ts      # MAX_PRICE_USD, MARKUP_BPS, verified thresholds
├── scripts/
│   ├── v4-smoke-test.ts
│   ├── v3-smoke-test.ts
│   ├── v2-smoke-test.ts
│   ├── mcp-test.ts
│   └── smoke-test.ts
├── data/              # local api-stats.json (gitignored)
├── .cursor/
│   ├── mcp.json
│   └── rules/         # security + x402-stack agent rules
├── AGENTS.md          # product / roadmap context for agents
├── .env.example
└── package.json

セキュリティメモ

• ウォレット認証情報は .env からのみ読み込まれます — シークレットをハードコードしないでください。

• 自動支出はすべて、署名前に MAX_PRICE_USD で制限されます。

• V2 は CDP x402 支出制御（maxAmountPerPayment + Base Sepolia ネットワーク許可リスト）も設定します。

• Bazaar はカタログとして扱い、推奨とはみなさないでください。まずテストネットで少額の上限を好みます。

• CDP_WALLET_SECRET はポータルの Wallet Secret（長い base64）でなければならず、MetaMask の hex キーではありません。

スタックリファレンス

• Coinbase CDP ドキュメント

• x402 サービスを発見（Bazaar）

• x402 バイヤークイックスタート

• Model Context Protocol

ライセンス

ISC