HPP x402 MCP Bridge

@hpp-io/x402-mcp-bridge

The agent payment rail for HPP. A stdio MCP bridge + the hpp-x402 CLI that let

Claude Desktop / Claude Code / Cursor / Windsurf / OpenClaw make autonomous

HPP USDC.e payments over x402 — discover paid services,

pay per call, within a spend cap. No API keys, no manual signing.

📖 Full documentation

[hpp-io/x402-tools](https://github.com/hpp-io/x402-tools) — the complete manual: how it works, every command, buyer and seller flows, payment schemes (exact / upto), wallet modes, and troubleshooting. This README is a quick reference.

Install

# 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

Needs Node 20+. On a headless box (no OS keychain) use setup --print-key — see the manual.

Quick start

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

Restart your host and your agent can discover and pay for services. Browse and pay from the terminal too:

hpp-x402 discover "price prediction"               # semantic search; your network only

hpp-x402 describe # input args (schema + example) — no payment hpp-x402 call --body '{"hi":"there"}' # pay + call — a URL, or an id from discover

Pay from your HPP Smart Wallet instead

Rather than funding the agent's key, let it pay from your HPP Smart Wallet under a spending limit you set. In the wallet, open Agents → New, paste the agent's address (hpp-x402 wallet address), issue the delegation, then run the command the wallet shows — it is this, with the value filled in:

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

Run it on the machine where the agent's key lives. The value is checked against that key and the network before it is written, and again each time the bridge starts. The value can only be used by that key, within the limit, until it expires — but it does end up in your shell history, so treat it like a card with a cap. To stop the agent, revoke the delegation in the wallet.

Full command reference, selling (serve), schemes, and Safe mode → the [manual](https://github.com/hpp-io/x402-tools).

Use it from an MCP host

The host spawns the bridge over stdio. A bare entry boots zero-config on HPP Sepolia with an auto-created keychain wallet:

{ "mcpServers": { "hpp-x402": {

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

hpp-x402 install writes this for you. Note: a bare npx @hpp-io/x402-mcp-bridge runs the MCP server (what the host wants) — for the CLI use npx -y -p @hpp-io/x402-mcp-bridge hpp-x402 .

Host-facing tools

Every paid call stays within your spend cap (per-call cap defaults to 1 USDC.e; raise it with wallet_set_limit) and is paid only in allowlisted tokens; discovery never holds funds or sees your keys.

Key env (all optional)

Full environment reference + Safe/governance setup are in the manual.

Related

Building an agent / SDK integration (LangChain, OpenAI function-calling, AgentKit, A2A)? See the runnable gallery → hpp-io/hpp-x402-agent-sample

License

Apache-2.0