x402-payagent-mcp

@arispay/payagent-mcp

为 AI Agent 提供一体化 USDC 支付产品：调用由 x402 付费的 API，并支持支出授权、收据和幂等性。适用于 Claude Desktop、Cursor、Windsurf 或任何 MCP 客户端。这是对 payagent SDK 的轻量封装。

两种钱包托管方式：

• 本地密钥（无需注册）。 将 PAYAGENT_PRIVATE_KEY 设为已注资的 EOA 密钥。pay 在本地签署 EIP-3009——无需 ArisPay 账户或电子邮箱。唯一的限制是钱包余额；请使用余额较低的专用钱包。
• 委托托管（托管式，推荐）。 调用 setup({ email })，即可通过一次调用自动创建账户、CDP 管理的钱包和支出授权。ArisPay 会在签名之前于服务端执行单笔、每日和每月限额；此进程中不会存储私钥。

工具

七个核心工具（默认提供）：

工具	功能	资金
setup	通过一次调用创建或恢复账户和付款钱包（委托模式）	不转移资金
discover	根据意图和预算搜索付费 API 目录	只读
inspect	读取 URL 的价格和付款要求，不进行支付	只读
pay	完整的机器支付流程：请求 → 402 → 选择变体 → 验证策略 → 支付 → 生成结构化收据。必须提供 idempotencyKey；重复使用同一密钥会返回缓存的收据，不会再次支付	会花费真金白银
balance	当前身份、存款地址、链上 USDC 余额和授权限额	只读
history	最近的支付记录——服务端动态记录（委托模式）或本地收据（自行托管）	只读
check_payment_signal	购买 ArisPay Signal：关于 x402 资源的近期签名探测证据（真实付费探测是否已结算并交付？）。有效期内的缓存凭证会直接返回，不产生支出；未知资源免费作答	每次未缓存调用花费 1¢

仅当主机配置设定了 PAYAGENT_MCP_PROFILE=admin 时，才会加载钱包管理工具（create_agent、fund_agent、list_agents、rename_agent）。

每个工具都声明了 MCP 安全注解（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）；pay 和 check_payment_signal 是仅有的破坏性工具——两者都会花费真金白银。

支持矩阵

资产	网络	本地密钥（自行托管）	委托托管（托管式授权）
USDC	Base（默认）	✅	✅
USDC	Ethereum、Polygon	✅	✅
USDC	Base Sepolia（测试网）	✅	✅
USDC (SPL)	Solana、Solana devnet	❌（仅支持 EVM 签名）	✅（自 2026-08-25 起在 api.arispay.app 上线）
USD1	BNB Chain	✅	✅

说明：

• 所有价格均由卖家在 402 挑战中报价；pay 优先选择 EVM 变体；若卖家未提供 EVM 选项，则回退到 Solana。
• 委托授权使用整数分（美分），且会在生成任何签名之前于服务端验证。本地模式没有服务端限额。
• 结算通过单笔链上 transferWithAuthorization（EIP-3009）完成：要么成功，要么原子性回滚。卖家返回 X-PAYMENT-RESPONSE 时，收据会附带结算交易哈希。
• ArisPay 自有的 facilitator（facilitator.arispay.app）不收取 facilitator 费用；卖家可以使用任意 facilitator，并适用其费用和最终性策略。

设置

将此服务添加到 MCP 客户端配置中。无需设置环境变量——之后可在聊天中选择钱包模式，也可以设置以下某个环境选项。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "arispay": {
      "command": "npx",
      "args": ["-y", "@arispay/payagent-mcp"]
    }
  }
}

要使用无需注册的模式，请将密钥添加到 env 块中：

      "env": { "PAYAGENT_PRIVATE_KEY": "0x..." }

Cursor

在 .cursor/mcp.json 中添加相同的服务配置。Windsurf： 在 ~/.codeium/windsurf/mcp_config.json 中使用相同的配置方式。

从零开始，冷启动

• 无需注册： 使用 npx payagent wallet new 生成密钥，将其放入主机配置中的 PAYAGENT_PRIVATE_KEY，然后向打印出的地址发送 Base 上的 USDC。balance 会显示存款地址；pay 用于付款。
• 托管模式： 让 Agent 运行 setup({ email: "[email protected]" }) — 它会返回钱包地址和授权额度。向钱包充值 USDC，使用 balance 确认，然后调用 pay。凭据会持久保存到 ~/.payagent/config.json，并与 payagent CLI 共用。

环境变量（均为可选）

变量	说明
PAYAGENT_PRIVATE_KEY	已注资的 EOA 密钥，用于本地自托管签名（无需注册模式）。
ARISPAY_API_KEY	开发者密钥 — 通常无需设置；setup 会自动配置。
ARISPAY_URL	ArisPay API 基础 URL。默认值为 https://api.arispay.app。
PAYAGENT_MCP_PROFILE	admin 还会加载四个钱包管理工具。默认值：核心（七个工具）。
ARISPAY_AGENT_KEY / PAYAGENT_WALLET	面向 v2.0.x 主机的旧版单 Agent 配置对。

从 v3 迁移

v4 是一个不兼容的版本：功能范围收敛为单一的 x402/USDC 产品。

v3 工具	v4
create_user	setup
pay_api	pay（现在需要 idempotencyKey，并返回结构化回执）
discover_paid_api	discover
inspect_paid_api	inspect
check_wallet、get_balance_agent	balance
—	history（新增）
create_agent、fund_agent、list_agents、rename_agent	保持不变，通过 PAYAGENT_MCP_PROFILE=admin 启用
create_wallet、list_wallets、fund_wallet、get_balance、pay_merchant、create_enduser、attach_card_for_user、set_user_limits、get_user_status	已移除 — 法币充值和平台（终端用户）功能不再属于公开 MCP

回执与幂等性

pay 需要调用方选择 idempotencyKey（至少 8 个字符 — 请使用 UUID）。每笔已完成的付款都会将机器可读回执（金额、资产、网络、钱包、结算交易、剩余授权额度）写入 ~/.payagent/mcp-receipts.json。使用已付款的密钥再次调用 pay，会返回已存储的回执，不会再次付款 — 即使已付款请求在执行过程中失败也是如此。自托管模式下，history 会列出回执；委托模式下则会读取权威服务端信息流。

工作原理

1. Agent 使用 URL 和 idempotencyKey 调用 pay；卖家会以 HTTP 402 响应并提供价格。
2. 如果设置了 PAYAGENT_PRIVATE_KEY，payagent 会在本地签署 EIP-3009 授权。否则，ArisPay 会根据 Agent 的授权额度验证请求，并通过 Coinbase CDP 签名。
3. payagent 使用已签名的付款标头重试；卖家的清算服务会在链上结算 USDC。
4. 工具会返回付款后的响应以及结构化回执。

在委托模式下，此进程中不会存储私钥，超出授权额度的付款会在执行任何链上操作之前被拒绝。在本地模式下，密钥归你所有，并始终留在你的进程中。

安装

npm install @arispay/payagent-mcp

也可以在 MCP 客户端配置中通过 npx @arispay/payagent-mcp 直接调用 — 无需预先安装。npx buyforme-mcp 是同一服务的消费者品牌版本。

相关内容

• payagent — 用于编程调用的 SDK + CLI
• facilitator.arispay.app — ArisPay 的开源 x402 清算服务，用于结算付费的 402 请求
• x402 protocol — HTTP 402 付款标准

许可证

MIT