@vike-io/cli 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.14.0
+
+### Minor Changes
+
+- 62464b9: Skills audit (2026-10-19). `vike-data perp find-position` now sends `symbol` to `hl_position_match` (the tool renamed `coin` on 2026-10-19; the `--coin` flag is unchanged). Help text no longer claims six balance chains, "10+" label providers or "spot-perp" spreads. 36 skills become 31: `vike-router` folds into the umbrella `vike`; `vike-perp-funding-arb` + `vike-cross-venue-perps` become `vike-perp-funding`; `vike-perp-screener` + `vike-perp-spread-arb` become `vike-perp-overview`; `vike-polymarket-screener` folds into `vike-polymarket-smart-money`; `vike-hl-trader-profile` folds into `vike-hl-top-traders`. Installed copies of the removed skills need `npx skills add vike-io/vike-data-cli` again. The audit's errors are corrected in the skill text: the umbrella (tool and chain lists, page sizes, ENS direction, command names, alert semantics, credits, rate limit of 20,000 requests per hour), token skills (`bought` is every inbound transfer, read `net_tokens`; real columns; fixed 10 rows; native coin as the zero address; screener `holders` counts active wallets; no ascending sort), wallet trace (edge direction is `out_usd` / `in_usd`), label provenance (6 sources plus heuristic, `found: false`), Hyperliquid top traders (percent units, realized-only ROI, no per-wallet HL tool), wallet summary / balances / discover / batch / transactions output shapes, and the Polymarket output keys.
+
+### Patch Changes
+
+- 7aba637: The default MCP endpoint is now `https://data.vike.io/mcp`, the server's published address (same server, tools, key and hourly budget). `VIKE_MCP_URL` still overrides it; the older `https://vike.io/mcp` keeps answering while it is retired.
+
 ## 0.13.1
 
 ### Patch Changes

package/README.md

@@ -13,7 +13,7 @@ positions, fills, funding, liquidations, candles, and hourly long/short position
 cohort), **Polymarket** (markets, the trade and event tape, order-book snapshots, candles and
 on-chain settlements, plus a daily Parquet archive of the full L2 order book since 2026-07-25,
 licensed CC BY 4.0), and **labelled EVM wallets** on Ethereum and BNB Chain, with Base for token
