@vike-io/cli 0.13.1 → 0.15.0

package/skills/vike-candles/SKILL.md

@@ -21,9 +21,16 @@ vike-data candles hl <symbol>
   [--dex <name>]                        # HIP-3 builder DEX; default HL (the core venue)
   [--start <iso|epoch-ms>] [--end <iso|epoch-ms>]   # half-open [start, end)
   [--limit N]                           # default 500, max 5000
+  [--view export]                       # the same, limit defaults to 5000
   [--json]
+
+vike-data candles hl --view latest [--market perp|spot] [--dex <name>]   # the newest 1m bar of EVERY symbol
+                                                                         # that traded in the last hour (may still be forming)
 ```
 
+Live closed bars as they happen: `vike-data stream hl --channel hl.candles --filter coin=BTC,ETH --filter interval=1m`
+(also `market=perp|spot`, `dex=HL`; see `vike-stream`).
+
 Polymarket, ONE outcome token (a probability, 0-1):
 
 ```bash
@@ -41,7 +48,7 @@ vike-data candles polymarket <token_id>
 | "Hourly BTC perp candles, last week" | `vike-data candles hl BTC --interval 1h --limit 168` |
 | "HYPE spot daily candles" | `vike-data candles hl HYPE --market spot --interval 1d` |
 | "4h ETH, 200 bars" | `vike-data candles hl ETH --interval 4h --limit 200` |
-| "Price history of the YES outcome of market X" | get `clob_token_ids` from `vike-data polymarket market <condition_id>`, then `vike-data candles polymarket <token_id> --interval 1h` |
+| "Price history of the YES outcome of market X" | take the leg's `token_id` from `outcomes[]` in `vike-data polymarket markets` (or `clob_token_ids` in `vike-data polymarket market <condition_id>`), then `vike-data candles polymarket <token_id> --interval 1h` |
 
 ## Output
 
@@ -50,7 +57,7 @@ Polymarket: `ts`, `open`, `high`, `low`, `close`, `volume`, `trades`, oldest fir
 
 ## Pitfalls
 
-- Polymarket takes an **outcome token id**, not a `condition_id`. A condition id returns nothing useful; read the token ids off `clob_token_ids` in `vike-data polymarket market`.
+- Polymarket takes an **outcome token id**, not a `condition_id`. A condition id returns nothing useful; read the token ids off `outcomes[].token_id` in `vike-data polymarket markets` or `clob_token_ids` in `vike-data polymarket market`.
 - Polymarket has no cursor: a window wider than `--limit` is truncated at the **old** end. Raise `--from` to reach the recent end.
 - Polymarket `--from` / `--to` are epoch **milliseconds**; HL `--start` / `--end` also accept ISO-8601.
 - HL buckets are left-aligned UTC and the window is half-open.

package/skills/vike-core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vike-core
-description: Install-first skill — authentication, setup, and CLI conventions for the vike toolkit. Use when you see any `vike-data <cmd>` reference or the user mentions on-chain analytics, Hyperliquid perps, options flow, or prediction markets.
+description: Install-first skill — authentication, setup, and CLI conventions for the vike toolkit. Use when you see any `vike-data <cmd>` reference or the user mentions on-chain analytics, Hyperliquid perps, or prediction markets.
 metadata:
   openclaw:
     requires:
@@ -37,9 +37,9 @@ Get an API key at https://vike.io/account?tab=api-keys
 ## Verify
 
 ```bash
-vike-data doctor                        # Node version + API key + endpoint reachability + tool count
-vike-data whoami                        # which key is in use (masked)
-vike-data schema --pretty               # full command list with flags
+vike-data doctor                        # Node version + API key (masked, with its source) + endpoint reachability + tool count
+vike-data schema --pretty               # every MCP tool with its parameters
+vike-data --help                        # command list; add --help to any command for its flags
 ```
 
 ## Conventions
@@ -47,21 +47,25 @@ vike-data schema --pretty               # full command list with flags
 - 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: `eth`, `bsc`, `base`, `arb`, `hyper`, `btc`, `sol`, `tron`, `xmr`, `zec`, `dash` (depending on the command — some only support a subset).
-- Time windows: `24h`, `7d`, `30d`, `90d`, `all` (per command; check `vike-data <cmd> --help`).
+- 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
 
 - `No API key` → run `vike-data init` or set `VIKE_API_KEY`.
