@vike-io/cli 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.15.0
+
+### Minor Changes
+
+- 531c0c8: Every MCP tool is reachable, and the event streams are too.
+  
+  - `vike-data call <tool> --args '{json}'` (or `--args-file`, `--timeout`) calls any MCP tool by name and prints its raw result, so integers above 2^53 stay exact.
+  - A tool that refuses its input now exits 1 in every output mode; before, `--json` and piped output exited 0 with `{"error": ...}` on stdout.
+  - `vike-data stream <hl|hl-cohorts|onchain|polymarket> --channel ... [--filter key=value] [--cursor c]` reads `wss://stream.vike.io/v1/stream/<path>`: the key goes in the `X-API-KEY` header, every ping is answered, `event` and `gap` frames print as NDJSON, and after any drop it reconnects from the last cursor of each subscription. It exits 1, without reconnecting, on `replaced (4410)` (another program took the key's connection), on `HTTP 401` / `4401`, and on a refused subscription. The CLI keeps no channel list: the server decides what each path serves, including the live candles (`stream hl --channel hl.candles --filter coin=BTC --filter interval=1m`) that replace `wss://data.vike.io/v1/stream`. `--filter` sends `true` / `false` as a yes/no. A replay the server cannot read (`catchup_unavailable`) is retried after 1, 2, 4, 8 and 15 s, then the subscription continues from now and names the skipped window; a reconnect after an open connection waits 1 s; a full stdout pauses the socket (pings are still answered); a closed pipe (`| head`) ends with exit 0. New dependency: `ws`.
+  - `vike-data stream info`, `stream check <channel>` (the server's own validator, exit 1 when it refuses), `stream events <channel>` (stored events, 3 days) and `stream connections` (your recent connections) use the stream's MCP tools and open no socket.
+  - `vike-data search <q>`: the vike.io search over tokens, wallets and entities, Hyperliquid traders, vaults and builders, Polymarket wallets and markets.
+  - `vike-data hl`: `cohort-metrics`, `segments`, `wallet`, `wallet-activity`, `wallet-trades`, `leaderboard`, `liquidations`, `market` (with the `hourly` panel), `orders`, `twaps`, `ledger`, `leverage-changes`, `stats`, `hype-holders`, `builders`, `vaults`, `vault`, `archive`; a tool with several views takes `--view`.
+  - `polymarket markets` takes `--view search --query ...` and `--view market --condition-id ...`; `token transfers` takes `--hide-contracts`; `candles hl` takes `--view export` and `--view latest` (the newest bar of every symbol; no symbol, window or limit is sent with it), and sends only the flags given; `perp top-traders --size` now defaults to 20 (max 100) and `perp find-position --limit` to 50 (max 500), as the server tools do, and `--sort` lists `account_value`, `long_pnl`, `short_pnl`. 68 of the server's 70 MCP tools now have a command; `perp_open_interest` and `perp_long_short` are reached with `call`.
+  - `vike-data polymarket`: `market-trades`, `tape`, `orderbook`, `market-stats`, `settlement`, `settlements`, `archive`, `leaderboard`. `vike-data wallet`: `first-funder`, `exchange-usage`.
+  - `vike-data alerts`: `events`, `resend`, `rotate-secret`, `test-webhook`; `create` and `edit` take `--type` (transfer and the five Hyperliquid types), `--address` / `--address-role`, `--wallet`, `--actions`, `--pnl-cohorts`, `--size-cohorts`, `--index`, `--threshold`, `--band`, `--direction`. `--chain` takes eth, bsc, base or hyperevm and no longer defaults to eth on the client (a Hyperliquid alert refuses a chain; the server still defaults a transfer alert to eth). Discord is gone from `--channel`: the server refuses it.
+  - `vike-data whoami` is registered. `doctor` checks Node >= 22.12.0, the `engines` floor. The User-Agent carries the installed version (it said `vike-cli/dev` outside `npm run`) and is sent on `tools/list` and `initialize` too. The `sync-schema` npm script, whose file never existed, is gone.
+  - Skills: a new `vike-stream` skill (32 in all); the umbrella routes the new commands, streams and `call`, and no longer tells agents to deny WebSockets, per-address alerts or a per-wallet Hyperliquid tool; the alert skills cover the Hyperliquid types, address alerts, four chains and no Discord; the webhook check accepts either signature during a secret rotation.
+
 ## 0.14.0
 
 ### Minor Changes

package/README.md

@@ -55,7 +55,8 @@ The key is read from `VIKE_API_KEY` first, then from `~/.vike/config.json`
 | **Polymarket up/down families** (archive) | The same archive cut per market family, `asset=btc/tenor=5m` and so on, with an `asset=other/tenor=other` catch-all | free key | [polymarket-updown-markets](https://vike.io/data/polymarket-updown-markets) |
 | **Polymarket API** `/v1/polymarket` | Markets, the raw event and trade tape (about 30 days back), order-book snapshots, candles, on-chain settlements | free key | [polymarket](https://vike.io/data/polymarket) |
 | **Hyperliquid cohorts** `/v1/hyperliquid/coins/{coin}/cohort-metrics` | Long vs short per cohort, hourly, up to 8,760 hours in one request. Axes: `size` (account value, shrimp to 4x whale), `tier` (position notional), `pnl` (realized-PnL percentile), `pnl_abs` (PnL in dollars). `labelBasis=point_in_time` grades each hour with the label it had then (from 2026-04-07). | free key | [hl-cohorts](https://vike.io/data/hl-cohorts) |
-| **Hyperliquid API** `/v1/hyperliquid` | Trader rankings and leaderboards, 5-minute position snapshots kept for a year, wallet fills, funding and ledger, liquidations (inferred from snapshots), builders, candles since the start of 2026; closed bars also stream on `wss://vike.io/v1/stream` | free key | [hyperliquid](https://vike.io/data/hyperliquid) |
+| **Hyperliquid API** `/v1/hyperliquid` | Trader rankings and leaderboards, 5-minute position snapshots kept for a year, wallet fills, funding and ledger, liquidations (inferred from snapshots), builders, candles since the start of 2026; closed bars also stream live as the `hl.candles` channel of `wss://stream.vike.io/v1/stream/hl` | free key | [hyperliquid](https://vike.io/data/hyperliquid) |
+| **Event streams** `wss://stream.vike.io/v1/stream/<path>` | Live events with a resume cursor on four paths: `hl` (fills, liquidations, positions, liquidation risk, order walls, candles, TWAPs, ledger, leverage changes, funding), `hl-cohorts` (cohort flow, indices, cohort bias), `onchain` (transfers on eth, bsc, base, hyperevm), `polymarket` (trades, resolutions, price moves, new markets). `vike-data stream` reads them; `vike-data stream info` lists every channel and filter. Connections are not counted against the hourly limit. | free key | [stream channels](https://vike.io/docs/data/reference/stream-channels) |
 | **On-chain API** `/v1/onchain` | Wallet summaries, transactions, counterparties, PnL, address labels with per-source provenance, token holders and transfers. Ethereum on every route, BNB Chain on the wallet and token-flow routes, Base on token transfers. | free key | [onchain](https://vike.io/data/onchain) |
 
 Direct links that need no key:
@@ -138,20 +139,33 @@ Every data command is one `tools/call` to the MCP server. `vike-data <group> --h
 | Command | Subcommands | MCP tool |
 |---|---|---|
 | `vike-data token` | `search`, `transfers`, `screener`, `holders` (`--chain ethereum\|bsc\|base`) | `token_search`, `token_transfers`, `token_screener`, `token_holders` |
-| `vike-data wallet` | `summary`, `transactions` (`txs`), `compare`, `trace`, `batch`, `counterparties`, `pnl-history`, `balances`, `ens`, `discover` | `wallet_summary`, `wallet_transactions`, `wallet_compare`, `wallet_trace`, `wallet_batch_labels`, `wallet_counterparties`, `wallet_pnl_history`, `wallet_token_balances`, `wallet_ens`, `wallet_discover` |
+| `vike-data wallet` | `summary`, `transactions` (`txs`), `compare`, `trace`, `batch`, `counterparties`, `pnl-history`, `balances`, `ens`, `discover`, `first-funder`, `exchange-usage` | `wallet_summary`, `wallet_transactions`, `wallet_compare`, `wallet_trace`, `wallet_batch_labels`, `wallet_counterparties`, `wallet_pnl_history`, `wallet_token_balances`, `wallet_ens`, `wallet_discover`, `wallet_first_funder`, `wallet_exchange_usage` |
 | `vike-data labels <address>` | multi-source label provenance for one wallet | `wallet_label_provenance` |
 | `vike-data perp` | `top-traders`, `find-position` (Hyperliquid); `funding`, `spreads` (cross-venue funding rates and perp-vs-perp price gaps) | `hl_perp_top_traders`, `hl_position_match`, `perp_funding`, `perp_spreads` |
-| `vike-data candles` | `hl <symbol>` (Hyperliquid perp or spot, from executed fills), `polymarket <token_id>` (one outcome token) | `hl_ohlcv`, `polymarket_ohlcv` |
-| `vike-data polymarket` (`pm`) | `markets`, `market <condition_id>`, `wallet <address>`, `smart-money` | `polymarket_markets`, `polymarket_market_detail`, `polymarket_wallet`, `polymarket_smart_money` |
-| `vike-data alerts` | `list`, `channels`, `create`, `edit`, `delete`, `register-webhook` (email, Discord, or an HTTPS webhook, HMAC-signed when you set a secret) | `alerts_*` |
-| setup | `init`, `login`, `logout`, `doctor`, `schema`, `install` | — |
-
-Output is a table on a terminal and JSON with `--json` or whenever stdout is piped:
+| `vike-data hl` | `cohort-metrics <symbol>`, `segments`, `wallet <address>`, `wallet-activity <address>`, `wallet-trades <address>`, `leaderboard`, `liquidations`, `market`, `orders`, `twaps`, `ledger`, `leverage-changes`, `stats`, `hype-holders`, `builders`, `vaults`, `vault <vault>`, `archive`; a tool with several views takes `--view` | `hl_cohort_metrics`, `hl_segments`, `hl_wallet`, `hl_wallet_activity`, `hl_wallet_trades`, `hl_leaderboard`, `hl_liquidations`, `hl_market`, `hl_orders`, `hl_twaps`, `hl_ledger`, `hl_leverage_changes`, `hl_stats`, `hl_hype_holders`, `hl_builders`, `hl_vaults`, `hl_vault`, `hl_archive` |
+| `vike-data candles` | `hl <symbol>` (Hyperliquid perp or spot, from executed fills; `--view export`, or `--view latest` for the newest bar of every symbol), `polymarket <token_id>` (one outcome token); live bars: `stream hl --channel hl.candles` | `hl_ohlcv`, `polymarket_ohlcv` |
+| `vike-data polymarket` (`pm`) | `markets`, `market <condition_id>`, `wallet <address>`, `smart-money`, `leaderboard`, `market-trades <condition_id>`, `tape`, `orderbook <token_id>`, `market-stats <token_id>`, `settlement <condition_id>`, `settlements`, `archive` | `polymarket_markets`, `polymarket_market_detail`, `polymarket_wallet`, `polymarket_smart_money`, `polymarket_leaderboard`, `polymarket_market_trades`, `polymarket_tape`, `polymarket_orderbook`, `polymarket_market_stats`, `polymarket_settlement`, `polymarket_settlements_bulk`, `polymarket_archive` |
+| `vike-data alerts` | `list`, `channels`, `create`, `edit`, `delete`, `events`, `resend`, `register-webhook`, `test-webhook`, `rotate-secret`: transfer alerts (a token or one wallet, on eth, bsc, base, hyperevm) and Hyperliquid alerts (`--type hl_wallet`, `hl_cohort_fill`, `hl_liquidation`, `hl_cohort_bias`, `hl_liq_proximity`), by email or an HTTPS webhook, HMAC-signed | `alerts_*` |
+| `vike-data stream <path>` | live events from `wss://stream.vike.io/v1/stream/<path>` (`hl`, `hl-cohorts`, `onchain`, `polymarket`) as NDJSON: `--channel` (one or more), `--filter key=value`, `--cursor` | WebSocket, not MCP |
+| `vike-data stream` | `info`, `check <channel>` (the server's validator), `events <channel>` (stored events, 3 days), `connections` (yours) | `stream_info`, `stream_check_filter`, `stream_events`, `stream_connections` |
+| `vike-data search <q>` | tokens, wallets and entities, HL traders, vaults, builders, Polymarket wallets and markets by name, symbol, address or ENS name | `search` |
+| `vike-data call <tool>` | any MCP tool by name: `--args '{json}'` or `--args-file`, `--timeout`; prints the raw result | any |
+| setup | `init`, `login`, `logout`, `whoami`, `doctor`, `schema`, `install` | — |
+
+Output is a table on a terminal and JSON with `--json` or whenever stdout is piped. A tool that refuses its input
+exits 1 in every mode:
 
 ```bash
 vike-data token search BTC --json | jq '.'
+vike-data call hl_wallet --args '{"address":"0x...","view":"trades_summary","window":"30d"}'
+vike-data stream hl --channel hl.fills --filter coin=BTC --filter min_usd=100000
 ```
 
+`vike-data stream` answers the server's pings, prints `event` and `gap` frames as they arrive (status on stderr), and
+after any drop reconnects from the last cursor of each subscription. On each path one key holds one connection: a
+second program on the same key takes over, and the first exits with `replaced (4410)` instead of reconnecting. Give
+each program its own key.
+
 ## Examples
 
 [`examples/`](examples/) holds three Python scripts. Each declares its dependencies inline, so
@@ -173,9 +187,9 @@ Downloads go to `./vike-archive/`.
 
 ## For AI agents
 
-This package ships **31 skill playbooks** under [`skills/`](skills/): markdown files an AI coding
+This package ships **32 skill playbooks** under [`skills/`](skills/): markdown files an AI coding
 agent loads so it knows when and how to call each command. [`skills.sh.json`](skills.sh.json) groups
-them by domain (Tokens, Wallets, CEX perps, Hyperliquid perps, Candles, Polymarket, Alerts). The
+them by domain (Tokens, Wallets, CEX perps, Hyperliquid perps, Candles, Polymarket, Alerts, Live streams). The
 entry point is the umbrella skill `vike`, which routes a question to the specialised skill.
 
 ```bash

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "CLI, agent skills and MCP client for the free Vike Data API: a Polymarket full-L2 order-book archive in Parquet (CC BY 4.0), Hyperliquid positions, fills and cohorts, and labelled Ethereum/BNB wallets",
   "type": "module",
   "main": "src/index.js",
@@ -28,8 +28,7 @@
     "lint:fix": "eslint . --fix",
     "changeset": "changeset",
     "changeset:version": "changeset version",
-    "changeset:publish": "changeset publish",
-    "sync-schema": "node scripts/sync-schema.js"
+    "changeset:publish": "changeset publish"
   },
   "keywords": [
     "vike",
@@ -68,7 +67,8 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "commander": "^15.0.0"
+    "commander": "^15.0.0",
+    "ws": "^8.22.1"
   },
   "devDependencies": {
     "@changesets/cli": "^3.0.3",

package/skills/vike/SKILL.md

@@ -7,7 +7,7 @@ description: "Use this skill whenever the user asks any question about on-chain
 
 This skill is for anyone who asks an AI agent about crypto data: who is buying a token, what a wallet holds, what Hyperliquid or Polymarket traders are doing right now. It tells the agent which vike tool answers which question and how to read the result, so it does not guess or invent numbers. It reads its data from vike.io and needs a free vike API key.
 
-What the platform has: wallet and token analytics on Ethereum and BSC, with Base for token transfers and labels (each tool's chain list is under "What each tool really returns"), multi-source wallet labels, CEX perpetual funding and cross-venue spreads, Hyperliquid top traders / share-card lookup / candles, Polymarket markets, traders and smart-money signals, and transfer alerts. 31 tools in one MCP server.
+What the platform has: wallet and token analytics on Ethereum and BSC, with Base for token transfers and labels (each tool's chain list is under "What each tool really returns"), multi-source wallet labels, CEX perpetual funding and cross-venue spreads, Hyperliquid wallets, cohorts, leaderboards, liquidations, markets, builders, vaults and candles, Polymarket markets, traders, tape, order books, settlements and the Parquet archive, transfer and Hyperliquid alerts, and live event streams over WebSocket. 70 tools in one MCP server.
 
 **MCP endpoint for all calls:** `https://data.vike.io/mcp` (JSON-RPC 2.0)
 **Or use the CLI:** `npm install -g @vike-io/cli` → `vike-data <command>`
@@ -25,8 +25,8 @@ Hard rules — agents that violate these produce wrong answers. Read once, apply
 1. **Addresses are always full 0x-hex (42 chars).** Never truncate when querying. Never display truncated when the user asks for the address — they'll copy-paste it.
 2. **Perp and Hyperliquid symbols are upper-cased by the server.** Echo back what the user wrote.
 3. **Windows are counted in UTC calendar days, not a rolling 24 hours.** On the token screener `24h` spans yesterday and today; on Hyperliquid `30d` is today plus the previous 30 days.
-4. **Page sizes are small and differ per tool; there is no paging.** Max 20: `wallet_discover` (`size`), `hl_perp_top_traders` (`size`), `polymarket_smart_money`. Max 30: `polymarket_markets`. Max 50: `token_holders`, `wallet_counterparties`, `wallet_compare`, `hl_position_match`. Max 100: `token_screener`, and 100 addresses for `wallet_batch_labels`. Max 500: `wallet_transactions`. `token_transfers` has no limit: it always returns 10 rows. To go deeper, narrow the filter or the window instead of asking for more rows.
-5. **Refresh differs per tool; never promise "minutes".** `wallet_discover` and `wallet_summary` are rebuilt nightly, so a wallet active an hour ago may not show. Transfers are synced block by block. `hl_position_match` only matches positions seen within 15 minutes of the newest snapshot batch. Alerts are checked on a cron, not streamed.
+4. **Page sizes are small and differ per tool; these have no paging.** Max 20: `wallet_discover` (`size`), `polymarket_smart_money`. Max 30: `polymarket_markets`. Max 50: `token_holders`, `wallet_counterparties`, `wallet_compare`. Max 100: `token_screener`, `hl_perp_top_traders` (`size`), and 100 addresses for `wallet_batch_labels`. Max 500: `wallet_transactions`, `hl_position_match`. `token_transfers` has no limit: it always returns 10 rows. To go deeper, narrow the filter or the window instead of asking for more rows. The `hl` commands, `polymarket market-trades`, `tape`, `settlements` and `alerts events` DO page: pass the answer's next cursor back with `--cursor`.
+5. **Refresh differs per tool; never promise "minutes".** `wallet_discover` and `wallet_summary` are rebuilt nightly, so a wallet active an hour ago may not show. Transfers are synced block by block. `hl_position_match` only matches positions seen within 15 minutes of the newest snapshot batch. For events as they happen use `vike-data stream` (`vike-stream`).
 6. **USD amounts are floats in dollars.** `--min-usd 10000` = ten thousand dollars, not micro-USD.
 7. **`--json` is always available** on CLI commands and gives stable machine-readable output. The default (human) format may change; `--json` will not.
 8. **Resolve a token before asking transfer/holder questions.** `token_search` → take the canonical address → pass it to `token_transfers` / `token_holders`. Symbol-only queries lose precision on tickers that collide across chains (e.g. FUN, BEAM, USDC).
@@ -95,13 +95,25 @@ Pick by the question, then read the named skill for the recipe and the traps. If
 | Cross-venue price spread, "perp market overview" | `vike-data perp spreads` + `perp funding` + `perp top-traders` | `vike-perp-overview` |
 | Top Hyperliquid traders; "is this HL address any good" | `vike-data perp top-traders` / `hl_perp_top_traders` | `vike-hl-top-traders` |
 | HL share card → which wallet holds it | `vike-data perp find-position` / `hl_position_match` | `vike-hl-position-match` |
-| Candles: Hyperliquid perp/spot, Polymarket outcome token | `vike-data candles hl` / `candles polymarket` | `vike-candles` |
+| One HL wallet: equity, positions, cohorts, risk; its fills / funding / ledger | `vike-data hl wallet`, `hl wallet-activity` / `hl_wallet`, `hl_wallet_activity` | this skill |
+| Are whales / smart money long or short X (HL cohorts) | `vike-data hl cohort-metrics <symbol>`, `hl segments`, `hl market --view indices` | this skill |
+| HL leaderboard with the full risk set, liquidations, open interest, builders, vaults | `vike-data hl leaderboard`, `hl liquidations`, `hl market`, `hl builders`, `hl vaults`, `hl vault` | this skill |
+| HL orders and order clusters, TWAPs, the ledger, leverage changes, closed trades, venue stats, HYPE holders, the Parquet archive | `vike-data hl orders`, `hl twaps`, `hl ledger`, `hl leverage-changes`, `hl wallet-trades`, `hl stats`, `hl hype-holders`, `hl archive` | this skill |
+| A name, symbol, address, ENS name or polymarket.com link → what it is | `vike-data search <q>` / `search` | this skill |
+| Candles: Hyperliquid perp/spot (history, or the newest bar of every symbol), Polymarket outcome token; live HL bars | `vike-data candles hl` (`--view latest`), `candles polymarket`; `stream hl --channel hl.candles` | `vike-candles` |
 | Trending Polymarket markets (by 24h volume) | `vike-data polymarket markets` / `polymarket_markets` | `vike-polymarket-markets` |
 | One Polymarket market | `vike-data polymarket market <condition_id>` / `polymarket_market_detail` | `vike-polymarket-market-detail` |
 | One Polymarket trader | `vike-data polymarket wallet` / `polymarket_wallet` | `vike-polymarket-trader` |
 | Polymarket smart-money flows / mispricings / overview | `vike-data polymarket smart-money` / `polymarket_smart_money` | `vike-polymarket-smart-money` |
-| Alerts: create / list / edit / delete | `vike-data alerts ...` / `alerts_*` | `vike-alerts-setup` |
-| Alert delivery to an HTTPS webhook | `vike-data alerts register-webhook` | `vike-alerts-webhook` |
+| Polymarket wallet leaderboard | `vike-data polymarket leaderboard` / `polymarket_leaderboard` | this skill |
+| One market's trades with wallets; raw tape; order book; tape stats | `vike-data polymarket market-trades`, `tape`, `orderbook`, `market-stats` | this skill |
+| Polymarket resolutions; the Parquet archive | `vike-data polymarket settlement`, `settlements`, `archive` | this skill |
+| Who funded a wallet; which exchanges it uses | `vike-data wallet first-funder`, `wallet exchange-usage` | this skill |
+| Find Polymarket markets by slug, or one by condition_id | `vike-data polymarket markets --view search --query btc-updown` / `--view market --condition-id 0x...` | this skill |
+| Alerts: create / list / edit / delete / events (transfer and Hyperliquid) | `vike-data alerts ...` / `alerts_*` | `vike-alerts-setup` |
+| Alert delivery to an HTTPS webhook | `vike-data alerts register-webhook`, `test-webhook`, `rotate-secret` | `vike-alerts-webhook` |
+| Live events: HL fills, liquidations, positions, candles, TWAPs, ledger, leverage, funding, cohort flow and bias; on-chain transfers; Polymarket trades and new markets | `vike-data stream <hl\|hl-cohorts\|onchain\|polymarket> --channel ...`; `stream info`, `check`, `events`, `connections` | `vike-stream` |
+| A tool with no command of its own | `vike-data call <tool> --args '{...}'` | this skill |
 | Install, auth, errors, conventions | — | `vike-core` |
 
 **When in doubt, start with `vike-data token search` or `vike-data wallet summary`.** Both are cheap and disambiguate what the user actually meant.
@@ -132,7 +144,12 @@ vike-data wallet summary 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --json
 vike-data perp funding --symbol BTC --json
 ```
 
-**B) Via an MCP connector (recommended when your client has one).** All 31 tools live at `https://data.vike.io/mcp`. Connect the client to that address with the `X-API-KEY` header above, then call a tool by name with its arguments, for example `wallet_summary` with `address` set to a full 0x address.
+Any MCP tool, including one with no command of its own, is one `call` away; it prints the tool's raw JSON and exits 1 when the tool refuses the input:
+```bash
+vike-data call hl_wallet --args '{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","view":"summary"}'
+```
+
+**B) Via an MCP connector (recommended when your client has one).** All 70 tools live at `https://data.vike.io/mcp`. Connect the client to that address with the `X-API-KEY` header above, then call a tool by name with its arguments, for example `wallet_summary` with `address` set to a full 0x address.
 
 Run `vike-data schema --pretty` (or call MCP `tools/list`) to see the live arg shape for every tool. Always read the schema before constructing arguments — defaults and enum values change.
 
@@ -181,11 +198,19 @@ Neither returns mark prices or bid/ask per venue. "Spread" here is perp vs perp
 | `hl_perp_top_traders` | up to 20 wallets: `total_realized_pnl`, `roi_pct`, `win_rate_pct`, `max_drawdown_pct` (all percents; 12.5 = 12.5%), `trade_count`, `total_volume`. ROI = window realized PnL / CURRENT account value; drawdown is account-level and all-time |
 | `hl_position_match` | wallets whose open position matches a share card (`symbol`, side, leverage, entry) |
 | `hl_ohlcv` | perp or spot candles |
+| `hl_wallet` (`vike-data hl wallet`) | one wallet: equity, open positions, cohort labels, risk metrics, lifetime flow; `--view trades_summary` for closed-trade stats |
+| `hl_wallet_activity` (`hl wallet-activity`) | one wallet's fills, funding, ledger or builder routing, newest first, paged with `--cursor` |
+| `hl_cohort_metrics` (`hl cohort-metrics <symbol>`) | hourly long/short notional per cohort of one symbol; `bias` is a fraction -1..+1. For a backtest pass `--label-basis point_in_time` |
+| `hl_segments` (`hl segments`) | the cohort labels (`--view cohorts`), one cohort now (`summary`), the symbol x cohort board (`heatmap`), one cohort hour by hour (`history`) |
+| `hl_leaderboard` (`hl leaderboard`) | traders on 20 metrics; `--min-win-rate` is a FRACTION here (0.6), a percent in `perp top-traders` |
+| `hl_liquidations`, `hl_market`, `hl_builders`, `hl_vaults`, `hl_vault` | liquidations / risk / heatmap; open interest, symbol series, positions, indices, large fills, an hourly panel of up to 64 symbols; builder codes; vaults |
+| `hl_orders`, `hl_twaps`, `hl_ledger`, `hl_leverage_changes` | resting orders at one instant, one wallet's orders, order clusters; the cross-wallet feeds (follow one with `--order asc` and each `nextCursor`, stop on an empty page) |
+| `hl_wallet_trades`, `hl_stats`, `hl_hype_holders`, `hl_archive` | one wallet's closed trades; hourly venue equity / open interest / volume; HYPE holders; the daily fills and positions Parquet files (`--view url` = a 7-day link) |
 
-There is no per-wallet Hyperliquid profile, no open-interest and no cohort tool in the CLI yet. Say so instead of improvising from the leaderboard.
+Every `hl` command takes `--view` (the first view is the default) and only the flags that view uses: a flag the view does not take is refused by name, not ignored.
 
 ### Candles
-`hl_ohlcv` (Hyperliquid perp or spot, 1m–1d, built from HL's own fills, also HIP-3 builder DEXs) and `polymarket_ohlcv` (ONE outcome token, price = probability 0–1, needs a `token_id`, not a condition_id). There is no candle source for CEX tickers or an arbitrary ERC-20.
+`hl_ohlcv` (Hyperliquid perp or spot, 1m–1d, built from HL's own fills, also HIP-3 builder DEXs) and `polymarket_ohlcv` (ONE outcome token, price = probability 0–1, needs a `token_id`, not a condition_id). `candles hl --view latest` is the newest 1-minute bar of every symbol; live closed bars come from `vike-data stream hl --channel hl.candles --filter coin=BTC --filter interval=1m`. There is no candle source for CEX tickers or an arbitrary ERC-20.
 
 ### Polymarket
 | Tool | Returns |
@@ -196,15 +221,16 @@ There is no per-wallet Hyperliquid profile, no open-interest and no cohort tool
 | `polymarket_smart_money` | MARKETS where the profitable-wallet cohort is flowing (`flows`) or bought below the mid (`mispricings`); not a list of top traders |
 
 ### Alerts
-Create + manage on-chain transfer alerts delivered to email, Discord or an HTTPS webhook.
+Create + manage on-chain transfer alerts and Hyperliquid alerts, delivered by email or an HTTPS webhook.
 
 | Tool | Does |
 |---|---|
 | `alerts_list`, `alerts_list_channels` | list rules / enabled channels |
-| `alerts_create`, `alerts_edit`, `alerts_delete` | manage a rule (token symbol + chain `eth`/`bsc` + USD thresholds) |
-| `alerts_register_webhook` | register an HTTPS webhook (HMAC-signed deliveries) |
+| `alerts_create`, `alerts_edit`, `alerts_delete` | manage a rule: transfer (token and/or one `address`, chain `eth`/`bsc`/`base`/`hyperevm`, USD thresholds) or Hyperliquid (`--type hl_wallet`, `hl_cohort_fill`, `hl_liquidation`, `hl_cohort_bias`, `hl_liq_proximity`) |
+| `alerts_events`, `alerts_resend_delivery` | what fired and each delivery's status (15 days); send one again |
+| `alerts_register_webhook`, `alerts_test_webhook`, `alerts_rotate_webhook_secret` | an HTTPS webhook (HMAC-signed deliveries): register, test, rotate its secret |
 
-An alert fires on ANY transfer of the token above the USD threshold on that chain. It cannot watch one address, and there is no price or funding alert. There is no Telegram delivery. Alerts are checked on a cron, not streamed; do not suggest WebSockets.
+A token-wide transfer alert fires on ANY transfer of the token above the USD threshold on that chain; an address alert on every transfer of that wallet. Hyperliquid alerts go to a webhook or are read with `alerts events` (no email). There is no price or funding alert, no Discord (off) and no Telegram delivery. For a live feed without a rule, use `vike-data stream`.
 
 ---
 
@@ -222,9 +248,7 @@ Credits are an accounting figure only; they never block a call. The one limit is
 
 - **No NFT data** — out of scope by design.
 - **No on-chain trading / signing** — read-only platform, no execution.
-- **No WebSocket / push streaming alerts.**
-- **No ENS name → address**, no per-address alerts, no candles for CEX tickers or arbitrary ERC-20 contracts.
-- **No Hyperliquid per-wallet profile, open interest or cohort positioning** through the CLI yet.
+- **No ENS name → address**, no candles for CEX tickers or arbitrary ERC-20 contracts.
 - **No non-EVM chains** (Bitcoin, Solana, Tron, Monero, Zcash, Dash) and no Arbitrum.
 
 If the user asks for any of the above, say so directly rather than proposing a workaround.

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

@@ -1,6 +1,6 @@
 ---
 name: vike-alerts-setup
-description: Create, list, edit, and delete on-chain transfer alerts. Alerts fire when a token transfer crosses USD thresholds you set and deliver to email or Discord. Use when the user asks "alert me when X" / "watch for big transfers" / "notify on whale moves".
+description: Create, list, edit, and delete alerts - on-chain transfer alerts (a token, one wallet, USD thresholds; eth, bsc, base, hyperevm) and Hyperliquid alerts (a wallet's fills, cohort fills, liquidations, cohort bias, liquidation proximity) - and read the events they produced. Delivered by email or an HTTPS webhook. Use when the user asks "alert me when X" / "watch for big transfers" / "notify on whale moves" / "tell me when this wallet trades".
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -12,7 +12,7 @@ allowed-tools: Bash(vike-data:*)
 vike-data alerts channels --json
 ```
 
-Returns enabled email + Discord channels. **If a user creates an alert with a channel they haven't verified, the alert is saved but won't fire notifications.** Always check first.
+Returns enabled email + webhook channels. **If a user creates an alert with a channel they haven't verified, the alert is saved but won't fire notifications.** Always check first. A Hyperliquid alert is delivered only by a webhook (`vike-alerts-webhook`), or read with `vike-data alerts events`.
 
 ## CRUD
 
@@ -35,14 +35,44 @@ vike-data alerts create \
   --cooldown 60
 ```
 
-Required: `--label`. Common: `--token`, `--chain eth|bsc`, `--min-usd`, `--channel email|discord` (can repeat).
+Required: `--label`. Transfer alerts: `--token`, `--chain eth|bsc|base|hyperevm` (default eth), `--min-usd`, `--max-usd`, `--address 0x...` with `--address-role any|from|to` to watch ONE wallet, `--channel email webhook`.
+
+```bash
+# One wallet: every transfer it receives on base (no cooldown, no daily cap)
+vike-data alerts create --label "Treasury in" --chain base \
+  --address 0x1111111111111111111111111111111111111111 --address-role to --channel email
+```
+
+Hyperliquid alerts (`--type`; leave out `--chain`, `--address`, `--max-usd`; delivered by `--channel webhook`, or with no channel read them with `vike-data alerts events`):
+
+| `--type` | Fires on | Flags |
+|---|---|---|
+| `hl_wallet` | every fill of one wallet | `--wallet` (required), `--actions open close flip increase reduce`, `--token`, `--min-usd` |
+| `hl_cohort_fill` | fills by wallets in cohorts | `--pnl-cohorts "3x smart" ...` and/or `--size-cohorts "4x whale" ...` (one required), `--min-usd` >= 10000 (required) |
+| `hl_liquidation` | liquidations | optional `--wallet`, cohorts, `--token`, `--min-usd` |
+| `hl_cohort_bias` | a cohort index crossing a level | `--token` and `--index smi\|wsi\|smart_bias\|whale_bias\|smi_wsi_gap` (required), `--threshold`, `--band`, `--direction up\|down\|both` |
+| `hl_liq_proximity` | a wallet getting close to liquidation | `--wallet` (required), `--threshold` (0-1, default 0.8), `--band` |
+
+```bash
+vike-data alerts create --label "BTC smart money flips" --type hl_cohort_bias \
+  --token BTC --index smi --threshold 0 --band 0.1 --channel webhook
+```
 
 ### Edit (partial update — only fields you pass are changed)
 
 ```bash
 vike-data alerts edit 42 --min-usd 5000000          # raise threshold
 vike-data alerts edit 42 --active false             # pause
-vike-data alerts edit 42 --channel email --channel discord  # add second channel
+vike-data alerts edit 42 --channel email webhook    # both channels
+vike-data alerts edit 42 --address ''               # drop the wallet condition
+```
+
+### Events (what fired, and each delivery's status, kept 15 days)
+
+```bash
+vike-data alerts events --limit 50 --json           # page on with --cursor <next_cursor>
+vike-data alerts events --rule-id 42 --json
+vike-data alerts resend <delivery_id>               # send one delivery again
 ```
 
 ### Delete
@@ -54,10 +84,10 @@ vike-data alerts delete 42 --hard                   # permanently remove
 
 ## Notes + gotchas
 
-- Currently chains supported: **eth** and **bsc** only. For both, create two alerts.
-- **An alert watches a token, not an address.** It fires on ANY transfer of that token on that chain whose USD value crosses the thresholds. There is no wallet filter, so "alert me when whale 0xABCD sells" cannot be built: say so, and offer the token-wide alert or periodic `vike-data wallet transactions` checks instead. There are no price or funding alerts, and delivery is email, Discord or an HTTPS webhook (no Telegram).
+- Transfer chains: **eth**, **bsc**, **base**, **hyperevm**, one per alert. For several, create several alerts.
+- **A transfer alert watches a token, one wallet, or both.** Without `--address` it fires on ANY transfer of that token on that chain whose USD value crosses the thresholds. With `--address` it fires on every transfer that wallet sent (`from`), received (`to`) or either (`any`); without `--min-usd` that includes dust and unpriced tokens. "Alert me when whale 0xABCD sells" is `--address 0xABCD --address-role from`; on Hyperliquid it is `--type hl_wallet --wallet 0xABCD --actions close reduce`. There are no price or funding alerts, and delivery is email or an HTTPS webhook (Discord is off; no Telegram).
 - Thresholds are in **USD value** of the transfer at fire time, not token quantity.
-- `--cooldown` is per-alert minimum gap between triggers (default 60 min). Useful to avoid spam during high-volume hours.
+- `--cooldown` is the minimum gap between notifications of a token-wide transfer alert (default 60 min). Address alerts and Hyperliquid alerts notify on every event and ignore it.
 - Tokens are matched by symbol (UPPERCASE). For cross-chain symbols like `USDC` that exist on multiple chains, be explicit with `--chain`.
 - Alerts created without a verified channel will be **silently inactive at fire time** — there is no automatic warning. Use `vike-data alerts channels` first.
 

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

@@ -1,6 +1,6 @@
 ---
 name: vike-alerts-webhook
-description: Register an HTTPS webhook as an alert delivery channel — get HMAC-signed POST notifications when alerts fire. Use when the user has a server / bot / Slack integration and wants programmatic alert delivery instead of email/Discord.
+description: Register an HTTPS webhook as an alert delivery channel — get HMAC-signed POST notifications when alerts fire (the only channel for Hyperliquid alerts); test it, rotate its secret, resend a delivery. Use when the user has a server / bot / Slack integration and wants programmatic alert delivery instead of email.
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -29,7 +29,14 @@ vike-data alerts register-webhook https://api.mycoolbot.com/vike-alert \
 # → { "ok": true, "channel_id": 42, "url_preview": "https://api.myc...", "signed": true }
 ```
 
-Then create an alert and reference the channel — webhooks fire alongside email/discord. (Currently the `alerts create` flow doesn't accept channel IDs directly; webhooks fire if they're the user's enabled channels.)
+Then create an alert with `--channel webhook` (alongside `email` if wanted; a Hyperliquid alert takes the webhook only). Registration sends one signed `test` event at once; the channel id is in `vike-data alerts channels`.
+
+```bash
+vike-data alerts test-webhook <channel_id>     # send the signed test event again
+vike-data alerts rotate-secret <channel_id>    # new secret; the old one keeps signing for 24 hours
+vike-data alerts events --json                 # what fired, with each delivery's status
+vike-data alerts resend <delivery_id>          # send one delivery again (up to 15 days)
+```
 
 ## What we POST to your URL
 
@@ -49,10 +56,10 @@ X-Vike-Signature: t=1716658923,sig=a3f8b2c...
 import hmac, hashlib, time
 
 def verify(secret, headers, body):
-    sig_header = headers.get("X-Vike-Signature", "")
-    parts = dict(p.split("=", 1) for p in sig_header.split(","))
-    ts, sig = parts.get("t"), parts.get("sig")
-    if not ts or not sig:
+    ts = headers.get("X-Vike-Timestamp", "")
+    # During a secret rotation the header carries TWO sig= values: accept if ANY matches.
+    sigs = [p.split("=", 1)[1] for p in headers.get("X-Vike-Signature", "").split(",") if p.startswith("sig=")]
+    if not ts or not sigs:
         return False
     # Reject replays older than 5 min
     if abs(time.time() - int(ts)) > 300:
@@ -60,7 +67,7 @@ def verify(secret, headers, body):
     expected = hmac.new(
         secret.encode(), f"{ts}.{body.decode()}".encode(), hashlib.sha256
     ).hexdigest()
-    return hmac.compare_digest(expected, sig)
+    return any(hmac.compare_digest(expected, s) for s in sigs)
 ```
 
 ## Anti-patterns
@@ -76,7 +83,7 @@ def verify(secret, headers, body):
 2. Reject if `X-Vike-Timestamp` is more than ~5 min old (replay protection)
 3. Return `200` quickly; queue work async
 4. Log full body for unsigned-but-suspicious requests
-5. Rotate the secret if you suspect compromise — re-register a new channel
+5. Rotate the secret if you suspect compromise — `vike-data alerts rotate-secret <channel_id>`
 
 ## Pairs well with
 

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

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` on the token and wallet commands (`wallet discover` and `wallet balances` serve ethereum and bsc only; `wallet first-funder` and `exchange-usage` also take `hyperevm`; `alerts` takes `eth`, `bsc`, `base` or `hyperevm`). Base coverage is narrower than the flag suggests: documented for token transfers and `wallet batch`, not for the per-wallet transfer commands, so an empty Base result means "not covered". Non-EVM chains and Arbitrum are not served. Check `vike-data <cmd> --help` for the exact list.
 - Time windows: `24h`, `7d`, `30d`, `90d`, `all` (per command; check `vike-data <cmd> --help`). Windows are counted in UTC calendar days.
 
 ## Errors
@@ -56,6 +56,9 @@ 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
 

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]
 ```
 

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

@@ -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]
 ```
 
@@ -50,7 +50,7 @@ All `*_pct` fields are percents: `12.5` means 12.5%. (Before 2026-10-19 `roi_pct
 
 ## 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:
+Ask the wallet directly: `vike-data hl wallet <address> --json` (equity, open positions, cohort labels, risk metrics, lifetime flow) and `vike-data hl wallet <address> --view trades_summary --window 30d --json` (closed-trade statistics). `top-traders` cannot filter by address; to see where it ranks, scan the leaderboard for it:
 
 ```bash
 vike-data perp top-traders --window 30d --sort pnl --size 20 --json

package/skills/vike-perp-overview/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: Bash(vike-data:*)
 
 # vike-perp-overview
 
-One-shot market overview for perpetuals, plus the cross-venue price-gap tool. The overview is exactly what these three tools return: funding arbs, price gaps and the HL leaderboard. There is **no open-interest, market-wide volume or per-venue mark-price tool** in the CLI; say so if asked.
+One-shot market overview for perpetuals, plus the cross-venue price-gap tool. The overview is exactly what these three tools return: funding arbs, price gaps and the HL leaderboard. There is **no CEX open-interest, market-wide volume or per-venue mark-price command** in the CLI; say so if asked (Hyperliquid open interest is `vike-data hl market --json`).
 
 ## Price spreads
 

package/skills/vike-stream/SKILL.md

@@ -0,0 +1,98 @@
+---
+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.
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-stream
+
+```bash
+vike-data stream <hl|hl-cohorts|onchain|polymarket> --channel <channel...> [--filter key=value ...] [--cursor <cursor>]
+```
+
+Connects to `wss://stream.vike.io/v1/stream/<path>` with the API key in the `X-API-KEY` header, subscribes once per
+`--channel`, and prints one JSON object per line on stdout: every `event` frame and every `gap` frame, exactly as the
+server sent them. Status lines (subscribed, reconnecting, errors) go to stderr. It runs until Ctrl-C.
+
+| 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` |
+| `onchain` | `chain.transfers` |
+| `polymarket` | `pm.trades`, `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.
+
+`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).
+
+## Examples
+
+```bash
+# Hyperliquid BTC and ETH fills of $100k or more, by smart wallets
+vike-data stream hl --channel hl.fills --filter coin=BTC,ETH --filter min_usd=100000 --filter "pnl_cohort=3x smart,2x smart"
+
+# Live 1-minute and 1-hour BTC and ETH perp candles (closed bars)
+vike-data stream hl --channel hl.candles --filter coin=BTC,ETH --filter interval=1m,1h --filter market=perp
+
+# 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
+
+# Keep only the events, with jq
+vike-data stream polymarket --channel pm.trades --filter min_usd=10000 | jq -c 'select(.type == "event") | .event'
+```
+
+`--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
+
+## Without a socket
+
+These are MCP calls: they open no connection, so they never replace one.
+
+```bash
+vike-data stream info --json                                    # every path, channel, filter key, limit and close code
+vike-data stream check hl.fills --filter coin=BTC --filter min_usd=50000   # the server's own validator; exit 1 if refused
+vike-data stream events hl.liquidations --filter coin=BTC --since-ms 1793178870000 --json   # stored events (3 days), paged by --cursor
+vike-data stream connections --hours 24 --json                  # your recent connections: who closed whom (4410), events sent
+```
+
+Run `stream check` before a long-running `stream`: it shows the filter exactly as the server will apply it (with
+the `hl.fills` default `min_usd` of 1000 added) or the server's error naming the bad key.
+
+## Reading the output
+
+- Keep the **frame's** `cursor` (the top-level one, not `event.cursor`) of the last line you handled. `--cursor <it>`
+  on the next run resumes from there, up to 3 days back; older is `cursor_expired` and the stream continues from now.
+- The CLI resumes by itself after any drop (restart, network, slow reader) from the last cursor of each subscription.
+  Delivery is at least once: drop a repeated `event.event_id`.
+- A `gap` frame (`reason: channel_idle`) means the channel was not running between `from` and `to` (nobody was
+  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.
+
+## One connection per key
+
+On each path, one API key holds one connection; an account holds at most 3. A second program on the same key and
+path takes over, and the first exits with `replaced (4410)` and does not reconnect (two programs reconnecting would
+take the connection from each other forever). Give each program its own key (`VIKE_API_KEY=... vike-data stream ...`).
+`vike-data stream connections` shows which of your connections closed which.
+Exit 1 also on `HTTP 401` / `4401` (the key) and on a refused subscription (`bad_subscription`, `unknown_channel`).
+
+## Anti-patterns
+
+- 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`).
+- 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.

package/skills.sh.json

@@ -50,7 +50,7 @@
     },
     {
       "title": "Hyperliquid perps",
-      "description": "Top traders (and checking one address against the leaderboard) and share-card reverse-lookup.",
+      "description": "Top traders, one wallet's profile and activity, and share-card reverse-lookup; the `vike-data hl` commands are routed by the umbrella skill.",
       "skills": [
         "vike-hl-top-traders",
         "vike-hl-position-match"
@@ -75,11 +75,18 @@
     },
     {
       "title": "Alerts",
-      "description": "Create, list, edit, delete on-chain transfer alerts (USD thresholds per token); register HTTPS webhooks with HMAC delivery.",
+      "description": "Create, list, edit, delete transfer alerts (a token or one wallet, USD thresholds) and Hyperliquid alerts; read what fired; HTTPS webhooks with HMAC delivery.",
       "skills": [
         "vike-alerts-setup",
         "vike-alerts-webhook"
       ]
+    },
+    {
+      "title": "Live streams",
+      "description": "Hyperliquid, HL cohort, on-chain and Polymarket events as they happen over WebSocket, as NDJSON, resumed by cursor.",
+      "skills": [
+        "vike-stream"
+      ]
     }
   ]
 }