@vike-io/cli 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes are documented here. Entries follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.7.0 — 5 new commands (transactions, compare, trace, batch, screener)
+
+- **`vike wallet transactions <address>`** (alias `txs`) — raw per-wallet transfer list with `--direction in|out|all`, `--days`, `--min-usd`, `--token` filters.
+- **`vike wallet compare <a> <b>`** — diff two wallets (shared counterparties + shared tokens within a window).
+- **`vike wallet trace <address>`** — counterparty graph traversal, depth 1-5, width 1-10, with min-USD threshold.
+- **`vike wallet batch <addr1> <addr2> ...`** — bulk label + 30d summary lookup for up to 100 addresses, preserves input order.
+- **`vike token screener`** — token discovery filter ranked by volume / net inflow / holders / smart-money inflow.
+- 5 new SKILL.md playbooks: `vike-wallet-transactions`, `vike-wallet-compare`, `vike-wallet-trace`, `vike-wallet-batch`, `vike-token-screener`.
+
+Total: 38 skills (was 33), 34 MCP tools (was 29).
+
 ## 0.6.0 — infra hardening + observability + skill eval harness
 
 Mostly internal-quality improvements; no new commands. Backbone for everything that follows.

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "AI-agent CLI for vike.io on-chain analytics, perps, options, and prediction markets across 11 chains",
   "type": "module",
   "main": "src/index.js",

package/skills/vike-token-screener/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: vike-token-screener
+description: Token discovery filter — rank tokens by volume / net inflow / holder count / smart-money inflow within a window, with min-volume and min-holder filters. Use when the user asks "what tokens are trending today" / "find tokens with smart money accumulating" / "rising tokens this week" / token discovery from scratch.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-token-screener
+
+## Command
+
+```bash
+vike token screener
+  [--chain ethereum|bsc|base]
+  [--window 24h|7d|30d|90d]
+  [--sort volume|net_inflow|holders|smart_inflow]
+  [--limit N]              (max 100)
+  [--min-volume USD]       (filter dust)
+  [--min-holders N]        (require N+ unique holders)
+  [--smart-money-only]     (restrict to smart-money cohort flows)
+  [--json]
+```
+
+## Examples
+
+```bash
+# Trending today by volume
+vike token screener --window 24h --sort volume --limit 20
+
+# Find tokens smart money is accumulating
+vike token screener --window 7d --sort smart_inflow --smart-money-only
+
+# Rising holders count (organic growth signal)
+vike token screener --window 30d --sort holders --min-volume 100000
+
+# Mid-cap tokens with real activity
+vike token screener --min-volume 1000000 --min-holders 100 --sort net_inflow
+```
+
+## Output columns
+
+`token_address`, `symbol` (when known), `name`, `volume_usd`, `net_flow_usd`, `in_usd`, `out_usd`, `unique_holders`, `tx_count`.
+
+## Sort modes
+
+| Sort | What it surfaces |
+|---|---|
+| `volume` | Most-traded tokens (default) — captures attention-driven action |
+| `net_inflow` | Tokens with biggest accumulation (in > out) — "what's being bought" |
+| `holders` | Tokens gaining unique addresses — organic growth signal |
+| `smart_inflow` | Tokens our smart-money cohort is buying — alpha signal |
+
+## Reading
+
+- **High volume + balanced in/out** = churn (DEX MM, arb bots). Low signal.
+- **High volume + strong net_inflow** = real demand. Worth investigating.
+- **Strong holder growth + flat volume** = small buys, distribution widening. Often early signal.
+- **`smart_inflow` mode** + high values + low overall volume = cohort is positioned BEFORE retail. Highest-conviction signal in the tool.
+
+## Filter tips
+
+| Goal | Filters |
+|---|---|
+| "Rising memecoins" | `--window 24h --sort holders --min-holders 50 --min-volume 50000` |
+| "Mid-cap alpha" | `--sort smart_inflow --min-volume 500000 --smart-money-only` |
+| "What's getting dumped" | `--sort net_inflow` then reverse — bottom rows have biggest outflows |
+
+## Anti-patterns
+
+- Don't quote the symbol as authoritative if `symbol` is null/blank — token hasn't been mapped, identify by address instead
+- Don't use `--window 24h --sort smart_inflow` for hot-new-token discovery — smart money usually positions BEFORE the 24h window; try `--window 7d` for that mode
+- Don't omit `--min-holders` when sorting by holders — junk airdrops with 50,000 1-tx addresses dominate the top otherwise
+- Don't omit `--min-volume` when sorting by net_inflow — tiny tokens with $100 net flow can rank high in % terms
+
+## Cost note
+
+3 credits per call. Cheaper than `wallet trace` (which is 4) but heavier than per-tool lookups. Use deliberately for discovery, not as a default.
+
+## Pairs well with
+
+- `vike token holders <addr>` — drill into the top holders of any flagged token
+- `vike token transfers <addr>` — see WHO is buying/selling once a token is interesting
+- `vike-smart-money-discovery` — composite playbook starting from this screen

