x402 MCP 工具演示——真实的 402、真实的拒绝与真实的结算

一个极简演示，展示 x402 支付协议 如何保护 MCP 风格的工具端点，并针对真实的 x402==2.16.0 Python 包及其默认公共协调器（https://x402.org/facilitator）在 Base Sepolia 测试网 上运行。这里没有任何手写的协议 JSON——captured_responses/ 中的每个响应都来自库本身，未作编辑。

配套内容：如何为 MCP 工具收费：一小时内实现可用的 x402 端点。

内容一览

Related MCP server: 402-mcp

运行方法

pip install -r requirements.txt
python gen_wallets.py          # writes wallets.json (gitignored) -- two fresh, empty keys
python server.py               # starts on 127.0.0.1:8402
python client_probe.py         # in a second terminal

你会看到什么

第 1 轮——无付款。 一个带有 payment-required 头（base64 JSON）的 402：包含方案、网络、资产合约、以代币最小单位计量的金额，以及收款地址。

第 2 轮——真实签名付款，余额为零。 客户端使用一次性密钥构建并签署实际的 EIP-3009 授权，将其作为 X-PAYMENT 附加，协调器会对照真实的 Base Sepolia 链状态进行检查。它返回：

{ "error": "invalid_exact_evm_insufficient_balance" }

该字符串是协调器真实的错误代码，而非猜测——当协议完全按设计运行且付款人根本没有钱时，你得到的就是这个。

第 3 轮——已注资，真实结算。 agent_address 已从 Circle 公共水龙头 获得 20 枚测试网 USDC，然后再次对同一服务器运行 client_probe.py。这一次，第 2 轮返回 200：

{
  "url": "https://example.com/mcp",
  "recommendation": "expose as a priced x402 tool at $0.01/call",
  "paid": true
}

带有一个可解码为以下内容的 payment-response 头：

{ "success": true, "payer": "0x3214cB6C...E0E9", "transaction": "0x9530b663...0dd86", "network": "eip155:84532" }

该交易哈希是真实且可独立验证的——在 Base Sepolia Blockscout 上查看：状态为 ok，发送到 USDC 合约，方法为 transferWithAuthorization——正是付款人签署的 EIP-3009 无 Gas 转账模式。任何人都可以验证这一点，无需信任本 README。

为什么 client_probe.py 需要手动往返

x402 2.16.0 自带 PaymentRoundTripper，但它是一个回调（handle_response(...)），旨在接入自定义的 httpx/requests 传输层——它本身并不是可直接替换的传输层，尽管文档字符串暗示如此。client_probe.py 直接调用其内部使用的同样三个原语（get_payment_required_response → create_payment_payload → encode_payment_signature_header），对于演示来说组件更少，并产生完全相同的线上输出。

安全注意事项

• gen_wallets.py 使用 eth_account.Account.create() 生成密钥——密码学随机，从未注资，本演示中从不接触主网。

• wallets.json 已被 gitignore。wallets.example.json 使用一个众所周知的销毁地址展示其结构，以便仓库在全新克隆后即可运行，且 git 历史中不包含机密信息。

• 协调器 URL、网络和资产合约都是库自带的测试网默认值——这里的一切都不会与 Base 主网通信，也不会转移真实价值。