-- `MCP error -32000: Hourly rate limit exceeded` → you hit the per-key cap; wait or upgrade your plan.
-- `Network error` / timeout → check `vike-data doctor`; the endpoint is `https://vike.io/mcp`.
+- `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
 
-Each tool call consumes credits against your API key quota. Cheap calls: `token search`, `wallet summary`, `alerts list`. Heavier: `wallet discover`, `hl_perp_top_traders` (large result sets).
+Credits are an accounting figure on each call and never block one. The limit is 20,000 requests per rolling hour per key, shared by the MCP server and the REST API. Free (0 credits): `token search`, `alerts list`, `alerts channels`. Heaviest: `wallet trace` (4), then `token screener`, `wallet compare`, `wallet balances` (3).
 
-## When to use a router skill vs a task skill
+## Which skill to use
 
-- **Router skills** (`vike-router`, topic-level) — when the user is exploring or unsure which command they need.
-- **Task skills** (`vike-smart-money-discovery`, `vike-perp-funding-arb`, etc.) — when the user has a specific question that maps to a known workflow.
+- The umbrella skill `vike` holds the routing table — use it when the user is exploring or unsure which command they need.
+- Task skills (`vike-smart-money-discovery`, `vike-perp-funding`, etc.) — when the user has a specific question that maps to a known workflow.
+- If unsure between two, prefer the task skill (a workflow) over the per-tool skill (one command). For raw data, use the per-tool skill with `--json`.

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

@@ -12,12 +12,12 @@ Find the wallet(s) holding an open Hyperliquid perp position that match a share
 
 ```bash
 vike-data perp find-position
-  --coin <SYM>         # e.g. BTC, ETH, SOL
+  --coin <SYM>         # the asset symbol, e.g. BTC, ETH, SOL (sent to the tool as `symbol`)
   --side long|short
   --leverage <X>       # e.g. 25
   --entry <PRICE>      # entry price from the card
   [--mark <PRICE>]     # current mark price — sharpens tie-break when multiple wallets share entry
