@vike-io/cli 0.14.0 → 0.16.0

package/skills/vike-candles/SKILL.md

@@ -21,9 +21,16 @@ vike-data candles hl <symbol>
   [--dex <name>]                        # HIP-3 builder DEX; default HL (the core venue)
   [--start <iso|epoch-ms>] [--end <iso|epoch-ms>]   # half-open [start, end)
   [--limit N]                           # default 500, max 5000
+  [--view export]                       # the same, limit defaults to 5000
   [--json]
+
+vike-data candles hl --view latest [--market perp|spot] [--dex <name>]   # the newest 1m bar of EVERY symbol
+                                                                         # that traded in the last hour (may still be forming)
 ```
 
+Live closed bars as they happen: `vike-data stream hl --channel hl.candles --filter coin=BTC,ETH --filter interval=1m`
+(also `market=perp|spot`, `dex=HL`; see `vike-stream`).
+
 Polymarket, ONE outcome token (a probability, 0-1):
 
 ```bash
@@ -57,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; `alerts` takes `eth` or `bsc`). 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
@@ -56,13 +56,16 @@ vike-data --help                        # command list; add --help to any comman
 - `MCP error -32000: Hourly rate limit exceeded` → you hit the per-key cap of 20,000 requests per rolling hour; the window slides, so capacity returns continuously.
 - `Network error` / timeout → check `vike-data doctor`; the endpoint is `https://data.vike.io/mcp`.
 - `503` from a tool → upstream data source temporarily down; retry in 30s.
+- A tool that refuses its input (`{"error": ...}`) exits 1 in every mode, `--json` included: read the message, it names the fix.
+- A tool with no command of its own: `vike-data call <tool> --args '{"key":"value"}'` prints its raw result.
+- `vike-data stream` exits 1 on `replaced (4410)`: another program took this key's connection on that address; give each program its own key. On `HTTP 401` or `4401` fix the key. Every other drop reconnects by itself.
 
 ## 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`

