@vike-io/cli 0.14.0 → 0.16.0

package/skills/vike-wallets-related/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: vike-wallets-related
+description: Gather evidence on whether two wallets, or a wallet and its possible siblings, belong to the same entity - labels, first funders, shared counterparties and tokens with exchanges and routers removed, direct links, a depth-2 trace - with confidence tiers. Use when the user asks "are these wallets the same person" / "find wallets related to 0x..." / "is this a sybil cluster" / "does B belong to A".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-wallets-related
+
+Evidence, never proof: no tool exposes a deposit-address owner or a cluster id. Cap the cluster at 10 wallets and ask before widening. About 20-30 credits.
+
+## Chain
+
+```bash
+vike-data labels $A --json                                           # 1  A and B: same entity already?
+vike-data labels $B --json
+vike-data wallet first-funder $A --json                              # 2  earliest inbound coin and token, sender labelled
+vike-data wallet first-funder $B --json
+vike-data wallet compare $A $B --window 90d --limit 50 --json        # 3, up to ~20 s on busy wallets
+vike-data wallet batch <shared counterparties> --json                # 2  label them, drop exchanges and routers
+vike-data wallet trace $A --depth 2 --width 10 --window 90d --min-usd 1000 --json   # 4  is B in A's neighbourhood?
+```
+
+Add `--chain bsc|base|hyperevm` to every wallet command when the wallets live there (default ethereum); `labels` reads the Ethereum label table, so on other chains use `wallet batch --chain`.
+
+## Siblings mode (only A is known)
+
+`wallet counterparties $A --window 90d --limit 50`, label them with `wallet batch`, drop `cex`, `dex`, `market_maker` and contract rows, keep the highest-volume unlabelled or `user` wallets, then `wallet compare $A <candidate>` for the top 3-5, `wallet first-funder` on each, and `wallet trace` once. Stop at 10 wallets.
+
+## Reading
+
+- `compare` returns `shared_counterparties` (`wallet`, `a_volume_usd`, `b_volume_usd`, `entity`, `wallet_type`) and `shared_tokens`. The big shared rows are almost always an exchange, a router or USDT/USDC/the native coin: in a live market-maker pair the top shared counterparties were Binance, another wallet of the same firm and Coinbase, the shared tokens ETH, USDT and USDC. **Remove CEX, router and stablecoin overlap before counting anything.**
+- **Direct links**: B appearing as a node of A's trace (an edge with `out_usd` or `in_usd` > 0 between them) is stronger than any overlap.
+- **First funders**: the same non-exchange sender in `first_native_in` or `first_token_in` of both is a link; the same exchange hot wallet is not (everyone withdrawing from it shares it). Native rows hold top-level sends only and history starts per chain (`coverage.history_from`): no match is not evidence against.
+
+| Tier | Evidence |
+|---|---|
+| High | the same entity in `labels` / `batch` for both; or a direct transfer between them AND a shared non-CEX counterparty |
+| Medium | several shared non-exchange counterparties AND shared niche tokens (not stablecoins/ETH); one direct link of size; or the same non-exchange first funder |
+| Low / none | overlap only through exchanges, routers, stablecoins; matching ENS style; funding from the same CEX |
+
+State the tier and the list of what was removed.
+
+## Anti-patterns
+
+- Don't claim "same person" from a shared CEX hot wallet: everyone who uses that exchange shares it.
+- Don't trace through exchanges or past 10 wallets; don't trace at `--min-usd 0`.
+- Don't call two wallets unrelated from one chain: run the commands on the chain where both are active (`wallet balances` shows where the value is).
+
+## Pairs well with
+
+- `vike-wallet-who-is`, `vike-wallet-compare`, `vike-wallet-counterparties`, `vike-wallet-trace`, `vike-wallet-batch`
+- `vike-polymarket-trader`: for Polymarket wallets, `polymarket wallet` returns `correlated`, the wallets trading the same markets

package/skills.sh.json