package/skills/vike-wallet-batch/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: vike-wallet-batch
+description: Bulk label + 30d summary lookup for up to 100 addresses in one call. Use when the user pastes a CSV of addresses, asks "enrich this list with labels", or wants to quickly screen many wallets for entity / risk / activity.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-wallet-batch
+
+## Command
+
+```bash
+vike wallet batch <addr1> <addr2> <addr3> ...
+  [--chain ethereum|bsc|base]
+  [--json]
+```
+
+Caps at 100 addresses per call. For larger lists, split into chunks.
+
+## Example
+
+```bash
+vike wallet batch 0xd8da... 0xabc... 0xdef... --json
+```
+
+## Output
+
+One row per INPUT address (preserves input order — useful when joining back to a source CSV):
+
+```json
+[
+  { "wallet": "0xd8da...", "entity": null,       "wallet_type": "user", "confidence": "Medium", "risk_flag": null,    "net_30d_usd": 12000, "volume_30d_usd": 50000, "tx_30d": 42, "tokens_30d_count": 8, "found": true },
+  { "wallet": "0xabc...",  "entity": "Binance",  "wallet_type": "cex",  "confidence": "High",   "risk_flag": null,    "net_30d_usd": -5e9,  "volume_30d_usd": 9e9,   "tx_30d": 2000, "tokens_30d_count": 80, "found": true },
+  { "wallet": "0xdef...",  "entity": null,       "wallet_type": null,   "confidence": null,     "risk_flag": null,    "net_30d_usd": 0,     "volume_30d_usd": 0,     "tx_30d": 0,    "tokens_30d_count": 0,  "found": false }
+]
+```
+
+`found: false` = address has no labels AND no 30d activity in our DB (might be brand-new wallet or one we haven't indexed).
+
+## Reading
+
+- Filter to `wallet_type = "user"` to find real-people addresses worth investigating further
+- Any `risk_flag != null` → flag prominently in any user-facing report
+- High `volume_30d_usd` but `tx_30d = 0` shouldn't happen — if it does, indicates stale aggregate; recompute
+- `entity = "Binance"` + `wallet_type = "cex"` rows in a "smart money" list = false positives (CEX deposits aren't traders)
+
+## Anti-patterns
+
+- Don't run individual `vike wallet summary` in a loop for >5 addresses — this batch is ~20× faster
+- Don't pass mixed-case addresses inconsistently — they're normalised but cleaner CSVs help readers
+- Don't expect lifetime data — this is 30d window. For lifetime use the individual `wallet summary`
+
+## Pairs well with
+
+- `vike labels <addr>` — drill into any address showing high-confidence labels
+- `vike wallet compare <a> <b>` — pick two interesting batch results and diff them
+- `vike funds` — when batch reveals fund/MM/treasury wallets, get their flows

package/skills/vike-wallet-compare/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: vike-wallet-compare
+description: Diff two wallets — find their shared counterparties (both transacted with these addresses) and shared tokens (both touched these tokens) within a window. Use when the user asks "are these two wallets related" / "what do X and Y have in common" / "find connections between wallet A and B".
+allowed-tools: Bash(vike:*)
+---
+
+# vike-wallet-compare
+
+## Command
+
+```bash
+vike wallet compare <address_a> <address_b>
+  [--chain ethereum|bsc|base]
+  [--window 24h|7d|30d|90d|180d|all]
+  [--limit N]   (max 50)
+  [--json]
+```
+
+## Output
+
+```json
+{
+  "address_a": "0x...",
+  "address_b": "0x...",
+  "window": "30d",
+  "shared_counterparties": [
+    { "wallet": "0x...", "a_volume_usd": 50000, "b_volume_usd": 75000, "a_tx_count": 3, "b_tx_count": 5, "entity": "Binance", "wallet_type": "cex" },
+    ...
+  ],
+  "shared_tokens": [
+    { "token_address": "0x...", "a_volume_usd": 12000, "b_volume_usd": 8000, "a_tx_count": 2, "b_tx_count": 4 },
+    ...
+  ],
+  "summary": { "shared_counterparty_count": 7, "shared_token_count": 12 }
+}
+```
+
+## Reading
+
+- Many shared counterparties + same entity types = likely operated by same person/group
+- Same exchange (Binance hot wallet) as counterparty for both = trivial overlap, both users of that CEX
+- Shared NICHE tokens (long-tail memes, low-vol) with similar tx counts = strong signal of coordination
+- Shared infra contracts (Uniswap, 1inch) = trivial overlap, ignore
+- Zero shared = wallets genuinely independent
+
+## Anti-patterns
+
+- **Don't infer common ownership from CEX overlap.** Millions of users deposit to the same Binance hot wallets. Shared CEX counterparty = nothing.
+- **Don't claim coordination from common DEX router overlap** (Uniswap, 1inch routers). Almost every DEX user shares those.
+- Filter mentally for `wallet_type IN ('user', 'unknown')` overlap if you want a meaningful relatedness signal.
+
+## Pairs well with
+
+- `vike labels <addr>` — drill into any interesting shared counterparty
+- `vike wallet trace <addr>` — follow money outward from either wallet
+- `vike wallet counterparties <addr>` — top partners per wallet individually

package/skills/vike-wallet-trace/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: vike-wallet-trace
+description: Counterparty graph traversal from a root wallet outward. At each hop, expand to the top N counterparties by USD volume. Use when the user asks "where did funds from X go" / "follow the money 3 hops out" / "trace the network around this wallet" / wallet investigation.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-wallet-trace
+
+## Command
+
+```bash
+vike wallet trace <address>
+  [--chain ethereum|bsc|base]
+  [--depth N]    (1-5, default 2)
+  [--width N]    (1-10, default 5)
+  [--window 24h|7d|30d|90d|all]
+  [--min-usd N]  (default 10000 — prunes noise)
+  [--json]
+```
+
+## Output
+
+```json
+{
+  "root": "0xabc...",
+  "depth": 2, "width": 5, "window": "30d", "min_usd": 10000,
+  "nodes": [
+    { "address": "0xabc...", "depth": 0, "total_volume_usd": 0.0 },
+    { "address": "0xdef...", "depth": 1, "total_volume_usd": 250000, "label": "Binance", "wallet_type": "cex" },
+    { "address": "0x123...", "depth": 2, "total_volume_usd": 45000, "label": null, "wallet_type": null },
+    ...
+  ],
+  "edges": [
+    { "from": "0xabc...", "to": "0xdef...", "volume_usd": 200000, "tx_count": 4 },
+    ...
+  ],
+  "stats": { "node_count": 23, "edge_count": 31, "max_depth_reached": 2 }
+}
+```
+
+## Reading the graph
+
+- **Root (depth 0)** = the wallet you traced from. `total_volume_usd` = 0 because it's where edges originate.
+- **Depth 1** = direct counterparties. Most useful layer.
+- **Depth 2-3** = "friend-of-friend" — useful for finding where funds end up.
+- **Edge volume_usd** = the volume between those two specific addresses, NOT cumulative.
+- **`wallet_type = "cex"`** at depth 1 = funds went to / came from an exchange. Often the END of the trail (anonymous from there).
+- **Unlabeled wallet with high volume at depth 1-2** = potentially related wallet, investigate with `vike labels`.
+
+## Parameter tuning
+
+| Parameter | Effect | Use when |
+|---|---|---|
+| `--depth 1` | Direct counterparties only | "Who does X trade with" — same as `wallet counterparties` |
+| `--depth 2` | One degree of separation | Default. Reveals immediate networks. |
+| `--depth 3+` | Wider net | Investigation / OSINT. Returns much more data; graph gets noisy. |
+| `--width 3` | Top 3 per hop | Cleaner, focused on biggest flows |
+| `--width 10` | Top 10 per hop | Wider scan, more noise |
+| `--min-usd 50000` | High-value flows only | Strip out dust/airdrops |
+
+## Cost note
+
+Tool credits = 4 per call (heavier than other graph-less tools). Graph explodes exponentially with depth — depth 3 + width 10 = up to 1000 nodes per scan. Use `--depth 2 --width 5` as default.
+
+## Anti-patterns
+
+- Don't trace through CEX deposits. Once funds enter Binance/Coinbase, the trail goes opaque (CEX internal accounting, not on-chain). Note CEX nodes and stop following.
+- Don't depth-5 by default. Graph blows up; results become noise.
+- Don't ignore `min_usd` — without it, dust transfers create false-positive edges.
+
+## Pairs well with
+
+- `vike labels <addr>` — identify any interesting node
+- `vike wallet compare <addr_a> <addr_b>` — confirm relatedness once trace surfaces candidates
+- `vike wallet transactions <addr>` — drill into specific transfers between two nodes

package/skills/vike-wallet-transactions/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: vike-wallet-transactions
+description: Raw per-wallet transfer list (individual transactions, not aggregates) with direction, day, USD, and token filters. Use when the user asks "show me recent transfers for X" / "last 100 transactions of Y" / "all USDC moves from this wallet" / any forensic audit query.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-wallet-transactions
+
+## Command
+
+```bash
+vike wallet transactions <address>     # alias: vike wallet txs
+  [--chain ethereum|bsc|base]
+  [--direction in|out|all]
+  [--days N]   (max 365)
+  [--limit N]  (max 500)
+  [--min-usd N]
+  [--token <addr>]
+  [--json]
+```
+
+## Examples
+
+```bash
+# Recent in+out transfers, last 7 days
+vike wallet txs 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --days 7 --limit 20
+
+# Only outgoing > $10k in last 30d
+vike wallet txs 0xabc... --direction out --min-usd 10000
+
+# Only USDC transfers
+vike wallet txs 0xabc... --token 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
+```
+
+## Output columns
+
+`time`, `tx_hash`, `from_address`, `to_address`, `token_address`, `value_usd`, `direction` (in/out), `block`.
+
+Sorted descending by time (most recent first).
+
+## Reading
+
+- High `tx_count` over short window + low `value_usd` per tx = bot / MM / contract
+- Mixed in/out with similar volumes = active trader
+- Many `out` to one address = sweep / deposit pattern
+- One huge `in` then nothing = airdrop receiver / one-time deposit
+
+## Anti-patterns
+
+- Don't use this for aggregated metrics (volume, PnL) — use `wallet summary` instead, it's faster
+- Don't paginate by re-running with smaller windows — limit max 500, just bump `--limit`
+- Don't use `--token` on every query if you want full activity; the filter restricts to one token
+
+## Pairs well with
+
+- `vike wallet summary <addr>` — aggregate metrics over same window
+- `vike wallet counterparties <addr>` — who they trade with most
+- `vike wallet trace <addr>` — graph-traverse outward from this wallet
+- `vike labels <addr>` — identify the wallet itself

package/src/commands/token.js

@@ -58,6 +58,32 @@ export function registerToken(program) {
       } catch (err) { emitError(err, opts); }
     });
 
