feat: helius-smartmoney skill + scoreWallet MCP action#111
Draft
bernardogv wants to merge 6 commits into
Draft
Conversation
… mode The compiler (`scripts/compile-skills.ts`) now also keeps reference files in `helius-plugin/skills/<dir>/references/` and `helius-cursor/skills/<dir>/references/` byte-identical with their canonical sources in `helius-skills/<skill>/references/`, and re-injects the canonical version into plugin/cursor SKILL.md frontmatter from `versions.json`. `--check` mode validates all generated outputs in-place and exits 1 with a per-file diff summary if any drift is found. Replaces the 6 duplicated bash blocks in `.github/workflows/sync-check.yml` (592 → 22 lines) with a single `compile-skills.ts --check` step. Collapses the 6 per-skill sync paragraphs in `CLAUDE.md` (~210 → 103 lines) to one short note about running the compiler. SKILL.md bodies in plugin/cursor remain hand-managed (intentionally not identical to canonical, per existing project policy) — only frontmatter version is auto-synced.
Bootstraps `helius-cli` test infrastructure with vitest@2 and adds 16 smoke tests covering the JSON envelope contract that downstream agent integrations depend on (PRs helius-labs#106/helius-labs#107): - `classifyError` Tier 2: HTTP status embedded in message (Helius HTTP, webhooks `HTTP error! status:`) - `classifyError` Tier 3: keyword matching (insufficient SOL/USDC, no API key, invalid address, ECONNREFUSED, SyntaxError) - `getExitCode` round-trip mapping for every classifier-produced code - `CLI_GUIDANCE` coverage — every error code surfaces a suggestion - `jsonReplacer` bigint handling (lamports come back as BigInt from web3.js) Adds a parallel `test-cli` job to `.github/workflows/test.yml` so the suite runs in CI alongside `helius-mcp`. `pnpm test` from `helius-cli/`: 16/16 passing in ~300ms.
…wallets
A new composition skill that teaches agents to find good wallets to follow
using Helius's existing wallet, asset, and transaction primitives. Covers
four discovery vectors:
- token-anchored ("who got rich on $WIF?") — getTokenHolders + per-wallet
P&L + identity enrichment
- seed-anchored ("find wallets like @cobie") — getWalletFundedBy +
sibling expansion + token-overlap clustering
- provider-anchored ("verify Cielo's smart-money list") — batch enrichment
and divergence analysis on lists from OKX/Cielo/Nansen/Arkham/GMGN/BullX
- behavioral scoring (deterministic 0-100 quality classifier from on-chain
activity, diversification, recency, volume, hold age)
Plus 5 end-to-end integration patterns: token-themed copy lists, KOL
cluster mapping, signal verifiers, pump.fun early-entry hunters, and a
copy-trading bot foundation.
Reference files written under canonical helius-skills/helius-smartmoney/
and auto-generated for plugin/cursor/.agents/system-prompts via the new
compiler fan-out (PR helius-labs#110). versions.json + scripts/compile-skills.ts
updated. README.md, AGENTS.md, helius-mcp/README.md skill listings
updated to include this and previously-missing helius-jupiter,
helius-okx, helius-phantom rows.
New routed MCP action under heliusWallet that wraps the behavioral-scoring formula from the helius-smartmoney skill into a single call. Composes existing primitives in parallel: - getWalletHistory → activity + recency - getWalletBalances → diversification - getWalletTransfers → volume - getWalletHistory page → hold age (oldest tx in window) Returns the composite score plus all 5 components and any flags (EMPTY_WALLET, NEW_WALLET, NO_RECENT_ACTIVITY) so callers can audit ranking decisions and recompute with custom weights. Wired through: - HELIUS_WALLET_ACTIONS (auto-catalogued via addEntries) - ACTION_REQUIRED_PARAMS: scoreWallet → ['address'] - registerWalletTools(server) — new tool definition The score is a quality classifier, not a P&L estimate — see helius-smartmoney/references/behavioral-scoring.md for the formula and limitations. helius-mcp test suite: 223/223 passing (no regressions).
…d-age, window-bounded activity End-to-end testing of the v1 formula against live wallet data revealed three issues that produced misleading scores: 1. **`Transfer.amountUsd` doesn't exist on the SDK type** (only `amount`, `amountRaw`, `decimals`). The `volume` component therefore always evaluated to 0, distorting the composite. Fixed by removing volume from the v1 formula and redistributing its 0.20 weight across the remaining four components (activity 0.30, diversification 0.25, recency 0.25, holdAge 0.20). v2 may add volume back once a price oracle is integrated. 2. **`activity` counted ALL fetched txs, not txs in the lookback window.** A wallet with 100 transactions over 6 months scored full activity even when dormant for the last 30 days. Fixed by filtering `history.data` to txs with `timestamp >= now - lookbackDays * 86400` before counting. 3. **`holdAge` from oldest-tx-in-page under-estimated for old wallets.** The 100-tx page only covers however far back the wallet was active, not its true age. Fixed by using `getWalletFundedBy` to get the timestamp of the wallet's first funding transaction (its true birth date), with the oldest-tx fallback retained for wallets whose funder can't be traced. Net result: cost drops from ~420 to ~310 credits (3 SDK calls instead of 4), accuracy improves substantially, scores correctly discriminate. Validation: - 11 new unit tests in `helius-mcp/tests/scoreWallet.test.ts` covering the formula end-to-end with mocked SDK responses: high-quality trader profile (≥70), bag holder (10-40), empty wallet flag, no-recent-activity flag, new-wallet flag, getFundedBy fallback, window filtering, score caps, lookback parameter, determinism. - New `helius-mcp/tests/smoke-scoreWallet.ts` one-shot smoke test that spawns the locally-built MCP server, calls scoreWallet via MCP protocol on a real address, and verifies the response. Lives outside the vitest include glob — runnable manually with HELIUS_API_KEY. - Verified end-to-end: live call against $WIF top holder `BAd1gxws...` returns score 32/100 with components matching the hand-computed expectation (within rounding). - helius-mcp test suite: 234/234 passing (was 223; +11 new). - compile-skills.ts --check passes after skill reference updates. Skill reference docs (behavioral-scoring.md, integration-patterns.md, provider-anchored.md, seed-anchored.md, SKILL.md) updated to reflect the new 4-component formula. Plugin/cursor copies auto-synced via the compiler.
…P call
Wraps the full helius-smartmoney token-anchored workflow into one
routed action under heliusWallet:
heliusWallet({ action: "searchTopWallets", mint, limit?, lookbackDays? })
→ ranked top-N table with score + components per wallet
Pipeline (executed server-side):
1. getTokenAccounts(mint, limit=20) — top holders
2. getBatchIdentity(holders) — identity enrichment
3. Filter holders whose `name` is set — drop CEX/exchange/program addrs
4. computeWalletScore × N in parallel — 4-component quality score
5. Sort by score desc — return ranked table
Output is a markdown table with columns: rank, address, score,
activity, diversification, recency, hold-age, flags. Includes the
"score < 70 typically means not smart money" disclaimer that anchors
the skill's central thesis.
Implementation:
- Extracted `computeWalletScore()` from scoreWallet's tool handler into
a shared internal helper. scoreWallet's handler now just calls
computeWalletScore + formats the single-wallet view; searchTopWallets
calls it once per candidate. The 4-component formula lives in one
place.
- Per-wallet failures don't abort the search — each candidate gets an
ERR flag in the table if its scoring throws.
- limit capped at 20 (max getTokenAccounts return), default 5.
Wiring:
- 'searchTopWallets' added to HELIUS_WALLET_ACTIONS (auto-catalogued).
- ACTION_REQUIRED_PARAMS['searchTopWallets'] = ['mint'].
- HELIUS_WALLET_SCHEMA gained `mint` and `lookbackDays` optional fields
(previously the router would strip them before dispatch — found
during smoke testing).
Validation:
- 7 new unit tests in tests/searchTopWallets.test.ts: ranked output
with components, CEX/program filtering via `name` discriminator,
NO_HOLDERS error, all-labeled fallback, limit cap, per-wallet error
resilience, ranking determinism.
- helius-mcp suite: 241/241 passing (was 234; +7 new).
- Live smoke test (helius-mcp/tests/smoke-searchTopWallets.ts) against
$WIF mint returns ranked top 5 in 1491ms — same ranking as the
multi-call discovery pipeline (4cTyus helius-labs#1 at 42, BAd1gx helius-labs#2 at 32).
- compile-skills.ts --check passes after SKILL.md updates documenting
the new action.
A new helper script tests/discover-top-wallets.ts performs the same
discovery via individual MCP calls (for comparison / debugging) — also
a one-shot tool, lives outside the vitest include glob.
Skill SKILL.md (canonical, plugin, cursor) updated to document both
scoreWallet and searchTopWallets as the routed actions for the
token-anchored and single-wallet workflows.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two commits — read independently. Stacks on top of #110 (compiler fan-out): branch was cut from
feat/compiler-fanout-and-cli-tests. Once #110 merges, this PR fast-forwards ontomaincleanly.helius-smartmoneyskill (3890280): A new composition skill that teaches agents how to find and follow high-quality Solana wallets by chaining existing Helius primitives. Covers four discovery vectors and 5 end-to-end integration patterns. Helius does not have a native "top wallets" endpoint; this skill packages the workflow that agents would otherwise have to assemble themselves — token-anchored discovery, seed-anchored expansion, provider-anchored verification, and behavioral scoring.scoreWalletMCP action (531f7aa): A new routed action underheliusWalletthat wraps the behavioral-scoring formula into a single call. Returns a deterministic 0-100 quality score plus all 5 components (activity, diversification, recency, volume, hold age) and audit flags. Uses no external providers — pure composition of existing wallet primitives.Skill structure
Same content auto-generated via the compiler (PR #110) into
helius-plugin/skills/smartmoney/,helius-cursor/skills/smartmoney/,.agents/skills/helius-smartmoney/, andhelius-mcp/system-prompts/helius-smartmoney/.Design intent
This is integration-only like the
helius-okxskill: it composes existing primitives rather than asking for new infrastructure. Helius's role is per-wallet enrichment and behavioral scoring; cross-token "top wallet" discovery is delegated to providers (or to token-anchored / seed-anchored workflows).The
scoreWalletaction keeps its scope narrow: one wallet in, one composite score + components out. Batch ranking and orchestrated discovery (searchTopWallets) are intentionally deferred — the skill teaches the patterns first, and we can package proven patterns into more tools later.Why this matters
Today, Helius provides excellent wallet enrichment (
getWalletIdentity,getWalletFundedBy,getWalletHistory,getWalletBalances) but no guidance on how to chain them into a discovery pipeline. Agents currently either reinvent the workflow each time or default to "use OKX". This skill is the missing playbook — and thescoreWalletaction is the canonical scoring primitive that pipeline depends on.Files
helius-skills/helius-smartmoney/(1 SKILL.md + 5 reference files, ~1500 lines markdown)helius-plugin/skills/smartmoney/,helius-cursor/skills/smartmoney/(SKILL.md hand-managed, refs auto-copied by compiler).agents/skills/helius-smartmoney/,helius-mcp/system-prompts/helius-smartmoney/(compiler)scripts/compile-skills.tsSKILLS array,versions.jsonhelius-mcp/src/router/actions.ts,helius-mcp/src/router/required-params.ts,helius-mcp/src/tools/wallet.ts(+89 lines)README.md,AGENTS.md,helius-mcp/README.mdskill listingsTest plan
npx tsx scripts/compile-skills.ts— clean, all 7 skills compile (helius-smartmoney listed with 5 refs + 3 prompts)npx tsx scripts/compile-skills.ts --check— passes on clean treepnpm testfromhelius-mcp/: 223/223 passing (no regression with new action wired in)validate-catalog.jspasses (auto-includes scoreWallet via HELIUS_WALLET_ACTIONS)tscbuild clean for helius-mcpTestsandSync Check)Out of scope (deferred)
searchTopWallets— orchestrated batch discovery + ranking. Spec'd in skill (integration-patterns.mdPattern 1) but the skill teaches the composition; a future PR can package proven patterns.provider-anchored.mdbut not implemented as MCP tools. Each has its own auth/SDK and can be its own skill.Generated with Claude Code