mcp-x402-pay

Name: mcp-x402-pay
Author: CryptoAPIs-io

本地服务

github.com/CryptoAPIs-io金融数据02 天前更新

代码仓库

关于 mcp-x402-pay

mcp-x402-pay 是供 Agent 发现并支付 x402 保护资源的 MCP 服务。它支持 EVM 和 Solana 付款，在本地签名，并可限制付款请求的站点和金额。

主要功能

01付款后获取并重试 x402 保护的 URL
02发现资源及其标价
03使用每次调用提供的私钥本地签名
04限制付款网络、金额和站点
05支持 EVM 和 Solana 付款

适用场景

01在 x402 目录中查找付费 API
02调用返回 402 Payment Required 的 URL

MCP 相关

通过 stdio 向 MCP 客户端提供 x402_pay 和 x402_discover 工具。x402_pay 会先授权并在本地签名，再重试受保护的请求。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cryptoapis-io-mcp-x402-pay": {
      "command": "npx",
      "args": [
        "-y",
        "@cryptoapis-io/mcp-x402-pay"
      ]
    }
  }
}

启动命令npx -y @cryptoapis-io/mcp-x402-pay

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@cryptoapis-io/mcp-x402-pay0.5.3stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
url	string	是	要获取的资源 URL（可能需要付费）
body	string	否	请求正文（字符串；如有需要，可通过 headers 设置 content-type）
apiKey	string	否	你的 CryptoAPIs API 密钥，需包含 X402_BUYER 功能（仅用于调用 buyer /authorize）。如果未设置，则使用 CRYPTOAPIS_API_KEY 环境变量；设置一次后即可省略此参数。
method	enum	否	HTTP 方法（默认 GET）GET \| POST \| PUT \| PATCH \| DELETE
headers	object	否	额外请求头
tronKey	string	否	Tron 私钥（十六进制）。如果未设置，则依次使用 X402_TRON_KEY、privateKey/X402_PRIVATE_KEY（相同的 secp256k1 曲线）。
utxoWif	string	否	WIF 格式的 UTXO 私钥——用于签署 utxo-transaction 付款（bitcoin/ltc/doge/dash/bch/zcash）。如果未设置，则使用 X402_UTXO_WIF。
xrpSeed	string	否	XRP 密钥/种子（base58，例如 s...）——用于签署 xrp-transaction 付款。如果未设置，则使用 X402_XRP_SEED。
kaspaKey	string	否	Kaspa 私钥（十六进制，32 字节）——用于签署 kaspa-transaction 付款。如果未设置，则使用 X402_KASPA_KEY。
walletId	string	否	CryptoAPIs buyer-service 钱包 RECORD ID（由 POST /wallets 返回的 ID）——不是链上地址；传入地址会返回 wallet_not_found。如果未设置，则使用 X402_WALLET_ID 环境变量。请先创建一个（每个 blockchain+network 创建一次）：向 https://ai.cryptoapis.io/x402/buyer/wallets 发送 POST 请求，并提供 {blockchain, network（CAIP-2 ID，例如 eip155:8453 或 solana:<genesisHash>——不能是无前缀名称）, address（你的公钥地址；Solana/Kaspa 必填）} → 返回 walletId。
maxAmount	string	否	可选的安全上限：如果所需的原子单位金额超过此值，则拒绝付款。
svmSecret	string	否	Solana 密钥（base58 编码的 64 字节密钥对密钥）——用于签署 svm-transaction 付款。如果未设置，则使用 X402_SVM_SECRET。
privateKey	string	否	EVM 私钥（十六进制，可选 0x 前缀）——用于签署 eip712（EVM）付款，默认也用于 Tron。如果未设置，则使用 X402_PRIVATE_KEY。安全提示：仅限可信的本地环境。
allowedHosts	array	否	限制允许付款的主机，例如 ["api.acme.com"]（前置点号可匹配子域名：".acme.com"）。列表外的 url 会在任何网络调用之前被拒绝。如果未设置，则使用 X402_ALLOWED_HOSTS 环境变量（逗号分隔）。请在该环境变量中设置允许列表，将其保护在模型无法触及的范围之外，防止提示词注入的 url 扩大允许列表。
buyerBaseUrl	string	否	覆盖 buyer 服务的基础 URL（默认值：https://ai.cryptoapis.io/x402/buyer）
allowedNetworks	array	否	限制允许付款的 CAIP-2 网络（例如 ["eip155:8453"]）

详细介绍

@cryptoapis-io/mcp-x402-pay

