@vike-io/cli 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.16.1
+
+### Patch Changes
+
+- 537b522: Skills for four new live stream channels (the server serves them from stream.vike.io; the CLI keeps no channel list, so `stream`, `stream check` and `stream events` take them as they are): `hl.top_positions` and `hl.closed_trades` (path `hl`), `hl.cohort_leverage` (path `hl-cohorts`) and `pm.positions` (path `polymarket`), and the new `leverage`, `liquidation_px` and `labels.tags` of `hl.positions` with its `min_leverage` and `tag` filters.
+  
+  - `vike-stream`: the channel table, what each new channel sends, its filters and volume, examples, and when each starts sending.
+  - `vike-hl-trader-profile` (`hl.closed_trades` by wallet), `vike-hl-cohort-positioning` (`hl.cohort_leverage`, `hl.top_positions`), `vike-hl-liquidation-radar` (`hl.positions` with `min_leverage`), `vike-pm-market-diligence`, `vike-polymarket-trader` and `vike-polymarket-smart-money` (`pm.positions` by market or wallet), the umbrella routing and the README.
+  - Fix: `vike-data stream ... --filter min_leverage=20` sent a list (`["20"]`), which the server refuses; it is a number now, like `min_usd`.
+
+## 0.16.0
+
+### Minor Changes
+
+- 0a84307: Fifteen workflow skills (47 in all): playbooks that chain several commands for one question, each naming only commands and flags that exist in this release.
+  
+  - Wallets: `vike-wallet-who-is` (search, labels, ENS, the chain it is active on, `wallet exchange-usage`, counterparties), `vike-follow-the-money` (`call wallet_trace` with `direction: out`, the transfers, labels, stop rules, a live `chain.transfers` watch with `contract=false`), `vike-wallets-related` (labels, `wallet first-funder`, shared counterparties with exchanges and routers removed, a trace, confidence tiers).
+  - Tokens: `vike-token-holder-diligence` (`call token_holders` with `sort: balance` for `supply_pct`, then labels and `token transfers --hide-contracts`), `vike-token-smart-money-trend` (the Ethereum smart-money screener at 24h / 7d / 30d / 90d, differenced into disjoint slices).
+  - Hyperliquid: `vike-hl-cohort-positioning` (cohort metrics, the indices, the biggest positions with `--sort size`, live `hl.cohort_bias`), `vike-hl-cohort-backtest` (point-in-time labels, alignment, seams, controls), `vike-hl-trader-profile` (`hl wallet`, `wallet-trades`, `wallet-activity`, orders, TWAPs, liquidations, a live feed of its fills), `vike-hl-asset-briefing`, `vike-hl-liquidation-radar` (`--min-value-usd`, heatmap, live `hl.liq_risk` and `hl.liquidations`), `vike-hl-builder-intel`.
+  - Perps, Polymarket, cross-market: `vike-perp-crowding` (funding, `call perp_open_interest` net of price, `call perp_long_short` per venue), `vike-pm-market-diligence` (search, order book, tape, trades with wallets, settlement, holders, a live feed), `vike-pm-l2-archive` (archive files, link, settlements to join), `vike-daily-brief`.
+  - Existing skills: Base and HyperEVM on the token and wallet skills (the "Base not covered" hedges are gone; `wallet discover` on base and hyperevm needs `--window all`; `wallet summary` names its `chain` and `call wallet_summary` asks one); `token transfers` lists net buyers or sellers and takes `--hide-contracts`; `wallet balances` covers four chains and prices the native coin; `vike-polymarket-market-detail` describes what the tool returns (holders, trades with wallets, no quote or cohort block); `vike-perp-overview` reaches open interest and long/short with `call`; `search` resolves an ENS name; the umbrella routes every new playbook; eval questions for each.
+
 ## 0.15.0
 
 ### Minor Changes

package/README.md

@@ -12,8 +12,8 @@
 positions, fills, funding, liquidations, candles, and hourly long/short positioning by wallet
 cohort), **Polymarket** (markets, the trade and event tape, order-book snapshots, candles and
 on-chain settlements, plus a daily Parquet archive of the full L2 order book since 2026-07-25,
-licensed CC BY 4.0), and **labelled EVM wallets** on Ethereum and BNB Chain, with Base for token
-transfers. The same data is served three ways: an **MCP server** at `https://data.vike.io/mcp` (the one
+licensed CC BY 4.0), and **labelled EVM wallets** on Ethereum and BNB Chain, with Base and HyperEVM
+for the wallet and token tools. The same data is served three ways: an **MCP server** at `https://data.vike.io/mcp` (the one
 this CLI calls), a **REST API** at `https://data.vike.io/v1/`, and the **Parquet archive** at
 `https://data.vike.io/archive/`. A key allows 20,000 requests an hour, and an account can hold up
 to 5 keys; archive downloads are not counted. The archive manifest and a sample market need no key
