@vike-io/cli 0.11.0 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.12.1
+
+### Patch Changes
+
+- e4f4b6c: package.json description and keywords now describe the free Data API (Polymarket L2 Parquet archive, Hyperliquid, labelled wallets, MCP). `vike doctor` / `vike init` no longer assume `/mcp` answers `initialize` without a key: with no key the check fails with the "No API key" message, and `vike init` reports a rejected key instead of printing ok. The postinstall hint links https://vike.io/data/ and the API-keys page instead of the dead https://vike.io/api.
+- e4f4b6c: README: answer-first summary of the free Vike Data API, a Free datasets section with direct links, MCP setup, the full command list, and an examples/ folder (Polymarket archive, Hyperliquid cohorts, DuckDB).
+- 7f4be01: Umbrella skill: add a plain what-it-is-for paragraph, describe the MCP connector instead of a raw HTTP POST, and fix the tool count (31).
+- 31952b5: Umbrella skill: add a 'What it does and who it is for' section (the marketplace check looks for a prose paragraph there).
+- ffb25f3: Skills: replace links to sibling skills with their names, so a skill imported on its own (e.g. a marketplace bundle of `skills/vike`) has no dead links.
+
+## 0.12.0
+
+### Minor Changes
+
+- 6a41844: Remove the commands and skills whose MCP tool the server no longer offers: `vike funds` (`fund_holdings`), `vike defi` (`defi_positions`), `vike ohlcv` (`ohlcv`), `vike token chart` (`token_chart`), `vike options flow` (`options_flow`) and `vike web search|fetch` (`web_search`, `web_fetch`), plus the `vike-fund-holdings`, `vike-defi-positions`, `vike-ohlcv`, `vike-options-flow`, `vike-web-search`, `vike-web-fetch` and `vike-web-research` skills and every cross-reference to them.
+  
+  Add `vike candles hl <symbol>` and `vike candles polymarket <token_id>` (the `hl_ohlcv` and `polymarket_ohlcv` tools) and the `vike-candles` skill.
+
 ## 0.11.0
 
 ### Minor Changes

package/README.md

@@ -1,121 +1,222 @@
-# @vike-io/cli
+# @vike-io/cli — the Vike Data API from your terminal and your AI agent
 
