Coin Scout

[coin-scout: Solana forensics for AI agents]

Give your AI agent a Solana forensics lab.

Trace stolen funds across hops and bridges, unmask wallet clusters run by one operator and screen tokens for rug risk, straight from a chat with Claude or any MCP client. Read-only, powered by Helius.

[CI] [Latest release] [OpenSSF Scorecard] [MIT license]

Install · What it can do · How it works · Tools · Privacy

[An agent asks coin-scout whether BONK is a rug risk. analyze_token returns risk 5/100: mint and freeze authority renounced, top holder 9.5%, top 10 hold 39%, metadata still mutable.]

_{Numbers from a real analyze_token run on BONK, 5 November 2026.}

What it can do

• Follow the money. trace_funds walks transfers forward or backward up to 5 hops, values every edge in USD at the moment it moved, and stops at Wormhole, deBridge, Mayan and Circle CCTP crossings to tell you which chain and address the funds landed on. With followEvm it keeps going on the EVM side.
• Know who is on the other end. 16,050 OKX wallets ship built in, each one proven by OKX's own signed proof-of-reserves message. Traces stop at exchange wallets and mark the address before them as a likely deposit address, so you know which exchange to ask.
• Catch fake volume. detect_wash_trading reads trades straight from a token's pools and flags wallets trading with themselves, same-slot round trips and bot farms funded from one wallet.
• Find the operator. find_cluster mines fee payers, co-signers, rent destinations, shared funders and same-slot activity to surface wallets one actor controls, with the signatures behind every link.
• Screen before you buy. analyze_token checks mint and freeze authority, metadata mutability and holder concentration, and tells pools and other program-controlled holders apart from real whales.
• See who profited. wallet_pnl prices every swap at the time it happened and flags sales of tokens the wallet never bought.
• Build a case. Save traces and clusters to case files, label addresses with confidence and evidence, and export a Markdown report with SVG fund-flow diagrams.
• Can't touch your money. No keys, no signing. The raw RPC tool forwards only read methods, so sendTransaction, requestAirdrop and friends never reach the network. The only thing it writes is your local case files.

Try asking:

• "Profile wallet <address>: who funded it, where did its money go, anything suspicious?"
• "Is <mint> a rug risk? Who actually holds the supply?"
• "Trace funds out of <address> for 3 hops, save it to case exchange-hack, then export the report."
• "Are these four wallets the same person?"
• "Did <wallet> profit from <mint>, and who sent it tokens for free?"
• "Is the volume on <mint> real, or bots trading with themselves?"

Install

You need a Helius API key (the free tier works) and Node.js 22.19 or newer. coin-scout speaks the 2026-07-28 MCP revision over stdio and Streamable HTTP, still serves 2025-era clients, and is listed in the official MCP Registry as io.github.dennisyilmaz/coin-scout.

Claude Desktop and other MCPB clients

[Download coin-scout.mcpb]

Open the downloaded coin-scout.mcpb with your client and paste your Helius API key when asked. The key is stored by the client, not in the bundle.

Claude Code

curl -LO https://github.com/dennisyilmaz/coin-scout/releases/latest/download/coin-scout.mjsnode coin-scout.mjs

The single file is the whole server. Run interactively, it asks for your Helius key, copies itself to ~/.coin-scout/ and registers itself with claude mcp add at user scope. Restart Claude Code and the tools are there.

Any MCP client, from source

git clone https://github.com/dennisyilmaz/coin-scout.git && cd coin-scoutnpm ci && npm run build

{  "mcpServers": {    "coin-scout": {      "command": "node",      "args": ["/absolute/path/to/coin-scout/build/index.js"],      "env": { "HELIUS_API_KEY": "your-key" }    }  }}

For Streamable HTTP instead of stdio, run node build/http.js. It binds 127.0.0.1:8787 only, rejects foreign Host headers, and serves GET /health with transport metrics.

Verify a download

Every release is built in GitHub Actions with signed build provenance, and ships a SHA256SUMS file and a CycloneDX SBOM (coin-scout.cdx.json).

gh attestation verify coin-scout.mjs --repo dennisyilmaz/coin-scout

How it works

[Your AI agent calls coin-scout tools; coin-scout batches, paces and caches the RPC calls and queries Helius, DefiLlama and the bridge APIs]

