Agent Wormhole

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

The security layer for agentic commerce.

agentwormhole.com · docs · dashboard · research

AI agents now read instructions they did not write, sign payments a merchant priced, and buy tokens whose metadata an attacker typed. All three are the same problem — untrusted text reaching a model that acts — and this is one stack that covers all three:

Everything verifiable is free forever — badges, attestations, signatures, verdicts. The metered work is what costs, in USDC over x402, and an agent can pay for itself with no human in the loop.

Quickstarts

Protect a coding agent — 30 seconds, offline, free

pipx install wormhole-guard
wormhole scan ~/your-project --blast-radius   # what is there now
wormhole init ~/your-project                  # harden + baseline (dry run until --apply)

 CRITICAL  SessionStart hook executes a script from an unusual path  [AUTOSTART-002]
  .claude/settings.json
  `node .github/setup.js` runs unprompted on SessionStart. This survives
  uninstalling the package that planted it.

No account, no API token, no network call. Your CLAUDE.md never leaves the machine. Then wire the three hooks — what arrives, what leaves, what persists:

wormhole readguard --install   # inbound: fetched pages, shell output, MCP responses
wormhole outbound --install    # outbound: refuse to pass a payload on
wormhole guard --install       # writes: the PreToolUse hook

Give any MCP agent the check-first habit

Claude Code, Cursor, any MCP host — five tools, including check_token (check a token launch before reading its metadata) and check_before_use (check a page, manifest, or listing before trusting it):

{
  "mcpServers": {
    "wormhole": {
      "command": "npx",
      "args": ["-y", "wormhole-x402", "mcp"],
      "env": { "WORMHOLE_API_KEY": "awk_..." }
    }
  }
}

Without a key the tools run locally and read the free registry; with one, unobserved tokens are scanned on demand.

Agent-native API — register and arrive funded, one call

No GitHub, no browser, no human. Attach an x402 payment (USDC on Base or Solana) and the new tenant is born funded:

curl -X POST https://dashboard.agentwormhole.com/api/v1/register \
  -H "content-type: application/json" \
  -H "X-PAYMENT: <base64 x402 payment>" \
  -d '{"name":"my trading agent"}'
# → { "api_key": "awk_…", "balance_micro_usdc": "1000000", ... }

Registering without a payment also works — the key starts at zero and any paid call answers 402 with an exact quote for both rails. Sign EVM authorizations with hours of validity, not minutes: an expired authorization is money nobody can collect.

# then: check any token before your agent reads it (free)
curl https://dashboard.agentwormhole.com/api/v1/token/4663/0x…      # Robinhood Chain
curl https://dashboard.agentwormhole.com/api/v1/token/0/<base58>    # Solana

# scan one on demand ($0.01) — metadata plus every link it ships with
curl -X POST https://dashboard.agentwormhole.com/api/v1/scan \
  -H "x-api-key: awk_…" -H "content-type: application/json" \
  -d '{"network":"solana","address":"<mint>"}'

# put a token's website on a continuous watch (re-checks bill at $0.005)
curl -X POST https://dashboard.agentwormhole.com/api/v1/watch \
  -H "x-api-key: awk_…" -H "content-type: application/json" \
  -d '{"kind":"url","subject":"https://token-site.example"}'

Gate a launchpad — two calls and an image tag

Scan at creation, before the token exists; mint with the same bytes and the pre-attestation chains to the on-chain one:

curl -X POST https://dashboard.agentwormhole.com/api/v1/scan \
  -H "x-api-key: awk_…" -H "content-type: application/json" \
  -d '{"bundle":{"name":"…","symbol":"…","description":"…"}}'

<a href="https://dashboard.agentwormhole.com/t/4663/{address}">
  <img src="https://dashboard.agentwormhole.com/api/badge/token/4663/{address}" height="28" />
</a>

The badge is live: green check while clean, amber on a metadata change, red on findings, grey when stale — and it never says "safe", because that is not what is being attested. Full kit with 402 handling and offline signature verification: docs.agentwormhole.com#launchpad-kit.

Prices

Prepaid USDC via x402 on Base or Solana. No subscription, no minimum. When credit runs out the endpoint answers 402 with an exact, signed-payable quote.

Why

June 2026: the Miasma worm disabled 73 Microsoft GitHub repositories — not with a memory bug, but by writing agent configuration: SessionStart hooks, .cursor/rules, folderOpen tasks. The persistence survives npm uninstall and survives reinstalling the agent. Your vendor protects its own settings.json; nothing protects your CLAUDE.md — and by default your agent can write to it. (Threat model, with the Dataminr analysis and the NDSS 2026 AgentWorm paper: 82% attack success via skill poisoning, 0% under sandbox isolation, and 0 of 82 public configs had it on.)

The same asymmetry runs through payments and launches. A payment to an attacker's address simulates perfectly — so wormhole-x402 checks the transaction against the merchant's own 402 quote, a channel the model never touches. A token launch is attacker-controlled text that reaches a trading agent before any moderation exists — the launch layer's first live scan caught a token impersonating "STOCK" with an invisible zero-width character. Every launch on Robinhood Chain is now observed within minutes, attested with an ed25519 signature over its exact bytes, and re-checked daily; a metadata edit — on-chain or in the IPFS JSON — voids the attestation by arithmetic, publicly, with a counter.

What the words never say is "safe". Verdicts are clean_by_rules or findings; badges say checked, changed, or findings. Rules are the evadable layer and are labelled as such — the load-bearing parts are hashes, signatures, and baselines, which do not care how a payload is worded.

What it does, precisely

This is an integrity monitor for the text an agent acts on. The parts that matter do not care what the payload says.

The control that drives infection to zero is sandbox isolation, and it lives in your agent framework, not here — per Anthropic's own docs it does not cover Read/Edit/Write by default. This tool makes that gap impossible to overlook.

Limits

Stated plainly, because a security tool that overclaims is worse than none:

• Regex rules catch shapes, not meaning. Novel phrasing evades them. Detection falls to roughly 71% under combined mutation, and that is an upper bound — the mutations are lexical and offline.
• clean_by_rules is not a safety certificate, abstain is not an all-clear, and a checked token can still rug. Contract code, tokenomics, and teams are out of scope, on purpose.
• watch reads transcripts after the fact; nothing here removes an infection from a running agent or contains an agent running as root.
• Memo worms are not happening yet — 40,000 Solana signatures scanned, zero injection findings. A null result is worth publishing because it makes a first occurrence visible.
• Miasma is confirmed in the wild via package installs. Fully autonomous self-replication is still a lab result, not an observation. We will not blur those two.

The local tools send nothing anywhere: no account, no telemetry, no network call at any point. In full: docs/limits.md.

Documentation

Runnable examples, each with its actual output pasted in: claude-code-hooks · x402-solana · x402-evm · quote-scanning · ci-github-action · agent-fleet

Published research, every number reproducible: the launch layer · 26,844 MCP servers scanned · the agentic-trading injection · ACP seller re-pricing · Solana memo base rate

Contributing

Every new detection rule ships with a benign twin — a file discussing the same attack without being one. If the rule fires on the twin, it does not ship. See CONTRIBUTING.md and SECURITY.md.

License

Apache 2.0.