Agent Wormhole

wormhole-x402

Integration guide: payment safety, policy, confirmed top-ups and launch attestations.

Your agent is about to sign a payment. Is it the one it was quoted?

ALLOW    pays the quoted merchant, quoted amount

REFUSE pays an ATTACKER instead [X402-001] payment destination is not the account derived from the quote REFUSE pays the merchant but 900x the amount [X402-002] payment amount does not match the quoted amount REFUSE pays correctly + silently approves a delegate [X402-006] Approve — delegates spending authority over the account ABSTAIN garbage bytes could not deserialize — refusing to report it as safe

5 transactions checked in 5ms — no RPC, no network

The gap

Every transaction-security product answers the same question: what will this transaction do? Simulation, asset diffs, address reputation. All useful.

None of it helps an agent, because a payment to an attacker's address simulates perfectly. Correct balances. No revert. Clean verdict. The transaction is entirely valid — it is simply not the one that was asked for.

Nobody answers *is this the transaction that was asked for?*

In the leading provider's API that question is not merely unimplemented, it is not expressible. Their Solana scan request carries origin — *"DApp domain proposing these transactions"* — and has no field for the agent's instructions at all. The stack is shaped around a human approving a website's request. A headless agent has neither a website nor a human.

How it decides

One call, either chain

verify() takes a quote and the payment about to be signed, picks the rail from the network string, and returns one verdict. It runs the quote-text scan first — an injected instruction in a merchant's description is refused before its numbers are ever treated as authoritative — then compares destination, asset and amount.

import { verify } from "wormhole-x402/verify";