-  [--limit N]          # max matches, default 10, max 50
+  [--limit N]          # max matches, default 50, max 500
   [--json]
 ```
 
@@ -49,11 +49,11 @@ The response includes `tolerance_used` so the caller knows which band matched (`
 {
   "match_count": 3,
   "tolerance_used": "tight",          // tight | loose | fallback | no_match
-  "query": { "coin": "ETH", "side": "long", "leverage": 25, "entry_price": 3210, "mark_price_hint": 3215 },
+  "query": { "symbol": "ETH", "side": "long", "leverage": 25, "entry_price": 3210, "mark_price_hint": 3215 },
   "matches": [
     {
       "address": "0x...",
-      "coin": "ETH", "side": "long",
+      "symbol": "ETH", "side": "long",
       "snapshot_ts": 1716700000,       // unix seconds — how fresh the snapshot is
       "size_token": 12.5, "size_usd": 40250,
       "entry_price": 3209.8, "mark_price": 3215.3,
@@ -71,16 +71,16 @@ The response includes `tolerance_used` so the caller knows which band matched (`
 - **Multiple matches at the exact same entry** (e.g. five wallets long ETH at 3210.00) — popular round-number entries collide. Treat as ambiguous; surface all and let the user disambiguate by size or address. Don't claim "this is the wallet" when `match_count > 1` in the tight band.
 - **`tolerance_used: fallback`** — the closest match is >0.5% off the queried entry. The card might be from a previous fill that's since been added to (size-weighted entry moves on add) or from a different exchange. Treat as low-confidence.
 - **`tolerance_used: no_match`** — the position is closed, the entry was from a margin-changing event, or the wallet was outside our HL coverage. Don't suggest a wallet anyway.
-- **`snapshot_ts`** is the snapshot time of that position row. The pipeline refreshes <5 min behind live; older `snapshot_ts` doesn't mean the position is stale, just that the wallet hasn't transacted since.
+- **`snapshot_ts`** is the snapshot time of that position row. Only positions seen within 15 minutes of the newest snapshot batch are matched (older rows are ghosts of closed positions), so a match is a position that was open in the last quarter hour; it does not mean the position is still open now.
+- **Response keys:** each match and the `query` block name the asset `symbol`. Servers before 2026-10-19 called it `coin` (or `asset`) and renamed it on 2026-10-19, so read `symbol` and fall back to `coin` if it is missing.
 
 ## Anti-patterns
 
 - Don't fabricate matches when the tool returns `match_count: 0`. Say "no open position matches that share card" — closed positions, post-card adds, or non-HL cards all produce empty results.
 - Don't strip the address when displaying — share-card investigations always want the full 0x...40hex (users copy-paste it).
-- Don't infer trader skill from a single share-card match. Use `vike-data perp top-traders` or `vike-data wallet summary` for profile context.
+- Don't infer trader skill from a single share-card match. Use `vike-data perp top-traders` for leaderboard context (see `vike-hl-top-traders` for what it can and cannot say about one address).
 
 ## Pairs well with
 
-- `vike-wallet-summary` — once you have the address, get the trader's HL profile + multi-chain identity.
-- `vike-hl-top-traders` — check if the matched wallet is on a leaderboard.
+- `vike-hl-top-traders` — check if the matched wallet is on a leaderboard. (`vike-data wallet summary` has no Hyperliquid data: it shows on-chain transfer activity on one chain only.)
 - `vike-wallet-label-provenance` — find out if the wallet is a known CEX/fund/MM rather than a retail trader.

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

@@ -1,6 +1,6 @@
 ---
 name: vike-hl-top-traders
-description: Rank top Hyperliquid perp traders by PnL / ROI / win rate / volume / trade count / drawdown across a window. Use when the user asks "top HL traders" / "best Hyperliquid wallets" / "HL leaderboard".
+description: Rank top Hyperliquid perp traders by PnL / ROI / win rate / volume / trade count / drawdown across a window, and check whether one HL address is on that leaderboard. Use when the user asks "top HL traders" / "best Hyperliquid wallets" / "HL leaderboard" / "is this trader any good" / "profile this address" / "what's this wallet's HL track record".
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -13,10 +13,10 @@ vike-data perp top-traders
   [--window 1d|7d|30d|all]
   [--sort pnl|roi|win_rate|volume|trade_count|drawdown]
   [--order asc|desc]
-  [--min-trades N]      # default 3
-  [--min-win-rate P]    # 0-100 percent
+  [--min-trades N]       # default 3; 0-2 are treated as 3
+  [--min-win-rate P]     # percent, 0-100
   [--min-volume USD]
-  [--size N]            # max 20
+  [--size N]             # default 20, max 100
   [--json]
 ```
 
@@ -30,23 +30,58 @@ vike-data perp top-traders
 | "Most active traders today" | `--window 1d --sort trade_count` |
 | "Smallest drawdown winners" | `--sort drawdown --order asc --min-trades 20` |
 
-## Output columns
+## Output
 
-`address`, `pnl_usd`, `roi_pct`, `win_rate_pct`, `volume_usd`, `trade_count`, `max_drawdown_usd`.
+An object `{ "traders": [...], "total": N }`; each trader:
+
+`address`, `total_realized_pnl` (USD), `roi_pct`, `win_rate_pct`, `long_win_rate_pct`, `short_win_rate_pct`, `win_count`, `loss_count`, `trade_count`, `total_volume` (USD), `long_pnl`, `short_pnl`, `max_drawdown_pct`, `account_value` (USD), `avg_leverage`.
+
+All `*_pct` fields are percents: `12.5` means 12.5%. (Before 2026-10-19 `roi_pct` and `max_drawdown_pct` came back 100× too large; a transcript showing a 1,750% ROI is from that period.) `avg_leverage` is not populated (reads 0): ignore it. There is no `pnl_usd` and no `max_drawdown_usd`.
 
 ## Reading
 
-- `roi_pct` here is **realized + unrealized** (uses live position marks).
+- **`roi_pct` is realized only.** It is the window's realized PnL divided by the wallet's CURRENT account value. Open positions are not counted, and a wallet that has since withdrawn most of its equity looks better than it was (and a recent deposit makes it look worse).
+- **`max_drawdown_pct` is account-level and all-time**, built from the account's hourly equity history. It does not change with `--window`.
+- **Windows are UTC days:** `1d`, `7d`, `30d` mean today plus the previous 1, 7 or 30 days; `all` is the last 365 days.
+- **`trade_count` counts completed trades only**, filed under the UTC day the position opened. A trade still open, or opened before the window and closed inside it, is not counted, so a wallet's count here differs from a per-wallet trade summary (which counts both).
 - A wallet with 90% win rate on 4 trades is statistical noise. Min trades 10–20 for any "skill" claim.
 - Top by PnL ≠ top by ROI. Whales win big in $ but small in % terms; ROI sort surfaces smaller-account discretionary skill.
-- `max_drawdown_usd` is peak-to-trough realized — does NOT include unrealized intra-position drawdown.
+- The leaderboard rewards survivors: wallets that blew up don't appear, so the PnL distribution is right-skewed.
+
+## Is this specific address any good?
+
+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
+vike-data perp top-traders --window 7d  --sort pnl --size 20 --json
+vike-data perp top-traders --window 30d --sort roi --min-trades 10 --size 20 --json
+vike-data perp top-traders --window 30d --sort win_rate --min-trades 10 --size 20 --json
+```
+
+- **Found** → report that row for that window and sort (all columns above). That is the whole profile you can give.
+- **Not found** → say "not in the top 20 for this window and sort". Only the top 20 of thousands of wallets ever shows, so absence says nothing about quality.
+- `vike-data wallet summary` has **no Hyperliquid data** (it reads on-chain transfers on one chain): don't present it as the HL profile. `vike-data labels <addr>` shows whether the address is a known entity.
+- The REST API has per-wallet Hyperliquid routes (`/v1/hyperliquid/wallets/{address}`, `.../trades/summary`), but no CLI command or MCP tool exposes them yet. Say so if the user needs fills, funding or per-trade history.
+
+Classification of a found wallet:
+
+| Pattern | Label |
+|---|---|
+| Top-20 PnL + high ROI + many trades + low drawdown | **Sharp** |
+| Top-20 PnL + low ROI + huge volume | **Whale** (size matters more than skill) |
+| High win rate on <10 trades | **Unverified — too few data points** |
+| One big trade dominates PnL (`win_count` small, PnL large) | **One-shot** (lucky directional bet) |
 
 ## Anti-patterns
 
 - Don't claim a wallet is "the best HL trader" from a 1d window. Anything < 30d is short-term.
-- The leaderboard rewards survivors — wallets that blew up don't appear, so PnL distribution is right-skewed survivorship bias.
+- Don't claim "this is one of the best HL traders" from win rate alone — need volume + trade count for context.
+- Pass an exact `--sort` value: a typo is not rejected, it silently falls back to a PnL ranking.
+- Don't describe a wallet outside the top 20 as bad.
 
 ## Pairs well with
 
-- `vike-hl-trader-profile` to drill into a specific address from the leaderboard
-- `vike-perp-funding-arb` to see if leaders are positioned against funding
+- `vike-hl-position-match` to find the wallet behind a share card first
+- `vike-perp-funding` to see whether the leaders are positioned against funding
+- `vike-candles` for the price action behind a period of PnL

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

@@ -0,0 +1,82 @@
+---
+name: vike-perp-funding
+description: Perpetual-futures funding rates across CEX venues and Hyperliquid — the top cross-venue funding-arb opportunities, and the per-venue funding of one symbol. Use when the user asks "any funding arb today" / "where to long-short X for funding" / "highest funding rates" / "where to trade X" / "compare BTC perp across exchanges" / "best venue for ETH long".
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-perp-funding
+
+Funding rates across the CEX venues and Hyperliquid, from one tool (`perp funding`) in two modes. The rows name the exchange; there is no mark price and no bid/ask in either mode.
+
+## Commands
+
+### A. Arb opportunities (no symbol)
+
+```bash
+vike-data perp funding --json
+```
+
+Returns **at most 5** pre-ranked rows where the spread between the highest-funding and the lowest-funding venue is ≥ 0.3% per day (spreads of more than ~10% per day are dropped as artifacts). Each row:
+- `symbol`
+- `long_exchange`, `long_daily_pct` (the venue to be long: lowest funding)
+- `short_exchange`, `short_daily_pct` (the venue to be short: highest funding)
+- `spread_daily_pct`
+
+**These are pre-ranked and already normalised to daily % — cite the rows directly.** The list is a short top-5, not a full-market scan.
+
+### B. One symbol, every venue
+
+```bash
+vike-data perp funding --symbol BTC --json
+```
+
+One row per venue: `exchange`, `symbol`, `funding_rate`, `interval_h`, `next_ts`, `vol_24h_usd`.
+
+`funding_rate` is the **raw per-interval rate as a fraction** (0.0001 = 0.01% per interval) and venues use different intervals (`interval_h`: Hyperliquid 1h, most CEXs 8h). **Normalise yourself before comparing venues:**
+
+```
+daily_pct = funding_rate × (24 / interval_h) × 100
+annualised_pct = daily_pct × 365
+```
+
+`vol_24h_usd` is the venue's 24h perp notional: use it as the liquidity check.
+
+## Venue comparison (one symbol)
+
+Run B, normalise, then report:
+
+> **`<SYM>` perp — funding by venue**
+>
+> | Venue | Funding per interval | Interval | Daily % | 24h volume |
+> |---|---|---|---|---|
+> | ... | ... | ... | ... | ... |
+>
+> **Best venue to long**: `<X>` (lowest daily funding, i.e. longs pay least or receive)
+> **Best venue to short**: `<Y>` (highest daily funding, i.e. shorts receive most)
+> **Funding edge**: long-short = X%/day, gross
+
+- Positive funding → longs pay shorts: a good place to be short. Negative → shorts pay longs: a good place to be long.
+- A divergence above 0.5%/day between two venues with similar liquidity is an edge worth quantifying.
+
+## Reading the arb
+
+```
+spread_daily_pct = 0.42%   →  ~$420/day per $100k notional per leg, gross
+                              (before fees, slippage, margin and transfer costs)
+```
+
+A funding arb at 0.4–1% daily is real. Anything much higher on a liquid pair is usually a halted market or a venue artifact: check `vol_24h_usd` in mode B for both venues before calling it a trade.
+
+## Anti-patterns
+
+- Don't quote a daily funding rate as "annualized" without converting (× 365). Be explicit about the unit.
+- Funding flips every 1–8 hours depending on the venue. The number is the current rate, not a forecast — don't extrapolate without saying so.
+- Spread < 0.3% daily is filtered out at the source (not enough to cover fees + execution). Don't try to lower the filter.
+- Don't blindly pick the lowest-funding venue without checking `vol_24h_usd` — Hyperliquid funding looks great on small alts but the book can be thin.
+- Don't read `funding_rate` of an 8h venue against a 1h venue without normalising.
+- Don't promise a price comparison from this tool: for price gaps across venues use `vike-perp-overview` (`perp spreads`).
+
+## Pairs well with
+
+- `vike-perp-overview` for cross-venue price gaps and the market snapshot
+- `vike-hl-top-traders` to see how Hyperliquid's best traders are doing

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

@@ -0,0 +1,69 @@
+---
+name: vike-perp-overview
+description: Perp-market snapshot and cross-venue price spreads — the top funding arbs, the widest perp price gaps between venues, and the Hyperliquid leaderboard in one read. Use when the user asks "what's happening in perps today" / "perp market overview" / "any perp arb today" / "price differences across exchanges" / "where's X cheapest".
+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 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
+
+```bash
+vike-data perp spreads --json                 # up to 10 symbols with a cross-venue price gap >= 0.5%
+vike-data perp spreads --symbol BTC --json    # the same list, filtered to one symbol
+```
+
+Rows: `symbol`, `buy_exchange`, `buy_price`, `sell_exchange`, `sell_price`, `spread_pct`. Pre-ranked: cite the rows directly.
+
+- **"Spread" is perp vs perp across venues, not spot vs perp.** `buy_exchange` is the cheapest venue and `sell_exchange` the dearest for that symbol.
+- **`--symbol` only filters the global top 10.** An empty answer means the symbol is not among today's widest gaps, not that its venues agree. Don't answer "where's X cheapest" from an empty result; say the tool only lists the 10 widest gaps.
+- Outliers (> 400 bps off the cross-venue median) are filtered upstream — typically unit-mismatch listings like `1000SHIB` vs `SHIB`, or stale prices.
+- It reads the latest ticker snapshots: a row is a current snapshot, not a forecast.
+
+`spread_pct = 0.7%` on a liquid pair is an opportunity **before** taker fees, slippage and the time to move inventory between venues. For the funding side of the same trade use `vike-perp-funding`.
+
+## Market snapshot (3 parallel calls)
+
+```bash
+vike-data perp funding --json &              # top funding-arb opportunities (max 5)
+vike-data perp spreads --json &              # widest cross-venue price gaps (max 10)
+vike-data perp top-traders --window 1d --sort pnl --size 10 --json &   # HL leaderboard
+wait
+```
+
+### Report template
+
+> **Perp market snapshot (HL leaderboard: today and yesterday, UTC)**
+>
+> **Top funding arbs (>0.3% daily spread)**
+> - `BTC`: long Bybit @ -0.5%/d, short Hyperliquid @ +0.8%/d → spread 1.3%/d
+> - ...
+>
+> **Widest cross-venue price gaps (>0.5%)**
+> - `SOL`: buy Aster @ 138.20, sell OKX @ 139.05 → 0.61%
+> - ...
+>
+> **Top HL traders, last 1d (by realized PnL)**
+> - `0xabc...` +$X (`total_realized_pnl`), ROI Y%, rank #1 — ...
+> - ...
+
+## When to skip the 3-call snapshot
+
+- User asked about one symbol's funding or venues → `vike-perp-funding`.
+- User asked about one HL trader → `vike-hl-top-traders`.
+- User only wants price gaps → run `perp spreads` alone.
+
+## Anti-patterns
+
+- Don't quote funding rates in 8h chunks when the tool returns daily % — be consistent (daily %).
+- Don't present a price gap as "free money" without fees / transfer time.
+- Trading 1000-token-suffix pairs without normalizing — `1000PEPE` on Binance ≠ `PEPE` on Bybit; if the spread looks insane it's probably this.
+- "Top by PnL today" is noise for swing-trader narratives; only useful for "who's hot right now". Use 7d or 30d for skill claims, and remember `1d` covers today plus the previous UTC day, not a rolling 24 hours.
+- Don't present the top-traders list as "the best traders": the leaderboard rewards survivors.
+
+## Pairs well with
+
+- `vike-perp-funding` for the funding deep dive and one-symbol venue comparison
+- `vike-hl-top-traders` for the leaderboard filters and how to read its columns

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

@@ -39,4 +39,5 @@ vike-data polymarket market 0x1234abcd...
 ## 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-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

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

@@ -9,10 +9,10 @@ allowed-tools: Bash(vike-data:*)
 ## Command
 
 ```bash
-vike-data polymarket markets [--category C] [--limit N] [--json]
+vike-data polymarket markets [--category C] [--limit N] [--json]     # limit default 10, max 30
 ```
 
-`C` is one of: `Crypto`, `Sports`, `Politics`, `Pop-Culture`, `Tech`, `all` (default).
+`C` is one of: `Crypto`, `Sports`, `Politics`, `Pop-Culture`, `Tech`, `all` (default). Names are exact.
 
 ## Examples
 
@@ -22,23 +22,28 @@ vike-data polymarket markets --category Politics --limit 20
 vike-data pm markets --json                    # `pm` alias
 ```
 
-## Output columns
+## Output
 
-`condition_id`, `slug`, `question`, `end_date`, `market_vol_24h` (USD), `liquidity`, plus per-outcome `outcome` / `mid` / `bid` / `ask` for both Yes and No legs.
+One row per market, ranked by **24h volume only** (there is no liquidity or volatility ranking):
+
+`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.
 
 ## Reading the data
 
 - `mid` is the midpoint price as a probability (0.0 to 1.0). `0.42` means "the market thinks 42% chance".
 - A bid/ask spread > 0.05 (5 cents) = thin liquidity; the price is noisier.
-- `end_date` is when the market resolves. Sort priority for action-oriented users: markets ending in the next 7 days.
+- `end_date` is when the market resolves. Sort priority for action-oriented users: markets ending in the next 7 days. Check `ended`: a market that closed earlier today can still rank by its 24h volume.
 
 ## Anti-patterns
 
 - Don't quote `mid` as a percentage without saying so. "Yes is 0.42" is the raw probability; "42% chance" is the user-friendly translation.
 - For tiny markets (<$50k 24h volume) the quotes are often stale or one-sided. Skip them unless explicitly asked.
+- Don't call a list of markets "what smart money is doing": for that use `polymarket smart-money`.
 
 ## Pairs well with
 
 - `vike-polymarket-market-detail` — deep-dive on one market once you have its condition_id
-- `vike-polymarket-smart-money` — see which markets cohort wallets are buying/selling
-- `vike-polymarket-screener` — composite multi-call screener
+- `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

@@ -1,20 +1,18 @@
 ---
 name: vike-polymarket-smart-money
-description: Smart-money signals on Polymarket. Two modes — flows (markets with largest net cohort inflow) or mispricings (markets where cohort bought meaningfully below current mid). Use when the user asks "what is smart money buying on Polymarket" or "any prediction-market alpha".
+description: Smart-money signals on Polymarket, plus a one-pass market overview. Two modes — flows (markets with largest net cohort inflow) or mispricings (markets where the cohort bought meaningfully below the current mid); the overview combines them with trending markets. Use when the user asks "what is smart money buying on Polymarket", "any prediction-market alpha", "give me a Polymarket overview" or "what's happening in prediction markets today".
 allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-polymarket-smart-money
 
-The "smart-money cohort" is wallets meeting all three criteria:
-- ≥ $1,000 lifetime realized PnL
-- ≥ 5 resolved markets (so hit-rate is meaningful)
-- ≥ $5,000 lifetime volume
+The "smart-money cohort" is the set of wallets with at least $1,000 of realized PnL, at least 5 resolved markets and at least $5,000 of volume. The tool reports what that cohort is doing **in markets**. It does not return a list of top traders: for one trader use `vike-polymarket-trader`.
 
 ## Command
 
 ```bash
 vike-data polymarket smart-money --mode flows|mispricings [--hours N] [--category C] [--limit N] [--json]
+# --hours 1-720 (default 24); --limit default 10, max 20; category names are exact
 ```
 
 ## Mode A — flows (default)
@@ -23,10 +21,9 @@ vike-data polymarket smart-money --mode flows|mispricings [--hours N] [--categor
 vike-data polymarket smart-money --mode flows --hours 24 --category all
 ```
 
-Markets with the largest **net buy** from cohort wallets in the last N hours.
-`net_flow = buy_inflow - sell_outflow`. Useful for "where is smart money concentrating today".
+Markets with the largest **net buy** from cohort wallets in the last N hours. `net_inflow = buy_inflow − sell_outflow`, in dollars (not shares). Useful for "where is smart money concentrating today".
 
-Output: `condition_id`, `title`, `slug`, `smart_wallets` (cohort count), `buy_inflow_usd`, `sell_outflow_usd`, `trades`, `latest_yes_mid`.
+Output: `condition_id`, `title`, `slug`, `smart_wallets` (cohort count), `buy_inflow`, `sell_outflow`, `net_inflow`, `trades`, `last_ts`, `yes_mid` (null when the market has no recorded mid: absent data, not zero). Best first by `net_inflow`.
 
 ## Mode B — mispricings
 
@@ -34,25 +31,53 @@ Output: `condition_id`, `title`, `slug`, `smart_wallets` (cohort count), `buy_in
 vike-data polymarket smart-money --mode mispricings --hours 24 --category Crypto
 ```
 
-Markets where cohort wallets recently bought meaningfully **below** the current mid — i.e. the market has moved away from where cohort got their fills.
+Markets where cohort wallets recently bought meaningfully **below** the current mid — the market has since moved toward the cohort's entry. A market appears only if the cohort put in at least $500 and the mid is at least 0.03 in their favour.
 
-Output: `condition_id`, `title`, `slug`, `side` (Yes or No), `smart_avg_buy`, `current_mid`, `delta_pct`, `smart_buy_usd`.
+Output: `condition_id`, `title`, `slug`, `smart_wallets`, `last_buy_ts`, `total_buy_value`, `side`, `avg_buy_price`, `current_mid`, `delta`, `buy_value`. Best first by `delta`.
 
-`delta_pct > 5` = cohort got in 5+ cents better than current. Potential edge if you think cohort was right.
+- `delta = current_mid − avg_buy_price` for the side they bought, as a probability difference (0.05 = 5 cents). It records where the cohort was early; it is not a forecast.
+- `side` is `YES` (the first outcome) or `NO` (the second), not literally Yes/No: on a two-team or Over/Under market take the names from the market.
+
+## Market overview (3 parallel calls)
+
+For "give me a Polymarket overview" / "what's happening in prediction markets today":
+
+```bash
+vike-data polymarket markets --category all --limit 10 --json &
+vike-data polymarket smart-money --mode flows --hours 24 --json &
+vike-data polymarket smart-money --mode mispricings --hours 24 --json &
+wait
+```
+
+> **Polymarket snapshot (last 24h)**
+>
+> **Top 5 trending markets by volume**
+> - `<question>` — Yes mid `<m>` (from `outcomes[]`), `volume_24h` `$X` — ends `<end_date>`
+>
+> **Top 5 smart-money inflows**
+> - `<title>` (`<slug>`) — `<smart_wallets>` cohort wallets, `net_inflow` `$X`, `yes_mid` `<m>`
+>
+> **Top 5 mispricings**
+> - `<title>` (`<side>`) — cohort `avg_buy_price` `<p>`, `current_mid` `<m>`, `delta` `<d>`, `buy_value` `$X`
+
+Trim aggressively if the user asked a narrower question. About 5 credits for the three calls.
 
 ## Reading
 
 - **Flows**: high net inflow + low `smart_wallets` count = concentrated bet (few wallets, big size). Higher conviction signal than diffuse inflow across 50 wallets.
-- **Mispricings**: high `delta_pct` is interesting only when paired with cohort that has a history in that category. Cross-check with `vike-polymarket-trader` on the top wallets.
+- **Mispricings**: a large `delta` is interesting only when paired with a cohort that has a history in that category. Cross-check with `vike-polymarket-trader` on the top wallets.
+- **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.
 
 ## 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.
 - Mispricings can be slow-to-resolve. A 5% mispricing on a market resolving in 3 months might be efficient pricing for tail risk, not edge.
 - Don't combine the cohort definition with strict ROI filters — the cohort is built on realized PnL, not Sharpe.
+- Don't report all three overview sections if the user asked a narrower question; trending markets that closed earlier today still rank by 24h volume, so check `ended` / `end_date` before recommending a position.
 
 ## Pairs well with
 
+- `vike-polymarket-markets` — the trending list without the cohort view
 - `vike-polymarket-market-detail` — drill into a flagged market
 - `vike-polymarket-trader` — profile the top wallets active in flagged markets
-- `vike-polymarket-screener` — full multi-call market scan

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

@@ -1,6 +1,6 @@
 ---
 name: vike-polymarket-trader
-description: Profile a Polymarket wallet — realized PnL across 24h / 7d / 30d / all, hit-rate on resolved markets, total volume, top categories traded, recent positions. Use when the user gives a Polymarket wallet address.
+description: Profile a Polymarket wallet — realized PnL over a window, hit-rate on resolved markets, total volume, top categories traded, recent trades and open positions. Use when the user gives a Polymarket wallet address.
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -21,35 +21,38 @@ vike-data pm wallet 0xabcdef1234... --json     # `pm` alias
 
 ## Output
 
-Per-wallet summary:
-- `realized_pnl_usd` (lifetime + windowed)
-- `hit_rate_pct` (resolved markets only)
-- `resolved_markets` (count — denominator for hit_rate)
-- `volume_all_usd`, `volume_<window>_usd`
-- `trades_all`, `trades_<window>`
-- Category breakdown (Crypto/Sports/Politics/etc.)
-- Last seen timestamp
+Per-wallet profile (`--window` defaults to `all`):
+
+- `realized_pnl_usd`, `resolved_markets`, `hit_rate`, `hit_rate_ci`: scoped to the window, cut by **resolution** time (only markets that resolved inside the window count)
+- `trades_window`, `volume_window_usd`: scoped to the window, cut by trade time
+- `trades_all`, `volume_all_usd`, `avg_trade_usd`, `markets_count`, `first_seen`, `last_seen`: lifetime
+- `markets` (max 30), `trades` (max 100), `open_positions` (max 30), `open_exposure_usd`, `equity_curve`, `category_breakdown`, `daily_activity`, `correlated`, `tags`, `streak`: not window-scoped
+
+There is no `hit_rate_pct`, `volume_<window>_usd` or `trades_<window>` field.
 
 ## Reading
 
+- **`hit_rate` is a fraction (0.41 = 41%) and volume-weighted, not a count of wins.** It is the share of the wallet's resolved dollar volume that sat in markets where it made money, so an integer number of won markets will not reproduce it. `hit_rate_ci` is its confidence half-width: with few resolved markets it is wide, so don't rank on the point value.
+- **`realized_pnl_usd` is realized only.** An open position adds nothing until its market resolves; markets resolved invalid are excluded.
+- `open_positions` and `open_exposure_usd` understate: positions without a recent quote are left out.
+- Zeros in a window (`trades_window: 0`, `realized_pnl_usd: 0`) mean "nothing resolved in this window", not "no activity".
+
 | Pattern | Read |
 |---|---|
-| `hit_rate_pct > 60` with `resolved_markets > 20` | **Skilled** — consistent over a real sample |
-| `hit_rate_pct > 80` with `resolved_markets < 10` | **Lucky — too few data points** |
-| Positive PnL but `hit_rate_pct < 50` | **Asymmetric bettor** — wins big when right, loses small |
+| `hit_rate` > 0.60 with `resolved_markets` > 20 | **Skilled** — consistent over a real sample |
+| `hit_rate` > 0.80 with `resolved_markets` < 10 | **Lucky — too few data points** |
+| Positive PnL but `hit_rate` < 0.50 | **Asymmetric bettor** — wins big when right, loses small |
 | Negative PnL with high volume | **Volume trader / MM-style** — pays the spread |
-| One category dominates >80% of activity | **Specialist** — only trust their reads in that category |
-
-## Hit-rate caveat
-
-`hit_rate_pct` is computed only on **resolved** markets. A wallet with 100 trades but only 5 resolved has a hit_rate based on those 5. Always inspect `resolved_markets` before quoting hit_rate.
+| One category dominates >80% of `category_breakdown` | **Specialist** — only trust their reads in that category |
 
 ## Anti-patterns
 
-- Don't claim "this trader is good at predictions" from <10 resolved markets. Below that, hit_rate is noise.
-- Multi-category specialists are rare. If the wallet trades 5+ categories, treat hit_rate as a generic "good at probabilities" signal, not "deep edge".
+- Don't claim "this trader is good at predictions" from <10 resolved markets. Below that, `hit_rate` is noise.
+- Always read `resolved_markets` before quoting `hit_rate`: a wallet with 100 trades but only 5 resolved has a hit rate based on those 5.
+- Multi-category specialists are rare. If the wallet trades 5+ categories, treat `hit_rate` as a generic "good at probabilities" signal, not "deep edge".
+- A wallet with no recorded trades is refused with an error, not an empty profile.
 
 ## Pairs well with
 
 - `vike-polymarket-market-detail` — see which markets they're currently in
-- `vike-polymarket-smart-money` — confirm they're in the smart-money cohort
+- `vike-polymarket-smart-money` — whether the profitable-wallet cohort is moving in the same markets