package/skills/vike-hl-builder-intel/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: vike-hl-builder-intel
+description: Hyperliquid builder codes - which front-ends and bots earn the most fees, how concentrated their users are, their symbols and fee series, and which builders one wallet routes through. Use when the user asks "which Hyperliquid builder codes earn the most" / "who runs builder X and how big is it" / "builder fee revenue" / "how much of Hyperliquid volume is routed through builders".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-hl-builder-intel
+
+A builder code lets a front-end or bot attach its address to an order and keep a slice of the fee. About 5 calls, 1 credit each.
+
+## Chain
+
+```bash
+vike-data hl builders --view leaderboard --window 30d --sort fee --limit 10 --json     # who earns
+vike-data hl builders --view stats --window 30d --json                                  # venue totals, routed share of volume
+B=0x5af1b5f44207784dcb850bbb4143c5dcd1885f71
+vike-data hl builders --view profile --builder $B --window 30d --json                   # by symbol, by dex, user deciles, lifetime
+vike-data hl builders --view users --builder $B --window 30d --limit 10 --json
+vike-data hl builders --view series --builder $B --bucket 1d --limit 30 --json
+```
+
+`search <name>` finds a builder by name (its `builders` section). Other views: `fills` (the raw routed fills, `--symbol`, `--side`). One wallet's builders: `vike-data hl wallet-activity <wallet> --view builders --window 30d`. `--window` is `1d|7d|30d|all`; page with `nextCursor` -> `--cursor`. `profile`, `users`, `fills` and `series` require `--builder`; a flag a view does not take is refused, not ignored.
+
+## Reading
+
+- `leaderboard` rows: `rank`, `builder`, `fee_usd`, `volume_usd`, `fills`, `users`, `revenue_per_user`, `fee_rate_bps`, `taker_pct`, `market_share_pct`, `active_days`. `--sort fee` ranks the builder's own cut, not what traders paid; the order differs from `--sort volume`.
+- **Three fee columns are not interchangeable**: `fee_usd` is the builder's revenue, `trader_fee_usd` what traders paid in total, `builder_routed_deployer_fee_usd` the deployer's cut on builder-routed flow only. On `fills`, `fee` is in its own `fee_token`.
+- `stats.totals.builder_routed_share_pct` is the share of all fill notional carrying a builder code.
+- `profile` adds `by_symbol`, `by_dex`, `user_volume_distribution` (users split into volume deciles: separates "19k users" from "one whale plus a tail") and `lifetime`. In `users`, `closed_pnl_usd` (and `--sort pnl`) is the TRADERS' realized PnL, not the builder's.
+- `series` `users` is a distinct count per bucket and not additive across days; take a period total from `profile`. Builder history starts at different dates: compare `active_days` and the resolved `window` first.
+
+## Anti-patterns
+
+- Don't call a builder profitable or its users winners from `closed_pnl_usd`.
+- Don't add daily `users` together, or compare two windows of unequal `active_days`.
+
+## Pairs well with
+
+- `vike-hl-top-traders`, `vike-hl-trader-profile` (one wallet's routing)

package/skills/vike-hl-cohort-backtest/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: vike-hl-cohort-backtest
+description: Method for testing whether a Hyperliquid wallet cohort's positioning led or lagged price, with point-in-time labels and without look-ahead - which axes are honest, how to pull and align the hours, the seams and controls, how to report. Describes a method on this data; it does not claim a tradable edge. Use when the user asks "did whale / smart money positioning predict BTC" / "backtest the cohort signal" / "does the smart-minus-rekt spread lead price" / "lead or lag of Hyperliquid cohorts".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-hl-cohort-backtest
+
+Cohort positioning against price over history. A single `--hours` call returns `hours x rungs` rows (2160 hours of the 13-rung `pnl` axis is about 28,000 rows, 13 MB), so **write each pull to a file and analyse it with code; never print it into the conversation.** 1 credit per call.
+
+## Pull
+
+```bash
+vike-data hl cohort-metrics BTC --axis pnl --label-basis point_in_time --hours 2160 --json > btc_pnl_pit.json
+vike-data hl cohort-metrics BTC --axis size --hours 2160 --json > btc_size.json
+vike-data candles hl BTC --view export --interval 1h --start 2026-08-01T00:00:00Z --json > btc_1h.json   # up to 5000 bars a call
+```
+
+Rows: `ts` (hour, UTC), `cohort`, `total_position_value`, `total_position_value_long` (USD notional), `bias` (fraction -1..+1). Newest hour first; page older hours with `nextCursor` -> `--cursor`. Candles: `ts` is epoch ms, left-aligned, the window half-open `[start, end)`.
+
+Whole-venue alternative (all symbols summed): `vike-data hl segments --view history --cohort "3x smart" --axis pnl --hours 2160 --json` (axis `size` or `pnl`; hours before 2026-04-07 are never returned; page back with `--end` = the oldest `ts` minus 1 second). Position-level history: `hl market --view positions --symbol BTC --start ...` rows carry `label_causal`, the previous hour's label.
+
+## Which labels are honest
+
+| Axis / option | Look-ahead? |
+|---|---|
+| `pnl` with `--label-basis point_in_time` | No. Point-in-time history starts 2026-04-07 (earlier hours return nothing). |
+| `size`, `tier` | No by construction: account value or position size at that hour |
+| `pnl` default (`current`) | **Yes**: today's grading applied to old hours |
+| `pnl_abs` | **Yes** always: dollar bands of today's PnL |
+| `pnl_unrealized` | No, but it grades POSITIONING (who is currently onside), not skill, and turns over far faster than the realized ladder |
+| `--grading realized-pit` | A frozen control that stops growing: a recent window comes back short; `freshness.behind_hours` says by how much |
+
+`--opened-within` is refused with `point_in_time`, `realized-pit` and `pnl_unrealized`. With `point_in_time` the rows leave out `position_count*`, `total_unrealized_pnl` and `total_position_size*`: use only the notional columns and `bias`, and never read a missing value as 0. Read `label_computed` on every response: it names the source and the seam. **Label resolution changes at 2026-08-06**: daily labels before (constant across that day's 24 hours), hourly after. A turnover count or a difference taken across the seam shows an artefact that looks like a regime change; split the sample there or use `realized-pit` as the control.
+
+## Signal definitions
+
+- Group several rungs by summing notional: `bias_g = (2*sum(L) - sum(V)) / sum(V)` with `L = total_position_value_long`, `V = total_position_value`. Never average the biases.
+- Level (`bias_g`), change (`bias_g[t] - bias_g[t-k]`), or the spread between a top group (`3x smart`, `2x smart`, `smart`) and a bottom group (`rekt`, `2x rekt`, `3x rekt`). Leave `unknown` out.
+
+## Alignment and statistics
+
+1. The in-progress hour is never returned, so a row stamped `T` is only knowable once hour `T` has closed. Measure forward returns from the OPEN of candle `T+1h`, never from candle `T`. Check the alignment on your own sample before trusting a lag of one or two hours.
+2. Forward returns at several horizons (1h, 4h, 24h) and lead/lag correlations over lags in both directions. If the cohort moves AFTER the return, that is positioning chasing price, not a lead.
+3. Neighbouring hours overlap and positions are autocorrelated: report the number of independent observations, not the number of hours, and a confidence interval. Count the cohorts, lags and horizons you tried and correct for it.
+4. Split the sample (before / after 2026-08-06, or first half / second half) and say which half the result lives in.
+5. Add a placebo: the same test on the `size` axis, or on a shuffled cohort assignment.
+
+## What to report
+
+> On `<symbol>`, `<axis>` with point-in-time labels, `<start>` to `<end>` (`N` hours, about `M` independent): `<signal>` vs the `<h>`-hour forward return from the next candle's open: correlation `<r>` (CI `<lo, hi>`); first half `<r1>`, second half `<r2>`; placebo `<r0>`. Labels change resolution on 2026-08-06. This describes this sample; it is not an out-of-sample test or a trading rule, and costs, funding and slippage are not included.
+
+## Anti-patterns
+
+- Don't use the default `pnl` labels or `pnl_abs` for anything backtest-like.
+- Don't quote a hit rate without the sample size and the placebo; don't call a lag "alpha".
+- Don't extrapolate: the point-in-time history starts 2026-04-07, one regime.
+
+## Pairs well with
+
+- `vike-hl-cohort-positioning` for the current read, `vike-candles` for the price series, `vike-hl-asset-briefing` for context

package/skills/vike-hl-cohort-positioning/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: vike-hl-cohort-positioning
+description: Are whales, profitable wallets or losing wallets net long or short a Hyperliquid symbol right now - long/short notional per wallet cohort on the size and pnl ladders, the smart-money and whale indices, and the biggest individual positions, plus a live feed of the cohort lean. Use when the user asks "are whales long or short BTC" / "what are profitable Hyperliquid wallets doing on ETH" / "who is long SOL on Hyperliquid" / "Hyperliquid positioning" / "net long or short by wallet size".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-hl-cohort-positioning
+
+A current read of how each wallet cohort is positioned in ONE symbol. 1 credit per call, about 6. For history and anything backtest-like use `vike-hl-cohort-backtest`: this skill's `pnl` labels are today's.
+
+## Chain
+
+```bash
+vike-data hl segments --view cohorts --json                       # the exact cohort labels per ladder
+vike-data hl cohort-metrics BTC --axis size --hours 1 --json      # whales: one row per size rung
+vike-data hl cohort-metrics BTC --axis pnl  --hours 1 --json      # profitable vs losing wallets (today's grading)
+vike-data hl market --view indices --symbol BTC --hours 24 --json # series: smi, wsi per hour; latest: also smart_bias, whale_bias
+vike-data hl segments --view summary --axis pnl --cohort smart --json     # that cohort across ALL symbols
+vike-data hl market --view positions --symbol BTC --sort size --limit 20 --json   # the biggest open positions, largest first
+```
+
+`--hours 1..24` is a current read; the newest SETTLED hour comes back (the hour in progress never does). Symbols are upper case; a HIP-3 market is `dex:TICKER`. Read `freshness`: `stale: true` means do not call it "now" (`behind_hours` says how far behind).
+
+## Units and the ladders
+
+- `bias` = (long - short) / (long + short) of NOTIONAL, a **fraction** from -1 (all short) to +1 (all long). Long share = (1 + bias) / 2. `total_position_value` and `total_position_value_long` are USD; `position_count` counts positions.
+- **Several rungs as one group: sum the notional, never average the biases.** `bias_group = (2 * sum(total_position_value_long) - sum(total_position_value)) / sum(total_position_value)`.
+- `size` ladder = account value: `shrimp` from $0, `fish` $10k, `dolphin` $50k, `shark` $250k, `whale` $1M, `2x whale` $2.5M, `3x whale` $5M, `4x whale` $10M and up. `pnl` ladder = percentile of cumulative realized PnL with at least 10 closed trades, from `3x smart` (top) through `winner` / `loser` to `3x rekt`; `unknown` = too few trades. `hl segments --view segments` gives each rung's bounds.
+- The indices are ratios from -1 to +1: `smi` = long share of the smart cohorts minus that of the rekt cohorts, `wsi` = long share of whales minus shrimp, `smart_bias` / `whale_bias` = (long - short) / (long + short) of those groups. `hl market --view indices` returns `series` (settled hours, `smi` and `wsi` only, pnl rungs graded as of their hour) and `latest` (the newest snapshot, today's grading, with `smart_bias` and `whale_bias` too). `smi_wsi_gap` exists only on the `hl.indices` stream and in `hl_cohort_bias` alerts.
+
+## Reading
+
+- Check `position_count` and the rung's notional before saying a cohort "is short": 20 wallets, or one wallet, can set a rung's bias. Compare rungs, not just totals: whales net short while `smart` is net long is a disagreement worth stating as such.
+- `--opened-within 24h|7d|30d` (on `cohort-metrics` and `segments summary`) restricts to recently opened positions: how much of the lean is new.
+- `hl market --view positions --sort size` needs `--symbol` and at most `--limit 500`, and takes no cursor; each row has `size_usd`, `leverage`, `liquidation_price`, `unrealized_pnl`, `opened_at` and the wallet's `account_value`. Without `--sort size` rows come in key order, not by size. Never run `positions` without `--symbol` or `--wallet`.
+
+## Live
+
+```bash
+vike-data stream hl-cohorts --channel hl.cohort_bias --filter coin=BTC --filter axis=pnl     # every cohort's long/short, each position capture (~12 min)
+vike-data stream hl-cohorts --channel hl.indices --filter coin=BTC,ETH --filter index=smi,wsi   # only when an index crosses -0.10 / +0.10
+```
+
+`hl.cohort_bias` covers the 50 coins with the most open value; a `cohort` belongs to one axis (`3x smart` with `axis=size` matches nothing). For a stored rule: `vike-data alerts create --type hl_cohort_bias --index smi ...` (see `vike-alerts-setup`).
+
+## Answer template
+
+> BTC on Hyperliquid, hour `<ts>` UTC (`freshness.stale: false`): whales (`4x`..`whale`) are `<bias_group>` (`$L` long / `$S` short across `N` positions); `smart` wallets are `<bias>`; `rekt` wallets `<bias>`; `smi` `<v>`. Positioning is notional-weighted, today's cohort labels, Hyperliquid only: a position can be a hedge held elsewhere.
+
+## Anti-patterns
+
+- Don't turn a lean into a price forecast, and don't say "smart money is short" when the group is one rung of 20 positions.
+- Don't use these default labels on history: the `pnl` ladder is graded today (look-ahead).
+- Don't write `bias` or an index as a percent: they are fractions.
+
+## Pairs well with
+
+- `vike-hl-asset-briefing` (adds funding, OI, liquidations), `vike-hl-cohort-backtest` (history), `vike-hl-trader-profile` (one wallet from the positions list)

package/skills/vike-hl-liquidation-radar/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: vike-hl-liquidation-radar
+description: Where Hyperliquid liquidations are likely - which liquid symbols have the most open interest near liquidation, where one symbol's liquidation clusters sit around the mark, which liquidations just happened, and a live feed of positions entering the liquidation zone and of liquidations as they print. Use when the user asks "which coins are closest to a liquidation cascade" / "where are ETH liquidations clustered" / "liquidation heatmap" / "who just got liquidated on Hyperliquid" / "alert me to big liquidations".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-hl-liquidation-radar
+
+Three reads of the same idea and a live feed, 1 credit per call. Risk and the heatmap come from 5-minute position snapshots, so they are inferred; the liquidation events are read from the liquidated accounts' own fills since 2026-08-03 (inferred from snapshots before).
+
+## Chain
+
+```bash
+vike-data hl liquidations --view risk --min-value-usd 50000000 --json       # symbols with $50M+ open, ranked by percent_risk
+vike-data hl liquidations --view heatmap --symbol ETH --bins 20 --json      # liquidation value per price bin
+vike-data hl liquidations --view fills --symbol ETH --direction long --limit 50 --json   # recent long liquidations
+vike-data candles hl ETH --interval 1h --limit 48 --json                    # distance from the mark to the clusters
+```
+
+## Reading
+
+- **`risk`**: rows `symbol`, `total_value_usd`, `risk_value_usd`, `percent_risk` (a **fraction**, 0.234 = 23.4%), `positions_count`, `at_risk_count`. A position is at risk when it sits within half of its liquidation buffer. The ranking is by `percent_risk`, so without `--min-value-usd` thin HIP-3 and micro-cap markets lead. Add `--axis size|pnl|pnl_abs --cohort <label>` to ask the same of one cohort.
+- **`heatmap`** (`--symbol` required, `--bins` 5-500): bins are equal-width over +-50% of `mark_price`, each with `liquidation_value_usd`, `positions_count`, `long_value_usd`, `short_value_usd`, `most_impacted_cohort`. **Long liquidations sit below the mark** (price falling), shorts above. `coverage` says what the map leaves out (positions beyond +-50% and those with no liquidation price), so a cluster is a floor.
+- **`fills`**: `--direction` is the side of the position that was CLOSED (`long` = longs liquidated = price falling). `--wallet <addr>` asks whether one wallet was liquidated. Most rows are small: sort by size before quoting.
+- Liquidation prices move with margin, price and funding; a cluster is a snapshot, not a level that will be hit.
+
+## Live
+
+```bash
+vike-data stream hl --channel hl.liq_risk hl.liquidations --filter coin=BTC,ETH,HYPE --filter min_usd=1000000
+```
+
+- **`hl.liq_risk`**: a position of $100,000 or more announced once as its `liq_ratio` reaches 0.80 (0 = at entry, 1 = at the liquidation price), not again until it drops below 0.70 or closes. It comes with each position capture, about every 12 minutes. The first capture after the channel starts sends every position already in the zone with `prev: null` (about 300 on 2026-11-02); after that `prev: "out"` = just entered. `data` has `direction`, `liq_ratio`, `mark_price`, `entry_price`, `liquidation_price`, `size_usd`, `leverage`.
+- **`hl.liquidations`**: each liquidation from the account's own fill, typically within a minute or two, `data.direction` the closed side, `size_usd`, `mark_price`; no size floor of its own.
+- `min_usd` is the position size on `hl.liq_risk` and the liquidation size on `hl.liquidations`. A stored rule for one wallet: `vike-data alerts create --type hl_liq_proximity --wallet 0x... ...` (see `vike-alerts-setup`).
+
+## Answer template
+
+> Closest to a cascade among symbols with at least $50M open: `<symbol>` `<percent_risk>` (`$risk` of `$total`). `<ETH>`: `$V` of long notional liquidates between `<p1>` and `<p2>` (`<x%>` below the mark), `$W` of shorts above `<p3>`; the map covers `<c>` of open notional. Last hour: `<n>` long liquidations, largest `$M`.
+
+## Anti-patterns
+
+- Don't rank micro-cap or HIP-3 markets next to BTC without the notional floor.
+- Don't write `percent_risk` as a percent without multiplying, or treat the heatmap as complete.
+- Don't predict a cascade: say where open interest is exposed.
+
+## Pairs well with
+
+- `vike-hl-asset-briefing`, `vike-hl-cohort-positioning` (who holds the exposed side), `vike-candles`, `vike-stream`

package/skills/vike-hl-position-match/SKILL.md

@@ -17,7 +17,7 @@ vike-data perp find-position
   --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
+  [--limit N]          # max matches, default 50, max 500
   [--json]
 ```
 
@@ -78,9 +78,10 @@ The response includes `tolerance_used` so the caller knows which band matched (`
 
 - 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-data perp top-traders` for leaderboard context (see `vike-hl-top-traders` for what it can and cannot say about one address).
+- Don't infer trader skill from a single share-card match. Profile the wallet with `vike-hl-trader-profile` (`vike-data hl wallet <address>`).
 
 ## Pairs well with
 
-- `vike-hl-top-traders` — check if the matched wallet is on a leaderboard. (`vike-data wallet summary` has no Hyperliquid data: it shows on-chain transfer activity on one chain only.)
+- `vike-hl-trader-profile` — track record, equity, open positions, funding and deposits of the matched wallet.
+- `vike-hl-top-traders` — where the wallet ranks. (`vike-data wallet summary` has no Hyperliquid data: it shows on-chain transfer activity on one chain only.)
 - `vike-wallet-label-provenance` — find out if the wallet is a known CEX/fund/MM rather than a retail trader.

package/skills/vike-hl-top-traders/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vike-hl-top-traders
-description: Rank top Hyperliquid perp traders by PnL / ROI / win rate / volume / trade count / drawdown across a window, and check whether one HL address is on that leaderboard. Use when the user asks "top HL traders" / "best Hyperliquid wallets" / "HL leaderboard" / "is this trader any good" / "profile this address" / "what's this wallet's HL track record".
+description: Rank Hyperliquid perp traders by PnL / ROI / win rate / volume / trade count / drawdown over a window - the quick top list, or the full leaderboard with Calmar, profit factor, streaks, cohort filters, paging and PnL net of deposits - and see where one address ranks. Use when the user asks "top HL traders" / "best Hyperliquid wallets" / "HL leaderboard" / "who made the most on Hyperliquid this week" / "top traders net of deposits".
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -16,7 +16,7 @@ vike-data perp top-traders
   [--min-trades N]       # default 3; 0-2 are treated as 3
   [--min-win-rate P]     # percent, 0-100
   [--min-volume USD]
-  [--size N]             # default 10, max 20
+  [--size N]             # default 20, max 100
   [--json]
 ```
 
@@ -36,21 +36,35 @@ An object `{ "traders": [...], "total": N }`; each trader:
 
 `address`, `total_realized_pnl` (USD), `roi_pct`, `win_rate_pct`, `long_win_rate_pct`, `short_win_rate_pct`, `win_count`, `loss_count`, `trade_count`, `total_volume` (USD), `long_pnl`, `short_pnl`, `max_drawdown_pct`, `account_value` (USD), `avg_leverage`.
 
-All `*_pct` fields are percents: `12.5` means 12.5%. (Before 2026-10-19 `roi_pct` and `max_drawdown_pct` came back 100× too large; a transcript showing a 1,750% ROI is from that period.) `avg_leverage` is not populated (reads 0): ignore it. There is no `pnl_usd` and no `max_drawdown_usd`.
+All `*_pct` fields are percents: `12.5` means 12.5%. (Before 2026-10-19 `roi_pct` and `max_drawdown_pct` came back 100× too large; a transcript showing a 1,750% ROI is from that period.) `avg_leverage` is the notional-weighted leverage of the open positions (real since 2026-10-25); 0 = no open position. There is no `pnl_usd` and no `max_drawdown_usd`.
 
 ## Reading
 
 - **`roi_pct` is realized only.** It is the window's realized PnL divided by the wallet's CURRENT account value. Open positions are not counted, and a wallet that has since withdrawn most of its equity looks better than it was (and a recent deposit makes it look worse).
-- **`max_drawdown_pct` is account-level and all-time**, built from the account's hourly equity history. It does not change with `--window`.
+- **`max_drawdown_pct` is account-level and all-time** here, a percent from 0 to 100 built from the account's equity history; `null` = too little equity history to say. It does not change with `--window`.
 - **Windows are UTC days:** `1d`, `7d`, `30d` mean today plus the previous 1, 7 or 30 days; `all` is the last 365 days.
-- **`trade_count` counts completed trades only**, filed under the UTC day the position opened. A trade still open, or opened before the window and closed inside it, is not counted, so a wallet's count here differs from a per-wallet trade summary (which counts both).
+- **`trade_count` counts the trades CLOSED in the window** (filed under the UTC day they closed, whenever they opened). A trade still open is not counted, so a wallet's count here differs from a per-wallet trade summary (which counts open trades too).
 - A wallet with 90% win rate on 4 trades is statistical noise. Min trades 10–20 for any "skill" claim.
 - Top by PnL ≠ top by ROI. Whales win big in $ but small in % terms; ROI sort surfaces smaller-account discretionary skill.
 - The leaderboard rewards survivors: wallets that blew up don't appear, so the PnL distribution is right-skewed.
 
+## `hl leaderboard`: the full board
+
+```bash
+vike-data hl leaderboard
+  [--view ranking|flow_adjusted] [--window 1d|7d|30d|all]
+  [--sort pnl|realized_pnl|roi|volume|trades|win_rate|profit_factor|expectancy|calmar|max_drawdown|current_drawdown|fees|win_streak|...]   # an unknown key is refused
+  [--order asc|desc] [--cohort <label> --axis size|pnl|pnl_abs]
+  [--min-trades N] [--min-win-rate F] [--min-volume USD]   # win rate is a FRACTION here: 0.6 = 60%
+  [--limit N]            # default 25, max 500; page with nextCursor -> --cursor (resend the same filters)
+  [--json]
+```
+
+Rows are keyed `wallet` (not `address`) with `account_value`, `total_realized_pnl`, `pnl_pct`, `roi`, `win_rate` (a fraction), `profit_factor`, `expectancy`, `max_drawdown_pct`, `current_drawdown_pct`, `calmar_ratio`, streaks, `size_cohort`, `pnl_cohort`. Prefer `pnl_pct` to `roi` (`roi` is unguarded on a near-empty account). Here the drawdown fields are computed over the window's equity (0-100; `null` = too little equity history), unlike `perp top-traders`. `--view flow_adjusted` ranks fills-derived trading PnL, which excludes deposits, and takes only `--window`, `--min-trades`, `--limit`, `--cursor`; when its `flow_unbalanced` is true the flow figures are unreliable.
+
 ## Is this specific address any good?
 
-There is **no per-wallet Hyperliquid command or tool** yet, and `top-traders` cannot filter by address. The only check is to scan the leaderboard and look for the address:
+Profile the wallet itself: `vike-hl-trader-profile` (`vike-data hl wallet <address>`). To see where it ranks, scan a leaderboard for it:
 
 ```bash
 vike-data perp top-traders --window 30d --sort pnl --size 20 --json
@@ -60,9 +74,8 @@ vike-data perp top-traders --window 30d --sort win_rate --min-trades 10 --size 2
 ```
 
 - **Found** → report that row for that window and sort (all columns above). That is the whole profile you can give.
-- **Not found** → say "not in the top 20 for this window and sort". Only the top 20 of thousands of wallets ever shows, so absence says nothing about quality.
+- **Not found** → say "not in the top N for this window and sort". Absence says nothing about quality; `hl leaderboard --limit 500` pages deeper.
 - `vike-data wallet summary` has **no Hyperliquid data** (it reads on-chain transfers on one chain): don't present it as the HL profile. `vike-data labels <addr>` shows whether the address is a known entity.
-- The REST API has per-wallet Hyperliquid routes (`/v1/hyperliquid/wallets/{address}`, `.../trades/summary`), but no CLI command or MCP tool exposes them yet. Say so if the user needs fills, funding or per-trade history.
 
 Classification of a found wallet:
 
@@ -82,6 +95,6 @@ Classification of a found wallet:
 
 ## Pairs well with
 
-- `vike-hl-position-match` to find the wallet behind a share card first
+- `vike-hl-trader-profile` for one wallet's full record; `vike-hl-position-match` to find the wallet behind a share card first
 - `vike-perp-funding` to see whether the leaders are positioned against funding
 - `vike-candles` for the price action behind a period of PnL