Agent Wormhole — Claude Code MCP server: x402 payment checks
Checks whether the payment your agent is about to sign matches the one it was quoted. Verdicts come back offline.
claude mcp add --env WORMHOLE_API_KEY=<WORMHOLE_API_KEY> --env WORMHOLE_VERIFY_URL=<WORMHOLE_VERIFY_URL> --env WORMHOLE_ADDRESS_LEDGER=<WORMHOLE_ADDRESS_LEDGER> --transport stdio x402-guard -- npx -y wormhole-x402What Agent Wormhole does
Your agent has a quote and is one step from signing. Agent Wormhole compares the destination, the asset and the amount against what the quote actually said, then returns a single verdict: allow, refuse or abstain. The reason this matters: a payment to an attacker's address simulates cleanly. Balances line up, nothing reverts, the transaction is valid. It just isn't the one that was requested.
The core is verify(), which picks the rail from the network string and scans the quote text first — an instruction hidden in a merchant's description gets refused before its numbers are treated as trustworthy. Other entry points cover the rest: guardedPay() and guardedFetch() sit in front of sign(), verifyReceipt() and replayMatches() check a receipt without a socket, and createVerifyHandler() lets you host the verifier yourself. Time arrives as an argument instead of being read from the clock, so replaying a request gives the same verdict.
A verdict that came over a socket is a claim, not an answer. That's why guardedPay and guardedFetch demand an integrity option with no default — any default would either weaken your security quietly or change behaviour behind your back. Under mode: "required" a decisive verdict clears only when a receipt is present, its signature matches your key, and the receipt's decision agrees with the envelope's. Everything else turns into an abstain.
What it helps with
- catch a swapped payment destination before signing
- match the payment amount against the quoted one
- spot a hidden Approve that grants spending authority
- tell a failed check apart from a clean one
- verify a payment receipt with no network call
Example prompts for the agent
- Check this x402 payment with wormhole-x402 before I sign it
- Compare the destination and amount in this transaction against the quote
- Verify the receipt for this request offline
How to install Agent Wormhole
Platform CLI
claude mcp add --env WORMHOLE_API_KEY=<WORMHOLE_API_KEY> --env WORMHOLE_VERIFY_URL=<WORMHOLE_VERIFY_URL> --env WORMHOLE_ADDRESS_LEDGER=<WORMHOLE_ADDRESS_LEDGER> --transport stdio x402-guard -- npx -y wormhole-x402Replace <…> with your own values
Platform CLI
codex mcp add x402-guard --env WORMHOLE_API_KEY=<WORMHOLE_API_KEY> --env WORMHOLE_VERIFY_URL=<WORMHOLE_VERIFY_URL> --env WORMHOLE_ADDRESS_LEDGER=<WORMHOLE_ADDRESS_LEDGER> -- npx -y wormhole-x402Replace <…> with your own values
Config file
{
"mcpServers": {
"x402-guard": {
"command": "npx",
"args": [
"-y",
"wormhole-x402"
],
"env": {
"WORMHOLE_API_KEY": "<WORMHOLE_API_KEY>",
"WORMHOLE_VERIFY_URL": "<WORMHOLE_VERIFY_URL>",
"WORMHOLE_ADDRESS_LEDGER": "<WORMHOLE_ADDRESS_LEDGER>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"x402-guard": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"wormhole-x402"
],
"env": {
"WORMHOLE_API_KEY": "<WORMHOLE_API_KEY>",
"WORMHOLE_VERIFY_URL": "<WORMHOLE_VERIFY_URL>",
"WORMHOLE_ADDRESS_LEDGER": "<WORMHOLE_ADDRESS_LEDGER>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e WORMHOLE_API_KEY=<WORMHOLE_API_KEY> -e WORMHOLE_VERIFY_URL=<WORMHOLE_VERIFY_URL> -e WORMHOLE_ADDRESS_LEDGER=<WORMHOLE_ADDRESS_LEDGER> x402-guard npx -y wormhole-x402Replace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Agent Wormhole
How do I install Agent Wormhole in Claude Code?
Run claude mcp add wormhole-x402 -e WORMHOLE_API_KEY=<WORMHOLE_API_KEY> -- npx -y wormhole-x402. Or register it with a verifier URL and an address ledger: `claude mcp add --env WORMHOLE_API_KEY=<WORMHOLE_API_KEY> --env WORMHOLE_VERIFY_URL=<WORMHOLE_VERIFY_URL> --env WORMHOLE_ADDRESS_LEDGER=<WORMHOLE_ADDRESS_LEDGER> --transport stdio x402-guard -- npx -y wormhole-x402`.
What does Agent Wormhole do?
It compares the payment an agent is about to sign with the quote it received — destination, asset, amount — and returns allow, refuse or abstain. An abstain means the check couldn't be completed, not that the payment is safe.
Does the server need a key?
Yes, the install commands pass WORMHOLE_API_KEY. To validate hosted verdicts, set WORMHOLE_VERIFY_PUBKEY; without it an allow is downgraded to abstain.
