@vike-io/cli 0.13.1 → 0.15.0

package/skills/vike/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: vike
-description: "Use this skill whenever the user asks any question about on-chain crypto data, wallet behavior, token transfers, smart money, CEX perpetual futures, Hyperliquid perps, prediction markets (Polymarket), ENS, or on-chain flows — and live data from vike.io would improve the answer. This includes questions like \"who is buying X token\", \"what is wallet 0x... doing\", \"top wallets by PnL\", \"funding rate spread across Binance/Bybit/OKX\", \"largest HL perp traders this week\", \"who is winning on Polymarket\", \"resolve this ENS\", \"label this wallet\", \"trace this transfer\", \"top tokens by smart-money inflow\". Always use this skill proactively when the user's query could benefit from real-time or historical on-chain data — don't wait for the user to explicitly ask to \"use vike\". If the user asks a general on-chain question that requires synthesis across wallets/tokens/venues, route to vike first."
+description: "Use this skill whenever the user asks any question about on-chain crypto data, wallet behavior, token transfers, smart money, CEX perpetual futures, Hyperliquid perps, prediction markets (Polymarket), ENS, or on-chain flows — and live data from vike.io would improve the answer. This includes questions like \"who is buying X token\", \"what is wallet 0x... doing\", \"top wallets by PnL\", \"funding rate spread across Binance/Bybit/OKX\", \"largest HL perp traders this week\", \"who is winning on Polymarket\", \"what is the ENS name of this address\", \"label this wallet\", \"trace this transfer\", \"top tokens by smart-money inflow\". It is also the entry point that decides which vike-* skill answers a question (tokens, wallets, labels, perps, Hyperliquid, Polymarket, candles, alerts). Always use this skill proactively when the user's query could benefit from real-time or historical on-chain data — don't wait for the user to explicitly ask to \"use vike\". If the user asks a general on-chain question that requires synthesis across wallets/tokens/venues, route to vike first."
 ---
 
-# vike — Multi-chain On-chain Analytics
+# vike — on-chain, perps and prediction-market data
 
 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.
 
-Answer on-chain questions using the vike.io platform: 11 chains (ETH, BSC, Base, Arbitrum, HyperEVM, BTC, Solana, Tron, XMR, ZEC, Dash), full Hyperliquid perps coverage, CEX perps across 5 venues, Polymarket prediction markets, multi-source wallet labels, and a 34-tool 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://vike.io/mcp` (JSON-RPC 2.0)
-**Or use the CLI:** `npm install -g @vike-io/cli` → `vike <command>`
+**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>`
 
 ## What it does and who it is for
 
@@ -23,13 +23,14 @@ It is for traders, researchers and developers who use an AI agent to look at cry
 Hard rules — agents that violate these produce wrong answers. Read once, apply always.
 
 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. **Symbols are case-insensitive in queries, but display as the user typed.** `btc` and `BTC` both resolve; echo back what they wrote.
-3. **Time windows are UTC, day-boundaries cut at 00:00 UTC.** "Today" = since 00:00 UTC today, not local-time today.
-4. **Default page size is 50, max 500.** Don't request `--limit 10000` to "get everything" — paginate or use a screener tool instead.
-5. **Refresh cadence varies by tool.** Wallet PnL, HL positions: ≤2 min. Transfer-derived metrics: 5 min. Token price history: 1 min. Always assume <5 min unless a tool says otherwise.
+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; 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` flag is always available** on CLI commands and gives stable machine-readable output. Default (human) format may change; `--json` will not.
-8. **Resolve a token before asking transfer/holder questions.** `token_search` → take the canonical address → pass to `token_transfers` / `token_holders`. Symbol-only queries lose precision on tickers that collide across chains (e.g. FUN, BEAM, USDC).
+7. **`--json` is always available** on CLI commands and gives stable machine-readable output. The default (human) format may change; `--json` will not.
+8. **Resolve a token before asking transfer/holder questions.** `token_search` → take the canonical address → pass it to `token_transfers` / `token_holders`. Symbol-only queries lose precision on tickers that collide across chains (e.g. FUN, BEAM, USDC).
+9. **`bought` in `token_transfers` is every inbound transfer**, flash-loan round trips included. Read `net_tokens` (bought − sold) before calling a wallet a buyer.
 
 ---
 
