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 個坑（別處沒有）

本文真實驗證案例（可鏈上核對）

常見問題