# Agent Wormhole

Checks whether the payment your agent is about to sign matches the one it was quoted. Verdicts come back offline.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: runningoffcode
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/runningoffcode/agent-wormhole/tree/HEAD/x402-guard
- Updated: 2026-09-25
- HTML: https://affpapa.org/en/nevibecode/mcp/agent-wormhole

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `WORMHOLE_API_KEY`, `WORMHOLE_VERIFY_URL`, `WORMHOLE_ADDRESS_LEDGER` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
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-x402
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-x402
```
Replace <…> with your own values

## When to use it
- 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
- 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

## Similar
- [agentwallet](https://affpapa.org/en/nevibecode/skills/agentwallet.md) — skill · 2600 installs
- [mpp32-mcp-server](https://affpapa.org/en/nevibecode/mcp/mpp32-mcp-server.md) — MCP server · ★ 221
- [x402 Universal Payer](https://affpapa.org/en/nevibecode/mcp/x402-universal-payer.md) — MCP server · ★ 250
- [TollWarden](https://affpapa.org/en/nevibecode/mcp/tollwarden.md) — MCP server · ★ 2
- [SAP MCP Server](https://affpapa.org/en/nevibecode/mcp/sap-mcp-server.md) — MCP server · ★ 3
- [Onchain Agent Wallets](https://affpapa.org/en/nevibecode/mcp/onchain-agent-wallets.md) — MCP server · ★ 9

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md