@@ -38,7 +39,7 @@ Hard rules — agents that violate these produce wrong answers. Read once, apply
 Follow this decision tree **before every session**. Do not skip to Step 2 until auth is confirmed.
 
 ```
-1. Is the `vike` CLI installed? (`vike-data --version`)
+1. Is the CLI installed? (`vike-data --version`)
    ├── YES → continue
    └── NO  → `npm install -g @vike-io/cli`
 
@@ -57,7 +58,7 @@ If the user has no API key yet, tell them:
 > 2. Save it: `vike-data login --api-key vk_...` (or `export VIKE_API_KEY=vk_...`).
 > 3. Verify: `vike-data doctor`.
 >
-> Per-key default cap: 2000 requests/hour. Most calls return in <500ms.
+> One key gets 20,000 requests per rolling hour, shared by the MCP server and the REST API.
 
 If using the MCP server directly (without the CLI), authenticate with the key in this header:
 ```
@@ -66,50 +67,69 @@ X-API-KEY: vk_...
 
 ---
 
-## Step 2: Route to the Right Service
+## Step 2: Route the question
 
-| User is asking about... | Service | CLI / Tool |
+Pick by the question, then read the named skill for the recipe and the traps. If two rows fit, prefer the task skill (a multi-call workflow) over the per-tool skill.
+
+| User is asking about... | CLI / MCP tool | Skill |
 |---|---|---|