const result = await verify( { network: "eip155:8453", // or "solana" quote, // what the merchant's 402 said payload, // what the agent is about to sign }, { quoteProvenance: "caller_asserted", issuedAt: new Date().toISOString() }, );

if (result.decision !== "allow") { // refuse AND abstain both mean do not sign. "We could not check it" is // never "it is fine" — that conflation is the bug this library exists for. throw new Error(result.findings.map((f) => f.code).join(",")); }

Time is an input rather than read from the clock, so a verdict is a pure function of its request and replays identically later.

The other entry points

guardedPay takes the transport as an argument rather than a URL, so the same call runs against the local verifier or a remote one and the two cannot drift.

A verdict off a socket is a claim, not an answer

guardedPay and guardedFetch require an integrity option. It has no default, because every default here is either a silent downgrade of your security or a surprise change to your behaviour:

import { guardedPay } from "wormhole-x402/client";

import { publicKeyFromSpkiBase64 } from "wormhole-x402/receipt";

// The verifier publishes its key at GET /v1/key const publicKey = publicKeyFromSpkiBase64(publishedKeyBase64);

const res = await guardedPay({ network, quote, payload, transport, integrity: { mode: "required", publicKey }, }); if (res.allow) await sign(payload);

Under mode: "required" a decisive verdict clears only if a receipt is present, its signature verifies against your key, the receipt is bound by digest to the request you actually sent, and the receipt's own decision agrees with the envelope's. Anything else becomes an abstain — never an allow, and never a refuse — with integrityFailure naming which check failed. res.verified tells you whether the cryptography actually ran.

For an in-process transport that never crosses a network, say so explicitly:

integrity: { mode: "trusted_transport", reason: "in-process verify(), no socket" }

verified is then false, because nothing was checked. A verifier running without a signing key produces abstains under required, which is the honest answer: an unsigned verdict is one nobody can check.

The MCP server applies the same rule to hosted verdicts. Set WORMHOLE_VERIFY_PUBKEY to the published key; without it a hosted allow is downgraded to abstain unless you explicitly accept an unverifiable one with WORMHOLE_ALLOW_UNSIGNED_HOSTED=1.

Receipts

A decisive verdict carries a receipt: the decision, the rule codes, a coarse amount band and a SHA-256 digest of the request — never the quote text, never the payment bytes. Signed, it is checkable by someone who does not trust you:

import { verifyReceipt, replayMatches } from "wormhole-x402/receipt";

verifyReceipt(receipt, signature, publicKey); // did we really say this? replayMatches(receipt, request); // is it this exact request?

Neither call touches the network. That is the point of a receipt — an attestation you have to phone someone to check is just their word with extra steps.

Install

Every chain dependency is an optional peer, so you install only the one you use — and you must install it. The entry point for each chain imports its own SDK at the top level, so wormhole-x402 alone imports nothing useful:

# Solana

npm install wormhole-x402 @solana/web3.js @solana/spl-token

EVM

npm install wormhole-x402 viem

Text scanning only — no chain SDK needed

npm install wormhole-x402

Each entry point is independent. wormhole-x402/evm and wormhole-x402/quotetext work with no Solana packages present, and wormhole-x402 works with no viem. Importing an entry point whose SDK is not installed is a module-resolution error, not a silent no-op.

As an MCP tool server

Agents that cannot be rewired — Claude Code, Cursor, any MCP host — get the same checkpoint as a tool. Zero extra dependencies: the server is newline-delimited JSON-RPC over stdio, spoken with Node's own readline.

# full install — verifies payments on both rails

claude mcp add x402-guard -- npx -y -p wormhole-x402 -p @solana/web3.js -p @solana/spl-token -p viem wormhole-x402-mcp

lightest form — text scanning only; verify_payment abstains with install

instructions until the chain SDKs for your rail are present

claude mcp add x402-guard -- npx -y wormhole-x402

Two tools:

• `verify_payment` — network, quote, payload (and optionally expectedPayer) in; allow / refuse / abstain with findings out. Anything that is not allow means do-not-sign.
• `scan_text` — a 402 body, a merchant listing, an agent card, a memo; scanned for injection shapes before the model reads it.

The server always starts and scan_text always works — the verify core loads lazily, so a missing chain SDK is a per-call abstain naming the install command, never a startup crash.

Set WORMHOLE_API_KEY and verification runs against the hosted verifier instead, returning its answer verbatim — including any spend-policy decision the operator's account enforces there. An unreachable hosted verifier abstains rather than silently falling back to the local core: the operator configured hosted mode to get their policy applied, kill switch included. Verdicts carry caller_asserted provenance — the server cannot see where the quote came from, so its receipts say so rather than implying an attestation nobody made.

import { guardSigner } from "wormhole-x402";

// quote is the PaymentRequirements from the server's HTTP 402 response. const wallet = guardSigner(myWallet, () => currentQuote);

// Signing now throws unless the transaction matches the quote. await wallet.signTransaction(tx);

On EVM the payment is a detached EIP-3009 authorization rather than a transaction, so it has its own wrapper — same guarantee, async because domain verification can read the chain:

import { guardEvmSigner } from "wormhole-x402/evm";

const signer = guardEvmSigner(myWalletClient, () => currentQuote);

// viem sends this single object; ethers sends the same parts positionally — // signTypedData(domain, types, value) — and the wrapper recognises both. This // is the call that CREATES the signature, so there is nothing to recover from // yet. The wrapper checks the domain against the trusted table for (chainId, // asset), requires the TransferWithAuthorization struct exactly as verified, // and compares to, value, the validity window and the nonce to the quote. await signer.signTypedData({ domain, types, primaryType, message });

The typed-data request is what the wallet signs, so it is the one checked, read where the signer reads it: viem's one request object, the first argument, or ethers' domain, types and value, the first three. A call that could be read either way, or that carries an already-signed payment beside a typed-data request, is refused, with the typed request's own findings when it has any: which one a wallet would sign is the wallet's choice, and one cannot be checked for the other.

Both wrappers are default-deny. Every function property is wrapped, not a named subset: the ones the wrapper knows how to check are checked, and everything else is *refused* rather than handed back. Object properties that expose signing methods — viem's account, a wallet adapter's inner provider — are wrapped too, because handing back the raw object is the same hole one level down.

That means an unmodelled method is unusable rather than unchecked, which is the trade worth making: "we did not recognise the call so we allowed it" is how every bypass is written up afterwards. If a method cannot move funds, name it in allow — an escape hatch with a name on it. Dotted paths work for nested members (allow: ["account.sign"]).

No quote is a refusal, not a pass. Every optional security parameter with a permissive default ends up unset in production, and then the guard reports green on all traffic and nobody notices.

Or inspect without wrapping:

import { inspectPayment } from "wormhole-x402";

const verdict = inspectPayment(