Helius bills and rate-limits per RPC call, not per HTTP request, so raw parallelism just buys you 429s. The transport layer is built around that:

• JSON-RPC micro-batching. Calls issued within a 4 ms window are coalesced into one HTTP request. Measured on a 50-call getTransaction fan-out: 8 HTTP requests instead of 50, 2.2x faster wall clock.
• Adaptive batch sizing. A batch that gets 429'd is halved and the un-answered calls are requeued rather than failed; the size grows back on sustained success. Empirically the API accepts batches of 20 but rejects 50.
• Cost-aware adaptive rate limiting. Request spacing scales with the number of calls in a request, so a 20-call batch is spaced like 20 calls. Concurrency halves and spacing doubles on each 429, then decay back. server_metrics reports the converged rate.
• HTTP/2 + keep-alive over an undici pool, so there is no TLS handshake per call.
• Two-tier TTL cache with in-flight coalescing. Finalized transactions and blocks cache for hours; balances for seconds. Concurrent identical calls share one promise.
• Narrow payloads. Tools return one compact JSON document rather than raw node responses. The biggest lever on agent latency is tokens, not milliseconds.

Tools

Analysis (composite, start here)

Case files

Pass case: "<name>" to trace_funds, find_cluster or follow_bridge to save the result into that case. Labels from any case show up in every tool's label field, so later investigations build on earlier ones. Cases live in ~/.coin-scout/cases/<name>/ as plain JSON.

[A fund-flow diagram from case_export: an exploited vault sends 1,240 SOL to a drainer wallet, which splits it between an exchange deposit and a Wormhole crossing to Ethereum]

_{A case_export diagram, drawn by coin-scout's own renderer. Illustrative data.}

Data access

Prompts

investigate_address, screen_token, trace_stolen_funds: each encodes an investigation order of operations.

Configuration

All optional except the API key. See .env.example.

Data and privacy

Everything runs on your machine. What leaves it:

• Helius receives the addresses, signatures and mints you query, and your API key.
• DefiLlama receives mint addresses and timestamps for usdAtTime prices.
• WormholeScan, deBridge, Mayan and Circle receive transaction signatures when a bridge crossing is resolved.
• DexScreener receives the mint address when detect_wash_trading looks up a token's pools.
• Blockscout, or Etherscan when ETHERSCAN_API_KEY is set, receives EVM addresses when funds are traced on an EVM chain.

Only Helius and Etherscan get an API key, each only its own. Case files stay in your cases directory.

Accuracy notes

• Analysis tools sample recent history. When a result carries truncated or sampleTruncated, its counts are lower bounds; raise transferSample for more coverage.
• Current USD values come from Helius pricing and usdAtTime values from DefiLlama historical prices; both cover actively traded tokens only. A missing price means unknown, not zero.
• wallet_pnl only knows what the swaps in its sample show. Tokens that arrived by transfer or before the sample have no cost basis; their sales are reported as unmatchedProceedsUsd rather than realized PnL.
• find_cluster looks one funder up from the seed. Run it again on a strong member to go further.
• Bridge resolution covers Wormhole, deBridge, Mayan and Circle CCTP. deBridge and CCTP can only be followed outbound; chains the server does not recognise are shown by raw chain id.
• Built-in exchange labels come from OKX's proof-of-reserves snapshot of 1 November 2026, regenerated with scripts/okx-labels.ts. Deposit-address and hot-wallet labels are inferred from sweep patterns and say so in their confidence and source.
• detect_wash_trading reads token transfers in and out of pools, so liquidity adds and removals count as trades, and volume routed through other program accounts is reported separately as routedVolume. Same-slot buy and sell is also what sandwich and arbitrage bots look like.
• analyze_token scans up to 1000 token accounts. holderAccountsExact tells you whether the holder count is the real total or a floor. Holders whose owner is a program or a program-derived address are flagged isProgramOwned; concentration figures still include them, and programControlledPct says how much of the supply they hold.
• Risk flags and scores are heuristics for triage. They point an investigation at the right transactions; they are not a verdict.

Contributing and security

See CONTRIBUTING.md for development setup and the checks CI runs. Report vulnerabilities privately as described in SECURITY.md.

License

MIT