-transfers. The same data is served three ways: an **MCP server** at `https://vike.io/mcp` (the one
+transfers. The same data is served three ways: an **MCP server** at `https://data.vike.io/mcp` (the one
 this CLI calls), a **REST API** at `https://data.vike.io/v1/`, and the **Parquet archive** at
 `https://data.vike.io/archive/`. A key allows 20,000 requests an hour, and an account can hold up
 to 5 keys; archive downloads are not counted. The archive manifest and a sample market need no key
@@ -36,7 +36,7 @@ Get a free key at [vike.io/account?tab=api-keys](https://vike.io/account?tab=api
 with `vk_`), then:
 
 ```bash
-vike-data init                                   # paste the key; saves ~/.vike/config.json, checks vike.io/mcp
+vike-data init                                   # paste the key; saves ~/.vike/config.json, checks data.vike.io/mcp
 vike-data doctor                                 # Node version, key, MCP connectivity, tool list
 vike-data token search PEPE                      # first query
 vike-data perp top-traders --window 7d           # Hyperliquid wallets ranked by PnL
@@ -94,12 +94,12 @@ Full catalog: [vike.io/data/datasets](https://vike.io/data/datasets) · field re
 
 ## MCP server
 
-The crypto data MCP server is `https://vike.io/mcp` (Streamable HTTP, JSON-RPC 2.0), keyed with
+The crypto data MCP server is `https://data.vike.io/mcp` (Streamable HTTP, JSON-RPC 2.0), keyed with
 the same `X-API-KEY`. MCP and REST calls share one hourly counter.
 
 ```bash
 # Claude Code
-claude mcp add --transport http vike https://vike.io/mcp \
+claude mcp add --transport http vike https://data.vike.io/mcp \
   --header "X-API-KEY: $VIKE_API_KEY"
 ```
 
@@ -109,7 +109,7 @@ Cursor, in `~/.cursor/mcp.json`:
 {
   "mcpServers": {
     "vike": {
-      "url": "https://vike.io/mcp",
+      "url": "https://data.vike.io/mcp",
       "headers": { "X-API-KEY": "YOUR_KEY" }
     }
   }
@@ -117,12 +117,12 @@ Cursor, in `~/.cursor/mcp.json`:
 ```
 
 **Claude Desktop needs no key:** Settings → Connectors → Add custom connector, URL
-`https://vike.io/mcp`, leave the OAuth fields empty, then log in to Vike and click Allow.
+`https://data.vike.io/mcp`, leave the OAuth fields empty, then log in to Vike and click Allow.
 Setup for Gemini CLI, VS Code and other clients: [vike.io/docs/ai/data/setup](https://vike.io/docs/ai/data/setup).
 
 ```bash
 # Raw JSON-RPC: list the tools your key can call
-curl https://vike.io/mcp -H "X-API-KEY: $VIKE_API_KEY" \
+curl https://data.vike.io/mcp -H "X-API-KEY: $VIKE_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
 ```
@@ -140,7 +140,7 @@ Every data command is one `tools/call` to the MCP server. `vike-data <group> --h
 | `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 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 spot-perp spreads) | `hl_perp_top_traders`, `hl_position_match`, `perp_funding`, `perp_spreads` |
+| `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_*` |
@@ -173,7 +173,7 @@ Downloads go to `./vike-archive/`.
 
 ## For AI agents
 
-This package ships **36 skill playbooks** under [`skills/`](skills/): markdown files an AI coding
+This package ships **31 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
 entry point is the umbrella skill `vike`, which routes a question to the specialised skill.
@@ -198,7 +198,7 @@ block in files it does not own.
 | Variable | Default | Purpose |
 |---|---|---|
 | `VIKE_API_KEY` | — | API key; wins over the saved config |
-| `VIKE_MCP_URL` | `https://vike.io/mcp` | MCP endpoint override |
+| `VIKE_MCP_URL` | `https://data.vike.io/mcp` | MCP endpoint override |
 | `VIKE_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` | telemetry on | Turns off anonymous usage telemetry |
 | `VIKE_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER=1` | check on | Turns off the background npm update check |
 

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.13.1",
+  "version": "0.14.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",

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 top traders / share-card lookup / candles, Polymarket markets, traders and smart-money signals, and transfer alerts. 31 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; 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.
 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,57 @@ 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` |
+| Candles: Hyperliquid perp/spot, Polymarket outcome token | `vike-data candles hl` / `candles polymarket` | `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` |
+| 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 +129,102 @@ 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
 ```
 
-**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 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.
 
 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.
-
-| 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.
+`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.
 
----
-
-### 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.
+### 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 |
 
-| 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` |
+Neither returns mark prices or bid/ask per venue. "Spread" here is perp vs perp across venues, not spot vs perp.
 
-For per-symbol HL screening / individual trader deep-dive, use `vike-perp-screener` and `vike-hl-trader-profile`.
+### 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 |
 
----
+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.
 
 ### 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). 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` |
-
-Alerts fire on a 2-minute cron cycle (not streaming). Don't recommend WebSocket / push streaming — it's not how the platform works.
+Create + manage on-chain transfer alerts delivered to email, Discord or an HTTPS webhook.
 
-## 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 (token symbol + chain `eth`/`bsc` + USD thresholds) |
+| `alerts_register_webhook` | register an HTTPS webhook (HMAC-signed deliveries) |
 
-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.
+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.
 
 ---
 
-## 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 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 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

@@ -55,6 +55,7 @@ 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).
 - 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.
 - Tokens are matched by symbol (UPPERCASE). For cross-chain symbols like `USDC` that exist on multiple chains, be explicit with `--chain`.

package/skills/vike-candles/SKILL.md

@@ -41,7 +41,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 +50,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.