-| Token by symbol/name → address, market cap, holders | **Tokens** | `vike-data token search` / `token_search` |
-| Token holders, who bought/sold, top inflows | **Tokens** | `vike-data token transfers` / `token_transfers` |
-| Filter/screen tokens by smart-money flow, liquidity, age | **Tokens** | `vike-data token screener` / `token_screener` |
-| Single wallet's PnL, holdings, recent activity | **Wallets** | `vike-data wallet summary` / `wallet_summary` |
-| Top wallets by PnL on a token / leaderboard | **Wallets** | `vike-data wallet discover` / `wallet_discover` |
-| Recent wallet transactions with USD values | **Wallets** | `vike-data wallet transactions` / `wallet_transactions` |
-| Compare 2+ wallets side by side | **Wallets** | `vike-data wallet compare` / `wallet_compare` |
-| Trace funds N hops from a starting wallet | **Wallets** | `vike-data wallet trace` / `wallet_trace` |
-| Find counterparties (who sends to / receives from) | **Wallets** | `vike-data wallet counterparties` / `wallet_counterparties` |
-| Wallet PnL history (timeseries) | **Wallets** | `vike-data wallet pnl-history` / `wallet_pnl_history` |
-| Token balances for a wallet | **Wallets** | `vike-data wallet balances` / `wallet_token_balances` |
-| ENS name → address or address → ENS | **Wallets** | `vike-data wallet ens` / `wallet_ens` |
-| Bulk-label many wallets at once | **Wallets** | `vike-data wallet batch` / `wallet_batch_labels` |
-| Why is this wallet labeled X? (provenance) | **Labels** | `vike-data labels provenance` / `wallet_label_provenance` |
-| Funding rates across CEX perps (Binance/Bybit/OKX/Aster/HL) | **CEX Perps** | `vike-data perp funding` / `perp_funding` |
-| Price spreads of same symbol across CEX perp venues | **CEX Perps** | `vike-data perp spreads` / `perp_spreads` |
-| Top Hyperliquid perp traders by PnL / volume | **HL Perps** | `vike-data perp top-traders` / `hl_perp_top_traders` |
-| Reverse-lookup an HL share card → which wallet holds it | **HL Perps** | `vike-data perp find-position` / `hl_position_match` |
-| Historical candles for a Hyperliquid perp or spot market (1m–1d) | **Candles** | `vike-data candles hl <symbol>` / `hl_ohlcv` |
-| Historical probability candles for a Polymarket outcome token | **Candles** | `vike-data candles polymarket <token_id>` / `polymarket_ohlcv` |
-| Active Polymarket markets, volume, odds | **Polymarket** | `vike-data polymarket markets` / `polymarket_markets` |
-| Single Polymarket market detail | **Polymarket** | `vike-data polymarket detail` / `polymarket_market_detail` |
-| Polymarket trader profile / positions | **Polymarket** | `vike-data polymarket wallet` / `polymarket_wallet` |
-| Best-performing Polymarket traders | **Polymarket** | `vike-data polymarket smart-money` / `polymarket_smart_money` |
-| Create / list / edit price-or-flow alerts | **Alerts** | `vike-data alerts ...` / `alerts_*` |
-
-**When in doubt, start with `vike-data token search` or `vike-data wallet summary`** — both are cheap, return instantly, and disambiguate what the user actually meant.
+| Token symbol/name → address | `vike-data token search` / `token_search` | `vike-token-search` |
+| Who bought / sold a token (top 10, one side per call) | `vike-data token transfers` / `token_transfers` | `vike-token-transfers` |
+| "Research token X" end to end | search → transfers (both tabs) | `vike-token-research` |
+| Top holders of a token (ranked by net inflow, not balance) | `vike-data token holders` / `token_holders` | `vike-token-holders` |
+| Tokens trending / with the biggest inflow / smart-money inflow | `vike-data token screener` / `token_screener` | `vike-token-screener` |
+| "Is smart money buying X?" / alpha wallets | screener `--smart-money-only` → transfers | `vike-smart-money-discovery` |
+| One wallet's volume / inflow / outflow / tx count by window | `vike-data wallet summary` / `wallet_summary` | `vike-wallet-summary` |
+| Full picture of one wallet ("who is this", "everything about it") | several calls | `vike-wallet-portfolio` |
+| Top wallets by volume / flow / tx count | `vike-data wallet discover` / `wallet_discover` | `vike-wallet-discover` |
+| Individual transfers of a wallet | `vike-data wallet transactions` / `wallet_transactions` | `vike-wallet-transactions` |
+| Who a wallet trades with | `vike-data wallet counterparties` / `wallet_counterparties` | `vike-wallet-counterparties` |
+| Follow funds N hops out | `vike-data wallet trace` / `wallet_trace` | `vike-wallet-trace` |
+| Are wallets A and B related (exactly two) | `vike-data wallet compare` / `wallet_compare` | `vike-wallet-compare` |
+| Daily net-flow series (not PnL) | `vike-data wallet pnl-history` / `wallet_pnl_history` | `vike-wallet-pnl-history` |
+| What a wallet holds right now | `vike-data wallet balances` / `wallet_token_balances` | `vike-wallet-balances` |
+| ENS name of an address (reverse only) | `vike-data wallet ens` / `wallet_ens` | `vike-wallet-ens` |
+| Label many addresses (up to 100) | `vike-data wallet batch` / `wallet_batch_labels` | `vike-wallet-batch` |
+| Why is this wallet labelled X (sources) | `vike-data labels <address>` / `wallet_label_provenance` | `vike-wallet-label-provenance` |
+| Funding rates, funding arb, one symbol across venues | `vike-data perp funding` / `perp_funding` | `vike-perp-funding` |
+| Cross-venue price spread, "perp market overview" | `vike-data perp spreads` + `perp funding` + `perp top-traders` | `vike-perp-overview` |
+| Top Hyperliquid traders; "is this HL address any good" | `vike-data perp top-traders` / `hl_perp_top_traders` | `vike-hl-top-traders` |
+| HL share card → which wallet holds it | `vike-data perp find-position` / `hl_position_match` | `vike-hl-position-match` |
+| One HL wallet: equity, positions, cohorts, risk; its fills / funding / ledger | `vike-data hl wallet`, `hl wallet-activity` / `hl_wallet`, `hl_wallet_activity` | this skill |
+| Are whales / smart money long or short X (HL cohorts) | `vike-data hl cohort-metrics <symbol>`, `hl segments`, `hl market --view indices` | this skill |
+| HL leaderboard with the full risk set, liquidations, open interest, builders, vaults | `vike-data hl leaderboard`, `hl liquidations`, `hl market`, `hl builders`, `hl vaults`, `hl vault` | this skill |
+| 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` |
+| 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.
 
 ### Example query routing
 ```