@@ -4,35 +4,41 @@
   "groupings": [
     {
       "title": "Quick start",
-      "description": "Start here. The umbrella skill routes user questions to the right specialized skill below; vike-core covers install and auth.",
+      "description": "Start here. The umbrella skill routes user questions to the right specialized skill below; vike-core covers install and auth; vike-daily-brief is a cheap cross-market rundown.",
       "skills": [
         "vike",
-        "vike-core"
+        "vike-core",
+        "vike-daily-brief"
       ]
     },
     {
       "title": "Tokens",
-      "description": "Resolve, screen, and research tokens on Ethereum, BSC and Base. Smart-money inflow (Ethereum), holders, top buyers and sellers.",
+      "description": "Resolve, screen, and research tokens on Ethereum, BSC, Base and HyperEVM. Smart-money inflow and its trend over time (Ethereum), holders and holder due diligence, top buyers and sellers.",
       "skills": [
         "vike-token-search",
         "vike-token-research",
         "vike-token-transfers",
         "vike-token-holders",
+        "vike-token-holder-diligence",
         "vike-token-screener",
-        "vike-smart-money-discovery"
+        "vike-smart-money-discovery",
+        "vike-token-smart-money-trend"
       ]
     },
     {
       "title": "Wallets",
-      "description": "Per-wallet profile, flows, counterparty graphs, ENS, batch labelling, label provenance.",
+      "description": "Who a wallet is, per-wallet profile, flows, counterparty graphs, incident tracing, relatedness evidence, ENS, batch labelling, label provenance, on Ethereum, BSC, Base and HyperEVM.",
       "skills": [
+        "vike-wallet-who-is",
         "vike-wallet-summary",
         "vike-wallet-portfolio",
         "vike-wallet-discover",
         "vike-wallet-transactions",
         "vike-wallet-counterparties",
         "vike-wallet-trace",
+        "vike-follow-the-money",
         "vike-wallet-compare",
+        "vike-wallets-related",
         "vike-wallet-batch",
         "vike-wallet-pnl-history",
         "vike-wallet-balances",
@@ -42,18 +48,25 @@
     },
     {
       "title": "CEX perps",
-      "description": "Funding-rate arb and per-symbol venue comparison, plus cross-venue perp price gaps and a market snapshot.",
+      "description": "Funding-rate arb and per-symbol venue comparison, cross-venue perp price gaps, open interest and long/short lean per venue, and a crowding read that nets open interest against price.",
       "skills": [
         "vike-perp-funding",
-        "vike-perp-overview"
+        "vike-perp-overview",
+        "vike-perp-crowding"
       ]
     },
     {
       "title": "Hyperliquid perps",
-      "description": "Top traders (and checking one address against the leaderboard) and share-card reverse-lookup.",
+      "description": "Top traders and leaderboards, one-wallet profiles, wallet-cohort positioning and its backtest method, single-symbol briefings, liquidation risk, builder codes, and share-card reverse-lookup.",
       "skills": [
         "vike-hl-top-traders",
-        "vike-hl-position-match"
+        "vike-hl-trader-profile",
+        "vike-hl-position-match",
+        "vike-hl-cohort-positioning",
+        "vike-hl-cohort-backtest",
+        "vike-hl-asset-briefing",
+        "vike-hl-liquidation-radar",
+        "vike-hl-builder-intel"
       ]
     },
     {
@@ -65,21 +78,30 @@
     },
     {
       "title": "Polymarket",
-      "description": "Prediction-market discovery, single-market deep-dives, trader profiles, and smart-money signals with a market overview.",
+      "description": "Prediction-market discovery, single-market deep-dives and due diligence (order book, tape, trades with wallets, holders, on-chain settlement), trader profiles, smart-money signals, and the free L2 Parquet archive.",
       "skills": [
         "vike-polymarket-markets",
         "vike-polymarket-market-detail",
+        "vike-pm-market-diligence",
         "vike-polymarket-trader",
-        "vike-polymarket-smart-money"
+        "vike-polymarket-smart-money",
+        "vike-pm-l2-archive"
       ]
     },
     {
       "title": "Alerts",
-      "description": "Create, list, edit, delete on-chain transfer alerts (USD thresholds per token); register HTTPS webhooks with HMAC delivery.",
+      "description": "Create, list, edit, delete transfer alerts (a token or one wallet, USD thresholds) and Hyperliquid alerts; read what fired; HTTPS webhooks with HMAC delivery.",
       "skills": [
         "vike-alerts-setup",
         "vike-alerts-webhook"
       ]
+    },
+    {
+      "title": "Live streams",
+      "description": "Hyperliquid, HL cohort, on-chain and Polymarket events as they happen over WebSocket, as NDJSON, resumed by cursor.",
+      "skills": [
+        "vike-stream"
+      ]
     }
   ]
 }

package/src/commands/alerts.js

@@ -1,11 +1,45 @@
 import { callTool } from '../mcp-client.js';
 import { emit, emitError } from '../format.js';
 import { parseBool, parseInt10 } from '../util.js';