@@ -56,7 +56,7 @@ The key is read from `VIKE_API_KEY` first, then from `~/.vike/config.json`
 | **Polymarket API** `/v1/polymarket` | Markets, the raw event and trade tape (about 30 days back), order-book snapshots, candles, on-chain settlements | free key | [polymarket](https://vike.io/data/polymarket) |
 | **Hyperliquid cohorts** `/v1/hyperliquid/coins/{coin}/cohort-metrics` | Long vs short per cohort, hourly, up to 8,760 hours in one request. Axes: `size` (account value, shrimp to 4x whale), `tier` (position notional), `pnl` (realized-PnL percentile), `pnl_abs` (PnL in dollars). `labelBasis=point_in_time` grades each hour with the label it had then (from 2026-04-07). | free key | [hl-cohorts](https://vike.io/data/hl-cohorts) |
 | **Hyperliquid API** `/v1/hyperliquid` | Trader rankings and leaderboards, 5-minute position snapshots kept for a year, wallet fills, funding and ledger, liquidations (inferred from snapshots), builders, candles since the start of 2026; closed bars also stream live as the `hl.candles` channel of `wss://stream.vike.io/v1/stream/hl` | free key | [hyperliquid](https://vike.io/data/hyperliquid) |
-| **Event streams** `wss://stream.vike.io/v1/stream/<path>` | Live events with a resume cursor on four paths: `hl` (fills, liquidations, positions, liquidation risk, order walls, candles, TWAPs, ledger, leverage changes, funding), `hl-cohorts` (cohort flow, indices, cohort bias), `onchain` (transfers on eth, bsc, base, hyperevm), `polymarket` (trades, resolutions, price moves, new markets). `vike-data stream` reads them; `vike-data stream info` lists every channel and filter. Connections are not counted against the hourly limit. | free key | [stream channels](https://vike.io/docs/data/reference/stream-channels) |
+| **Event streams** `wss://stream.vike.io/v1/stream/<path>` | Live events with a resume cursor on four paths: `hl` (fills, liquidations, positions, top-10 positions per coin, closed trades, liquidation risk, order walls, candles, TWAPs, ledger, leverage changes, funding), `hl-cohorts` (cohort flow, indices, cohort bias, cohort leverage), `onchain` (transfers on eth, bsc, base, hyperevm), `polymarket` (trades, wallet position changes, resolutions, price moves, new markets). `vike-data stream` reads them; `vike-data stream info` lists every channel and filter. Connections are not counted against the hourly limit. | free key | [stream channels](https://vike.io/docs/data/reference/stream-channels) |
 | **On-chain API** `/v1/onchain` | Wallet summaries, transactions, counterparties, PnL, address labels with per-source provenance, token holders and transfers. Ethereum on every route, BNB Chain on the wallet and token-flow routes, Base on token transfers. | free key | [onchain](https://vike.io/data/onchain) |
 
 Direct links that need no key:
@@ -138,7 +138,7 @@ Every data command is one `tools/call` to the MCP server. `vike-data <group> --h
 
 | Command | Subcommands | MCP tool |
 |---|---|---|
-| `vike-data token` | `search`, `transfers`, `screener`, `holders` (`--chain ethereum\|bsc\|base`) | `token_search`, `token_transfers`, `token_screener`, `token_holders` |
+| `vike-data token` | `search`, `transfers`, `screener`, `holders` (`--chain ethereum\|bsc\|base\|hyperevm`) | `token_search`, `token_transfers`, `token_screener`, `token_holders` |
 | `vike-data wallet` | `summary`, `transactions` (`txs`), `compare`, `trace`, `batch`, `counterparties`, `pnl-history`, `balances`, `ens`, `discover`, `first-funder`, `exchange-usage` | `wallet_summary`, `wallet_transactions`, `wallet_compare`, `wallet_trace`, `wallet_batch_labels`, `wallet_counterparties`, `wallet_pnl_history`, `wallet_token_balances`, `wallet_ens`, `wallet_discover`, `wallet_first_funder`, `wallet_exchange_usage` |
 | `vike-data labels <address>` | multi-source label provenance for one wallet | `wallet_label_provenance` |
 | `vike-data perp` | `top-traders`, `find-position` (Hyperliquid); `funding`, `spreads` (cross-venue funding rates and perp-vs-perp price gaps) | `hl_perp_top_traders`, `hl_position_match`, `perp_funding`, `perp_spreads` |
@@ -187,10 +187,14 @@ Downloads go to `./vike-archive/`.
 
 ## For AI agents
 
-This package ships **32 skill playbooks** under [`skills/`](skills/): markdown files an AI coding
+This package ships **47 skill playbooks** under [`skills/`](skills/): markdown files an AI coding
 agent loads so it knows when and how to call each command. [`skills.sh.json`](skills.sh.json) groups
-them by domain (Tokens, Wallets, CEX perps, Hyperliquid perps, Candles, Polymarket, Alerts, Live streams). The
-entry point is the umbrella skill `vike`, which routes a question to the specialised skill.
+them by domain (Quick start, Tokens, Wallets, CEX perps, Hyperliquid perps, Candles, Polymarket, Alerts, Live streams). The
+entry point is the umbrella skill `vike`, which routes a question to the specialised skill. Per-tool
+skills read one command; the workflow playbooks chain several: who a wallet is, where its money went,
+whether two wallets are related, token holder diligence and the smart-money trend, Hyperliquid cohort
+positioning and how to backtest it, one trader's profile, a symbol briefing, liquidation risk, builder
+codes, perp crowding, a Polymarket market's due diligence, the free L2 archive, a cross-market daily brief.
 
 ```bash
 npx skills add vike-io/vike-data-cli --list    # see them first

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "CLI, agent skills and MCP client for the free Vike Data API: a Polymarket full-L2 order-book archive in Parquet (CC BY 4.0), Hyperliquid positions, fills and cohorts, and labelled Ethereum/BNB wallets",
   "type": "module",
   "main": "src/index.js",

package/skills/vike/SKILL.md

@@ -7,7 +7,7 @@ description: "Use this skill whenever the user asks any question about on-chain
 
 This skill is for anyone who asks an AI agent about crypto data: who is buying a token, what a wallet holds, what Hyperliquid or Polymarket traders are doing right now. It tells the agent which vike tool answers which question and how to read the result, so it does not guess or invent numbers. It reads its data from vike.io and needs a free vike API key.
 
-What the platform has: wallet and token analytics on Ethereum and BSC, with Base for token transfers and labels (each tool's chain list is under "What each tool really returns"), multi-source wallet labels, CEX perpetual funding and cross-venue spreads, Hyperliquid wallets, cohorts, leaderboards, liquidations, markets, builders, vaults and candles, Polymarket markets, traders, tape, order books, settlements and the Parquet archive, transfer and Hyperliquid alerts, and live event streams over WebSocket. 70 tools in one MCP server.
+What the platform has: wallet and token analytics on Ethereum, BSC, Base and HyperEVM (each tool's chain list is under "What each tool really returns"), multi-source wallet labels, CEX perpetual funding and cross-venue spreads, Hyperliquid wallets, cohorts, leaderboards, liquidations, markets, builders, vaults and candles, Polymarket markets, traders, tape, order books, settlements and the Parquet archive, transfer and Hyperliquid alerts, and live event streams over WebSocket. 70 tools in one MCP server.
 
 **MCP endpoint for all calls:** `https://data.vike.io/mcp` (JSON-RPC 2.0)
 **Or use the CLI:** `npm install -g @vike-io/cli` → `vike-data <command>`
@@ -30,7 +30,7 @@ Hard rules — agents that violate these produce wrong answers. Read once, apply
 6. **USD amounts are floats in dollars.** `--min-usd 10000` = ten thousand dollars, not micro-USD.
 7. **`--json` is always available** on CLI commands and gives stable machine-readable output. The default (human) format may change; `--json` will not.
 8. **Resolve a token before asking transfer/holder questions.** `token_search` → take the canonical address → pass it to `token_transfers` / `token_holders`. Symbol-only queries lose precision on tickers that collide across chains (e.g. FUN, BEAM, USDC).
-9. **`bought` in `token_transfers` is every inbound transfer**, flash-loan round trips included. Read `net_tokens` (bought − sold) before calling a wallet a buyer.
+9. **`token_transfers` lists the top 10 NET buyers (`tab=bought`) or net sellers, ranked by net USD**, and a net buyer's `net_usd` is negative. A row can still be a pool, vault or router: `--hide-contracts` leaves out the contracts we know of.
 
 ---
 
@@ -77,10 +77,15 @@ Pick by the question, then read the named skill for the recipe and the traps. If
 | Who bought / sold a token (top 10, one side per call) | `vike-data token transfers` / `token_transfers` | `vike-token-transfers` |
 | "Research token X" end to end | search → transfers (both tabs) | `vike-token-research` |
 | Top holders of a token (ranked by net inflow, not balance) | `vike-data token holders` / `token_holders` | `vike-token-holders` |
+| Holder quality: largest balances, share of supply, exchanges / contracts / fresh / flagged wallets | `call token_holders` (`sort: "balance"`) → `wallet batch` | `vike-token-holder-diligence` |
 | Tokens trending / with the biggest inflow / smart-money inflow | `vike-data token screener` / `token_screener` | `vike-token-screener` |
 | "Is smart money buying X?" / alpha wallets | screener `--smart-money-only` → transfers | `vike-smart-money-discovery` |
+| Is smart money entering, holding or exiting X over 24h / 7d / 30d / 90d | screener at four windows, differenced | `vike-token-smart-money-trend` |
 | One wallet's volume / inflow / outflow / tx count by window | `vike-data wallet summary` / `wallet_summary` | `vike-wallet-summary` |
-| Full picture of one wallet ("who is this", "everything about it") | several calls | `vike-wallet-portfolio` |
+| Who is this address, is it an exchange, which exchanges does it use, who funded it | `search` → `labels` → `wallet summary` → `wallet exchange-usage` → `wallet counterparties` | `vike-wallet-who-is` |
+| Full picture of one wallet (holdings, flows, counterparties) | several calls | `vike-wallet-portfolio` |
+| Where did the money go, did it reach an exchange (exploit, scam) | `call wallet_trace` (`direction: "out"`) → `wallet txs` → `wallet batch`; `stream onchain` | `vike-follow-the-money` |
+| Do these wallets share an owner, find a wallet's siblings | `labels` → `wallet first-funder` → `wallet compare` → `wallet trace` | `vike-wallets-related` |
 | Top wallets by volume / flow / tx count | `vike-data wallet discover` / `wallet_discover` | `vike-wallet-discover` |
 | Individual transfers of a wallet | `vike-data wallet transactions` / `wallet_transactions` | `vike-wallet-transactions` |
 | Who a wallet trades with | `vike-data wallet counterparties` / `wallet_counterparties` | `vike-wallet-counterparties` |
@@ -92,12 +97,17 @@ Pick by the question, then read the named skill for the recipe and the traps. If
 | Label many addresses (up to 100) | `vike-data wallet batch` / `wallet_batch_labels` | `vike-wallet-batch` |
 | Why is this wallet labelled X (sources) | `vike-data labels <address>` / `wallet_label_provenance` | `vike-wallet-label-provenance` |
 | Funding rates, funding arb, one symbol across venues | `vike-data perp funding` / `perp_funding` | `vike-perp-funding` |
-| Cross-venue price spread, "perp market overview" | `vike-data perp spreads` + `perp funding` + `perp top-traders` | `vike-perp-overview` |
-| Top Hyperliquid traders; "is this HL address any good" | `vike-data perp top-traders` / `hl_perp_top_traders` | `vike-hl-top-traders` |
+| Cross-venue price spread, "perp market overview"; CEX open interest or long/short of one symbol | `vike-data perp spreads` + `perp funding` + `perp top-traders`; `call perp_open_interest`, `call perp_long_short` | `vike-perp-overview` |
+| Is X crowded: funding, open interest net of price, long/short per venue | `perp funding` + `call perp_open_interest` + `call perp_long_short` + `candles hl` | `vike-perp-crowding` |
+| Top Hyperliquid traders; the full leaderboard | `vike-data perp top-traders` / `hl_perp_top_traders`; `vike-data hl leaderboard` | `vike-hl-top-traders` |
 | HL share card → which wallet holds it | `vike-data perp find-position` / `hl_position_match` | `vike-hl-position-match` |
-| One HL wallet: equity, positions, cohorts, risk; its fills / funding / ledger | `vike-data hl wallet`, `hl wallet-activity` / `hl_wallet`, `hl_wallet_activity` | this skill |
-| Are whales / smart money long or short X (HL cohorts) | `vike-data hl cohort-metrics <symbol>`, `hl segments`, `hl market --view indices` | this skill |
-| HL leaderboard with the full risk set, liquidations, open interest, builders, vaults | `vike-data hl leaderboard`, `hl liquidations`, `hl market`, `hl builders`, `hl vaults`, `hl vault` | this skill |
+| One HL wallet: equity, positions, cohorts, risk, closed trades, funding, ledger, orders, liquidations | `vike-data hl wallet`, `hl wallet-trades`, `hl wallet-activity` | `vike-hl-trader-profile` |
+| Are whales / smart money long or short X (HL cohorts) | `vike-data hl cohort-metrics <symbol>`, `hl segments`, `hl market --view indices` | `vike-hl-cohort-positioning` |
+| Did cohort positioning lead price (a backtest without look-ahead) | `hl cohort-metrics --label-basis point_in_time` + `candles hl` | `vike-hl-cohort-backtest` |
+| Brief on one HL symbol: price, funding, OI, cohorts, liquidations | several `hl` calls + `perp funding` | `vike-hl-asset-briefing` |
+| Liquidation risk by symbol, liquidation heatmap, recent or live liquidations | `vike-data hl liquidations`; `stream hl --channel hl.liq_risk hl.liquidations` | `vike-hl-liquidation-radar` |
+| Builder codes: fees, users, routed share | `vike-data hl builders` | `vike-hl-builder-intel` |
+| HL open interest, vaults | `vike-data hl market`, `hl vaults`, `hl vault` | this skill |
 | HL orders and order clusters, TWAPs, the ledger, leverage changes, closed trades, venue stats, HYPE holders, the Parquet archive | `vike-data hl orders`, `hl twaps`, `hl ledger`, `hl leverage-changes`, `hl wallet-trades`, `hl stats`, `hl hype-holders`, `hl archive` | this skill |
 | A name, symbol, address, ENS name or polymarket.com link → what it is | `vike-data search <q>` / `search` | this skill |
 | Candles: Hyperliquid perp/spot (history, or the newest bar of every symbol), Polymarket outcome token; live HL bars | `vike-data candles hl` (`--view latest`), `candles polymarket`; `stream hl --channel hl.candles` | `vike-candles` |
@@ -106,13 +116,14 @@ Pick by the question, then read the named skill for the recipe and the traps. If
 | One Polymarket trader | `vike-data polymarket wallet` / `polymarket_wallet` | `vike-polymarket-trader` |
 | Polymarket smart-money flows / mispricings / overview | `vike-data polymarket smart-money` / `polymarket_smart_money` | `vike-polymarket-smart-money` |
 | Polymarket wallet leaderboard | `vike-data polymarket leaderboard` / `polymarket_leaderboard` | this skill |
-| One market's trades with wallets; raw tape; order book; tape stats | `vike-data polymarket market-trades`, `tape`, `orderbook`, `market-stats` | this skill |
-| Polymarket resolutions; the Parquet archive | `vike-data polymarket settlement`, `settlements`, `archive` | this skill |
-| Who funded a wallet; which exchanges it uses | `vike-data wallet first-funder`, `wallet exchange-usage` | this skill |
+| One market's liquidity, trades with wallets, raw tape, order book, tape stats, on-chain resolution | `vike-data polymarket market-trades`, `tape`, `orderbook`, `market-stats`, `settlement` | `vike-pm-market-diligence` |
+| Many resolutions; the Parquet L2 archive | `vike-data polymarket settlements`, `archive` | `vike-pm-l2-archive` |
+| Who funded a wallet; which exchanges it uses | `vike-data wallet first-funder`, `wallet exchange-usage` | `vike-wallet-who-is` |
+| A daily brief across perps, Hyperliquid, Polymarket and on-chain | several calls, cheap first | `vike-daily-brief` |
 | Find Polymarket markets by slug, or one by condition_id | `vike-data polymarket markets --view search --query btc-updown` / `--view market --condition-id 0x...` | this skill |
 | Alerts: create / list / edit / delete / events (transfer and Hyperliquid) | `vike-data alerts ...` / `alerts_*` | `vike-alerts-setup` |
 | Alert delivery to an HTTPS webhook | `vike-data alerts register-webhook`, `test-webhook`, `rotate-secret` | `vike-alerts-webhook` |
-| Live events: HL fills, liquidations, positions, candles, TWAPs, ledger, leverage, funding, cohort flow and bias; on-chain transfers; Polymarket trades and new markets | `vike-data stream <hl\|hl-cohorts\|onchain\|polymarket> --channel ...`; `stream info`, `check`, `events`, `connections` | `vike-stream` |
+| Live events: HL fills, liquidations, positions, top-10 positions, closed trades, candles, TWAPs, ledger, leverage, funding, cohort flow, bias and leverage; on-chain transfers; Polymarket trades, position changes and new markets | `vike-data stream <hl\|hl-cohorts\|onchain\|polymarket> --channel ...`; `stream info`, `check`, `events`, `connections` | `vike-stream` |
 | A tool with no command of its own | `vike-data call <tool> --args '{...}'` | this skill |
 | Install, auth, errors, conventions | — | `vike-core` |
 
@@ -120,16 +131,16 @@ Pick by the question, then read the named skill for the recipe and the traps. If
 
 ### Example query routing
 ```
-"Who bought the most PEPE in the last 24h?"          → token_search, then token_transfers (tab=bought, period=24h; 10 rows; rank by net_tokens)
+"Who bought the most PEPE in the last 24h?"          → token_search, then token_transfers (tab=bought, period=24h; the top 10 net buyers)
 "What is 0xd8dA6BF...AbA96 holding?"                  → wallet_token_balances   (+ wallet_summary for flows)
 "Funding rate for BTC across all perp venues"         → perp_funding            (symbol=BTC; raw per-interval rates)
 "Which venue pays the most funding on ETH?"           → perp_funding            (symbol=ETH, normalise to daily yourself)
 "Biggest HL perp PnL last week"                       → hl_perp_top_traders     (window=7d, sort=pnl)
 "What are the hottest crypto prediction markets?"     → polymarket_markets      (category=Crypto) → polymarket_market_detail
 "Why is 0x28C6... labeled 'Binance hot wallet'?"      → wallet_label_provenance (address=0x28C6...)
-"What is the ENS name of 0xd8dA6BF...?"               → wallet_ens              (address=0xd8dA...; name → address is NOT supported)
+"What is the ENS name of 0xd8dA6BF...?"               → wallet_ens              (address=0xd8dA...; name → address is `search`)
 "Alert me on WBTC transfers over $1M"                 → alerts_create           (token_symbol=WBTC, min_value_usd=1000000; fires on ANY such transfer)
-"Trace funds from 0xHACKER 3 hops out"                → wallet_trace            (address=0xHACKER, depth=3)
+"Trace funds from 0xHACKER 3 hops out"                → wallet_trace            (address=0xHACKER, depth=3, direction=out)
 ```
 
 ---
@@ -161,41 +172,44 @@ Run `vike-data schema --pretty` (or call MCP `tools/list`) to see the live arg s
 | Tool | Returns | Not |
 |---|---|---|
 | `token_search` | symbol, name, address, logo for a query | no market cap |
-| `token_transfers` | 10 wallets, one side (`tab` = `bought` or `sold`) per call, period 1h/24h/7d/30d: `address, bought, sold, net_tokens, usd_spent, usd_received, net_usd, chains` | no `--min-usd`; window ends at the token's newest priced row; a net seller has `net_usd > 0` |
-| `token_holders` | wallets ranked by cumulative net inflow USD, with entity/type | not balances, no concentration metric |
+| `token_transfers` | the top 10 net buyers (`tab=bought`) or net sellers, ranked by net USD, period 1h/24h/7d/30d: `address, bought, sold, net_tokens, usd_spent, usd_received, net_usd, chains`; `hide_contracts` drops known pools and routers | no `--min-usd`; window ends at the token's newest priced row; a net seller has `net_usd > 0` |
+| `token_holders` | wallets ranked by cumulative net inflow USD, with entity/type; `sort: "balance"` (via `call`) ranks by on-chain balance and adds `balance`, `value_usd`, `supply_pct` | the balance ranking covers candidate wallets, not every holder, and not every chain |
 | `token_screener` | per-token volume, net/in/out USD, `unique_holders` (wallets ACTIVE in the window, not growth), tx count | no age, liquidity or sector filter; no ascending sort; native coin shows as `0x000…000`; `symbol` is often blank |
 
 ### Wallets
 | Tool | Returns | Not |
 |---|---|---|
-| `wallet_summary` | a dict keyed `all, 90d, 30d, 7d, 24h`, each with `total_volume, total_inflow, total_outflow, net_flow, tx_count, tokens_traded, first_seen, last_active`, for ONE chain (the most recently active; never summed) | no PnL, holdings or labels |
-| `wallet_discover` | `{wallets, total}` ranked by volume / inflow / outflow / net_flow / tx_count / pnl (`size` ≤ 20; ethereum, bsc) | `realized_pnl` is a ranking key only, not a dollar figure; no labels column |
+| `wallet_summary` | a dict keyed `all, 90d, 30d, 7d, 24h`, each with `total_volume, total_inflow, total_outflow, net_flow, tx_count, tokens_traded, first_seen, last_active`, for ONE chain, named in `chain` (the more recently active of ethereum and bsc; never summed) | no PnL, holdings or labels; the command has no `--chain`: `call wallet_summary` with `chain` asks one chain |
+| `wallet_discover` | `{wallets, total}` ranked by volume / inflow / outflow / net_flow / tx_count / pnl (`size` ≤ 20) | `realized_pnl` is a ranking key only, not a dollar figure; no labels column; base and hyperevm serve `window=all` reliably |
 | `wallet_transactions` | single transfers, newest first | no aggregates |
 | `wallet_compare` | shared counterparties + shared tokens of exactly two wallets | not 3+ wallets |
-| `wallet_trace` | nodes + edges; direction lives in each edge's `out_usd` / `in_usd` | `from` is the side expanded first, not the sender |
+| `wallet_trace` | nodes + edges; direction lives in each edge's `out_usd` / `in_usd`; `direction` `out` / `in` (via `call`) expands by where money went / came from | `from` is the side expanded first, not the sender |
 | `wallet_counterparties` | top partners with sent/received USD and labels | |
 | `wallet_pnl_history` | daily net inflow USD (a proxy) | not realized PnL |
-| `wallet_token_balances` | holdings read from the chain at request time (ethereum, bsc); native coin is a row with `usd_value: null` | not a DeFi-position view |
-| `wallet_ens` | name for an address, or `null` | no name → address |
-| `wallet_batch_labels` | entity, type, risk flag + 30-day flow fields per address, in input order | on `bsc` the 30-day fields are `null` |
+| `wallet_token_balances` | holdings read from the chain at request time; the native coin is always listed | not a DeFi-position view; on base and hyperevm only mapped and priced tokens unless `min_usd=0` |
+| `wallet_ens` | name for an address, or `null` | no name → address here (`vike-data search <name.eth>` searches the address a name points to) |
+| `wallet_batch_labels` | entity, type, risk flag + 30-day flow fields per address, in input order, from that chain's tables | the 30-day fields are `null` for an address with no label |
+| `wallet_first_funder`, `wallet_exchange_usage` | the earliest inbound coin and token transfers with the senders' labels; the exchanges a wallet sent to and received from | not proof of who funded it or owns it |
 
-Chains: most token and wallet tools accept `chain` = `ethereum` | `bsc` | `base`, but Base coverage is narrower: it is documented for token transfers and `wallet_batch_labels`, while the per-wallet transfer tools (`wallet_transactions`, `wallet_counterparties`, `wallet_trace`, `wallet_compare`, `wallet_pnl_history`) are documented for Ethereum and BSC. `wallet_discover` takes `ethereum` | `bsc`, `wallet_token_balances` serves `ethereum` | `bsc` (anything else lands in `chain_errors`) and alerts take `eth` | `bsc`. `token_screener` smart-money mode and `smart_inflow` sort are `ethereum` only (a 400 elsewhere). `wallet_label_provenance` is for Ethereum wallets. Arbitrum, Bitcoin, Solana, Tron and other non-EVM chains are not served. When a chain is not covered, say so; an empty Base result means "not covered", not "no activity".
+Chains: every token and wallet tool takes `chain` = `ethereum` | `bsc` | `base` | `hyperevm` (default ethereum; `token_transfers` also `all`), and `wallet_token_balances` scans all four by default. Exceptions: `token_screener` smart-money mode and `smart_inflow` sort are `ethereum` only (a 400 elsewhere); `wallet_label_provenance` reads the Ethereum label table; labels are sparse on hyperevm; alerts and the stream spell Ethereum `eth`. Arbitrum, Bitcoin, Solana, Tron and other non-EVM chains are not served: say so.
 
 ### Labels
-`wallet_label_provenance` returns the raw source labels (at most 6 sources plus our heuristic classifier) and a consensus entity/type. When an answer hinges on "is this really a CEX hot wallet?", call it rather than trusting one source. `found: false` means the wallet is missing from our labelled-wallet table and no source is consulted at all, so it is not proof that nobody labels it, and it is not proof the wallet is clean.
+`wallet_label_provenance` returns the raw source labels (at most 6 sources plus our heuristic classifier) and a consensus entity/type. When an answer hinges on "is this really a CEX hot wallet?", call it rather than trusting one source. Every source is read on every call, and `found` is true when ANY source knows the address; `found: false` means none does and the wallet is not in our label table. It is not proof the wallet is clean.
 
 ### CEX perps
 | Tool | Returns |
 |---|---|
 | `perp_funding` | with `symbol`: raw per-venue `funding_rate` + `interval_h` (daily % = rate × 24 / interval_h × 100); without: up to 5 pre-ranked arb rows (`long_exchange`, `short_exchange`, `spread_daily_pct`) |
 | `perp_spreads` | up to 10 cross-venue price-gap rows (≥ 0.5%); `symbol` only filters that global top 10, so it is often empty |
+| `perp_open_interest` (`call`) | `oi_usd` per venue (USD notional, moves with price), newest print or an hourly series (`hours` 1-168); `stale_venues` are never in a total |
+| `perp_long_short` (`call`) | `long_share`, `short_share` (fractions), `long_short_ratio` per venue, each with its `basis` (what the venue counts); about 40 major symbols |
 
-Neither returns mark prices or bid/ask per venue. "Spread" here is perp vs perp across venues, not spot vs perp.
+These two have no command: `vike-data call perp_open_interest --args '{"symbol":"BTC","hours":24}'`. None returns mark prices or bid/ask per venue. "Spread" here is perp vs perp across venues, not spot vs perp.
 
 ### Hyperliquid
 | Tool | Returns |
 |---|---|
-| `hl_perp_top_traders` | up to 20 wallets: `total_realized_pnl`, `roi_pct`, `win_rate_pct`, `max_drawdown_pct` (all percents; 12.5 = 12.5%), `trade_count`, `total_volume`. ROI = window realized PnL / CURRENT account value; drawdown is account-level and all-time |
+| `hl_perp_top_traders` | up to 100 wallets (`size`, default 20): `total_realized_pnl`, `roi_pct`, `win_rate_pct`, `max_drawdown_pct` (all percents; 12.5 = 12.5%), `trade_count`, `total_volume`. ROI = window realized PnL / CURRENT account value; drawdown is account-level and all-time |
 | `hl_position_match` | wallets whose open position matches a share card (`symbol`, side, leverage, entry) |
 | `hl_ohlcv` | perp or spot candles |
 | `hl_wallet` (`vike-data hl wallet`) | one wallet: equity, open positions, cohort labels, risk metrics, lifetime flow; `--view trades_summary` for closed-trade stats |
@@ -216,7 +230,7 @@ Every `hl` command takes `--view` (the first view is the default) and only the f
 | Tool | Returns |
 |---|---|
 | `polymarket_markets` | markets ranked by 24h volume only (`volume_24h`, `liquidity`, `ended`, `outcomes[]` with `token_id`, `mid`, `bid`, `ask`) |
-| `polymarket_market_detail` | one market: quotes, smart-money cohort flows, top wallets, resolution status |
+| `polymarket_market_detail` | one market: outcomes with `clob_token_ids`, volume, liquidity, an hourly series per outcome, the top 30 holders per side, the last 100 trades with wallets, tape stats, resolution status; no live quote and no smart-money block |
 | `polymarket_wallet` | one trader: realized PnL, volume-weighted `hit_rate`, `resolved_markets`, positions |
 | `polymarket_smart_money` | MARKETS where the profitable-wallet cohort is flowing (`flows`) or bought below the mid (`mispricings`); not a list of top traders |
 
@@ -230,7 +244,7 @@ Create + manage on-chain transfer alerts and Hyperliquid alerts, delivered by em
 | `alerts_events`, `alerts_resend_delivery` | what fired and each delivery's status (15 days); send one again |
 | `alerts_register_webhook`, `alerts_test_webhook`, `alerts_rotate_webhook_secret` | an HTTPS webhook (HMAC-signed deliveries): register, test, rotate its secret |
 
-A token-wide transfer alert fires on ANY transfer of the token above the USD threshold on that chain; an address alert on every transfer of that wallet. Hyperliquid alerts go to a webhook or are read with `alerts events` (no email). There is no price or funding alert, no Discord (off) and no Telegram delivery. For a live feed without a rule, use `vike-data stream`.
+A token-wide transfer alert fires on ANY transfer of the token above the USD threshold on that chain; an address alert on every transfer of that wallet. Every match is recorded in `alerts events` (15 days) whatever the channels; a transfer alert left with no enabled channel e-mails the account address. Hyperliquid alerts go to a webhook or are read with `alerts events`; only `hl_wallet` may also use email. There is no price or funding alert, no Discord (off) and no Telegram delivery. For a live feed without a rule, use `vike-data stream`.
 
 ---
 
@@ -239,7 +253,7 @@ A token-wide transfer alert fires on ANY transfer of the token above the USD thr
 Credits are an accounting figure only; they never block a call. The one limit is 20,000 requests per rolling hour per key, shared by MCP and REST.
 
 - **0 credits:** `token_search`, `alerts_list`, `alerts_list_channels`.
-- **1:** `wallet_ens`, `wallet_label_provenance`, `perp_funding`, `perp_spreads`, `hl_ohlcv`, `polymarket_markets`, `polymarket_ohlcv`.
+- **1:** `wallet_ens`, `wallet_label_provenance`, `perp_funding`, `perp_spreads`, `perp_open_interest`, `perp_long_short`, `search`, every `hl` command, `hl_ohlcv`, `polymarket_markets`, `polymarket_ohlcv`, the Polymarket tape, order book, stats, trades, settlement and archive calls.
 - **2:** most others, `wallet_summary` among them.
 - **3:** `token_screener`, `wallet_compare`, `wallet_token_balances`, `alerts_create`.
 - **4:** `wallet_trace`.
@@ -248,7 +262,7 @@ Credits are an accounting figure only; they never block a call. The one limit is
 
 - **No NFT data** — out of scope by design.
 - **No on-chain trading / signing** — read-only platform, no execution.
-- **No ENS name → address**, no candles for CEX tickers or arbitrary ERC-20 contracts.
+- **No ENS name → address in `wallet ens`** (`vike-data search <name.eth>` does it), no candles for CEX tickers or arbitrary ERC-20 contracts.
 - **No non-EVM chains** (Bitcoin, Solana, Tron, Monero, Zcash, Dash) and no Arbitrum.
 
 If the user asks for any of the above, say so directly rather than proposing a workaround.

package/skills/vike-alerts-setup/SKILL.md

@@ -12,7 +12,7 @@ allowed-tools: Bash(vike-data:*)
 vike-data alerts channels --json
 ```
 
-Returns enabled email + webhook channels. **If a user creates an alert with a channel they haven't verified, the alert is saved but won't fire notifications.** Always check first. A Hyperliquid alert is delivered only by a webhook (`vike-alerts-webhook`), or read with `vike-data alerts events`.
+Returns enabled email + webhook channels. **A channel kind the user has no enabled channel of is dropped from a transfer alert, and a transfer alert left with no channel e-mails the account address.** Whatever the channels, every match is recorded and read with `vike-data alerts events` (kept 15 days). A Hyperliquid alert is delivered by a registered webhook (`vike-alerts-webhook`; asking for one the user has not registered is an error) or only read with `alerts events`; `hl_wallet` alone may also use `--channel email`.
 
 ## CRUD
 
@@ -43,7 +43,7 @@ vike-data alerts create --label "Treasury in" --chain base \
   --address 0x1111111111111111111111111111111111111111 --address-role to --channel email
 ```
 
-Hyperliquid alerts (`--type`; leave out `--chain`, `--address`, `--max-usd`; delivered by `--channel webhook`, or with no channel read them with `vike-data alerts events`):
+Hyperliquid alerts (`--type`; leave out `--chain`, `--address`, `--max-usd`; delivered by `--channel webhook` (`hl_wallet` also `email`, at most one mail per pass), or with no channel read them with `vike-data alerts events`):
 
 | `--type` | Fires on | Flags |
 |---|---|---|
@@ -75,13 +75,15 @@ vike-data alerts events --rule-id 42 --json
 vike-data alerts resend <delivery_id>               # send one delivery again
 ```
 
-### Delete
+### Delete (only when the user explicitly asks)
 
 ```bash
 vike-data alerts delete 42                          # soft-delete (pauses, keeps history)
-vike-data alerts delete 42 --hard                   # permanently remove
+vike-data alerts delete 42 --hard                   # permanently remove: only on an explicit "delete it for good"
 ```
 
+Never delete or hard-delete an alert on your own initiative, to "clean up" or to replace it: pause it with `edit --active false` if the user only wants it quiet.
+
 ## Notes + gotchas
 
 - Transfer chains: **eth**, **bsc**, **base**, **hyperevm**, one per alert. For several, create several alerts.
@@ -89,7 +91,7 @@ vike-data alerts delete 42 --hard                   # permanently remove
 - Thresholds are in **USD value** of the transfer at fire time, not token quantity.
 - `--cooldown` is the minimum gap between notifications of a token-wide transfer alert (default 60 min). Address alerts and Hyperliquid alerts notify on every event and ignore it.
 - Tokens are matched by symbol (UPPERCASE). For cross-chain symbols like `USDC` that exist on multiple chains, be explicit with `--chain`.
-- Alerts created without a verified channel will be **silently inactive at fire time** — there is no automatic warning. Use `vike-data alerts channels` first.
+- A transfer alert whose channels are not set up is not silent: it falls back to e-mailing the account address, and every match is in `alerts events`. Run `vike-data alerts channels` first so the user gets the delivery they expect.
 
 ## Confirmation flow with the user
 

package/skills/vike-alerts-webhook/SKILL.md

@@ -14,7 +14,7 @@ vike-data alerts register-webhook <https://your-server.com/vike-hook>
   [--json]
 ```
 
-The secret is **optional but strongly recommended** — without it we still POST, but the recipient has no way to verify it came from us.
+**Every POST is signed** (HMAC-SHA256). `--secret` is optional: without it the server generates one and returns it as `secret` in the answer. Show it to the user right away (it is also under Account → Alerts → channels, Show secret) so the receiver can verify deliveries.
 
 ## Example
 
@@ -33,7 +33,7 @@ Then create an alert with `--channel webhook` (alongside `email` if wanted; a Hy
 
 ```bash
 vike-data alerts test-webhook <channel_id>     # send the signed test event again
-vike-data alerts rotate-secret <channel_id>    # new secret; the old one keeps signing for 24 hours
+vike-data alerts rotate-secret <channel_id>    # only when the user explicitly asks: new secret, the old one keeps signing for 24 hours
 vike-data alerts events --json                 # what fired, with each delivery's status
 vike-data alerts resend <delivery_id>          # send one delivery again (up to 15 days)
 ```
@@ -72,7 +72,8 @@ def verify(secret, headers, body):
 
 ## Anti-patterns
 
-- **Don't** skip the secret. Anyone who knows your webhook URL can spoof alerts without it.
+- **Don't** lose the secret or skip verifying: every delivery is signed with it (yours, or the one the server generated), and without the check anyone who knows the URL can spoof alerts.
+- **Don't** rotate the secret unless the user asks: the receiver must install the new one within 24 hours.
 - **Don't** trust the body without verifying the signature. The URL doesn't authenticate the sender; the HMAC does.
 - **Don't** use HTTP (only HTTPS) in production — the body is sensitive.
 - **Don't** respond slowly — we time out after 10s. If your handler does heavy work, queue it (push to a job queue, return 200 immediately).

package/skills/vike-candles/SKILL.md

@@ -64,5 +64,6 @@ Polymarket: `ts`, `open`, `high`, `low`, `close`, `volume`, `trades`, oldest fir
 
 ## Pairs well with
 
-- `vike-data polymarket market <condition_id>` — to find the token ids
-- `vike-data perp top-traders` — who is trading the asset behind the candles
+- `vike-data polymarket market <condition_id>` — to find the token ids; `vike-pm-market-diligence` for the order book and tape of the same token
+- `vike-data perp top-traders` — who is trading the asset behind the candles; `vike-hl-cohort-positioning` for how cohorts are positioned in it
+- `vike-hl-cohort-backtest` — cohort positioning against these candles, without look-ahead

package/skills/vike-core/SKILL.md

@@ -47,7 +47,7 @@ vike-data --help                        # command list; add --help to any comman
 - All commands accept `--json` for pipe-friendly output. Without it, you get a human-readable table.
 - Addresses: pass full 0x-prefixed hex (42 chars). Never truncate when reporting back to the user.
 - USD amounts: integers/decimals (e.g. `--min-usd 10000`).
-- Chain identifiers: `ethereum`, `bsc`, `base` on the token and wallet commands (`wallet discover` and `wallet balances` serve ethereum and bsc only; `wallet first-funder` and `exchange-usage` also take `hyperevm`; `alerts` takes `eth`, `bsc`, `base` or `hyperevm`). Base coverage is narrower than the flag suggests: documented for token transfers and `wallet batch`, not for the per-wallet transfer commands, so an empty Base result means "not covered". Non-EVM chains and Arbitrum are not served. Check `vike-data <cmd> --help` for the exact list.
+- Chain identifiers: `ethereum`, `bsc`, `base`, `hyperevm` on the token and wallet commands (`alerts` and `stream` spell Ethereum `eth`). Exceptions: `wallet discover` on `base` and `hyperevm` needs `--window all` (the shorter windows there answer only while freshly rebuilt); `token screener --smart-money-only` and `--sort smart_inflow` are Ethereum only; `labels` reads the Ethereum label table. `wallet summary` has no chain flag: it answers for one chain and names it in `chain` (`vike-data call wallet_summary --args '{"address":"0x...","chain":"base"}'` asks one). Non-EVM chains and Arbitrum are not served (`wallet balances` lists them under `chain_errors`).
 - Time windows: `24h`, `7d`, `30d`, `90d`, `all` (per command; check `vike-data <cmd> --help`). Windows are counted in UTC calendar days.
 
 ## Errors
@@ -62,10 +62,10 @@ vike-data --help                        # command list; add --help to any comman
 
 ## Cost awareness
 
-Credits are an accounting figure on each call and never block one. The limit is 20,000 requests per rolling hour per key, shared by the MCP server and the REST API. Free (0 credits): `token search`, `alerts list`, `alerts channels`. Heaviest: `wallet trace` (4), then `token screener`, `wallet compare`, `wallet balances` (3).
+Credits are an accounting figure on each call and never block one. The limit is 20,000 requests per rolling hour per key, shared by the MCP server and the REST API. Free (0 credits): `token search`, `alerts list`, `alerts channels`. Every `hl` command, `search`, and the Polymarket tape, order book, stats, trades, settlement and archive commands are 1 credit. Heaviest: `wallet trace` (4), then `token screener`, `wallet compare`, `wallet balances` (3).
 
 ## Which skill to use
 
 - The umbrella skill `vike` holds the routing table — use it when the user is exploring or unsure which command they need.
-- Task skills (`vike-smart-money-discovery`, `vike-perp-funding`, etc.) — when the user has a specific question that maps to a known workflow.
+- Task skills (`vike-wallet-who-is`, `vike-follow-the-money`, `vike-hl-asset-briefing`, `vike-pm-market-diligence`, `vike-daily-brief`, `vike-smart-money-discovery`, `vike-perp-funding`, etc.) — when the user has a specific question that maps to a known workflow.
 - If unsure between two, prefer the task skill (a workflow) over the per-tool skill (one command). For raw data, use the per-tool skill with `--json`.

package/skills/vike-daily-brief/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: vike-daily-brief
+description: One-page cross-market brief of what changed today - perp funding, open interest and long/short lean, Hyperliquid cohort positioning, liquidation risk and venue totals, trending Polymarket markets with smart-money flows, and Ethereum tokens the smart-money cohort is buying. Cheap calls first, every section skippable. Use when the user asks "daily brief" / "morning brief" / "what is happening across crypto today" / "give me a market rundown across perps, Hyperliquid, Polymarket and on-chain".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-daily-brief
+
+About 15 credits for all four sections; run only the ones the user wants and say which were skipped. Calls inside a section are independent: run them in parallel. If a call fails, omit its bullet and say so.
+
+## 1. Perps (about 5 credits)
+
+```bash
+vike-data perp funding --json &                                    # top cross-venue funding arbs (daily %, spread >= 0.3%)
+vike-data call perp_open_interest --args '{"symbol":"BTC"}' &      # repeat for ETH; oi_usd is USD notional
+vike-data call perp_long_short --args '{"symbol":"BTC"}' &         # repeat for ETH; read each venue's `basis`
+wait
+```
+
+- Funding rows are `long_exchange` / `short_exchange` / `spread_daily_pct`. The top rows are often thin tokens: check `vol_24h_usd` with `perp funding --symbol <S>` before presenting one as a trade.
+- Report BTC and ETH OI per venue and leave out `stale_venues`; report each venue's long share with its basis, never an average.
+
+## 2. Hyperliquid (about 4 credits)
+
+```bash
+vike-data hl cohort-metrics BTC --axis pnl --hours 1 --json &                       # repeat for ETH
+vike-data hl liquidations --view risk --min-value-usd 50000000 --limit 10 --json &  # symbols with $50M+ open, closest to liquidation
+vike-data hl stats --view ecosystem --limit 25 --json &                             # venue-wide equity, open interest, positions per hour
+wait
+```
+
+- `bias` is a fraction -1..+1 of notional; report the `3x smart`..`smart` group and the `rekt` group (sum notional; see `vike-hl-cohort-positioning`), and check `freshness.stale`. Today's labels, not a history.
+- Liquidation risk: `percent_risk` is a fraction; name the top 3 symbols.
+- Venue totals: compare the newest hour with the one 24 rows back (rows are newest first).
+
+## 3. Polymarket (about 3 credits)
+
+```bash
+vike-data polymarket markets --category Crypto --limit 5 --json &
+vike-data polymarket smart-money --mode flows --hours 24 --category Crypto --limit 5 --json &
+wait
+```
+
+- Skip rows that are already decided: a mid of 0.98 or more (or 0.02 or less) is a finished game, and in an unfiltered flows list the top rows are often last night's sports results. Quotes are probabilities.
+- Check `ended` on trending markets before presenting one.
+
+## 4. On-chain, Ethereum (3 credits)
+
+```bash
+vike-data token screener --chain ethereum --window 24h --sort smart_inflow --smart-money-only --limit 10 --json
+```
+
+- Rows are the smart-money cohort's flow per token. Skip `0x0000000000000000000000000000000000000000` (the native coin) and stablecoins unless asked; report `symbol` (or the address when blank), `net_flow_usd`, `unique_holders`. `24h` is yesterday plus today (UTC).
+- For one interesting token run `vike-token-smart-money-trend`; do not name buyers from this call.
+
+## Output
+
+Five to ten bullets, each with its number and unit, grouped by section, then one line: what the brief does not cover (no news, no price forecasts, no CEX spot, smart money on Ethereum only) and the data time. No advice.
+
+## Anti-patterns
+
+- Don't run section 4 first (it is the most expensive) or repeat a section the user did not ask for.
+- Don't mix percents and fractions in one line, and don't call a decided market "smart-money conviction".
+
+## Pairs well with
+
+- `vike-perp-overview`, `vike-hl-asset-briefing`, `vike-polymarket-smart-money`, `vike-token-smart-money-trend`
+- `vike-stream` for the same markets as events, e.g. `hl.liquidations` or `pm.trades` with a `min_usd` floor

package/skills/vike-follow-the-money/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: vike-follow-the-money
+description: Trace where the money of one wallet went - the outbound graph hop by hop, the actual transfers, every node labelled, stopping at an exchange - then watch the trail live. Use when the user asks "where did the funds from 0x... go" / "follow the money" / "trace this exploit or scam wallet" / "did it reach an exchange" / "investigate this address".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-follow-the-money
+
+Incident-style trace from one root wallet. About 12 credits. Per-tool details live in `vike-wallet-trace`; this is the order to run them in and the stop rules.
+
+## Chain
+
+```bash
+ADDR=0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4
+vike-data labels $ADDR --json          # 1  is the root itself an exchange, MM or contract?
+# 4 credits: direction "out" expands each hop by where the money WENT (the `wallet trace` command has no --direction)
+vike-data call wallet_trace --args '{"address":"0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4","chain":"ethereum","direction":"out","depth":2,"width":5,"window":"30d","min_usd":100000}'
+vike-data wallet txs $ADDR --chain ethereum --direction out --min-usd 100000 --days 30 --limit 50 --json   # 2  the real transfers
+vike-data wallet batch <node addresses with an empty label> --chain ethereum --json                         # 2  label the rest
+vike-data wallet exchange-usage <endpoint> --chain ethereum --window 30d --json                             # 3  did it reach an exchange
+```
+
+Chains: `ethereum`, `bsc`, `base`, `hyperevm` on every command above; `labels` reads the Ethereum label table, so on other chains label with `wallet batch --chain`. "Where did it come from" is the same chain with `"direction":"in"`, or `vike-data wallet first-funder $ADDR --chain <c>` for the earliest inbound transfers.
+
+## Reading the trace
+
+- Each edge carries `out_usd` (flowed `from -> to`) and `in_usd` (flowed `to -> from`); `from` is the side expanded first, not the sender. Rank the root's edges by `out_usd` for "where did it go".
+- Nodes carry `label` and `wallet_type`; `wallet batch` is for the empty ones (adds `risk_flag`, 30-day flow).
+- **Stop** at a node with `wallet_type: cex` (the trail goes off-chain; report exchange and time), at a `dex` router (a swap, not a destination), after depth 3, or after about 10 wallets. Unlabelled, high-volume nodes at depth 1-2 are the leads.
+- Only transfers priced at or above `min_usd` count; a `value_usd` of 0 is UNPRICED, not worthless, and an unpriced token never shows in the graph. Say so if the loss was in an obscure token.
+- `max_depth_reached` below `depth` = nothing above the floor beyond that hop, or the server's expansion cap cut the graph; you cannot tell which.
+- `wallet txs` gives what the graph cannot: `tx_hash`, `time`, `token_address`, `value_usd`, `block` for each transfer. Quote hashes, not just totals.
+- `exchange-usage` on an endpoint lists the exchanges it sent to with USD and shares; `pattern: "sweeps_to_single_cex"` is an observed pattern, not proof of a deposit address.
+
+## Watch the trail live
+
+```bash
+# every transfer touching the root or its first hops (either side), pools and routers left out
+vike-data stream onchain --channel chain.transfers --filter chain=eth --filter wallet=0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4,<hop1> --filter contract=false
+```
+
+- The stream spells the chain `eth`, not `ethereum`. Events arrive in bursts about 3 minutes after the block.
+- **Never put `min_usd` on `chain.transfers`**: transfers are priced after they are streamed, so it drops almost every event. For one token use `--filter token=0x... --filter min_amount=<whole tokens>`.
+- `contract=false` drops a transfer when either side is a known contract; no mark does not mean "not a contract".
+- For a stored rule instead of a running process: `vike-data alerts create --label "Exploiter out" --chain eth --address $ADDR --address-role from --min-usd 10000 --channel email` (see `vike-alerts-setup`). Keep a `--min-usd`: an address alert notifies on EVERY matching transfer (no cooldown, no daily cap), and without a floor that includes dust and unpriced spam tokens. With it, only transfers that already carry a USD value match, so an unpriced token never fires.
+
+## Answer template
+
+> Root `<0x...>` (`<label or unlabelled>`). In the last `<window>` it sent `$X` to `N` counterparties; the largest: `<0x...>` `$A` (`<label>`), `<0x...>` `$B`. Trail: `<root> -> <hop 1> -> <exchange>` (last transfer `<time>`, tx `<hash>`). Unlabelled endpoints: `<list>`. Evidence from on-chain transfers above `$floor`; nothing below it or unpriced is included.
+
+## Anti-patterns
+
+- Don't continue past a CEX or call a deposit address a person.
+- Don't trace at `min_usd` 0: dust edges bury the path.
+- Don't present the trace as proof of intent or ownership.
+
+## Pairs well with
+
+- `vike-wallet-who-is` on each endpoint, `vike-wallets-related` to test whether two endpoints are one entity
+- `vike-wallet-trace` (parameters), `vike-wallet-transactions` (filters), `vike-stream` (the live feed)

package/skills/vike-hl-asset-briefing/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: vike-hl-asset-briefing
+description: One-page briefing on a single Hyperliquid symbol - price, Hyperliquid funding and open interest by the hour, funding and open interest on the other venues, how the size and PnL cohorts are positioned, where liquidations cluster, large fills and where resting orders stack. Use when the user asks "brief me on ETH on Hyperliquid" / "what is going on with SOL perps" / "positioning, funding and liquidations for BTC" / "is HYPE crowded".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-hl-asset-briefing
+
+About eight calls for ONE symbol, 1 credit each. Every section is skippable if the user asked something narrower. Symbols are upper case; a HIP-3 market is `dex:TICKER`.
+
+## Chain
+
+```bash
+S=ETH
+vike-data candles hl $S --interval 1h --limit 24 --json            # price: 24 hourly bars
+vike-data hl market --view hourly --symbols $S --days 7 --json     # Hyperliquid close, open interest, funding rate, premium per hour
+vike-data perp funding --symbol $S --json                          # funding on every venue now (normalise it yourself)
+vike-data call perp_open_interest --args '{"symbol":"ETH"}'        # open interest per venue, USD notional (no command of its own)
+vike-data hl cohort-metrics $S --axis size --hours 1 --json        # whales' long/short
+vike-data hl cohort-metrics $S --axis pnl  --hours 1 --json        # profitable vs losing wallets
+vike-data hl liquidations --view heatmap --symbol $S --bins 20 --json   # where liquidations would cluster
+vike-data hl market --view large_fills --symbol $S --json               # the newest fills of $50k+ (at most 200)
+```
+
+Optional: `hl orders --view clusters --symbol $S` (standing orders bucketed around the mid, `--range-pct`, `--step-bps`), `hl market --view size_breakdown --symbol $S` (position-size tiers with `value_close_to_liquidation`), `hl liquidations --view fills --symbol $S --limit 20` (the latest liquidations).
+
+## Reading each section
+
+- **Price**: candles of `ts` (epoch ms), `open..close`, `volume_usd`. The hourly panel gives the same closes beside funding and open interest, so a funding or OI change can be read against the price move of the same hour.
+- **Funding**: raw `funding_rate` per interval, and `interval_h` differs (Hyperliquid 1h, most CEXs 8h): `daily_pct = funding_rate x (24 / interval_h) x 100`. Positive = longs pay shorts. Halted or silent venues are left out of the per-symbol list.
+- **Open interest**: `oi_usd` is USD notional (contracts x mark price), so it moves with price even when nobody opens or closes. Venues in `stale_venues` are not in `venues` and never in a total.
+- **Cohorts**: `bias` is a fraction -1..+1 of notional; group rungs by summing notional (see `vike-hl-cohort-positioning`); check `position_count` before calling a rung's lean meaningful. Labels are today's.
+- **Liquidation heatmap**: bins are equal-width over +-50% of `mark_price`; `liquidation_value_usd` is open notional whose liquidation price falls in the bin, with `long_value_usd` / `short_value_usd` and `most_impacted_cohort`. `coverage.in_window_fraction_of_open` is the share of open notional the map covers: positions outside the window or without a liquidation price are dropped, so clusters are a floor. Long liquidations sit BELOW the mark, short ones above.
+- **Large fills**: the newest 200 fills of $50k+ the feed holds for the symbol, newest first; on a busy symbol they may reach back only minutes. Quote `covered_from` (how far back the answer reaches) and `truncated` (true = older fills may have been cut), never "today". `--min-usd` raises the floor.
+
+## Answer template
+
+> `<S>` on Hyperliquid: price `<p>` (`<24h change>`). Funding `<daily %>` on Hyperliquid (`<7d range>`) vs `<range>` on `<n>` other venues. OI `$X` on Hyperliquid, `$Y` across `<k>` venues. Whales `<bias_g>`, profitable wallets `<bias>`, losing wallets `<bias>` (labels as of today). Nearest liquidation cluster `<side>` `$V` around `<price range>` (`<coverage>` of open notional mapped). Largest fill since `<covered_from>`: `<side> $F` by `<wallet>`.
+
+## Anti-patterns
+
+- Don't call a funding spread "free money" and don't average funding across venues with different intervals.
+- Don't read an OI change in USD as new positions without taking out the price move (see `vike-perp-crowding`).
+- Don't run `hl market --view positions` here without `--symbol`.
+
+## Pairs well with
+
+- `vike-hl-cohort-positioning`, `vike-hl-liquidation-radar`, `vike-perp-funding`, `vike-perp-crowding`, `vike-candles`