@vike-io/cli 0.15.0 → 0.16.1

package/skills/vike-pm-market-diligence/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: vike-pm-market-diligence
+description: Full due diligence on one Polymarket market - finding it, spread and depth from the order book, recorded activity, large recent prints, who traded and who holds each side, on-chain resolution status and smart-money context, then a live feed of its trades, position changes and price moves. Handles the condition id versus token id split. Use when the user asks "is this Polymarket market liquid" / "who is on each side of this market" / "has this market resolved on-chain" / "check this prediction market before I trade" / "diligence on this Polymarket market".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-pm-market-diligence
+
+About 18 credits for every step with two outcomes and three holders. Run only the sections the question needs.
+
+**Two ids, never interchangeable.** A market has one `condition_id` (`0x` + 64 hex) and one OUTCOME TOKEN id per outcome (a long decimal number). `polymarket market`, `market-trades` and `settlement` take the condition id; `orderbook`, `market-stats`, `tape` and `candles polymarket` take a token id and answer nothing useful for a condition id. Token ids come from `clob_token_ids` in `polymarket market` (same order as its `outcomes`) or `outcomes[].token_id` in `polymarket markets`. **Map outcomes to ids by their label** everywhere else: `polymarket markets` has listed `No` before `Yes` and `Down` before `Up`.
+
+## Chain
+
+```bash
+vike-data search "fed rate cut december" --json                        # 1  `markets` section; a polymarket.com link works too
+vike-data polymarket markets --view search --query fed-rate-cut --json # 1  condition_id, token_ids, neg_risk, active/closed by slug
+CID=0xbac62ac581be240787167755692fda4e07b3f42fb24f61a5d73c06731f8ed158
+vike-data polymarket market $CID --json                                # 2  detail: outcomes, holders, last 100 trades, stats
+vike-data polymarket orderbook <token_id> --depth 5 --json             # 1 per outcome: spread and depth
+vike-data polymarket market-stats <token_id> --json                    # 1  what is recorded for this token
+vike-data polymarket tape --token-id <token_id> --from-ms <now-1h> --to-ms <now> --event-type trade --limit 1000 --json   # 1  large prints
+vike-data polymarket market-trades $CID --from-ms <now-24h> --limit 500 --json   # 1  trades WITH wallets, newest first
+vike-data polymarket settlement $CID --json                            # 1  on-chain resolution
+vike-data polymarket wallet <proxy_wallet> --json                      # 2 each: the top 3 holders
+vike-data polymarket smart-money --mode flows --hours 24 --json        # 2  is this market in the cohort's flows
+```
+
+## Reading
+
+- **`market`**: `question`, `end_date`, `active`, `closed`, `accepting_orders`, `resolution`, `volume_24h`, `liquidity`, `outcomes`, `clob_token_ids`, hourly `yes_series` / `no_series` (first and second outcome, named so even on Up/Down markets), `yes_holders` / `no_holders` (30 each: `proxy_wallet`, `net_shares`, `cost_basis`, `volume_usd`, `trades`), the latest 100 `trades` with wallets, and `stats`. No live quote, no cohort block, no fee rate.
+- **Resolved or not**: an `end_date` in the past only means the end has passed: a market can stay `active` with `resolution: null` and `settlement` = `[]` for weeks. `settlement` returns one row (`winning_index`, `winning_outcome`, `winning_token_id`, `payouts`, `resolved_block`, `resolved_ts_ms`) once the chain resolved it; `[]` means not resolved on chain, not that the market is open (a voided market has none). Take the resolution time from `resolved_ts_ms`, not `resolution.resolved_at`.
+- **`orderbook`** rows: `as_of_ts` (ms, the snapshot actually used: can be days old for a quiet or finished market), `side`, `level` (1 = best), `price` (a probability), `size` (shares), asks before bids. Keep one row per (`side`, `level`), take level 1 on each side for the spread, sum sizes within 5 cents for depth. A side can be missing, so no spread exists.
+- **`market-stats`**: `trade_volume` is in SHARES, not dollars. `total_events: 0` means never recorded: re-check the token id before calling a market dead.
+- **`tape`**: `ts` ms, `price` a probability, `size` shares, `side`. The window is at most 24 hours and `--to-ms` is exclusive; page while `has_more` with `--cursor`. It holds NO wallets.
+- **`market-trades`**: wallets per fill. One row is one ORDER's fill, not one match: a match is the resting `maker` rows plus one `taker` row of their summed size, so never add `size * price` over both roles. `proxy_wallet` is Polymarket's proxy, not necessarily the person's own address.
+- **Holders**: `polymarket wallet <proxy_wallet>` gives `realized_pnl_usd`, `resolved_markets`, volume-weighted `hit_rate` (a fraction) and `hit_rate_ci`, plus `correlated` wallets. Quote `hit_rate` only with 10 or more `resolved_markets`. A holder's `cost_basis` against the current mid says whether they are in profit on paper.
+- **Smart money** (wallets with $1k+ realized PnL on 5+ resolved markets): look for the `condition_id` in the `flows` / `mispricings` lists. Absence from a top list is not evidence.
+
+## Watch it live
+
+```bash
+vike-data stream polymarket --channel pm.trades pm.positions pm.price_moves pm.resolutions --filter market=$CID
+```
+
+`--filter` applies to every `--channel` of the command, and `market` is the only key all four take: a `role` filter here is refused (`bad_subscription`, exit 1). To count each match once, keep the taker rows of `pm.trades` with jq: `... | jq -c 'select(.type=="event" and .event.source=="pm.trades" and .event.data.role=="taker")'`. Don't start a second `stream polymarket` for it: one key holds one connection per path, and the second replaces the first (`4410`). `pm.trades` carries the trader's wallet; `pm.positions` is each of those trades again as what it did to the wallet's position (`data.action` `open`, `increase`, `reduce`, `close` or `flip`, `shares_before`, `shares`, `avg_price`: who is entering or leaving this market), so drop `pm.trades` from the list if you only want position changes; `pm.price_moves` is a move of 0.05 or more within five minutes; `pm.resolutions` the on-chain resolution. `shares` count trades only: shares a wallet got from a split, merge or transfer are not on the tape, so a wallet that sells them shows a negative `shares`.
+
+## Answer template
+
+> `<question>` ends `<end_date>`; `<open | past end, unresolved | resolved on-chain to X at T>`. `<Yes/Up>` mid `<m>`; spread `<s>`, depth to 5c `<n>` shares each side (book as of `<as_of_ts>`); 24h volume `$V`, liquidity `$L`. Largest prints last hour: `<size @ price>`. Top holders: `<n>` wallets hold `<outcome>`, cost basis `<c>`; `<k>` have 10+ resolved markets (hit rates `<...>`). Cohort: `<in flows | not in the top list>`. Quotes are probabilities, not dollars.
+
+## Anti-patterns
+
+- Don't pass a condition id to `orderbook`, `market-stats` or `tape`, and don't call a market "dead" on zero stats.
+- Don't say "insider" or "manipulated" from holders and flows: they show who is on a side, not why.
+- Don't read the first row of `outcomes[]` as Yes.
+
+## Pairs well with
+
+- `vike-polymarket-market-detail`, `vike-polymarket-trader`, `vike-polymarket-smart-money`, `vike-candles` (probability history), `vike-pm-l2-archive` (bulk history)

