@vike-io/cli 0.7.3 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes are documented here. Entries follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.8.0 — HL share-card reverse-lookup + multi-IDE installer + SKILL.md hardening
+
+- **`vike perp find-position`** (new command, alias for the new `hl_position_match` MCP tool). Reverse-lookup a Hyperliquid open position from share-card details: paste `coin + side + leverage + entry` and get the wallet(s) holding a matching open position back. Walks widening entry tolerance bands (tight 0.05% → loose 0.5% → fallback 1.0%) with leverage tolerance ±0.5; tie-break by closest mark price. Returns `tolerance_used` so callers can flag low-confidence matches. Backed by `position_snapshots_latest` — near-real-time, no new schema.
+- **`vike install`** (new command). One-shot multi-IDE skill drop: `--claude` writes `~/.claude/skills/vike/SKILL.md`; `--cursor` / `--copilot` / `--agents` update marker-fenced blocks in `.cursorrules` / `.github/copilot-instructions.md` / `AGENTS.md` (idempotent — re-running replaces the block, never clobbers surrounding user content). `--all` writes every target at once.
+- **Root `SKILL.md` hardening**: added a "Critical Rules" block (8 hard rules agents most often violate), per-service "Historical Data Availability" tables (transfers per chain, prices per venue, HL perps, CEX perps, Polymarket — so agents stop over-promising data we don't have), and UTM-tagged signup links for attribution.
+- New skill playbook: `vike-hl-position-match`. Total: 40 skills (was 39), 35 MCP tools (was 34).
+
 ## 0.7.3 — agent-discoverable SKILL.md + auto GH releases
 
 - **Root-level `SKILL.md`** — single agent-discoverable entry point covering all 34 MCP tools, auth flow, intent → tool routing table, and per-service tool reference. Ships in the npm package so installing `@vike-io/cli` also installs the skill. Existing per-tool playbooks under `skills/` are unchanged and cross-linked from the root.

package/SKILL.md

@@ -12,6 +12,21 @@ Answer on-chain questions using the vike.io platform: 11 chains (ETH, BSC, Base,
 
 ---
 
+## Critical Rules
+
+Hard rules — agents that violate these produce wrong answers. Read once, apply always.
+
+1. **Addresses are always full 0x-hex (42 chars).** Never truncate when querying. Never display truncated when the user asks for the address — they'll copy-paste it.
+2. **Symbols are case-insensitive in queries, but display as the user typed.** `btc` and `BTC` both resolve; echo back what they wrote.
+3. **Time windows are UTC, day-boundaries cut at 00:00 UTC.** "Today" = since 00:00 UTC today, not local-time today.
+4. **Default page size is 50, max 500.** Don't request `--limit 10000` to "get everything" — paginate or use a screener tool instead.
+5. **Refresh cadence varies by tool.** Wallet PnL, HL positions: ≤2 min. Transfer-derived metrics: 5 min. Token price history: 1 min. Always assume <5 min unless a tool says otherwise.
+6. **USD amounts are floats in dollars.** `--min-usd 10000` = ten thousand dollars, not micro-USD.
+7. **`--json` flag is always available** on CLI commands and gives stable machine-readable output. Default (human) format may change; `--json` will not.
+8. **Resolve a token before asking transfer/holder questions.** `token_search` → take the canonical address → pass to `token_transfers` / `token_holders`. Symbol-only queries lose precision on tickers that collide across chains (e.g. FUN, BEAM, USDC).
+
+---
+
 ## Step 1: Confirm Authentication
 
 Follow this decision tree **before every session**. Do not skip to Step 2 until auth is confirmed.
@@ -32,7 +47,7 @@ If the user has no API key yet, tell them:
 
 > **To use vike, you'll need a free API key:**
 >
-> 1. Visit https://vike.io/api/keys, sign in, and copy a key (starts with `vk_`).
+> 1. Visit https://vike.io/api/keys?utm_source=skill&utm_medium=ai&utm_campaign=cli_skill, sign in, and copy a key (starts with `vk_`).
 > 2. Save it: `vike login --api-key vk_...` (or `export VIKE_API_KEY=vk_...`).
 > 3. Verify: `vike doctor`.
 >
@@ -68,6 +83,7 @@ X-API-KEY: vk_...
 | Funding rates across CEX perps (Binance/Bybit/OKX/Aster/HL) | **CEX Perps** | `vike perp funding` / `perp_funding` |
 | Price spreads of same symbol across CEX perp venues | **CEX Perps** | `vike perp spreads` / `perp_spreads` |
 | Top Hyperliquid perp traders by PnL / volume | **HL Perps** | `vike perp top-traders` / `hl_perp_top_traders` |
+| Reverse-lookup an HL share card → which wallet holds it | **HL Perps** | `vike perp find-position` / `hl_position_match` |
 | Deribit options flow, put/call ratios, IV | **Options** | `vike options flow` / `options_flow` |
 | Active Polymarket markets, volume, odds | **Polymarket** | `vike polymarket markets` / `polymarket_markets` |
 | Single Polymarket market detail | **Polymarket** | `vike polymarket detail` / `polymarket_market_detail` |
@@ -195,6 +211,7 @@ On-chain perps data: snapshots, fills, ledger, funding, attribution.
 | Tool | Description | Skill |
 |---|---|---|
 | `hl_perp_top_traders` | Top HL traders by PnL/volume over a window | [vike-hl-top-traders](skills/vike-hl-top-traders/SKILL.md), [vike-hl-trader-profile](skills/vike-hl-trader-profile/SKILL.md) |
+| `hl_position_match` | Reverse-lookup: share-card details (coin/side/lev/entry) → wallet holding that open position | [vike-hl-position-match](skills/vike-hl-position-match/SKILL.md) |
 
 For per-symbol HL screening / individual trader deep-dive, use [vike-perp-screener](skills/vike-perp-screener/SKILL.md) and [vike-hl-trader-profile](skills/vike-hl-trader-profile/SKILL.md).
 
@@ -260,6 +277,67 @@ General web search + AI-summarized fetch for off-chain context (news, docs, soci
 
 ---
 
+## Historical data availability
+
+Coverage windows per dataset. Don't ask for data older than the window — the tool will return empty or 503.
+
+### Transfers & on-chain (per chain)
+
+| Chain | Earliest block / date | Notes |
+|---|---|---|
+| Ethereum | 2018-01 (block ~4.85M) | Full history; ETH + ERC-20 |
+| BSC | 2021-01 | Full history; BNB + BEP-20 |
+| Base | 2023-08 (chain launch) | Full history |
+| Arbitrum | 2024-Q3 onward | Backfill in progress; pre-2024 sparse |
+| HyperEVM | 2025-Q1 (chain launch) | Full history |
+| Bitcoin | 2024-01 | Recent windows only — full-history backfill not active |
+| Solana | 2026-Q1 onward | Recent only — see `vike-cli` chain-coverage notes |
+| Tron/XMR/ZEC/Dash | 2024 onward | Recent only |
+
+### Prices (data_history, spot)
+
+| Venue | Earliest | Notes |
+|---|---|---|
+| Binance | 2017-08 | Full minute-level OHLCV |
+| Bybit | 2020-03 | Full minute-level OHLCV |
+| OKX | 2019-04 | Full minute-level OHLCV |
+| Gate | 2017 (CSV) → 2024-05 (CSV ends) | After 2024-05 use API; capped 10k minutes/request |
+| Coinbase | 2015 | Full history (recently added) |
+| KuCoin | 2018 | Full history (recently added) |
+| Pyth | 2023 | On-chain price feed; sparse pre-2023 |
+| Deribit options | 2020 onward | BTC + ETH only |
+
+### Hyperliquid perps (hl_perps DB)
+
+| Dataset | Window | Notes |
+|---|---|---|
+| Snapshots (positions / equity) | 30 days | TTL — older snapshots dropped |
+| Fills | 30 days | TTL |
+| Ledger (deposits/withdrawals) | 30 days | TTL |
+| Funding payments | 90 days | API-backed since 2026-04-22 |
+| Daily attributed PnL | All-time | `wallet_pnl_attributed_daily` is the long-history view |
+| Daily flows | All-time | `wallet_flows_daily` |
+| Top-trader leaderboards | rolling 24h / 7d / 30d | derived on-the-fly |
+
+### CEX perps (data_perp DB)
+
+| Dataset | Window |
+|---|---|
+| `tickers_1m` (ticker snapshots) | rolling 24h |
+| Funding rates | 90 days |
+| Trades (ws_trades) | rolling 7-30 days per venue |
+
+### Polymarket
+
+| Dataset | Window | Notes |
+|---|---|---|
+| Active markets | live | scraper paused 2026-05-24 (CF block); historical snapshots still queryable |
+| Wallet positions | last known snapshot | not real-time until scraper resumes |
+
+If your query needs older data than what's listed: say so clearly and offer the nearest in-range window. Don't silently return empty.
+
+---
+
 ## Cost & rate-limit awareness
 
 - **Cheap (counts as 1 credit):** `token_search`, `wallet_summary`, `alerts_list`, `wallet_ens`, `perp_funding`.

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.7.3",
+  "version": "0.8.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-hl-position-match/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: vike-hl-position-match
+description: Reverse-lookup a Hyperliquid open position from share-card details (coin + side + leverage + entry price). Use when the user pastes or describes a HL share card and asks "whose card is this?", "find this trader", or "who has a 25x ETH long open at $3,200?". Returns matching wallet(s) ranked by entry-price proximity.
+allowed-tools: Bash(vike:*)
+---
+
+# vike-hl-position-match
+
+Find the wallet(s) holding an open Hyperliquid perp position that match a share card.
+
+## Command
+
+```bash
+vike perp find-position
+  --coin <SYM>         # e.g. BTC, ETH, SOL
+  --side long|short
+  --leverage <X>       # e.g. 25
+  --entry <PRICE>      # entry price from the card
+  [--mark <PRICE>]     # current mark price — sharpens tie-break when multiple wallets share entry
+  [--limit N]          # max matches, default 10, max 50
+  [--json]
+```
+
+## How matching works
+
+The tool walks three widening entry-price tolerance bands until it finds at least one match:
+
+| Band | Tolerance | When it's used |
+|---|---|---|
+| tight | ±0.05% | First pass — most share cards round-trip exactly |
+| loose | ±0.5% | Fallback if no tight matches |
+| fallback | ±1.0% | Last resort — anything wider is noise |
+
+Leverage must be within **±0.5** of the queried value (so `--leverage 5` matches positions at 4.5×–5.5×). Tie-breaking inside a band is by closest live `mark_price` to the queried `--mark` (or to `--entry` if `--mark` is not given).
+
+The response includes `tolerance_used` so the caller knows which band matched (`tight` / `loose` / `fallback` / `no_match`).
+
+## Common queries
+
+| User says | Flags |
+|---|---|
+| "Find this share card: 25x ETH long, entry $3,210" | `--coin ETH --side long --leverage 25 --entry 3210` |
+| "Whose 10x BTC short is open at $58,400? Current mark $57,900" | `--coin BTC --side short --leverage 10 --entry 58400 --mark 57900` |
+| "Top 5 matches for 50x SOL long around $145" | `--coin SOL --side long --leverage 50 --entry 145 --limit 5` |
+
+## Output schema
+
+```jsonc
+{
+  "match_count": 3,
+  "tolerance_used": "tight",          // tight | loose | fallback | no_match
+  "query": { "coin": "ETH", "side": "long", "leverage": 25, "entry_price": 3210, "mark_price_hint": 3215 },
+  "matches": [
+    {
+      "address": "0x...",
+      "coin": "ETH", "side": "long",
+      "snapshot_ts": 1716700000,       // unix seconds — how fresh the snapshot is
+      "size_token": 12.5, "size_usd": 40250,
+      "entry_price": 3209.8, "mark_price": 3215.3,
+      "leverage": 25.0,
+      "liquidation_price": 3082.1,
+      "unrealized_pnl": 68.75,
+      "entry_dist_pct": 0.0062         // |query.entry - match.entry| / query.entry × 100
+    }
+  ]
+}
+```
+
+## Reading the result
+
+- **Multiple matches at the exact same entry** (e.g. five wallets long ETH at 3210.00) — popular round-number entries collide. Treat as ambiguous; surface all and let the user disambiguate by size or address. Don't claim "this is the wallet" when `match_count > 1` in the tight band.
+- **`tolerance_used: fallback`** — the closest match is >0.5% off the queried entry. The card might be from a previous fill that's since been added to (size-weighted entry moves on add) or from a different exchange. Treat as low-confidence.
+- **`tolerance_used: no_match`** — the position is closed, the entry was from a margin-changing event, or the wallet was outside our HL coverage. Don't suggest a wallet anyway.
+- **`snapshot_ts`** is the snapshot time of that position row. The pipeline refreshes <5 min behind live; older `snapshot_ts` doesn't mean the position is stale, just that the wallet hasn't transacted since.
+
+## Anti-patterns
+
+- Don't fabricate matches when the tool returns `match_count: 0`. Say "no open position matches that share card" — closed positions, post-card adds, or non-HL cards all produce empty results.
+- Don't strip the address when displaying — share-card investigations always want the full 0x...40hex (users copy-paste it).
+- Don't infer trader skill from a single share-card match. Use `vike perp top-traders` or `vike wallet summary` for profile context.
+
+## Pairs well with
+
+- [vike-wallet-summary](../vike-wallet-summary/SKILL.md) — once you have the address, get the trader's HL profile + multi-chain identity.
+- [vike-hl-top-traders](../vike-hl-top-traders/SKILL.md) — check if the matched wallet is on a leaderboard.
+- [vike-wallet-label-provenance](../vike-wallet-label-provenance/SKILL.md) — find out if the wallet is a known CEX/fund/MM rather than a retail trader.

package/skills/vike-router/SKILL.md

@@ -22,6 +22,7 @@ Route the user's question to the right `vike-*` skill.
 | Perp funding rates / arb opportunities | `vike-perp-funding-arb` |
 | Cross-venue perp price spreads | `vike-perp-spread-arb` |
 | Top Hyperliquid perp traders | `vike-hl-top-traders` |
+| Match an HL share card → wallet (reverse-lookup) | `vike-hl-position-match` |
 | Profile a single HL perp trader | `vike-hl-trader-profile` |
 | HL market overview (vol/OI/funding) | `vike-perp-screener` |
 | Compare a symbol across all perp venues | `vike-cross-venue-perps` |

package/src/commands/install.js

@@ -0,0 +1,125 @@
+// `vike install` — copy SKILL.md into the agent-discoverable locations for
+// supported IDEs/agents so the skill loads without the user having to wire
+// it up manually.
+//
+// Targets:
+//   --claude    → ~/.claude/skills/vike/SKILL.md
+//   --cursor    → ./.cursorrules           (project root, joined under "## vike skill" header)
+//   --copilot   → ./.github/copilot-instructions.md  (same join pattern)
+//   --agents    → ./AGENTS.md              (same join pattern, project-root convention)
+//   --all       → all of the above
+//
+// Behaviour: idempotent. For files we don't own (project-root markdown), we
+// detect a fenced "<!-- vike-skill:begin -->...<!-- vike-skill:end -->" block
+// and replace just that block — never clobber the rest of the user's file.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const BEGIN = '<!-- vike-skill:begin -->';
+const END = '<!-- vike-skill:end -->';
+
+function readSkillSource() {
+  // SKILL.md ships at the root of the npm package, two levels up from
+  // src/commands/install.js.
+  const here = fileURLToPath(import.meta.url);
+  const candidate = resolve(dirname(here), '..', '..', 'SKILL.md');
+  if (!existsSync(candidate)) {
+    throw new Error(`SKILL.md not found at ${candidate}. Reinstall @vike-io/cli.`);
+  }
+  return readFileSync(candidate, 'utf8');
+}
+
+function writeStandalone(path, skill) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, skill, { mode: 0o644 });
+  return { path, mode: 'replaced' };
+}
+
+function upsertBlock(path, skill, header) {
+  const wrapped = `${BEGIN}\n${header ? header + '\n\n' : ''}${skill}\n${END}`;
+  if (!existsSync(path)) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, wrapped + '\n', { mode: 0o644 });
+    return { path, mode: 'created' };
+  }
+  const current = readFileSync(path, 'utf8');
+  if (current.includes(BEGIN) && current.includes(END)) {
+    const before = current.slice(0, current.indexOf(BEGIN));
+    const after = current.slice(current.indexOf(END) + END.length);
+    writeFileSync(path, before + wrapped + after, { mode: 0o644 });
+    return { path, mode: 'updated' };
+  }
+  const sep = current.endsWith('\n') ? '\n' : '\n\n';
+  writeFileSync(path, current + sep + wrapped + '\n', { mode: 0o644 });
+  return { path, mode: 'appended' };
+}
+
+function installClaude(skill) {
+  return writeStandalone(join(homedir(), '.claude', 'skills', 'vike', 'SKILL.md'), skill);
+}
+function installCursor(skill, cwd) {
+  return upsertBlock(join(cwd, '.cursorrules'), skill, '# vike skill — on-chain analytics for AI agents');
+}
+function installCopilot(skill, cwd) {
+  return upsertBlock(
+    join(cwd, '.github', 'copilot-instructions.md'),
+    skill,
+    '# vike skill — on-chain analytics for AI agents'
+  );
+}
+function installAgents(skill, cwd) {
+  return upsertBlock(join(cwd, 'AGENTS.md'), skill, '# vike skill — on-chain analytics for AI agents');
+}
+
+export function registerInstall(program) {
+  program
+    .command('install')
+    .description('Copy vike SKILL.md into agent-discoverable locations (Claude, Cursor, Copilot, AGENTS.md)')
+    .option('--claude', 'Install to ~/.claude/skills/vike/SKILL.md')
+    .option('--cursor', 'Append/update vike block in ./.cursorrules')
+    .option('--copilot', 'Append/update vike block in ./.github/copilot-instructions.md')
+    .option('--agents', 'Append/update vike block in ./AGENTS.md')
+    .option('--all', 'Install to every supported target')
+    .option('--cwd <dir>', 'Project root (defaults to current directory)')
+    .action((opts) => {
+      const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+      const targets = opts.all
+        ? { claude: true, cursor: true, copilot: true, agents: true }
+        : opts;
+      if (!targets.claude && !targets.cursor && !targets.copilot && !targets.agents) {
+        console.error('No target selected. Use --claude / --cursor / --copilot / --agents / --all.');
+        console.error('Examples:');
+        console.error('  vike install --claude');
+        console.error('  vike install --all');
+        process.exitCode = 1;
+        return;
+      }
+      let skill;
+      try {
+        skill = readSkillSource();
+      } catch (e) {
+        console.error(`vike install: ${e.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      const results = [];
+      try {
+        if (targets.claude) results.push(installClaude(skill));
+        if (targets.cursor) results.push(installCursor(skill, cwd));
+        if (targets.copilot) results.push(installCopilot(skill, cwd));
+        if (targets.agents) results.push(installAgents(skill, cwd));
+      } catch (e) {
+        console.error(`vike install: ${e.message}`);
+        process.exitCode = 1;
+        return;
+      }
+      for (const r of results) {
+        const size = (() => { try { return statSync(r.path).size; } catch { return 0; } })();
+        console.log(`${r.mode.padEnd(8)} ${r.path}  (${size} bytes)`);
+      }
+      console.log(`\nInstalled ${results.length} target(s). Restart your AI client to pick up the skill.`);
+    });
+}

package/src/commands/perp.js

@@ -31,6 +31,30 @@ export function registerPerp(program) {
       } catch (err) { emitError(err, opts); }
     });
 
+  cmd
+    .command('find-position')
+    .description('Reverse-lookup HL open positions matching a share-card (coin/side/lev/entry)')
+    .requiredOption('--coin <s>', 'Asset symbol (e.g. BTC, ETH)')
+    .requiredOption('--side <s>', 'long | short')
+    .requiredOption('--leverage <x>', 'Leverage from the share card (e.g. 25)')
+    .requiredOption('--entry <p>', 'Entry price from the share card')
+    .option('--mark <p>', 'Optional current mark price (sharpens tie-break)')
+    .option('--limit <n>', 'Max matches (default 10, max 50)', '10')
+    .option('--json', 'Emit JSON')
+    .action(async (opts) => {
+      try {
+        const r = await callTool('hl_position_match', {
+          coin: opts.coin,
+          side: opts.side,
+          leverage: Number(opts.leverage),
+          entry_price: Number(opts.entry),
+          mark_price: opts.mark != null ? Number(opts.mark) : undefined,
+          limit: parseInt10(opts.limit, 10),
+        });
+        emit(r, opts);
+      } catch (err) { emitError(err, opts); }
+    });
+
   cmd
     .command('top-traders')
     .description('Top Hyperliquid perp wallets by PnL / ROI / win rate / volume')

package/src/index.js

@@ -12,6 +12,7 @@ import { registerWeb } from './commands/web.js';
 // commands. New wallet subcommands (counterparties, pnl-history, balances,
 // ens) are added under registerWallet.
 import { registerInit } from './commands/init.js';
+import { registerInstall } from './commands/install.js';
 import { registerDoctor } from './commands/doctor.js';
 import { registerSchema } from './commands/schema.js';
 import { registerLogin, registerLogout } from './commands/auth.js';
@@ -55,6 +56,7 @@ program.hook('postAction', (_thisCmd, actionCmd) => {
 registerLogin(program);
 registerLogout(program);
 registerInit(program);
+registerInstall(program);
 registerDoctor(program);
 registerSchema(program);
 registerToken(program);