-"Top 20 wallets buying PEPE in the last 24h"          → wallet_discover         (token=PEPE, sort=net_inflow_usd)
-"What is 0xd8dA6BF...AbA96 holding?"                  → wallet_summary           + wallet_token_balances
-"Funding rate for BTC across all perp venues"         → perp_funding             (symbol=BTC)
-"Cheapest venue to short ETH right now?"              → perp_spreads             (symbol=ETH)
-"Biggest HL perp PnL last week"                       → hl_perp_top_traders      (window=7d, sort=pnl_usd)
-"Show me the largest Polymarket bets on US election"  → polymarket_market_detail + polymarket_smart_money
-"Why is 0x28C6... labeled 'Binance hot wallet'?"      → wallet_label_provenance  (addr=0x28C6...)
-"Resolve vitalik.eth"                                 → wallet_ens               (name=vitalik.eth)
-"Alert me when whale 0xABCD sells over $1M of WBTC"   → alerts_create
-"Trace funds from 0xHACKER 3 hops out"                → wallet_trace             (start=0xHACKER, depth=3)
+"Who bought the most PEPE in the last 24h?"          → token_search, then token_transfers (tab=bought, period=24h; 10 rows; rank by net_tokens)
+"What is 0xd8dA6BF...AbA96 holding?"                  → wallet_token_balances   (+ wallet_summary for flows)
+"Funding rate for BTC across all perp venues"         → perp_funding            (symbol=BTC; raw per-interval rates)
+"Which venue pays the most funding on ETH?"           → perp_funding            (symbol=ETH, normalise to daily yourself)
+"Biggest HL perp PnL last week"                       → hl_perp_top_traders     (window=7d, sort=pnl)
+"What are the hottest crypto prediction markets?"     → polymarket_markets      (category=Crypto) → polymarket_market_detail
+"Why is 0x28C6... labeled 'Binance hot wallet'?"      → wallet_label_provenance (address=0x28C6...)
+"What is the ENS name of 0xd8dA6BF...?"               → wallet_ens              (address=0xd8dA...; name → address is NOT supported)
+"Alert me on WBTC transfers over $1M"                 → alerts_create           (token_symbol=WBTC, min_value_usd=1000000; fires on ANY such transfer)
+"Trace funds from 0xHACKER 3 hops out"                → wallet_trace            (address=0xHACKER, depth=3)
 ```
 
 ---
@@ -121,182 +141,114 @@ X-API-KEY: vk_...
 **A) Via CLI (recommended for shell-bound agents).** All commands accept `--json` for machine-readable output:
 ```bash
 vike-data wallet summary 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --json
-vike-data perp funding --symbol BTC --window 24h --json
+vike-data perp funding --symbol BTC --json
+```
+
+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 31 tools live at `https://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 and `chain` set to `ethereum`.
+**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.
 
 ---
 
-## Per-service tool reference
-
-For deeper per-tool workflows (multi-step recipes, common pitfalls, output schemas), see the `skills/` directory in this repo. The router lives at `vike-router`.
+## What each tool really returns
 
 ### Tokens
-Address resolution, transfers, holder cohorts, screening.
-
-| Tool | Description | Skill |
+| Tool | Returns | Not |
 |---|---|---|
-| `token_search` | Symbol/name → contract address + chain + market cap | `vike-token-search` |
-| `token_transfers` | Recent transfers with USD values; supports `--min-usd`, time windows | `vike-token-transfers` |
-| `token_holders` | Top holders + concentration metrics | `vike-token-holders` |
-| `token_screener` | Filter tokens by smart-money inflow, age, liquidity, sector | `vike-token-screener` |
-
-**Key chains:** `ethereum`, `bsc`, `base`, `arbitrum`, `hyperevm` (EVM); `bitcoin`, `solana`, `tron`, `xmr`, `zec`, `dash` (non-EVM, limited tool support).
-
----
+| `token_search` | symbol, name, address, logo for a query | no market cap |
+| `token_transfers` | 10 wallets, one side (`tab` = `bought` or `sold`) per call, period 1h/24h/7d/30d: `address, bought, sold, net_tokens, usd_spent, usd_received, net_usd, chains` | no `--min-usd`; window ends at the token's newest priced row; a net seller has `net_usd > 0` |
+| `token_holders` | wallets ranked by cumulative net inflow USD, with entity/type | not balances, no concentration metric |
+| `token_screener` | per-token volume, net/in/out USD, `unique_holders` (wallets ACTIVE in the window, not growth), tx count | no age, liquidity or sector filter; no ascending sort; native coin shows as `0x000…000`; `symbol` is often blank |
 
 ### Wallets
-Profile, PnL, transactions, comparison, tracing, counterparty graph.
-
-| Tool | Description | Skill |
+| Tool | Returns | Not |
 |---|---|---|
