HPP x402 MCP Bridge

@hpp-io/x402-mcp-bridge

HPP 的 Agent 支付通道。一个 stdio MCP 桥接程序 + hpp-x402 命令行工具，让 Claude Desktop / Claude Code / Cursor / Windsurf / OpenClaw 能通过 x402 自主支付 HPP USDC.e——发现付费服务、按次付费，并遵守支出上限。无需 API 密钥，无需手动签名。

📖 完整文档

hpp-io/x402-tools — 完整手册： 工作原理、所有命令、买家和卖家工作流、支付方案（exact / upto）、钱包模式和故障排除。本 README 是快速参考。

安装

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/hpp-io/x402-tools/main/install/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/hpp-io/x402-tools/main/install/install.ps1 | iex
# …or npm
npm install -g @hpp-io/x402-mcp-bridge

需要 Node 20+。在无头环境（没有操作系统密钥链）中，请使用 setup --print-key——参见 手册。

快速开始

hpp-x402 setup --install claude-code   # create a wallet + register into your host
hpp-x402 fund                          # where to send USDC.e (gasless, no native gas)
hpp-x402 status                        # confirm it's wired

重启宿主后，Agent 就能发现服务并为其付款。也可以从终端浏览并付款：

hpp-x402 discover "price prediction"               # semantic search; your network only
hpp-x402 describe <id>                             # input args (schema + example) — no payment
hpp-x402 call <url-or-id> --body '{"hi":"there"}'  # pay + call — a URL, or an id from discover

改用 HPP Smart Wallet 付款

无需为 Agent 的密钥充值，让它在你设置的支出限额内通过 HPP Smart Wallet 付款。在钱包中，打开 Agents → New，粘贴 Agent 的 地址（hpp-x402 wallet address），签发委托，然后运行钱包显示的命令——命令如下，填入对应值：

hpp-x402 install claude-code -n eip155:190415 --delegation 0x…

请在 Agent 密钥所在的机器上运行。写入前会根据该密钥和网络检查该值，桥接程序每次启动时也会再次检查。该值只能由该密钥在限额内使用，直到过期——但它确实会出现在你的 shell 历史记录中，因此请像对待有额度上限的银行卡一样谨慎保管。要停止 Agent，请在钱包中撤销委托。

完整的命令参考、出售服务（serve）、支付方案和 Safe 模式，请参阅 → 手册。

在 MCP 宿主中使用

宿主通过 stdio 启动桥接程序。直接使用基本配置会在 HPP Sepolia 上以零配置模式启动，并自动创建密钥链钱包：

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

hpp-x402 install <host> 会为你写入此配置。注意：直接运行 npx @hpp-io/x402-mcp-bridge 会启动 MCP 服务（宿主所需的程序）——使用命令行工具时，请运行 npx -y -p @hpp-io/x402-mcp-bridge hpp-x402 <command>。

面向宿主的工具

工具	功能
wallet_address	返回你的钱包地址（用于为其充值）
hpp_discover	列出/搜索精选 HPP 目录（只读）
hpp_describe	查看单个服务的输入参数——架构 + 示例（只读）
hpp_call	调用已发现的服务（HTTP/MCP/A2A）；通过你的钱包付款
x402_http_call	付款并调用任意 x402 HTTP 端点
pay_a2a_agent	付款并向另一个 A2A Agent 发送消息

每次付费调用都不会超出你的支出上限；发现服务不会持有资金，也不会访问你的密钥。

关键环境变量（均可选）

变量	说明
DELEGATE_PRIVATE_KEY	如果未设置，会在 OS 密钥链中自动创建
HPP_NETWORK	eip155:181228 Sepolia（默认）/ eip155:190415 Mainnet
RESOURCE_SERVER_URL	代理一个上游 MCP 服务（省略则仅使用本地工具）
SAFE_ADDRESS + ALLOWANCE_MODULE_ADDRESS	两者均设置时启用 Safe（治理）模式
HPP_PAYMENT_DELEGATION	钱包授予此密钥的 ERC-7710 支付委托：支付 erc7710，并在链上限额内接受来自用户智能账户的付款——此密钥无需 USDC.e。运行 hpp-x402 install <host> --delegation <value> 可写入该值。安装和启动时都会根据密钥和网络进行检查（在其他网络上签发、已撤销或已过期的值都会导致桥接器停止，并说明原因）；未设置时会跳过此类接受

完整的环境变量参考和 Safe/治理设置，请参阅手册。

相关内容

正在构建 Agent / SDK 集成（LangChain、OpenAI function-calling、AgentKit、 A2A）？请查看可运行示例集 → hpp-io/hpp-x402-agent-sample

许可证

Apache-2.0