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}">
</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 via x402: USDC on Base or Solana, or USDG on Robinhood Chain. No subscription, no minimum. When credit runs out the endpoint answers 402 with an exact, signed-payable quote.
All of this revenue buys back $WORM on Robinhood Chain, and the $WORM bought is burned. The free tools never need the token. The wallets, and how Wormbook's fees are used, are in the docs.
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_rulesis not a safety certificate,abstainis not an all-clear, and a checked token can still rug. Contract code, tokenomics, and teams are out of scope, on purpose.watchreads 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.