package/skills/vike-polymarket-market-detail/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vike-polymarket-market-detail
-description: Deep-dive on a single Polymarket market — question, outcomes, current quotes, 24h volume, smart-money flows, top wallets active in it, resolution status. Use after vike-polymarket-markets when the user asks about a specific market.
+description: Read one Polymarket market by condition_id - question, outcomes and their token ids, resolution, an hourly probability series, the top 30 holders of each side, the latest 100 trades with wallets, and trade statistics. Use after vike-polymarket-markets when the user asks about one specific market, its holders or what its token ids are.
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -9,35 +9,40 @@ allowed-tools: Bash(vike-data:*)
 ## Command
 
 ```bash
-vike-data polymarket market <condition_id> [--json]
+vike-data polymarket market <condition_id> [--json]     # 2 credits
 ```
 
-`condition_id` is a hex string (you'll have it from `vike-data polymarket markets` output).
+`condition_id` is `0x` + 64 hex digits, from `vike-data polymarket markets` (or `vike-data search <words or polymarket.com link>`). It is NOT a token id.
 
 ## Example
 
 ```bash
 vike-data polymarket markets --category Crypto --limit 5 --json
 #   → pick a condition_id from the output, then:
-vike-data polymarket market 0x1234abcd...
+vike-data polymarket market 0xbac62ac581be240787167755692fda4e07b3f42fb24f61a5d73c06731f8ed158 --json
 ```
 
 ## What it returns
 
-- Market metadata: question, slug, category, end_date, fee_rate_bps
-- Current quotes for both outcomes (Yes / No mid / bid / ask)
-- 24h volume + liquidity
-- Smart-money cohort activity on this specific market (recent net flow)
-- Top wallets (by trade count or volume) active here
-- Resolution status (resolved / open / awaiting resolution)
+- Metadata: `question`, `slug`, `category` (can be an empty string), `end_date`, `active`, `closed`, `accepting_orders`, `volume_24h`, total volume, `liquidity`.
+- `outcomes` (labels) and `clob_token_ids`, in the same order: these token ids feed `candles polymarket`, `polymarket orderbook`, `market-stats` and `tape`. Match outcomes to ids by position HERE and by label everywhere else: `polymarket markets` can list the outcomes in another order.
+- `resolution`: `null` while unresolved. Its `resolved_at` can repeat `end_date`; the on-chain time is `resolved_ts_ms` in `vike-data polymarket settlement <condition_id>`.
+- `yes_series` / `no_series`: hourly `mid` for the first and second outcome (named yes/no even on Up/Down or team markets).
+- `yes_holders` / `no_holders`: up to 30 wallets per side with `proxy_wallet`, `net_shares`, `cost_basis`, `volume_usd`, `trades`.
+- `trades`: the latest 100, WITH `proxy_wallet`, `outcome`, `side`, `size` (shares), `price` (probability), `usd`.
+- `stats`: trade and wallet counts, volume, first and last seen.
+
+There is no live quote block (take bid/ask/mid from `polymarket markets` or `polymarket orderbook`), no smart-money block (use `polymarket smart-money`) and no fee rate.
 
 ## Anti-patterns
 
-- Don't claim a market is "manipulated" from cohort flow alone. High cohort buy ≠ insider info — it might just be popular among the cohort.
-- Resolution-pending markets can show stale mids. Cross-check with `last_traded` timestamp.
+- Don't claim a market is "manipulated" or has "insiders" from holders or trades alone; they show who is on a side, not why.
+- `end_date` passed is not resolved: a market can stay `active` with `resolution: null`. Confirm with `polymarket settlement`.
+- Only the latest 100 trades are returned: for a window use `polymarket market-trades` (with wallets) or `polymarket tape` (no wallets).
 
 ## Pairs well with
 
-- `vike-polymarket-trader` — profile any interesting wallet you find in the top-wallets list
-- `vike-polymarket-smart-money` (`--mode mispricings`) — markets where cohort bought below current mid
-- `vike-candles` — probability history: the market's `clob_token_ids` are the `token_id` values
+- `vike-pm-market-diligence` — the full playbook (spread, depth, large prints, settlement, holders' records)
+- `vike-polymarket-trader` — profile any holder's `proxy_wallet`
+- `vike-polymarket-smart-money` (`--mode mispricings`) — markets where the cohort bought below the current mid
+- `vike-candles` — probability history for a token id

package/skills/vike-polymarket-markets/SKILL.md

@@ -28,7 +28,7 @@ One row per market, ranked by **24h volume only** (there is no liquidity or vola
 
 `condition_id`, `slug`, `question`, `end_date`, `ended` (true once `end_date` has passed), `volume_24h` (USD), `liquidity`, `latest_ts`, and `outcomes`: a list with one entry per outcome leg, each with `token_id`, `outcome` (Yes / No or the leg's name), `mid`, `bid`, `ask`, `snap_vol_24h`.
 
-The `token_id` of each leg is what `vike-data candles polymarket <token_id>` needs, so candles need no extra detail call.
+The `token_id` of each leg is what `vike-data candles polymarket <token_id>`, `polymarket orderbook`, `market-stats` and `tape --token-id` need, so none of them needs a detail call. Read the leg by its `outcome` label, not by position: rows have listed `No` before `Yes` and `Down` before `Up`. The `condition_id` is the other id (for `polymarket market`, `market-trades` and `settlement`); never pass it where a token id is wanted.
 
 ## Reading the data
 
@@ -45,5 +45,6 @@ The `token_id` of each leg is what `vike-data candles polymarket <token_id>` nee
 ## Pairs well with
 
 - `vike-polymarket-market-detail` — deep-dive on one market once you have its condition_id
+- `vike-pm-market-diligence` — spread, depth, large prints, holders and on-chain resolution of one market
 - `vike-polymarket-smart-money` — which markets cohort wallets are buying, and a full market overview
 - `vike-candles` — probability history for a leg's `token_id`

package/skills/vike-polymarket-smart-money/SKILL.md

@@ -69,6 +69,14 @@ Trim aggressively if the user asked a narrower question. About 5 credits for the
 - **Short-dated markets dominate.** Five-minute "up or down" markets resolve fast and show huge deltas: pass `--category` (or skip those slugs) when you want slower markets. Very short `--hours` windows (an hour or two) are noisy for the mispricing read.
 - The category also scopes the cohort. An unknown category spelling returns an empty list, not an error.
 
+## Live
+
+```bash
+vike-data stream polymarket --channel pm.positions --filter market=<condition_id> --filter min_usd=1000   # who opens, adds to, reduces or closes in a flagged market
+```
+
+`min_usd` is the size of the trade. Each event names the wallet (`subject.wallet`), `data.action`, `shares` and `avg_price`, and carries that wallet's `labels.pnl_tier` and `volume_tier` (its Polymarket tier, not membership of the cohort above). To follow chosen wallets instead, `--filter wallet=0x...` (see `vike-polymarket-trader`). Unfiltered it is 60,000 to 150,000 events an hour (measured 2026-11-02): always filter by `market` or `wallet`. Fields, timing and the one-connection rule: `vike-stream`.
+
 ## Anti-patterns
 
 - Don't treat "smart-money cohort" as omniscient. They're filtered for past performance — survivorship bias applies, especially in fast-moving political markets.
@@ -80,4 +88,5 @@ Trim aggressively if the user asked a narrower question. About 5 credits for the
 
 - `vike-polymarket-markets` — the trending list without the cohort view
 - `vike-polymarket-market-detail` — drill into a flagged market
+- `vike-pm-market-diligence` — spread, depth, holders and resolution of a flagged market
 - `vike-polymarket-trader` — profile the top wallets active in flagged markets

package/skills/vike-polymarket-trader/SKILL.md

@@ -45,6 +45,14 @@ There is no `hit_rate_pct`, `volume_<window>_usd` or `trades_<window>` field.
 | Negative PnL with high volume | **Volume trader / MM-style** — pays the spread |
 | One category dominates >80% of `category_breakdown` | **Specialist** — only trust their reads in that category |
 
+## Watch it live
+
+```bash
+vike-data stream polymarket --channel pm.positions --filter wallet=<address> --filter action=open,close
+```
+
+Each trade of the wallet as what it did to its position in that outcome: `data.action` (`open`, `increase`, `reduce`, `close`, `flip`), `shares_before`, `shares`, `avg_price` (its average BUY price in that outcome after the trade), and the market in `subject` (`title`, `outcome`, `condition_id`). Drop `--filter action=...` for every change; `wallet` takes up to 1,000 comma-separated addresses. It runs about four minutes behind the chain and the first events come one to three minutes after you start. `shares` count trades only (shares from a split, merge or transfer are not on the tape, so a wallet that sells them goes negative). One key holds one `stream polymarket` connection: see `vike-stream`.
+
 ## Anti-patterns
 
 - Don't claim "this trader is good at predictions" from <10 resolved markets. Below that, `hit_rate` is noise.
@@ -54,5 +62,6 @@ There is no `hit_rate_pct`, `volume_<window>_usd` or `trades_<window>` field.
 
 ## Pairs well with
 
-- `vike-polymarket-market-detail` — see which markets they're currently in
+- `vike-polymarket-market-detail` — see which markets they're currently in (its holder lists give the `proxy_wallet` addresses to profile here)
+- `vike-pm-market-diligence` — the market-level playbook that ends with this wallet check
 - `vike-polymarket-smart-money` — whether the profitable-wallet cohort is moving in the same markets

package/skills/vike-smart-money-discovery/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: Bash(vike-data:*)
 
 # vike-smart-money-discovery
 
-Composite playbook built on `token screener --smart-money-only`. Smart money here means the cohort behind the screener's `smart_inflow` and `--smart-money-only`, which exist for **Ethereum only** (a 400 on bsc and base).
+Composite playbook built on `token screener --smart-money-only`. Smart money here means the cohort behind the screener's `smart_inflow` and `--smart-money-only`, which exist for **Ethereum only** (a 400 on bsc, base and hyperevm).
 
 **What this can and cannot say.** It can say which tokens the cohort is flowing into and how much, and who the biggest net buyers of a token are. It cannot list which of those buyers belong to the cohort: no tool returns cohort membership. State that limit in the answer.
 
@@ -25,10 +25,10 @@ vike-data token screener --chain ethereum --window 7d --sort smart_inflow --smar
 ### B. Who is accumulating it?
 
 ```bash
-vike-data token transfers <addr> --tab bought --period 7d --json
+vike-data token transfers <addr> --tab bought --period 7d --hide-contracts --json
 ```
 
-The list is the **top 10 by volume**, not the cohort. **Rank on `net_tokens`**, not `bought`: `bought` counts every inbound transfer, flash-loan and router round trips included. Keep rows with a clearly positive `net_tokens`; drop rows where `net_tokens` is near zero.
+The list is the **top 10 net buyers by net USD**, not the cohort (a buyer's `net_usd` is negative; `net_tokens` is the net in whole tokens). `--hide-contracts` leaves out the pools and routers we know of; a row can still be an exchange or an unmarked contract.
 
 ### C. Strip the intermediaries
 
@@ -63,6 +63,7 @@ Screener (3 credits) + `token transfers` (2) + `wallet batch` (2) + up to 5 × `
 
 ## Pairs well with
 
+- `vike-token-smart-money-trend` for whether the cohort is entering, holding or exiting ONE token over 24h / 7d / 30d / 90d
 - `vike-token-screener` for the filters and the column meanings
 - `vike-token-research` for the price/flow context
 - `vike-perp-funding` if the token has a perp listing (positioning bias)

package/skills/vike-stream/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vike-stream
-description: Live events over WebSocket with `vike-data stream` - Hyperliquid fills, liquidations, positions, liquidation risk, order walls, closed candles, TWAPs, ledger, leverage changes and funding; HL cohort flow, indices and cohort bias; on-chain transfers on eth, bsc, base and hyperevm; Polymarket trades, resolutions, price moves and new markets - printed as NDJSON, resumed by cursor after any drop. Use when the user wants to "watch", "tail", "follow live", "stream" or "be notified as it happens" rather than query history.
+description: Live events over WebSocket with `vike-data stream` - Hyperliquid fills, liquidations, positions (with leverage and liquidation price), top-10 positions per coin, closed trades, liquidation risk, order walls, closed candles, TWAPs, ledger, leverage changes and funding; HL cohort flow, indices, cohort bias and cohort leverage; on-chain transfers on eth, bsc, base and hyperevm; Polymarket trades, wallet position changes, resolutions, price moves and new markets - printed as NDJSON, resumed by cursor after any drop. Use when the user wants to "watch", "tail", "follow live", "stream" or "be notified as it happens" rather than query history.
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -16,10 +16,10 @@ server sent them. Status lines (subscribed, reconnecting, errors) go to stderr.
 
 | Path | Channels |
 |---|---|
-| `hl` | `hl.fills`, `hl.liquidations`, `hl.positions`, `hl.liq_risk`, `hl.order_walls`, `hl.candles`, `hl.twaps`, `hl.ledger`, `hl.leverage`, `hl.funding` |
-| `hl-cohorts` | `hl.cohort_flow`, `hl.indices`, `hl.cohort_bias` |
+| `hl` | `hl.fills`, `hl.liquidations`, `hl.positions`, `hl.liq_risk`, `hl.order_walls`, `hl.candles`, `hl.twaps`, `hl.ledger`, `hl.leverage`, `hl.funding`, `hl.top_positions`, `hl.closed_trades` |
+| `hl-cohorts` | `hl.cohort_flow`, `hl.indices`, `hl.cohort_bias`, `hl.cohort_leverage` |
 | `onchain` | `chain.transfers` |
-| `polymarket` | `pm.trades`, `pm.resolutions`, `pm.price_moves`, `pm.new_markets` |
+| `polymarket` | `pm.trades`, `pm.positions`, `pm.resolutions`, `pm.price_moves`, `pm.new_markets` |
 
 The server decides what each path serves: `vike-data stream info` prints the current channels and filter keys, and a
 channel the path does not serve is refused with `unknown_channel` and the list. The CLI has no channel list of its own.
@@ -27,6 +27,19 @@ channel the path does not serve is refused with `unknown_channel` and the list.
 `hl.candles` is the Hyperliquid candle stream: closed bars, filtered by `coin`, `interval` (`1m 5m 15m 30m 1h 4h 1d`),
 `market` (`perp` or `spot`) and `dex` (`HL` or a HIP-3 dex). The old `wss://data.vike.io/v1/stream` is closed (410).
 
+- `hl.positions`: the fills that change a big position. `data.leverage` and `data.liquidation_px` are the wallet's own
+  at the last position capture, i.e. BEFORE that fill (`null` for an `open`; a `liquidation_px` of 0 is "none"),
+  `labels.tags` its trader tags. Filters `min_leverage` (a number) and `tag` (a list) exist on this channel only.
+- `hl.top_positions`: per coin of the top 50, the position that `entered`, `left` or `moved` within the top 10 (filter
+  `event` takes ONE of those, `direction` one of `long` / `short`). The first capture sends all 10 of every coin as `entered`.
+- `hl.closed_trades`: a finished round trip (entry and exit price, `realized_pnl`, `duration_seconds`), in batches
+  every 30 minutes; unfiltered up to ~32,000 an hour (measured 2026-11-02): filter by `wallet` or `min_usd`.
+- `hl.cohort_leverage` (`hl-cohorts`): once an hour per cohort of one `axis`, `perp_bias` and `equity_exposure`
+  against account value; no wallet or coin, filters `axis` and `cohort` only.
+- `pm.positions`: each `pm.trades` fill again as its effect on the wallet's position, `data.action` (`open`,
+  `increase`, `reduce`, `close`, `flip`), `shares_before`, `shares`, `avg_price`. Filters `wallet`, `market`, `min_usd`
+  (the trade's size), `action`; unfiltered 60,000 to 150,000 an hour (measured 2026-11-02): filter by `wallet` or `market`.
+
 ## Examples
 
 ```bash
@@ -39,8 +52,17 @@ vike-data stream hl --channel hl.candles --filter coin=BTC,ETH --filter interval
 # Every liquidation and every fill of one wallet, on one connection
 vike-data stream hl --channel hl.liquidations hl.fills --filter wallet=0x1111111111111111111111111111111111111111
 
-# USDC transfers on base worth $1M+
-vike-data stream onchain --channel chain.transfers --filter chain=base --filter token=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 --filter min_usd=1000000
+# USDC transfers on base of 1M USDC or more (min_amount is in tokens; min_usd would drop the unpriced events)
+vike-data stream onchain --channel chain.transfers --filter chain=base --filter token=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 --filter min_amount=1000000
+
+# Position changes at 20x or more, BTC and ETH (the wallet's leverage and liquidation price before the fill are in data)
+vike-data stream hl --channel hl.positions --filter coin=BTC,ETH --filter min_leverage=20
+
+# Every round trip one wallet closes (a batch every 30 minutes)
+vike-data stream hl --channel hl.closed_trades --filter wallet=0x1111111111111111111111111111111111111111
+
+# One Polymarket wallet opening or closing a position
+vike-data stream polymarket --channel pm.positions --filter wallet=0x1111111111111111111111111111111111111111 --filter action=open,close
 
 # Keep only the events, with jq
 vike-data stream polymarket --channel pm.trades --filter min_usd=10000 | jq -c 'select(.type == "event") | .event'
@@ -48,8 +70,8 @@ vike-data stream polymarket --channel pm.trades --filter min_usd=10000 | jq -c '
 
 `--filter` applies to every `--channel` of the command; a key the channel does not take is refused by the server
 with the key's name. List keys (`wallet`, `coin`, `token`, `market`, `chain`, cohorts, ...) take comma-separated
-values and repeat; `side`, `direction`, `event`, `axis`, `move`, `role` take one value; `true` / `false` is sent as a yes/no (`contract=false`); `min_usd`, `min_amount`, `min_move`
-take a number. Channel fields and filter keys: https://vike.io/docs/data/reference/stream-channels
+values and repeat; `side`, `direction`, `event`, `axis`, `move`, `role` take one value; `true` / `false` is sent as a yes/no (`contract=false`); `min_usd`, `min_amount`, `min_move`,
+`min_leverage` take a number. Channels in one command must all take every key you pass (`min_leverage` and `tag` are `hl.positions` only). Channel fields and filter keys: https://vike.io/docs/data/reference/stream-channels
 
 ## Without a socket
 
@@ -75,7 +97,7 @@ the `hl.fills` default `min_usd` of 1000 added) or the server's error naming the
   subscribed). It does not mean nothing happened; read that window from the REST endpoints or the `hl` / `polymarket`
   commands. For what a socket missed while the channel was running, `vike-data stream events <channel> --cursor <c>`.
 - `hl.fills` without `min_usd` gets a $1,000 floor; `min_usd=0` is every fill (hundreds per second).
-  `chain.transfers` unfiltered is a firehose; `min_usd` on it drops unpriced transfers.
+  `chain.transfers` unfiltered is a firehose; transfers are priced after they are streamed, so `min_usd` on it drops almost every event: filter by `wallet`, `token` (with `min_amount`), `entity`, `wallet_type` or `contract=false`.
 
 ## One connection per key
 
@@ -89,10 +111,12 @@ Exit 1 also on `HTTP 401` / `4401` (the key) and on a refused subscription (`bad
 
 - Don't run two `vike-data stream` processes on the same key and path: they replace each other.
 - Don't treat silence as "nothing happened" in the first minutes: an idle channel starts on demand (up to ~12 minutes
-  for `hl.indices` and `hl.liq_risk`).
+  for `hl.indices`, `hl.liq_risk` and `hl.top_positions`, up to 30 for `hl.closed_trades`; `pm.positions` takes one to
+  three minutes like `pm.trades`; `hl.cohort_leverage` sends its newest hour at once, then one an hour).
 - Don't use the stream for history: it keeps 3 days. Use the query commands.
 
 ## Pairs well with
 
 - `vike-alerts-setup`: a stored rule that notifies by webhook without a running process.
 - `vike-hl-top-traders`: pick the wallets to put in a `wallet` filter.
+- Playbooks with a live section: `vike-hl-liquidation-radar` (`hl.liq_risk`, `hl.liquidations`, `hl.positions`), `vike-follow-the-money` (`chain.transfers`), `vike-hl-cohort-positioning` (`hl.cohort_bias`, `hl.indices`, `hl.cohort_leverage`, `hl.top_positions`), `vike-hl-trader-profile` (`hl.closed_trades`), `vike-pm-market-diligence` and `vike-polymarket-trader` (`pm.positions`).

package/skills/vike-token-holder-diligence/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: vike-token-holder-diligence
+description: Due diligence on who sits at the top of a token - the largest balances with their share of supply, how much of it is exchanges, contracts, labelled users, unlabelled or fresh wallets, which holders carry a risk flag, and whether they are selling now. Use when the user asks "is this token held by real wallets" / "are the top holders of X exchanges or contracts" / "how concentrated is X" / "holder quality of X" / "any fresh or flagged wallets among X holders".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-token-holder-diligence
+
+Classify the top 50 wallets of one token by what they are. About 10 credits.
+
+## Chain
+
+```bash
+vike-data token search ENA --chain ethereum --limit 3 --json            # 0  take the canonical address
+# 2  top holders by on-chain BALANCE, with supply_pct (the `token holders` command ranks by net inflow only)
+vike-data call token_holders --args '{"token_address":"0x57e114b691db790c35207b2e685d4a43181e6061","chain":"ethereum","limit":50,"sort":"balance"}'
+vike-data token holders 0x57e114b691db790c35207b2e685d4a43181e6061 --chain ethereum --limit 50 --json   # 2  by net inflow: who moved the most
+vike-data wallet batch <the 50 wallets> --chain ethereum --json         # 2  one call (max 100)
+vike-data token transfers 0x57e114b691db790c35207b2e685d4a43181e6061 --tab sold --period 7d --chain ethereum --hide-contracts --json   # 2  are they selling now?
+```
+
+Chains: `ethereum`, `bsc`, `base`, `hyperevm`. `sort: "balance"` is not served on every chain (the error names it); fall back to the flow ranking and say so. Holder calls scan the whole chain for the token and can take tens of seconds on a busy one: run each once. Add `"exclude_exchanges": true` to the `call` arguments to drop exchange-labelled wallets.
+
+## Reading
+
+- **Balance ranking** adds `balance`, `value_usd`, `supply_pct`, `balance_basis`, `balance_approximate`, `candidate_coverage`. The candidates are the wallets with the largest net inflow and volume, so a holder outside both is not in the list: `candidate_coverage` is the share of total supply the candidates hold. `balance_approximate: true` = a balance could not be read or the supply is unknown. `balance_basis: "unsupported"` = that row is still ranked by flow (as for a chain's native coin).
+- **Flow ranking**: `net_flow_usd` is cumulative net inflow over recorded history, not a balance. A row with huge `volume_usd` and a small net is an intermediary.
+- Holder rows carry `entity` and `wallet_type`; `wallet batch` adds `confidence` and `risk_flag`.
+
+Group the 50 rows and sum `supply_pct` (or `net_flow_usd` on the flow list) per group:
+
+| Group | Rule | Meaning |
+|---|---|---|
+| Exchange / custody | `wallet_type = cex` | aggregates many retail holders |
+| Contract / system | `dex`, `system` or any other non-`user` type | pools, routers, vaults: not a holder opinion |
+| Labelled users | `user` with an `entity` | a named person or fund |
+| Unlabelled | empty | unknown, say so |
+| Fresh | `first_seen` within 7 days | new money; a launch-day cluster is a flag |
+| Risk-flagged | non-empty `risk_flag` | quote the flag verbatim |
+
+Also read: `tx_count` 1-2 with a large balance = an airdrop or OTC receiver that may never have sold; `last_active` months old = dormant. On the `--tab sold` list, a top holder among the net sellers is the signal; `--hide-contracts` leaves out the pools and routers we know of.
+
+## Answer template
+
+> Top 50 by balance hold `X%` of supply (candidates cover `C%`): exchanges `A%`, contracts `B%`, labelled users `D%`, unlabelled `E%`; `N` wallets first seen in the last 7 days hold `F%`; `K` wallets are risk-flagged (`<flags>`). `<M>` of them are net sellers this week. `<Balances approximate / flow ranking only on this chain: say so.>`
+
+For what one wallet holds across its tokens: `vike-data wallet balances <addr> --chains <chain>` (3 credits, cap at 5 wallets).
+
+## Anti-patterns
+
+- Don't present the top-50 sum as the token's full concentration: the list is candidates, not every holder.
+- Don't call a token a rug or safe from this alone. It is one signal.
+- Don't count the exchange group as "retail" or as one holder: it is custody for many.
+
+## Pairs well with
+
+- `vike-token-holders` (the flow list), `vike-token-transfers` (who is buying or selling now), `vike-wallet-who-is` on any single holder
+- `vike-wallets-related` when several unlabelled top holders look like one cluster

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

@@ -9,7 +9,7 @@ allowed-tools: Bash(vike-data:*)
 ## Command
 
 ```bash
-vike-data token holders <token_address> [--chain ethereum|bsc|base] [--limit N] [--json]
+vike-data token holders <token_address> [--chain ethereum|bsc|base|hyperevm] [--limit N] [--json]
 ```
 
 ## Examples
@@ -34,10 +34,12 @@ vike-data token holders 0x6982508145454ce325ddbe47a25d4ec3d2311933 --limit 20
 
 ## Anti-patterns
 
-- "Top holders" here means cumulative net inflow over our recorded transfer history — NOT current on-chain balance. A wallet that bought $10M and sold $9M shows `net_flow_usd = $1M`, even if current balance is zero. The top rows are very often intermediaries (exchange wallets, lending protocols, MEV bots) with huge `volume_usd` against a small net: read this as "who moves the most of this token". **Always call this out** when reporting top holders. For what one specific wallet holds right now use `vike-data wallet balances <addr>` (Ethereum and BSC).
-- There is no concentration metric (top-N share of supply) in the output; don't compute one from `net_flow_usd`.
+- "Top holders" here means cumulative net inflow over our recorded transfer history — NOT current on-chain balance. A wallet that bought $10M and sold $9M shows `net_flow_usd = $1M`, even if current balance is zero. The top rows are very often intermediaries (exchange wallets, lending protocols, MEV bots) with huge `volume_usd` against a small net: read this as "who moves the most of this token". **Always call this out** when reporting top holders. For the largest current BALANCES use `vike-data call token_holders --args '{"token_address":"0x...","chain":"ethereum","limit":50,"sort":"balance"}'` (adds `balance`, `value_usd`, `supply_pct`; not on every chain), and for what one wallet holds `vike-data wallet balances <addr> --chains <chain>`.
+- Don't compute a share of supply from `net_flow_usd`; the balance ranking above has `supply_pct`.
 - Don't list `tx_count = 1` whales as "smart money" without context — could be an airdrop receiver who never sold.
-- For BSC tokens, pass `--chain bsc` explicitly; default is ethereum.
+- Pass `--chain` explicitly for anything but Ethereum (`bsc`, `base`, `hyperevm`); the default is ethereum.
+- **It is slow on busy tokens**: the tool scans the whole chain for the token (tens of seconds). Run it once and don't retry in a loop.
+- To classify the top holders (exchange, contract, fresh, risk-flagged) use `vike-token-holder-diligence`.
 
 ## Pairs well with
 

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

@@ -18,13 +18,12 @@ Multi-call token research workflow. It characterises WHO is moving the token (th
 
 2. **Recent buyers + sellers** (parallel calls)
    ```bash
-   vike-data token transfers <addr> --tab bought --period 24h --chain <chain> --json
-   vike-data token transfers <addr> --tab sold   --period 24h --chain <chain> --json
+   vike-data token transfers <addr> --tab bought --period 24h --chain <chain> --hide-contracts --json
+   vike-data token transfers <addr> --tab sold   --period 24h --chain <chain> --hide-contracts --json
    ```
-   Each call returns the top 10 wallets for one side.
+   Each call returns the top 10 net buyers or net sellers, ranked by net USD; `--hide-contracts` leaves out the pools and routers we know of.
 
-3. **Read `net_tokens`, not `bought`.** `bought` counts every inbound transfer (flash-loan and router round trips included). Merge the two lists by `address`, then:
-   - drop rows where `|net_tokens|` is below 1% of `max(bought, sold)`: they are round trips, not a position;
+3. **Read `net_tokens` and `net_usd`** (a net buyer's `net_usd` is negative). Merge the two lists by `address`, then:
    - label the rest with `vike-data wallet batch <addrs...> --chain <chain>` and drop CEX / router / contract rows if the user wants "real" flow;
    - split what is left into net accumulators (`net_tokens > 0`) and net distributors (`net_tokens < 0`) and add up each side's `|net_usd|`.
 
@@ -54,5 +53,6 @@ Step 1: free. Step 2: 2 calls × 2 credits. Step 3 labels: 2 credits. Total ≈
 
 ## Pairs well with
 
-- `vike-smart-money-discovery` to see whether the smart-money cohort is flowing into the token
+- `vike-smart-money-discovery` to see whether the smart-money cohort is flowing into the token; `vike-token-smart-money-trend` for its direction over time
+- `vike-token-holder-diligence` for who sits at the top (exchanges, contracts, fresh wallets, risk flags)
 - `vike-perp-funding` if the token has a perp listing (BTC/ETH/SOL/major alts)

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

@@ -10,7 +10,7 @@ allowed-tools: Bash(vike-data:*)
 
 ```bash
 vike-data token screener
-  [--chain ethereum|bsc|base]
+  [--chain ethereum|bsc|base|hyperevm]
   [--window 24h|7d|30d|90d]
   [--sort volume|net_inflow|holders|smart_inflow]
   [--limit N]                (default 20, max 100)
@@ -20,7 +20,7 @@ vike-data token screener
   [--json]
 ```
 
-`--smart-money-only` and `--sort smart_inflow` exist for `--chain ethereum` only; on `bsc` and `base` they are a 400.
+`--smart-money-only` and `--sort smart_inflow` exist for `--chain ethereum` only; on `bsc`, `base` and `hyperevm` they are a 400.
 
 ## Examples
 
@@ -76,7 +76,7 @@ vike-data token screener --min-volume 1000000 --min-holders 100 --sort net_inflo
 - Don't use `--window 24h --sort smart_inflow` for hot-new-token discovery: smart money usually positions before the 24h window; try `--window 7d`.
 - Don't omit `--min-holders` when sorting by `holders`: junk airdrops with 50,000 one-transaction addresses dominate the top otherwise.
 - Don't omit `--min-volume` when sorting by `net_inflow`: tiny tokens with $100 net flow can rank high in % terms.
-- Don't use `--smart-money-only` on `bsc` or `base`: it is a 400, not an empty result.
+- Don't use `--smart-money-only` on `bsc`, `base` or `hyperevm`: it is a 400, not an empty result.
 
 ## Cost note
 

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

@@ -11,7 +11,7 @@ Symbol/name → address resolver.
 ## Command
 
 ```bash
-vike-data token search <query> [--chain ethereum|bsc|base] [--limit N] [--json]
+vike-data token search <query> [--chain ethereum|bsc|base|hyperevm] [--limit N] [--json]
 ```
 
 ## Example
@@ -26,6 +26,7 @@ vike-data token search PEPE --chain ethereum --limit 5
 ## When to use
 
 - Any time the user mentions a token by symbol — always confirm the address before downstream calls.
+- `--chain hyperevm` searches a small registry (about 50 tokens), so no match may only mean the token is not in it. For a name across every chain, plus live price and the vike.io page, `vike-data search <name>` (its `tokens` section).
 - The default chain is **ethereum**; if the user asks "what's the address of CAKE", default to **bsc** if the symbol is bsc-native.
 
 ## Anti-patterns

package/skills/vike-token-smart-money-trend/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: vike-token-smart-money-trend
+description: Is the smart-money cohort entering, holding or exiting one Ethereum token over time - the cohort's net flow across 24h, 7d, 30d and 90d, differenced into disjoint slices, then the wallets behind the latest move. Use when the user asks "is smart money still buying X" / "did smart money exit X" / "how long has smart money been accumulating X" / "smart money trend for X".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-token-smart-money-trend
+
+Direction over time for ONE token, on **Ethereum only** (`--smart-money-only` and `--sort smart_inflow` are a 400 on bsc, base and hyperevm). For "which tokens is the cohort buying right now" use `vike-smart-money-discovery`. About 18 credits.
+
+## Chain
+
+```bash
+vike-data token search ENA --chain ethereum --limit 3 --json            # 0  the address
+vike-data token screener --chain ethereum --window 24h --sort smart_inflow --smart-money-only --limit 100 --json   # 3
+vike-data token screener --chain ethereum --window 7d  --sort smart_inflow --smart-money-only --limit 100 --json   # likewise 30d, 90d
+                                                                        # find the token's row in each
+vike-data token transfers <addr> --tab bought --period 7d --chain ethereum --hide-contracts --json   # 2  top 10 net buyers
+vike-data token transfers <addr> --tab sold   --period 7d --chain ethereum --hide-contracts --json   # 2  top 10 net sellers
+vike-data wallet batch <those addresses> --chain ethereum --json        # 2  drop cex / dex / market_maker rows
+```
+
+## Reading
+
+In smart-money mode a row is the COHORT's flow in that token: `net_flow_usd` = `in_usd` - `out_usd`, `unique_holders` = cohort wallets active, `tx_count`. Rows are sorted by `net_flow_usd`. The token absent from the top 100 means its cohort net flow is below the 100th row's, not that the cohort has no flow. Skip `0x000...0` (the native coin).
+
+**The windows overlap, so difference them** into disjoint slices before reading a trend. A window of N days is every UTC calendar day from `today - N` to today (today still in progress), so `24h` is yesterday plus today, not a rolling 24 hours:
+
+| Slice | = | Calendar days |
+|---|---|---|
+| newest | 24h | today and yesterday |
+| rest of the week | 7d - 24h | the 6 days before |
+| rest of the month | 30d - 7d | the 23 days before that |
+| rest of the quarter | 90d - 30d | the 60 days before that |
+
+**Compare signs, not magnitudes**: the slices differ in length and today is partial. Example, ENA on 2026-10-19: 24h +$14.9M, 7d +$38.3M, 30d +$27.9M, 90d +$54.0M, so newest +$14.9M, rest of the week +$23.4M, rest of the month -$10.4M, rest of the quarter +$26.1M: the cohort sold for three weeks, then came back in the last week.
+
+| Newest | Rest of week | Rest of month | Read |
+|---|---|---|---|
+| + | + | + | sustained accumulation |
+| + | + | - | re-accumulation: turned from seller to buyer |
+| + | - | any | a short buy after a quiet or selling week: weak until the week confirms |
+| - | + | any | reducing after a build |
+| - | - | - | distribution |
+
+Then name the wallets behind the latest slice from the two `token transfers` lists. They are ranked by net USD (`--tab bought` = net buyers, whose `net_usd` is NEGATIVE: net USD bought is `-net_usd`); `net_tokens` is the net in whole tokens. `--hide-contracts` leaves out the pools and routers we know of; still drop the rows `wallet batch` calls `cex`, `dex` or `market_maker`: an exchange hot wallet can top the net-buyer list.
+
+## Anti-patterns
+
+- No tool lists cohort members, and the `token transfers` lists are the top 10 net movers, not the cohort: say the named wallets are the largest net movers, not proven cohort members.
+- Don't read a 1-day sign as a trend, and don't read a screener sign as a price call.
+- Don't use it on bsc, base or hyperevm; there the answer is "no cohort data", not "no smart money".
+
+## Pairs well with
+
+- `vike-smart-money-discovery` (which tokens), `vike-token-screener` (columns), `vike-token-holder-diligence` (who holds it)
+- `vike-perp-crowding` if the token has a perp listing

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

@@ -12,7 +12,8 @@ allowed-tools: Bash(vike-data:*)
 vike-data token transfers <token_address>
   [--tab bought|sold]            # default sold; ONE side per call
   [--period 1h|24h|7d|30d]       # default 24h
-  [--chain ethereum|bsc|base|all]
+  [--chain ethereum|bsc|base|hyperevm|all]
+  [--hide-contracts]             # leave out the pools, routers and other contracts we know of
   [--json]
 ```
 
@@ -20,8 +21,8 @@ There is no `--limit`: every call returns the top 10 wallets for that side. For
 
 ## When to use
 
-- "Who's accumulating X?" → `--tab bought --period 24h`, then read `net_tokens`
-- "Who's dumping X?" → `--tab sold --period 24h`, then read `net_tokens`
+- "Who's accumulating X?" → `--tab bought --period 24h --hide-contracts`
+- "Who's dumping X?" → `--tab sold --period 24h --hide-contracts`
 - "Smart money on X this week" → `--tab bought --period 7d`, label the addresses with `vike-data wallet batch`
 
 ## Output columns
@@ -32,7 +33,7 @@ There is no `qty`, `usd_value`, `label` or `tx_count` column. To label an addres
 
 ## Reading tips
 
-- **`bought` is every inbound transfer, not purchases.** It includes flash-loan and router round trips. A wallet at the top of `--tab bought` with `bought ≈ sold` and `net_tokens ≈ 0` is a bot or venue passing tokens through, not a buyer. **Rank and judge by `net_tokens`** (bought − sold): positive = net accumulator, negative = net distributor.
+- **The rows are the top 10 NET buyers (`--tab bought`) or net sellers, ranked by net USD.** Wallets that only pass the token through (bought ≈ sold) are not listed, but a row can still be a pool, vault or settlement contract: `--hide-contracts` leaves out the ones we know of, and `wallet batch` labels the rest. `net_tokens` (bought − sold) is the net in whole tokens.
 - **Signs differ by convention.** `net_usd = usd_received − usd_spent`, so a net buyer has `net_tokens > 0` and `net_usd < 0`, and a net seller has `net_usd > 0`. Do not read a positive `net_usd` as "bought".
 - The two sides of the same period are separate top-10 lists. The same wallet in both = market maker / churn, not a signal.
 - The window ends at the token's newest PRICED row, not at the current time. For an illiquid token it can be hours behind "now".
@@ -41,12 +42,13 @@ There is no `qty`, `usd_value`, `label` or `tx_count` column. To label an addres
 
 ## Anti-patterns
 
-- Don't call a wallet a buyer or seller from `bought` / `sold` alone. Check `net_tokens`.
+- Don't call a contract row a buyer: use `--hide-contracts`, then label what is left.
 - Don't request `--chain all` unless you really need cross-chain: it maps the address to the token's address on each chain and is slower.
 - 1h period is sparse for low-liquidity tokens. Use 24h as the default starting window.
-- Don't treat the 10 rows as the token's whole market: they are the top 10 by volume on one side.
+- Don't treat the 10 rows as the token's whole market: they are the top 10 net movers on one side.
 
 ## Pairs well with
 
 - `vike-data wallet batch <addr...>` to label the rows and drop CEX / router rows
 - `vike-data wallet summary <addr>` to profile any interesting buyer/seller
+- `vike-token-smart-money-trend` to put the buyers next to the smart-money cohort's flow over time