x402dispatcher

面向 AI 代理的本地 x402 Bazaar 聚合器：从 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 中，并提供两个层级：

阈值（环境变量）：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 金库 付款方钱包

3. 在 Coinbase Bazaar 中搜索/列出 Base Sepolia（eip155:84532）上价格等于或低于 MAX_PRICE_USD 的 HTTP 资源

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. 收集加价差价（在可能的情况下进行 金库 → 商户 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 Portal → 非托管钱包 → 安全 的 Wallet Secret — 不是 MetaMask 私钥）

• 金库地址上的 Base Sepolia USDC（+ 少量用于 gas 的 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());"

将 Base Sepolia USDC（以及少量 ETH）发送到打印出的 evmAddress。

运行

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 资源注册一个 MCP 工具（名称如 x402_<host>_<path>_<n>）。每个工具接受可选的 query / body 参数并支付上游 URL。

测试

V4 端到端（推荐）

播种两次经济路由天气调用，将胜出者提升为验证层级，然后使用 tier=verified 进行报价/路由：

npm run test:v4

预期输出：V4 SMOKE TEST PASSED

早期版本

npm run test:v3
npm run test:v2

在 Cursor 中手动检查

1. 重新加载 x402dispatcher MCP 服务器

2. 使用经济路由请求天气几次（积累统计）

3. 询问：“列出已验证的 API” / “获取 API 统计”

4. 询问：“使用验证层级获取波士顿的天气”

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 必须是 Portal Wallet Secret（长 base64 字符串），而不是 MetaMask 十六进制密钥。

技术栈参考

• Coinbase CDP 文档

• 发现 x402 服务（Bazaar）

• x402 买方快速入门

• Model Context Protocol

许可证

ISC