x402 全流程部署教程：让 AI Agent 用 USDC 为你的数据付费

〇、这套东西是什么

两层协议，缺一不可：MCP 让 AI Agent 能发现并按接口调用你的工具（发现层）；x402 让 Agent 在拿到数据前先付钱（结算层，Base 主网 USDC）。买家钱包里只需有 USDC，不需要 ETH——gas 由 facilitator 代付（EIP-3009 免 gas 授权）。你不需要注册账号、不需要 API Key、不需要 Coinbase 账户就能收。

① 准备

• 一台能跑 Python 的服务器（本站在腾讯云 2C4G Ubuntu 24.04 上跑）
• 一个 Base 主网 USDC 收款地址（你自己控制私钥的那个）
• 一个域名 + HTTPS（Agent 发现与 x402 都要求 https）
• 可选：一个测试买家钱包，里面充一点 Base 主网 USDC 用来验证

装依赖

python3 -m venv venv && source venv/bin/activate
pip install "mcp<2" "x402==2.25.0" web3 httpx

② 写服务端 server.py（核心骨架）

import os
from mcp.server.fastmcp import FastMCP
from x402 import x402ResourceServer
from x402.http import FacilitatorConfig, HTTPFacilitatorClient
from x402.mechanisms.evm.exact import ExactEvmServerScheme
from x402.mcp import create_payment_wrapper
from x402.schemas.config import ResourceConfig

# 1. 链与 facilitator：Base 主网 + PayAI（免注册，支持 x402 v2 主网）
NETWORK = os.environ.get("X402_NETWORK", "eip155:8453")
FACILITATOR_URL = os.environ.get("X402_FACILITATOR",
                                 "https://facilitator.payai.network")

# 2. 收款地址：换成你自己的 Base 主网地址！别抄示例。
PAY_TO = os.environ.get("PAY_TO") or "0x你的收款地址"

# 3. 定价（按次，USD）
PRICE = {"my_data_tool": "$0.05"}

facilitator = HTTPFacilitatorClient(FacilitatorConfig(url=FACILITATOR_URL))
resource_server = x402ResourceServer(facilitator)
resource_server.register(NETWORK, ExactEvmServerScheme())
resource_server.initialize()
mcp = FastMCP("my-data-service")

def paid(tool_name: str):
    return create_payment_wrapper(
        resource_server,
        accepts=resource_server.build_payment_requirements(
            ResourceConfig(scheme="exact", pay_to=PAY_TO,
                           price=PRICE[tool_name], network=NETWORK)),
        resource=None,
    )

@mcp.tool(name="list_items")          # 免费工具：让 Agent 先看见你有货
def list_items() -> str:
    return '[{"name": "item-a"}]'

@mcp.tool(name="my_data_tool")        # 付费工具
@paid("my_data_tool")
def my_data_tool(item: str) -> str:
    return '{"item": "%s", "price": 1.24}' % item

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8797)

③ systemd 常驻

# /etc/systemd/system/x402.service
[Unit]
Description=My x402 paid MCP server
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/my-x402
Environment=X402_NETWORK=eip155:8453
Environment=X402_FACILITATOR=https://facilitator.payai.network
Environment=PORT=8797
ExecStart=/opt/my-x402/venv/bin/python server.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
# systemctl daemon-reload && systemctl enable --now x402

④ nginx 反代 /mcp

location ^~ /mcp {
    proxy_pass http://127.0.0.1:8797;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;   # streamable-http 走 SSE，必须关缓冲
    proxy_cache off;
    proxy_read_timeout 300s;
}

⑤ 零成本验证（不花真钱就有说服力）

# 零成本验证（不花真钱）：不付款直接调付费工具，应返回 402 支付挑战
curl -s https://你的域名/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'
# 然后在带 session id 的情况下调 tools/call（不带 X-PAYMENT），
# 响应的 accepts 里应看到：network=eip155:8453、asset=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913、
# payTo=你的地址、amount=50000（=$0.05）

⑥ 真钱验证（充 USDC + 链上核验）

# 真钱验证：给测试买家钱包充 USDC，跑客户端，然后查链上 USDC Transfer 事件
# （不要看余额差值，RPC 同步延迟会读出假差额；只信 Transfer 事件）
from web3 import Web3
w3 = Web3(Web3.HTTPProvider("https://base-rpc.publicnode.com"))  # mainnet.base.org 会 429
USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
topic = w3.keccak(text="Transfer(address,address,uint256)").hex()
logs = w3.eth.get_logs({
    "fromBlock": w3.eth.block_number - 3000,
    "toBlock": "latest",
    "address": USDC,
    "topics": [topic,
               "0x" + "0"*24 + buyer[2:].lower(),
               "0x" + "0"*24 + seller[2:].lower()],
})
for lg in logs:
    print(int(lg["data"].hex(), 16) / 1e6, "USDC 已到账")

⑦ 让别人找得到你（发现层）

• /.well-known/mcp.json 与 /.well-known/x402.json：机器可读的工具清单与价目，放站点根目录
• MCP 官方 Registry：用 GitHub releases 的 mcp-publisher 二进制（不是 npm 上的同名包，那个是假的），域名验证走 HTTP 文件（往 /.well-known/mcp-registry-auth 写一条 v=MCPv1 记录），不用动 DNS
• llms.txt：声明 MCP 端点与付费方式，AI 爬虫会抓

我们踩过的 7 个坑（别处没有）

本文真实验证案例（可链上核对）

常见问题