-> Repo + package: `@vike-io/cli` (npm) · `vike-io/vike-data-cli` (GitHub) · binary: `vike`
+> Repo + package: `@vike-io/cli` (npm) · `vike-io/vike-data-cli` (GitHub) · binary: `vike` (alias `vike-data`)
 
 [![npm version](https://img.shields.io/npm/v/@vike-io/cli.svg)](https://www.npmjs.com/package/@vike-io/cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen.svg)](https://nodejs.org)
 [![skills.sh](https://skills.sh/b/vike-io/vike-data-cli)](https://skills.sh/vike-io/vike-data-cli)
 
-> **Command-line interface for the [vike.io](https://vike.io) API.** On-chain analytics, perpetuals, options flow, and prediction-market data across 11 chains — designed to be driven by AI agents (Claude Code, OpenClaw) as well as humans.
+**`@vike-io/cli` is an open-source (MIT) command-line client and agent skill pack for the free
+[Vike Data API](https://vike.io/data/).** One free API key covers **Hyperliquid** (traders,
+positions, fills, funding, liquidations, candles, and hourly long/short positioning by wallet
+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
+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
+at all. Market data from centralised exchanges is not offered through the REST API.
 
 ## Install
 
 ```bash
-# Standard install — gives you the `vike` binary
+# The CLI (Node.js >= 22.12). Installs the `vike` binary.
 npm install -g @vike-io/cli
 
-# OR install just the skill playbooks into your AI agent (Claude Code, Cursor,
-# Codex, Copilot, OpenCode and 50+ more — auto-detected):
+# OR install only the skill playbooks into your AI agent (Claude Code, Cursor,
+# Codex, Copilot and others; the agent is auto-detected):
 npx skills add vike-io/vike-data-cli
 ```
 
-After `npm install`, you can also drop the skill into AI agents from the CLI itself:
+## Quickstart
+
+Get a free key at [vike.io/account?tab=api-keys](https://vike.io/account?tab=api-keys) (keys start
+with `vk_`), then:
 
 ```bash
-vike install --all          # writes to ~/.claude/skills/vike/, .cursorrules,
-                            # .github/copilot-instructions.md, AGENTS.md
+vike init                                   # paste the key; saves ~/.vike/config.json, checks vike.io/mcp
+vike doctor                                 # Node version, key, MCP connectivity, tool list
+vike token search PEPE                      # first query
+vike perp top-traders --window 7d           # Hyperliquid wallets ranked by PnL
+vike candles hl BTC --interval 1h --limit 48
+vike polymarket markets --category Crypto   # trending markets by 24h volume
 ```
 
-## Quick start
+The key is read from `VIKE_API_KEY` first, then from `~/.vike/config.json`
+(`vike login --api-key vk_...` writes it, `vike logout` removes it).
+
+## Free datasets
+
+| Dataset | What is in it | Access | Page |
+|---|---|---|---|
+| **Polymarket historical order book** (archive) | `book_events` (full L2: snapshots, `price_change` deltas, trades, tick-size and status markers), `trades` (taker tape), `l1_quotes` (derived top of book). One Parquet file per stream per UTC day since 2026-07-25, every recorded market (crypto up/down, sports, politics). CC BY 4.0. | Manifest + sample: no key. Full days: free key. | [polymarket-historical-data](https://vike.io/data/polymarket-historical-data) |
+| **Polymarket up/down families** (archive) | The same archive cut per market family, `asset=btc/tenor=5m` and so on, with an `asset=other/tenor=other` catch-all | free key | [polymarket-updown-markets](https://vike.io/data/polymarket-updown-markets) |
+| **Polymarket API** `/v1/polymarket` | Markets, the raw event and trade tape (about 30 days back), order-book snapshots, candles, on-chain settlements | free key | [polymarket](https://vike.io/data/polymarket) |
+| **Hyperliquid cohorts** `/v1/hyperliquid/coins/{coin}/cohort-metrics` | Long vs short per cohort, hourly, up to 8,760 hours in one request. Axes: `size` (account value, shrimp to 4x whale), `tier` (position notional), `pnl` (realized-PnL percentile), `pnl_abs` (PnL in dollars). `labelBasis=point_in_time` grades each hour with the label it had then (from 2026-04-07). | free key | [hl-cohorts](https://vike.io/data/hl-cohorts) |
+| **Hyperliquid API** `/v1/hyperliquid` | Trader rankings and leaderboards, 5-minute position snapshots kept for a year, wallet fills, funding and ledger, liquidations (inferred from snapshots), builders, candles since the start of 2026; closed bars also stream on `wss://vike.io/v1/stream` | free key | [hyperliquid](https://vike.io/data/hyperliquid) |
+| **On-chain API** `/v1/onchain` | Wallet summaries, transactions, counterparties, PnL, address labels with per-source provenance, token holders and transfers. Ethereum on every route, BNB Chain on the wallet and token-flow routes, Base on token transfers. | free key | [onchain](https://vike.io/data/onchain) |
+
+Direct links that need no key:
+
+- Archive manifest (every date, per-stream bytes and row counts, the schema, the license):
+  <https://data.vike.io/archive/manifest.json>
+- Free sample, one complete 5-minute crypto up/down market (both outcome tokens, open through
+  resolution), regenerated daily: <https://data.vike.io/archive/samples/>
+  ([README.txt](https://data.vike.io/archive/samples/README.txt),
+  [book_events.parquet](https://data.vike.io/archive/samples/book_events.parquet),
+  [trades.parquet](https://data.vike.io/archive/samples/trades.parquet),
+  [l1_quotes.parquet](https://data.vike.io/archive/samples/l1_quotes.parquet))
+
+Archive layout: `https://data.vike.io/archive/venue=polymarket/date=YYYY-MM-DD/{book_events,trades,l1_quotes}.parquet`.
+A full-day `book_events` file is several GB; `trades` is around 12 MB.
 
 ```bash
-vike init                      # interactive: paste API key, verify connection
-vike doctor                    # confirm everything works
-vike token search BTC          # your first query
+# No key: the newest day in the archive, and the sample tape
+curl -s https://data.vike.io/archive/manifest.json | jq '.dates[0]'
+curl -O https://data.vike.io/archive/samples/trades.parquet
+
+# Free key: one full day of the Polymarket tape, and a day of BTC cohort positioning
+export VIKE_API_KEY=vk_...
+curl -H "X-API-KEY: $VIKE_API_KEY" -C - -o polymarket-trades-2026-10-16.parquet \
+  "https://data.vike.io/archive/venue=polymarket/date=2026-10-16/trades.parquet"
+curl -H "X-API-KEY: $VIKE_API_KEY" \
+  "https://data.vike.io/v1/hyperliquid/coins/BTC/cohort-metrics?axis=size&hours=24"
 ```
 
-Get an API key at [vike.io/account?tab=api-keys](https://vike.io/account?tab=api-keys).
+Download an archive file whole, then read the local copy. A Parquet reader (DuckDB, polars,
+pyarrow) pointed at the URL turns one file into thousands of HTTP Range requests.
+
+Full catalog: [vike.io/data/datasets](https://vike.io/data/datasets) · field reference:
+[vike.io/data/schemas](https://vike.io/data/schemas) · keys and limits:
+[vike.io/data/api](https://vike.io/data/api).
 
-## Commands at a glance
+## MCP server
 
+The crypto data MCP server is `https://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 \
+  --header "X-API-KEY: $VIKE_API_KEY"
 ```
-vike token   search | transfers | chart
-vike ohlcv   <symbol>          # CEX candles, any timeframe (BTC, BTCUSDT)
-vike wallet  summary | discover
-vike perp    funding | spreads | top-traders
-vike options flow
-vike alerts  list | channels | create | edit | delete
-vike init | doctor | schema | whoami | login | logout
+
+Cursor, in `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vike": {
+      "url": "https://vike.io/mcp",
+      "headers": { "X-API-KEY": "YOUR_KEY" }
+    }
+  }
+}
 ```
 
-Run `vike schema --pretty` for the full command + flag reference.
+**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.
+Setup for Gemini CLI, VS Code and other clients: [vike.io/docs/ai/data/setup](https://vike.io/docs/ai/data/setup).
 
-## What it does
+```bash
+# Raw JSON-RPC: list the tools your key can call
+curl https://vike.io/mcp -H "X-API-KEY: $VIKE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
 
-| Domain | What you can ask |
-|---|---|
-| **Tokens** | Resolve symbols → addresses, see top buyers/sellers, pull OHLCV |
-| **Wallets** | Aggregate metrics per wallet, leaderboards by volume / PnL / netflow |
-| **Perps** | Funding rates + cross-venue spreads across Binance / Bybit / OKX / Aster / Hyperliquid |
-| **Hyperliquid** | Top-trader leaderboard with PnL / ROI / win-rate filters |
-| **Options** | Deribit flow for BTC / ETH / SOL with put-call ratios |
-| **Alerts** | Create transfer alerts; deliver to email or Discord |
+On `/mcp` a bad or missing key comes back as a JSON-RPC `error` in the body, so check the body and
+not only the HTTP status. A rate-limited call gets HTTP 429 with `Retry-After: 60`.
 
-## For AI agents
+## CLI commands
 
-This package ships **41 skill playbooks** under [`skills/`](skills/) — markdown files designed to be loaded by AI coding agents (Claude Code, Cursor, Codex, Copilot, OpenCode, …) so they know when and how to invoke each command. They are grouped in [`skills.sh.json`](skills.sh.json) by domain (Tokens / Wallets / CEX perps / Hyperliquid / Options / Polymarket / Alerts / Web research).
+Every data command is one `tools/call` to the MCP server. `vike <group> --help` lists the flags;
+`vike schema --pretty` prints every tool the server exposes, with its parameters.
 
-Three install paths, pick whichever fits your stack:
+| Command | Subcommands | MCP tool |
+|---|---|---|
+| `vike token` | `search`, `transfers`, `screener`, `holders` (`--chain ethereum\|bsc\|base`) | `token_search`, `token_transfers`, `token_screener`, `token_holders` |
+| `vike 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 labels <address>` | multi-source label provenance for one wallet | `wallet_label_provenance` |
+| `vike 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 candles` | `hl <symbol>` (Hyperliquid perp or spot, from executed fills), `polymarket <token_id>` (one outcome token) | `hl_ohlcv`, `polymarket_ohlcv` |
+| `vike polymarket` (`pm`) | `markets`, `market <condition_id>`, `wallet <address>`, `smart-money` | `polymarket_markets`, `polymarket_market_detail`, `polymarket_wallet`, `polymarket_smart_money` |
+| `vike alerts` | `list`, `channels`, `create`, `edit`, `delete`, `register-webhook` (email, Discord, or an HTTPS webhook, HMAC-signed when you set a secret) | `alerts_*` |
+| setup | `init`, `login`, `logout`, `doctor`, `schema`, `install` | — |
+
+Output is a table on a terminal and JSON with `--json` or whenever stdout is piped:
 
 ```bash
-# 1. Install just the skill files for your agent (no Node binary needed):
-npx skills add vike-io/vike-data-cli                # auto-detects the agent
-npx skills add vike-io/vike-data-cli -a claude-code # explicit target
-npx skills add vike-io/vike-data-cli --list          # list all 41 first
+vike token search BTC --json | jq '.'
+```
 
-# 2. Use the CLI itself to install the umbrella skill into multiple agents:
-vike install --claude --cursor --copilot --agents
+## Examples
+
+[`examples/`](examples/) holds three Python scripts. Each declares its dependencies inline, so
+`uv run` installs them; plain `pip install polars requests duckdb` works too.
+
+| Script | What it does | Key |
+|---|---|---|
+| [`polymarket_archive.py`](examples/polymarket_archive.py) | Reads `manifest.json`, downloads the free sample's `trades` and `l1_quotes` and summarises them with polars, then (with `VIKE_API_KEY` set) downloads one full day of `trades.parquet` and checks its size against the manifest | steps 1-2 none, step 3 free key |
+| [`hyperliquid_cohorts.py`](examples/hyperliquid_cohorts.py) | `GET /v1/hyperliquid/coins/BTC/cohort-metrics?axis=size&hours=24` into a polars DataFrame: positioning per account-size cohort at the latest hour, and bias per cohort per hour | free key |
+| [`duckdb_archive.py`](examples/duckdb_archive.py) | DuckDB over local archive Parquet: trades, shares and VWAP per outcome token, and mid and spread per minute from `l1_quotes`. Uses the free sample unless you pass your own files or globs. | none for the sample |
 
-# 3. Manual: point your agent at the skills/ folder of this npm package
-#    (lives at node_modules/@vike-io/cli/skills/ after install).
+```bash
+uv run examples/polymarket_archive.py
+VIKE_API_KEY=vk_... uv run examples/hyperliquid_cohorts.py
+uv run examples/duckdb_archive.py
 ```
 
-Entry-point skill: `vike` (the umbrella) — auto-routes the user's question to the right specialized skill below. Bypass it and pick a specialized one if you know exactly which you need (e.g. `vike-hl-position-match` for reverse-lookup of an HL share card).
+Downloads go to `./vike-archive/`.
 
-## Auth
+## For AI agents
 
-Three ways to provide your key, in order of precedence:
+This package ships **36 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.
 
 ```bash
-export VIKE_API_KEY=vk_...     # env (wins over everything)
-vike login --api-key vk_...    # saved to ~/.vike/config.json
-vike init                      # interactive
+npx skills add vike-io/vike-data-cli --list    # see them first
+npx skills add vike-io/vike-data-cli           # install
+
+# Or, from the installed CLI, write the umbrella skill into each agent's location:
+vike install --claude     # ~/.claude/skills/vike/SKILL.md
+vike install --cursor     # ./.cursorrules
+vike install --copilot    # ./.github/copilot-instructions.md
+vike install --agents     # ./AGENTS.md
+vike install --all        # all four
 ```
 
+`vike install` replaces only its own `<!-- vike-skill:begin -->` ... `<!-- vike-skill:end -->`
+block in files it does not own.
+
 ## Environment
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `VIKE_API_KEY` | — | API key (overrides saved config) |
-| `VIKE_MCP_URL` | `https://vike.io/mcp` | MCP endpoint (override for staging/local) |
+| `VIKE_API_KEY` | — | API key; wins over the saved config |
+| `VIKE_MCP_URL` | `https://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 |
 
-## Output formatting
+Telemetry sends the command name, the flag names (never their values), the duration, an error code
+and a random device id. It never sends what you queried, and it is off when `CI` is set.
 
-By default, table output for humans (TTY) and JSON when piped:
-
-```bash
-vike token search BTC                  # pretty table
-vike token search BTC --json           # JSON
-vike token search BTC | jq '.'         # auto-JSON when piped
-```
+`vike` here is the Data API client. The Vike Trader platform has its own, separate command line,
+`vike-cli` ([docs](https://vike.io/docs/trader/cli)).
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+The CLI is MIT, see [LICENSE](LICENSE). Archive data files are CC BY 4.0: use them for anything
+and credit Vike ("Polymarket L2 archive (c) Vike (vike.io/data), CC BY 4.0"). Details:
+[vike.io/data/licensing](https://vike.io/data/licensing).
 
 ## Links
 
-- Homepage: [vike.io](https://vike.io)
+- Free Data API: [vike.io/data](https://vike.io/data/)
+- Data API docs: [vike.io/docs/data](https://vike.io/docs/data/) · archive: [vike.io/docs/data/archive](https://vike.io/docs/data/archive/) · MCP tools: [vike.io/docs/ai/data](https://vike.io/docs/ai/data)
+- For LLMs: [vike.io/llms.txt](https://vike.io/llms.txt) · [vike.io/docs/llms.txt](https://vike.io/docs/llms.txt)
 - Issues: [github.com/vike-io/vike-data-cli/issues](https://github.com/vike-io/vike-data-cli/issues)
-- API docs: [vike.io/api](https://vike.io/api)

package/package.json

@@ -3,8 +3,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.11.0",
-  "description": "AI-agent CLI for vike.io on-chain analytics, perps, options, and prediction markets across 11 chains",
+  "version": "0.12.1",
+  "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",
   "bin": {
@@ -44,14 +44,16 @@
     "onchain",
     "perps",
     "hyperliquid",
-    "options",
-    "deribit",
     "polymarket",
     "prediction-markets",
     "defi",
     "ethereum",
     "bsc",
-    "base"
+    "base",
+    "parquet",
+    "order-book",
+    "historical-data",
+    "crypto-data"
   ],
   "author": "vike.io",
   "license": "MIT",
@@ -70,8 +72,8 @@
     "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.27.9",
+    "@changesets/cli": "^3.0.3",
     "eslint": "^10.4.0",
-    "vitest": "^4.1.7"
+    "vitest": "^5.0.4"
   }
 }

package/scripts/postinstall.js

@@ -30,7 +30,8 @@ try {
     '    vike doctor                — verify your install',
     '    vike token search BTC      — your first query',
     '',
-    '  Docs: https://vike.io/api',
+    '  Docs:    https://vike.io/data/',
+    '  API key: https://vike.io/account?tab=api-keys',
     '',
   ];
   process.stdout.write(lines.join('\n'));