-| `wallet_summary` | One-call profile: PnL, top holdings, recent activity, labels | `vike-wallet-summary` |
-| `wallet_discover` | Leaderboard of top wallets by PnL/inflow on a token | `vike-wallet-discover`, `vike-smart-money-discovery` |
-| `wallet_transactions` | Raw recent transactions (tx_hash, ts, from, to, token, usd) | `vike-wallet-transactions` |
-| `wallet_compare` | Side-by-side metrics for 2+ wallets | `vike-wallet-compare` |
-| `wallet_trace` | BFS funds tracing N hops from a starting wallet | `vike-wallet-trace` |
-| `wallet_counterparties` | Top counterparties (who they send to / receive from) | `vike-wallet-counterparties` |
-| `wallet_pnl_history` | Daily PnL timeseries over `--days N` | `vike-wallet-pnl-history` |
-| `wallet_token_balances` | Current token balances (Moralis-backed) | `vike-wallet-balances` |
-| `wallet_ens` | ENS name ↔ address (local cache: 477K wallets pre-resolved) | `vike-wallet-ens` |
-| `wallet_batch_labels` | Bulk-label up to 100 addresses in one call | `vike-wallet-batch` |
-
-**Address shape:** always full 0x-prefixed hex (42 chars). Never truncate when reporting back to the user.
-
----
+| `wallet_summary` | a dict keyed `all, 90d, 30d, 7d, 24h`, each with `total_volume, total_inflow, total_outflow, net_flow, tx_count, tokens_traded, first_seen, last_active`, for ONE chain (the most recently active; never summed) | no PnL, holdings or labels |
+| `wallet_discover` | `{wallets, total}` ranked by volume / inflow / outflow / net_flow / tx_count / pnl (`size` ≤ 20; ethereum, bsc) | `realized_pnl` is a ranking key only, not a dollar figure; no labels column |
+| `wallet_transactions` | single transfers, newest first | no aggregates |
+| `wallet_compare` | shared counterparties + shared tokens of exactly two wallets | not 3+ wallets |
+| `wallet_trace` | nodes + edges; direction lives in each edge's `out_usd` / `in_usd` | `from` is the side expanded first, not the sender |
+| `wallet_counterparties` | top partners with sent/received USD and labels | |
+| `wallet_pnl_history` | daily net inflow USD (a proxy) | not realized PnL |
+| `wallet_token_balances` | holdings read from the chain at request time (ethereum, bsc); native coin is a row with `usd_value: null` | not a DeFi-position view |
+| `wallet_ens` | name for an address, or `null` | no name → address |
+| `wallet_batch_labels` | entity, type, risk flag + 30-day flow fields per address, in input order | on `bsc` the 30-day fields are `null` |
+
+Chains: most token and wallet tools accept `chain` = `ethereum` | `bsc` | `base`, but Base coverage is narrower: it is documented for token transfers and `wallet_batch_labels`, while the per-wallet transfer tools (`wallet_transactions`, `wallet_counterparties`, `wallet_trace`, `wallet_compare`, `wallet_pnl_history`) are documented for Ethereum and BSC. `wallet_discover` takes `ethereum` | `bsc`, `wallet_token_balances` serves `ethereum` | `bsc` (anything else lands in `chain_errors`) and alerts take `eth` | `bsc`. `token_screener` smart-money mode and `smart_inflow` sort are `ethereum` only (a 400 elsewhere). `wallet_label_provenance` is for Ethereum wallets. Arbitrum, Bitcoin, Solana, Tron and other non-EVM chains are not served. When a chain is not covered, say so; an empty Base result means "not covered", not "no activity".
 
 ### Labels
-Wallet label provenance.
+`wallet_label_provenance` returns the raw source labels (at most 6 sources plus our heuristic classifier) and a consensus entity/type. When an answer hinges on "is this really a CEX hot wallet?", call it rather than trusting one source. `found: false` means the wallet is missing from our labelled-wallet table and no source is consulted at all, so it is not proof that nobody labels it, and it is not proof the wallet is clean.
 