+import { addTool } from './tool-command.js';
+
+// What a rule watches beyond token and USD bounds: a transfer alert's address, and the Hyperliquid
+// parameters. Which alert type takes which is the server's to check; it names the fix.
+const TARGET_OPTIONS = [
+  ['--address <a>', 'transfer: one wallet to watch (0x + 40 hex), sent or received'],
+  ['--address-role <r>', 'transfer: any | from | to (default any; needs --address)'],
+  ['--wallet <a>', 'Hyperliquid account (0x + 40 hex): required by hl_wallet and hl_liq_proximity, optional for hl_liquidation'],
+  ['--actions <a...>', 'hl_wallet: open close flip increase reduce (default all but reduce)'],
+  ['--pnl-cohorts <c...>', 'hl_cohort_fill, hl_liquidation: PnL cohorts, e.g. "3x smart" "2x smart"'],
+  ['--size-cohorts <c...>', 'hl_cohort_fill, hl_liquidation: size cohorts, e.g. "4x whale" whale'],
+  ['--index <i>', 'hl_cohort_bias (required): smi | wsi | smart_bias | whale_bias | smi_wsi_gap'],
+  ['--threshold <n>', 'hl_cohort_bias: level to cross (default 0); hl_liq_proximity: share of the way to liquidation, 0-1 (default 0.8)'],
+  ['--band <n>', 'hl_cohort_bias, hl_liq_proximity: hysteresis, > 0 (default 0.1)'],
+  ['--direction <d>', 'hl_cohort_bias: up | down | both (default both)'],
+];
+
+// `--pnl-cohorts ''` clears the list: send [] (the server refuses ['']).
+const list = (v) => (Array.isArray(v) && v.every((x) => x === '') ? [] : v);
+
+function targetArgs(opts) {
+  return {
+    address: opts.address,
+    address_role: opts.addressRole,
+    wallet: opts.wallet,
+    actions: list(opts.actions),
+    pnl_cohorts: list(opts.pnlCohorts),
+    size_cohorts: list(opts.sizeCohorts),
+    index: opts.index,
+    threshold: opts.threshold,
+    band: opts.band,
+    direction: opts.direction,
+  };
+}
 
 export function registerAlerts(program) {
   const cmd = program
     .command('alerts')
-    .description('Manage on-chain transfer alerts');
+    .description('Manage alerts: on-chain transfers and Hyperliquid fills, liquidations, cohort bias and liquidation proximity');
 
   cmd
     .command('list')
@@ -38,7 +72,7 @@ export function registerAlerts(program) {
 
   cmd
     .command('channels')
-    .description('List your enabled notification channels (email/discord/webhook)')
+    .description('List your enabled notification channels (email/webhook)')
     .option('--json', 'Emit JSON')
     .action(async (opts) => {
       try {
@@ -47,25 +81,31 @@ export function registerAlerts(program) {
       } catch (err) { emitError(err, opts); }
     });
 
-  cmd
+  const create = cmd
     .command('create')
-    .description('Create a new on-chain transfer alert')
+    .description('Create an alert: an on-chain transfer alert (default) or a Hyperliquid alert (--type)')
     .requiredOption('--label <l>', 'Alert label (user-visible name)')
-    .option('--token <sym>', 'Token ticker, UPPERCASE (e.g. USDC, ETH)')
-    .option('--chain <c>', 'eth | bsc', 'eth')
-    .option('--min-usd <n>', 'Minimum transfer USD value')
-    .option('--max-usd <n>', 'Maximum transfer USD value')
-    .option('--channel <c...>', 'Notification channel(s): email, discord')
-    .option('--cooldown <min>', 'Minimum gap between triggers (minutes)', '60')
+    .option('--type <t>', 'transfer | hl_wallet | hl_cohort_fill | hl_liquidation | hl_cohort_bias | hl_liq_proximity (default transfer)')
+    .option('--token <sym>', 'transfer: token ticker, UPPERCASE (e.g. USDC); Hyperliquid: the coin (BTC, kPEPE), required by hl_cohort_bias')
+    // No default chain: a Hyperliquid alert refuses one.
+    .option('--chain <c>', 'transfer only: eth | bsc | base | hyperevm (default eth)')
+    .option('--min-usd <n>', 'transfer: minimum USD value; Hyperliquid: fill or liquidation floor (hl_cohort_fill: required, >= 10000)')
+    .option('--max-usd <n>', 'transfer only: maximum USD value');
+  for (const [flags, text] of TARGET_OPTIONS) create.option(flags, text);
+  create
+    .option('--channel <c...>', 'Notification channel(s): email, webhook (Hyperliquid: webhook, or none and read them with `alerts events`)')
+    .option('--cooldown <min>', 'Token-wide transfer alerts: minimum gap between notifications (minutes)', '60')
     .option('--json', 'Emit JSON')
     .action(async (opts) => {
       try {
         const r = await callTool('alerts_create', {
           label: opts.label,
+          alert_type: opts.type,
           token_symbol: opts.token,
           chain: opts.chain,
           min_value_usd: opts.minUsd,
           max_value_usd: opts.maxUsd,
+          ...targetArgs(opts),
           channels: opts.channel,
           cooldown_minutes: parseInt10(opts.cooldown, 60),
         });
@@ -73,27 +113,29 @@ export function registerAlerts(program) {
       } catch (err) { emitError(err, opts); }
     });
 
-  cmd
+  const edit = cmd
     .command('edit <alert_id>')
-    .description('Update an alert (only fields you pass are modified)')
+    .description('Update an alert (only fields you pass are modified; \'\' clears an optional one)')
     .option('--label <l>')
     .option('--token <sym>')
     .option('--chain <c>')
     .option('--min-usd <n>')
-    .option('--max-usd <n>')
+    .option('--max-usd <n>');
+  for (const [flags, text] of TARGET_OPTIONS) edit.option(flags, text);
+  edit
     .option('--channel <c...>')
     .option('--cooldown <min>')
     .option('--active <bool>', 'Pause/resume (true|false)')
     .option('--json', 'Emit JSON')
     .action(async (alertId, opts) => {
       try {
-        const payload = { alert_id: alertId };
+        const payload = { alert_id: alertId, ...targetArgs(opts) };
         if (opts.label !== undefined) payload.label = opts.label;
         if (opts.token !== undefined) payload.token_symbol = opts.token;
         if (opts.chain !== undefined) payload.chain = opts.chain;
         if (opts.minUsd !== undefined) payload.min_value_usd = opts.minUsd;
         if (opts.maxUsd !== undefined) payload.max_value_usd = opts.maxUsd;
-        if (opts.channel !== undefined) payload.channels = opts.channel;
+        if (opts.channel !== undefined) payload.channels = list(opts.channel);
         if (opts.cooldown !== undefined) payload.cooldown_minutes = opts.cooldown;
         if (opts.active !== undefined) payload.is_active = parseBool(opts.active, true);
         const r = await callTool('alerts_edit', payload);
@@ -115,4 +157,32 @@ export function registerAlerts(program) {
         emit(r, opts);
       } catch (err) { emitError(err, opts); }
     });
+
+  addTool(cmd, 'events', {
+    tool: 'alerts_events',
+    desc: 'Events your alerts produced, oldest first, with each delivery\'s status (kept 15 days)',
+    options: [
+      ['--cursor <c>', 'next_cursor from the previous page (an empty page returns the same one)'],
+      ['--limit <n>', 'Events per page, 1-500 (default 100)'],
+      ['--rule-id <id>', 'Only the events of this alert'],
+    ],
+  });
+
+  addTool(cmd, 'resend <delivery_id>', {
+    tool: 'alerts_resend_delivery',
+    args: ['delivery_id'],
+    desc: 'Send one delivery again (its id from an event\'s delivery list in `alerts events`)',
+  });
+
+  addTool(cmd, 'rotate-secret <channel_id>', {
+    tool: 'alerts_rotate_webhook_secret',
+    args: ['channel_id'],
+    desc: 'New signing secret for a webhook channel; the old one keeps signing for 24 hours',
+  });
+
+  addTool(cmd, 'test-webhook <channel_id>', {
+    tool: 'alerts_test_webhook',
+    args: ['channel_id'],
+    desc: 'Send the signed test event to a webhook channel again',
+  });
 }

package/src/commands/call.js

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { callTool } from '../mcp-client.js';
+import { emitError } from '../format.js';
+
+export function registerCall(program) {
+  program
+    .command('call <tool>')
+    .description('Call any MCP tool by name and print its raw result (see `vike-data schema --pretty` for the tools and their arguments)')
+    .option('--args <json>', 'Tool arguments as a JSON object, e.g. \'{"symbol":"BTC"}\'')
+    .option('--args-file <path>', 'Read the arguments JSON from a file (- for stdin)')
+    .option('--timeout <s>', 'Seconds to wait for the answer', '60')
+    .option('--json', 'Errors as JSON on stdout (the result is JSON either way)')
+    .action(async (tool, opts) => {
+      try {
+        const text = (opts.argsFile !== undefined
+          ? readFileSync(opts.argsFile === '-' ? 0 : opts.argsFile, 'utf8')
+          : (opts.args ?? '{}')).replace(/^/, '').trim();     // a file saved with a UTF-8 BOM
+        let args;
+        try { args = JSON.parse(text); } catch (err) {
+          throw new Error(`arguments are not valid JSON: ${err.message}`);
+        }
+        if (!args || typeof args !== 'object' || Array.isArray(args)) {
+          throw new Error('arguments must be a JSON object, e.g. {"address":"0x..."}');
+        }
+        const seconds = Number(opts.timeout);
+        if (!(seconds > 0)) throw new Error(`--timeout must be a positive number of seconds, got ${opts.timeout}`);
+        // Parsed only to check it; the text itself is sent, so numbers above 2^53 are not rounded.
+        const r = await callTool(tool, args, { raw: true, argsText: text, timeoutMs: seconds * 1000 });
+        process.stdout.write((typeof r === 'string' ? r : JSON.stringify(r)) + '\n');
+      } catch (err) { emitError(err, opts); }
+    });
+}

package/src/commands/candles.js

@@ -8,26 +8,22 @@ export function registerCandles(program) {
     .description('Historical OHLCV candles — Hyperliquid markets and Polymarket outcome tokens');
 
   cmd
-    .command('hl <symbol>')
-    .description('Hyperliquid candles (perp or spot), aggregated from HL executed fills')
-    .option('--interval <i>', '1m | 5m | 15m | 30m | 1h | 4h | 1d', '1h')
-    .option('--market <m>', 'perp | spot', 'perp')
-    .option('--dex <d>', 'Perp DEX (default HL, the core venue; others are HIP-3 builder DEXs)')
+    .command('hl [symbol]')
+    .description('Hyperliquid candles (perp or spot), aggregated from HL executed fills; --view latest = the newest 1m bar of every symbol')
+    .option('--view <v>', 'candles (default; needs <symbol>) | export (the same, limit defaults to 5000) | latest (every symbol, no <symbol>)')
+    .option('--interval <i>', '1m | 5m | 15m | 30m | 1h | 4h | 1d (default 1h; latest: 1m only)')
+    .option('--market <m>', 'perp | spot (default perp)')
+    .option('--dex <d>', 'Perp DEX (default HL, the core venue; others are HIP-3 builder DEXs; latest: omit for every DEX)')
     .option('--start <t>', 'ISO-8601 UTC or epoch ms (inclusive)')
     .option('--end <t>', 'ISO-8601 UTC or epoch ms (exclusive)')
-    .option('--limit <n>', 'Max candles (default 500, max 5000)', '500')
+    .option('--limit <n>', 'Max candles (default 500, export 5000; max 5000)')
     .option('--json', 'Emit JSON')
     .action(async (symbol, opts) => {
       try {
-        const args = {
-          symbol,
-          interval: opts.interval,
-          market: opts.market,
-          limit: parseInt10(opts.limit, 500),
-        };
-        if (opts.dex !== undefined) args.dex = opts.dex;
-        if (opts.start !== undefined) args.start = opts.start;
-        if (opts.end !== undefined) args.end = opts.end;
+        // Only what was given: the server's defaults stay the defaults. `latest` takes only market, dex and
+        // interval, so a symbol, window or limit is not sent with it.
+        const args = { view: opts.view, interval: opts.interval, market: opts.market, dex: opts.dex };
+        if (opts.view !== 'latest') Object.assign(args, { symbol, start: opts.start, end: opts.end, limit: opts.limit });
         const r = await callTool('hl_ohlcv', args);
         emit(r, opts);
       } catch (err) { emitError(err, opts); }

package/src/commands/doctor.js

@@ -8,13 +8,13 @@ export function registerDoctor(program) {
     .action(async () => {
       const checks = [];
 
-      // 1. Node version
+      // 1. Node version: package.json engines is >=22.12.0
       const nodeVer = process.version;
-      const major = parseInt(nodeVer.slice(1).split('.')[0], 10);
+      const [major, minor] = process.versions.node.split('.').map(Number);
       checks.push({
         name: 'Node runtime',
-        ok: major >= 20,
-        detail: `${nodeVer} (need >= 20.0.0)`,
+        ok: major > 22 || (major === 22 && minor >= 12),
+        detail: `${nodeVer} (need >= 22.12.0)`,
       });
 
       // 2. API key