+  cmd
+    .command('screener')
+    .description('Token discovery filter — rank tokens by volume / inflow / holders / smart-money inflow')
+    .option('--chain <c>', 'ethereum | bsc | base', 'ethereum')
+    .option('--window <w>', '24h | 7d | 30d | 90d', '24h')
+    .option('--sort <s>', 'volume | net_inflow | holders | smart_inflow', 'volume')
+    .option('--limit <n>', 'Max tokens (max 100)', '20')
+    .option('--min-volume <usd>', 'Minimum window volume USD', '0')
+    .option('--min-holders <n>', 'Minimum unique holders', '0')
+    .option('--smart-money-only', 'Restrict flows to smart-money cohort')
+    .option('--json', 'Emit JSON')
+    .action(async (opts) => {
+      try {
+        const r = await callTool('token_screener', {
+          chain: opts.chain,
+          window: opts.window,
+          sort: opts.sort,
+          limit: parseInt10(opts.limit, 20),
+          min_volume_usd: parseFloat(opts.minVolume) || 0,
+          min_holders: parseInt10(opts.minHolders, 0),
+          smart_money_only: Boolean(opts.smartMoneyOnly),
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
   cmd
     .command('holders <token_address>')
     .description('Top holders of a token by cumulative net inflow USD')

package/src/commands/wallet.js

@@ -18,6 +18,87 @@ export function registerWallet(program) {
       } catch (err) { emitError(err, opts); }
     });
 
+  cmd
+    .command('transactions <address>')
+    .alias('txs')
+    .description('Raw per-wallet transfer list with filters')
+    .option('--chain <c>', 'ethereum | bsc | base', 'ethereum')
+    .option('--direction <d>', 'in | out | all', 'all')
+    .option('--days <n>', 'Days back (max 365)', '30')
+    .option('--limit <n>', 'Max txs (max 500)', '50')
+    .option('--min-usd <n>', 'Filter dust below this USD value', '0')
+    .option('--token <addr>', 'Optional: restrict to one token address')
+    .option('--json', 'Emit JSON')
+    .action(async (address, opts) => {
+      try {
+        const r = await callTool('wallet_transactions', {
+          address,
+          chain: opts.chain,
+          direction: opts.direction,
+          days: parseInt10(opts.days, 30),
+          limit: parseInt10(opts.limit, 50),
+          min_usd: parseFloat(opts.minUsd) || 0,
+          token_address: opts.token,
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('compare <address_a> <address_b>')
+    .description('Diff two wallets — shared counterparties + shared tokens')
+    .option('--chain <c>', 'ethereum | bsc | base', 'ethereum')
+    .option('--window <w>', '24h | 7d | 30d | 90d | 180d | all', '30d')
+    .option('--limit <n>', 'Max shared items per category (max 50)', '10')
+    .option('--json', 'Emit JSON')
+    .action(async (a, b, opts) => {
+      try {
+        const r = await callTool('wallet_compare', {
+          address_a: a, address_b: b,
+          chain: opts.chain, window: opts.window,
+          limit: parseInt10(opts.limit, 10),
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('trace <address>')
+    .description('Counterparty graph traversal from a root wallet')
+    .option('--chain <c>', 'ethereum | bsc | base', 'ethereum')
+    .option('--depth <n>', 'Hops to follow (1-5)', '2')
+    .option('--width <n>', 'Top counterparties per hop (1-10)', '5')
+    .option('--window <w>', '24h | 7d | 30d | 90d | all', '30d')
+    .option('--min-usd <n>', 'Minimum USD per transfer to follow', '10000')
+    .option('--json', 'Emit JSON')
+    .action(async (address, opts) => {
+      try {
+        const r = await callTool('wallet_trace', {
+          address,
+          chain: opts.chain,
+          depth: parseInt10(opts.depth, 2),
+          width: parseInt10(opts.width, 5),
+          window: opts.window,
+          min_usd: parseFloat(opts.minUsd) || 10000,
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
+  cmd
+    .command('batch <addresses...>')
+    .description('Bulk label + 30d summary lookup for many addresses (max 100)')
+    .option('--chain <c>', 'ethereum | bsc | base', 'ethereum')
+    .option('--json', 'Emit JSON')
+    .action(async (addresses, opts) => {
+      try {
+        const r = await callTool('wallet_batch_labels', {
+          addresses, chain: opts.chain,
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
   cmd
     .command('counterparties <address>')
     .description('Top trading partners of a wallet by combined transfer volume')