-| Tool | Description | Skill |
-|---|---|---|
-| `wallet_label_provenance` | Why a wallet got a given label (sources + confidence) | `vike-wallet-label-provenance` |
-
-Vike's label cascade is multi-source — when an answer hinges on "is this really a CEX hot wallet?", call `wallet_label_provenance` rather than trusting a single source.
-
----
-
-### CEX Perps
-5 venues: Binance, Bybit, OKX, Aster, Hyperliquid.
-
-| Tool | Description | Skill |
-|---|---|---|
-| `perp_funding` | Funding rates per symbol per venue + 24h/7d averages | `vike-perp-funding-arb` |
-| `perp_spreads` | Mark-price spreads of the same symbol across venues | `vike-perp-spread-arb`, `vike-cross-venue-perps` |
-
----
-
-### Hyperliquid Perps
-On-chain perps data: snapshots, fills, ledger, funding, attribution.
-
-| Tool | Description | Skill |
-|---|---|---|
-| `hl_perp_top_traders` | Top HL traders by PnL/volume over a window | `vike-hl-top-traders`, `vike-hl-trader-profile` |
-| `hl_position_match` | Reverse-lookup: share-card details (coin/side/lev/entry) → wallet holding that open position | `vike-hl-position-match` |
+### CEX perps
+| Tool | Returns |
+|---|---|
+| `perp_funding` | with `symbol`: raw per-venue `funding_rate` + `interval_h` (daily % = rate × 24 / interval_h × 100); without: up to 5 pre-ranked arb rows (`long_exchange`, `short_exchange`, `spread_daily_pct`) |
+| `perp_spreads` | up to 10 cross-venue price-gap rows (≥ 0.5%); `symbol` only filters that global top 10, so it is often empty |
 
-For per-symbol HL screening / individual trader deep-dive, use `vike-perp-screener` and `vike-hl-trader-profile`.
+Neither returns mark prices or bid/ask per venue. "Spread" here is perp vs perp across venues, not spot vs perp.
 
----
+### Hyperliquid
+| Tool | Returns |
+|---|---|
+| `hl_perp_top_traders` | up to 20 wallets: `total_realized_pnl`, `roi_pct`, `win_rate_pct`, `max_drawdown_pct` (all percents; 12.5 = 12.5%), `trade_count`, `total_volume`. ROI = window realized PnL / CURRENT account value; drawdown is account-level and all-time |
+| `hl_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) |
+
+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
-Historical OHLCV from venues whose data is on-chain.
-
-| Tool | Description | Skill |
-|---|---|---|
-| `hl_ohlcv` | Hyperliquid perp or spot candles, 1m–1d, built from HL's own executed fills (also HIP-3 builder DEXs) | `vike-candles` |
-| `polymarket_ohlcv` | Candles for ONE Polymarket outcome token (price = probability, 0–1); needs `token_id`, not a condition_id | `vike-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). `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
-Prediction markets — markets, traders, smart-money.
-
-| Tool | Description | Skill |
-|---|---|---|
-| `polymarket_markets` | Active markets sorted by volume / liquidity / volatility | `vike-polymarket-markets`, `vike-polymarket-screener` |
-| `polymarket_market_detail` | Single market: outcomes, holders, recent trades, time-to-resolution | `vike-polymarket-market-detail` |
-| `polymarket_wallet` | One trader's positions, PnL, win rate | `vike-polymarket-trader` |
-| `polymarket_smart_money` | Top-PnL Polymarket traders + their current open positions | `vike-polymarket-smart-money` |
-
----
+| Tool | Returns |
+|---|---|
+| `polymarket_markets` | markets ranked by 24h volume only (`volume_24h`, `liquidity`, `ended`, `outcomes[]` with `token_id`, `mid`, `bid`, `ask`) |
+| `polymarket_market_detail` | one market: quotes, smart-money cohort flows, top wallets, resolution status |
+| `polymarket_wallet` | one trader: realized PnL, volume-weighted `hit_rate`, `resolved_markets`, positions |
+| `polymarket_smart_money` | MARKETS where the profitable-wallet cohort is flowing (`flows`) or bought below the mid (`mispricings`); not a list of top traders |
 
 ### Alerts
-Create + manage alerts; deliver to email, Telegram, Discord, Webhook.
-
-| Tool | Description | Skill |
-|---|---|---|
-| `alerts_list` | List user's existing alerts | `vike-alerts-setup` |
-| `alerts_create` | Create a new price/transfer/funding alert | `vike-alerts-setup` |
-| `alerts_edit` | Edit an existing alert | `vike-alerts-setup` |
-| `alerts_delete` | Delete an alert | `vike-alerts-setup` |
-| `alerts_list_channels` | List user's registered delivery channels | `vike-alerts-setup` |
-| `alerts_register_webhook` | Register an HTTPS webhook (HMAC-signed deliveries) | `vike-alerts-webhook` |
+Create + manage on-chain transfer alerts and Hyperliquid alerts, delivered by email or an HTTPS webhook.
 
-Alerts fire on a 2-minute cron cycle (not streaming). Don't recommend WebSocket / push streaming — it's not how the platform works.
-
-## Historical data availability
-
-Coverage windows per dataset. Don't ask for data older than the window — the tool will return empty or 503.
-
-### Transfers & on-chain (per chain)
-
-| Chain | Earliest block / date | Notes |
-|---|---|---|
-| Ethereum | 2018-01 (block ~4.85M) | Full history; ETH + ERC-20 |
-| BSC | 2021-01 | Full history; BNB + BEP-20 |
-| Base | 2023-08 (chain launch) | Full history |
-| Arbitrum | 2024-Q3 onward | Backfill in progress; pre-2024 sparse |
-| HyperEVM | 2025-Q1 (chain launch) | Full history |
-| Bitcoin | 2024-01 | Recent windows only — full-history backfill not active |
-| Solana | 2026-Q1 onward | Recent only — see `vike-cli` chain-coverage notes |
-| Tron/XMR/ZEC/Dash | 2024 onward | Recent only |
-
-### Hyperliquid perps (hl_perps DB)
-
-| Dataset | Window | Notes |
-|---|---|---|
-| Snapshots (positions / equity) | 30 days | TTL — older snapshots dropped |
-| Fills | 30 days | TTL |
-| Ledger (deposits/withdrawals) | 30 days | TTL |
-| Funding payments | 90 days | API-backed since 2026-04-22 |
-| Daily attributed PnL | All-time | `wallet_pnl_attributed_daily` is the long-history view |
-| Daily flows | All-time | `wallet_flows_daily` |
-| Top-trader leaderboards | rolling 24h / 7d / 30d | derived on-the-fly |
-
-### CEX perps (data_perp DB)
-
-| Dataset | Window |
+| Tool | Does |
 |---|---|
-| `tickers_1m` (ticker snapshots) | rolling 24h |
-| Funding rates | 90 days |
-| Trades (ws_trades) | rolling 7-30 days per venue |
-
-### Polymarket
-
-| Dataset | Window | Notes |
-|---|---|---|
-| Active markets | live | scraper paused 2026-05-24 (CF block); historical snapshots still queryable |
-| Wallet positions | last known snapshot | not real-time until scraper resumes |
+| `alerts_list`, `alerts_list_channels` | list rules / enabled channels |
+| `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 |
 