这是 x402 的买方端——Agent 用来消费（为资源付款）的工具。想要对 API 收费的商家应使用中间件 SDK（@cryptoapis-io/x402-merchant-sdk），而不是 MCP 工具。

一个 MCP 服务，可让 AI Agent 查找并支付受 x402 保护的 HTTP 端点。

x402_pay——获取 URL；如果服务端返回 402 Payment Required，则通过 CryptoAPIs 买方服务授权付款，在本地签名，重试并返回付款后的响应。
x402_discover——浏览 facilitator 的 x402 资源目录及其价格，让 Agent 能找到付费 API，而不只是调用别人提供的 API。

**非托管：**私钥按请求传入，且不会离开进程（无 HTTP 服务——仅使用 stdio）。

**目前支持：**EVM（eip712，例如 Base USDC）和 Solana。Tron、Bitcoin/UTXO、XRP 和 Kaspa 即将推出——已接入但尚未启用；在这些网络上付款会返回明确的 family_not_yet_supported（“即将推出”）结果。

运行

node dist/cli.js            # stdio MCP server (no --api-key at startup; keys are per-tool-call)

前提条件——Agent 的 `walletId`

x402_pay 从 CryptoAPIs Agent 钱包（walletId）付款。付款前，请为每个区块链和网络创建一次钱包——向买方 API 发送一个 POST 请求即可获取 ID（非托管：只需注册你的公开地址）：

curl -X POST https://ai.cryptoapis.io/x402/buyer/wallets \
  -H "x-api-key: $CRYPTOAPIS_API_KEY" -H "content-type: application/json" \
  -d '{"blockchain":"base","network":"eip155:8453","address":"0xYourAddress"}'
# → { "walletId": "…" }

network 必须是 CAIP-2 ID（eip155:8453、solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp 等），不能是简单的名称；并且必须且只能提供 address（适用于任何链；Solana/Kaspa 必填）或 xpub（支持 xpub 的链）之一。格式错误的请求体会返回明确的 400 malformed_request。将返回的 ID 设置为 X402_WALLET_ID（或传入 walletId）。

工具：`x402_pay`

输入	必填	说明
`url`	✓	资源（可能需要付费）
`apiKey`	✓	你的 CryptoAPIs 密钥（X402_BUYER 功能）——仅用于调用买方 `/authorize`
`walletId`	✓	`POST /wallets` 返回的钱包记录 ID（注册表中的 `_id`）——不是链上地址（传入地址会得到 `wallet_not_found`）
`privateKey`	✓	钱包的 EVM 密钥——在本地签名，绝不会发送到任何地方
`method`/`body`/`headers`		要发起的请求
`allowedNetworks`		限制可付款的 CAIP-2 网络
`maxAmount`		安全上限——如果所需的最小单位金额超过该值，则拒绝
`allowedHosts`		限制允许付款的网站，例如 `["api.acme.com"]`（前置点号表示子域名）。列表之外的 URL 会在任何网络调用之前被拒绝。未设置时回退到 `X402_ALLOWED_HOSTS`（逗号分隔）——将其固定在此处，使允许列表不受模型控制

返回 { status, paid, body, settlement? }。对于没有可接受选项的 402 响应（或金额超过 maxAmount），会返回 paid:false 和 reason——不会签名或付款。

工具：`x402_discover`

浏览 x402“集市”——已注册的 x402 资源及其收费情况（规范 §8）。

输入	必填	说明
`type`		按资源类型筛选，例如 `"http"`
`limit`		分页大小，1–100（默认 20）
`offset`		分页时跳过的行数（默认 0）
`facilitatorBaseUrl`		覆盖 facilitator（QA/本地环境）

返回 { resources: [{ resource, type, x402Version, accepts, lastUpdated, metadata? }], pagination }。

公开——无需 API 密钥或钱包，也不会花费任何资金，因此始终可以安全调用。请注意，accepts[].amount 以最小单位表示（USDC 保留 6 位小数："10000" = $0.01）——向用户报价前请先换算。将选定的 resource 传给 x402_pay 即可实际购买。

流程

fetch(url)。如果不是 402 → 返回该响应。
遇到 402 → 选择一项 accepts 条目（遵循允许列表），通过买方 /authorize 授权 → 获取签名材料。
在本地签名（使用 @cryptoapis-io/mcp-signer 的 evm_sign 类型化数据）→ 构建 x402 PaymentPayload （线路方案始终为 exact；所属系列由 network 指定）。
使用 base64 编码的 X-PAYMENT 标头重试；返回付款后的响应以及 X-PAYMENT-RESPONSE 结算信息。