-If your query needs older data than what's listed: say so clearly and offer the nearest in-range window. Don't silently return empty.
+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`.
 
 ---
 
-## Cost & rate-limit awareness
+## Cost & rate limits
 
-- **Cheap (counts as 1 credit):** `token_search`, `wallet_summary`, `alerts_list`, `wallet_ens`, `perp_funding`.
-- **Standard (1-3 credits):** most tools.
-- **Heavy (5+ credits):** `wallet_discover` with large pages, `wallet_trace` with deep `--depth`, `token_screener` with no filters, `hl_perp_top_traders` with `--limit > 100`.
+Credits are an accounting figure only; they never block a call. The one limit is 20,000 requests per rolling hour per key, shared by MCP and REST.
 
-Per-key default: 2000 requests/hour. Hitting the cap returns `MCP error -32000: Hourly rate limit exceeded`. Wait or upgrade plan.
+- **0 credits:** `token_search`, `alerts_list`, `alerts_list_channels`.
+- **1:** `wallet_ens`, `wallet_label_provenance`, `perp_funding`, `perp_spreads`, `hl_ohlcv`, `polymarket_markets`, `polymarket_ohlcv`.
+- **2:** most others, `wallet_summary` among them.
+- **3:** `token_screener`, `wallet_compare`, `wallet_token_balances`, `alerts_create`.
+- **4:** `wallet_trace`.
 
 ## What vike does NOT do
 
 - **No NFT data** — out of scope by design.
 - **No on-chain trading / signing** — read-only platform, no execution.
-- **No WebSocket / push streaming alerts** — alerts run on a 2-minute cron.
+- **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,9 +84,10 @@ vike-data alerts delete 42 --hard                   # permanently remove
 
 ## Notes + gotchas
 
-- Currently chains supported: **eth** and **bsc** only. For both, create two alerts.
+- 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