@vike-io/cli 0.12.0 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/README.md +164 -62
  3. package/package.json +7 -5
  4. package/scripts/postinstall.js +2 -1
  5. package/skills/vike/SKILL.md +41 -50
  6. package/skills/vike-hl-position-match/SKILL.md +3 -3
  7. package/src/commands/init.js +1 -1
  8. package/src/mcp-client.js +5 -6
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.12.1
4
+
5
+ ### Patch Changes
6
+
7
+ - 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.
8
+ - 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).
9
+ - 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).
10
+ - 31952b5: Umbrella skill: add a 'What it does and who it is for' section (the marketplace check looks for a prose paragraph there).
11
+ - 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.
12
+
3
13
  ## 0.12.0
4
14
 
5
15
  ### Minor Changes
package/README.md CHANGED
@@ -1,120 +1,222 @@
1
- # @vike-io/cli
1
+ # @vike-io/cli — the Vike Data API from your terminal and your AI agent
2
2
 
3
- > Repo + package: `@vike-io/cli` (npm) · `vike-io/vike-data-cli` (GitHub) · binary: `vike`
3
+ > Repo + package: `@vike-io/cli` (npm) · `vike-io/vike-data-cli` (GitHub) · binary: `vike` (alias `vike-data`)
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@vike-io/cli.svg)](https://www.npmjs.com/package/@vike-io/cli)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
- [![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
7
+ [![Node](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen.svg)](https://nodejs.org)
8
8
  [![skills.sh](https://skills.sh/b/vike-io/vike-data-cli)](https://skills.sh/vike-io/vike-data-cli)
9
9
 
10
- > **Command-line interface for the [vike.io](https://vike.io) API.** On-chain analytics, perpetuals, and prediction-market data across 11 chains — designed to be driven by AI agents (Claude Code, OpenClaw) as well as humans.
10
+ **`@vike-io/cli` is an open-source (MIT) command-line client and agent skill pack for the free
11
+ [Vike Data API](https://vike.io/data/).** One free API key covers **Hyperliquid** (traders,
12
+ positions, fills, funding, liquidations, candles, and hourly long/short positioning by wallet
13
+ cohort), **Polymarket** (markets, the trade and event tape, order-book snapshots, candles and
14
+ on-chain settlements, plus a daily Parquet archive of the full L2 order book since 2026-07-25,
15
+ licensed CC BY 4.0), and **labelled EVM wallets** on Ethereum and BNB Chain, with Base for token
16
+ transfers. The same data is served three ways: an **MCP server** at `https://vike.io/mcp` (the one
17
+ this CLI calls), a **REST API** at `https://data.vike.io/v1/`, and the **Parquet archive** at
18
+ `https://data.vike.io/archive/`. A key allows 20,000 requests an hour, and an account can hold up
19
+ to 5 keys; archive downloads are not counted. The archive manifest and a sample market need no key
20
+ at all. Market data from centralised exchanges is not offered through the REST API.
11
21
 
12
22
  ## Install
13
23
 
14
24
  ```bash
15
- # Standard install — gives you the `vike` binary
25
+ # The CLI (Node.js >= 22.12). Installs the `vike` binary.
16
26
  npm install -g @vike-io/cli
17
27
 
18
- # OR install just the skill playbooks into your AI agent (Claude Code, Cursor,
19
- # Codex, Copilot, OpenCode and 50+ more — auto-detected):
28
+ # OR install only the skill playbooks into your AI agent (Claude Code, Cursor,
29
+ # Codex, Copilot and others; the agent is auto-detected):
20
30
  npx skills add vike-io/vike-data-cli
21
31
  ```
22
32
 
23
- After `npm install`, you can also drop the skill into AI agents from the CLI itself:
33
+ ## Quickstart
34
+
35
+ Get a free key at [vike.io/account?tab=api-keys](https://vike.io/account?tab=api-keys) (keys start
36
+ with `vk_`), then:
24
37
 
25
38
  ```bash
26
- vike install --all # writes to ~/.claude/skills/vike/, .cursorrules,
27
- # .github/copilot-instructions.md, AGENTS.md
39
+ vike init # paste the key; saves ~/.vike/config.json, checks vike.io/mcp
40
+ vike doctor # Node version, key, MCP connectivity, tool list
41
+ vike token search PEPE # first query
42
+ vike perp top-traders --window 7d # Hyperliquid wallets ranked by PnL
43
+ vike candles hl BTC --interval 1h --limit 48
44
+ vike polymarket markets --category Crypto # trending markets by 24h volume
28
45
  ```
29
46
 
30
- ## Quick start
47
+ The key is read from `VIKE_API_KEY` first, then from `~/.vike/config.json`
48
+ (`vike login --api-key vk_...` writes it, `vike logout` removes it).
49
+
50
+ ## Free datasets
51
+
52
+ | Dataset | What is in it | Access | Page |
53
+ |---|---|---|---|
54
+ | **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) |
55
+ | **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) |
56
+ | **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) |
57
+ | **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) |
58
+ | **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) |
59
+ | **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) |
60
+
61
+ Direct links that need no key:
62
+
63
+ - Archive manifest (every date, per-stream bytes and row counts, the schema, the license):
64
+ <https://data.vike.io/archive/manifest.json>
65
+ - Free sample, one complete 5-minute crypto up/down market (both outcome tokens, open through
66
+ resolution), regenerated daily: <https://data.vike.io/archive/samples/>
67
+ ([README.txt](https://data.vike.io/archive/samples/README.txt),
68
+ [book_events.parquet](https://data.vike.io/archive/samples/book_events.parquet),
69
+ [trades.parquet](https://data.vike.io/archive/samples/trades.parquet),
70
+ [l1_quotes.parquet](https://data.vike.io/archive/samples/l1_quotes.parquet))
71
+
72
+ Archive layout: `https://data.vike.io/archive/venue=polymarket/date=YYYY-MM-DD/{book_events,trades,l1_quotes}.parquet`.
73
+ A full-day `book_events` file is several GB; `trades` is around 12 MB.
31
74
 
32
75
  ```bash
33
- vike init # interactive: paste API key, verify connection
34
- vike doctor # confirm everything works
35
- vike token search BTC # your first query
76
+ # No key: the newest day in the archive, and the sample tape
77
+ curl -s https://data.vike.io/archive/manifest.json | jq '.dates[0]'
78
+ curl -O https://data.vike.io/archive/samples/trades.parquet
79
+
80
+ # Free key: one full day of the Polymarket tape, and a day of BTC cohort positioning
81
+ export VIKE_API_KEY=vk_...
82
+ curl -H "X-API-KEY: $VIKE_API_KEY" -C - -o polymarket-trades-2026-10-16.parquet \
83
+ "https://data.vike.io/archive/venue=polymarket/date=2026-10-16/trades.parquet"
84
+ curl -H "X-API-KEY: $VIKE_API_KEY" \
85
+ "https://data.vike.io/v1/hyperliquid/coins/BTC/cohort-metrics?axis=size&hours=24"
36
86
  ```
37
87
 
38
- Get an API key at [vike.io/account?tab=api-keys](https://vike.io/account?tab=api-keys).
88
+ Download an archive file whole, then read the local copy. A Parquet reader (DuckDB, polars,
89
+ pyarrow) pointed at the URL turns one file into thousands of HTTP Range requests.
90
+
91
+ Full catalog: [vike.io/data/datasets](https://vike.io/data/datasets) · field reference:
92
+ [vike.io/data/schemas](https://vike.io/data/schemas) · keys and limits:
93
+ [vike.io/data/api](https://vike.io/data/api).
39
94
 
40
- ## Commands at a glance
95
+ ## MCP server
41
96
 
97
+ The crypto data MCP server is `https://vike.io/mcp` (Streamable HTTP, JSON-RPC 2.0), keyed with
98
+ the same `X-API-KEY`. MCP and REST calls share one hourly counter.
99
+
100
+ ```bash
101
+ # Claude Code
102
+ claude mcp add --transport http vike https://vike.io/mcp \
103
+ --header "X-API-KEY: $VIKE_API_KEY"
42
104
  ```
43
- vike token search | transfers | screener | holders
44
- vike wallet summary | discover
45
- vike perp funding | spreads | top-traders
46
- vike candles hl <symbol> | polymarket <token_id>
47
- vike alerts list | channels | create | edit | delete
48
- vike init | doctor | schema | whoami | login | logout
105
+
106
+ Cursor, in `~/.cursor/mcp.json`:
107
+
108
+ ```json
109
+ {
110
+ "mcpServers": {
111
+ "vike": {
112
+ "url": "https://vike.io/mcp",
113
+ "headers": { "X-API-KEY": "YOUR_KEY" }
114
+ }
115
+ }
116
+ }
49
117
  ```
50
118
 
51
- Run `vike schema --pretty` for the full command + flag reference.
119
+ **Claude Desktop needs no key:** Settings → Connectors → Add custom connector, URL
120
+ `https://vike.io/mcp`, leave the OAuth fields empty, then log in to Vike and click Allow.
121
+ Setup for Gemini CLI, VS Code and other clients: [vike.io/docs/ai/data/setup](https://vike.io/docs/ai/data/setup).
52
122
 
53
- ## What it does
123
+ ```bash
124
+ # Raw JSON-RPC: list the tools your key can call
125
+ curl https://vike.io/mcp -H "X-API-KEY: $VIKE_API_KEY" \
126
+ -H "Content-Type: application/json" \
127
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
128
+ ```
54
129
 
55
- | Domain | What you can ask |
56
- |---|---|
57
- | **Tokens** | Resolve symbols → addresses, see top buyers/sellers, screen by smart-money flow |
58
- | **Wallets** | Aggregate metrics per wallet, leaderboards by volume / PnL / netflow |
59
- | **Perps** | Funding rates + cross-venue spreads across Binance / Bybit / OKX / Aster / Hyperliquid |
60
- | **Hyperliquid** | Top-trader leaderboard with PnL / ROI / win-rate filters |
61
- | **Candles** | Historical OHLCV for Hyperliquid perp/spot markets and Polymarket outcome tokens |
62
- | **Alerts** | Create transfer alerts; deliver to email or Discord |
130
+ On `/mcp` a bad or missing key comes back as a JSON-RPC `error` in the body, so check the body and
131
+ not only the HTTP status. A rate-limited call gets HTTP 429 with `Retry-After: 60`.
63
132
 
64
- ## For AI agents
133
+ ## CLI commands
65
134
 
66
- This package ships **36 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 / Candles / Polymarket / Alerts).
135
+ Every data command is one `tools/call` to the MCP server. `vike <group> --help` lists the flags;
136
+ `vike schema --pretty` prints every tool the server exposes, with its parameters.
67
137
 
68
- Three install paths, pick whichever fits your stack:
138
+ | Command | Subcommands | MCP tool |
139
+ |---|---|---|
140
+ | `vike token` | `search`, `transfers`, `screener`, `holders` (`--chain ethereum\|bsc\|base`) | `token_search`, `token_transfers`, `token_screener`, `token_holders` |
141
+ | `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` |
142
+ | `vike labels <address>` | multi-source label provenance for one wallet | `wallet_label_provenance` |
143
+ | `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` |
144
+ | `vike candles` | `hl <symbol>` (Hyperliquid perp or spot, from executed fills), `polymarket <token_id>` (one outcome token) | `hl_ohlcv`, `polymarket_ohlcv` |
145
+ | `vike polymarket` (`pm`) | `markets`, `market <condition_id>`, `wallet <address>`, `smart-money` | `polymarket_markets`, `polymarket_market_detail`, `polymarket_wallet`, `polymarket_smart_money` |
146
+ | `vike alerts` | `list`, `channels`, `create`, `edit`, `delete`, `register-webhook` (email, Discord, or an HTTPS webhook, HMAC-signed when you set a secret) | `alerts_*` |
147
+ | setup | `init`, `login`, `logout`, `doctor`, `schema`, `install` | — |
148
+
149
+ Output is a table on a terminal and JSON with `--json` or whenever stdout is piped:
69
150
 
70
151
  ```bash
71
- # 1. Install just the skill files for your agent (no Node binary needed):
72
- npx skills add vike-io/vike-data-cli # auto-detects the agent
73
- npx skills add vike-io/vike-data-cli -a claude-code # explicit target
74
- npx skills add vike-io/vike-data-cli --list # list all 41 first
152
+ vike token search BTC --json | jq '.'
153
+ ```
75
154
 
76
- # 2. Use the CLI itself to install the umbrella skill into multiple agents:
77
- vike install --claude --cursor --copilot --agents
155
+ ## Examples
156
+
157
+ [`examples/`](examples/) holds three Python scripts. Each declares its dependencies inline, so
158
+ `uv run` installs them; plain `pip install polars requests duckdb` works too.
159
+
160
+ | Script | What it does | Key |
161
+ |---|---|---|
162
+ | [`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 |
163
+ | [`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 |
164
+ | [`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 |
78
165
 
79
- # 3. Manual: point your agent at the skills/ folder of this npm package
80
- # (lives at node_modules/@vike-io/cli/skills/ after install).
166
+ ```bash
167
+ uv run examples/polymarket_archive.py
168
+ VIKE_API_KEY=vk_... uv run examples/hyperliquid_cohorts.py
169
+ uv run examples/duckdb_archive.py
81
170
  ```
82
171
 
83
- 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).
172
+ Downloads go to `./vike-archive/`.
84
173
 
85
- ## Auth
174
+ ## For AI agents
86
175
 
87
- Three ways to provide your key, in order of precedence:
176
+ This package ships **36 skill playbooks** under [`skills/`](skills/): markdown files an AI coding
177
+ agent loads so it knows when and how to call each command. [`skills.sh.json`](skills.sh.json) groups
178
+ them by domain (Tokens, Wallets, CEX perps, Hyperliquid perps, Candles, Polymarket, Alerts). The
179
+ entry point is the umbrella skill `vike`, which routes a question to the specialised skill.
88
180
 
89
181
  ```bash
90
- export VIKE_API_KEY=vk_... # env (wins over everything)
91
- vike login --api-key vk_... # saved to ~/.vike/config.json
92
- vike init # interactive
182
+ npx skills add vike-io/vike-data-cli --list # see them first
183
+ npx skills add vike-io/vike-data-cli # install
184
+
185
+ # Or, from the installed CLI, write the umbrella skill into each agent's location:
186
+ vike install --claude # ~/.claude/skills/vike/SKILL.md
187
+ vike install --cursor # ./.cursorrules
188
+ vike install --copilot # ./.github/copilot-instructions.md
189
+ vike install --agents # ./AGENTS.md
190
+ vike install --all # all four
93
191
  ```
94
192
 
193
+ `vike install` replaces only its own `<!-- vike-skill:begin -->` ... `<!-- vike-skill:end -->`
194
+ block in files it does not own.
195
+
95
196
  ## Environment
96
197
 
97
198
  | Variable | Default | Purpose |
98
199
  |---|---|---|
99
- | `VIKE_API_KEY` | — | API key (overrides saved config) |
100
- | `VIKE_MCP_URL` | `https://vike.io/mcp` | MCP endpoint (override for staging/local) |
200
+ | `VIKE_API_KEY` | — | API key; wins over the saved config |
201
+ | `VIKE_MCP_URL` | `https://vike.io/mcp` | MCP endpoint override |
202
+ | `VIKE_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` | telemetry on | Turns off anonymous usage telemetry |
203
+ | `VIKE_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER=1` | check on | Turns off the background npm update check |
101
204
 
102
- ## Output formatting
205
+ Telemetry sends the command name, the flag names (never their values), the duration, an error code
206
+ and a random device id. It never sends what you queried, and it is off when `CI` is set.
103
207
 
104
- By default, table output for humans (TTY) and JSON when piped:
105
-
106
- ```bash
107
- vike token search BTC # pretty table
108
- vike token search BTC --json # JSON
109
- vike token search BTC | jq '.' # auto-JSON when piped
110
- ```
208
+ `vike` here is the Data API client. The Vike Trader platform has its own, separate command line,
209
+ `vike-cli` ([docs](https://vike.io/docs/trader/cli)).
111
210
 
112
211
  ## License
113
212
 
114
- MIT — see [LICENSE](LICENSE).
213
+ The CLI is MIT, see [LICENSE](LICENSE). Archive data files are CC BY 4.0: use them for anything
214
+ and credit Vike ("Polymarket L2 archive (c) Vike (vike.io/data), CC BY 4.0"). Details:
215
+ [vike.io/data/licensing](https://vike.io/data/licensing).
115
216
 
116
217
  ## Links
117
218
 
118
- - Homepage: [vike.io](https://vike.io)
219
+ - Free Data API: [vike.io/data](https://vike.io/data/)
220
+ - 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)
221
+ - For LLMs: [vike.io/llms.txt](https://vike.io/llms.txt) · [vike.io/docs/llms.txt](https://vike.io/docs/llms.txt)
119
222
  - Issues: [github.com/vike-io/vike-data-cli/issues](https://github.com/vike-io/vike-data-cli/issues)
120
- - API docs: [vike.io/api](https://vike.io/api)
package/package.json CHANGED
@@ -3,8 +3,8 @@
3
3
  "publishConfig": {
4
4
  "access": "public"
5
5
  },
6
- "version": "0.12.0",
7
- "description": "AI-agent CLI for vike.io on-chain analytics, perps, options, and prediction markets across 11 chains",
6
+ "version": "0.12.1",
7
+ "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",
8
8
  "type": "module",
9
9
  "main": "src/index.js",
10
10
  "bin": {
@@ -44,14 +44,16 @@
44
44
  "onchain",
45
45
  "perps",
46
46
  "hyperliquid",
47
- "options",
48
- "deribit",
49
47
  "polymarket",
50
48
  "prediction-markets",
51
49
  "defi",
52
50
  "ethereum",
53
51
  "bsc",
54
- "base"
52
+ "base",
53
+ "parquet",
54
+ "order-book",
55
+ "historical-data",
56
+ "crypto-data"
55
57
  ],
56
58
  "author": "vike.io",
57
59
  "license": "MIT",
package/scripts/postinstall.js CHANGED
@@ -30,7 +30,8 @@ try {
30
30
  ' vike doctor — verify your install',
31
31
  ' vike token search BTC — your first query',
32
32
  '',
33
- ' Docs: https://vike.io/api',
33
+ ' Docs: https://vike.io/data/',
34
+ ' API key: https://vike.io/account?tab=api-keys',
34
35
  '',
35
36
  ];
36
37
  process.stdout.write(lines.join('\n'));
package/skills/vike/SKILL.md CHANGED
@@ -5,11 +5,17 @@ description: "Use this skill whenever the user asks any question about on-chain
5
5
 
6
6
  # vike — Multi-chain On-chain Analytics
7
7
 
8
+ 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.
9
+
8
10
  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.
9
11
 
10
12
  **MCP endpoint for all calls:** `https://vike.io/mcp` (JSON-RPC 2.0)
11
13
  **Or use the CLI:** `npm install -g @vike-io/cli` → `vike <command>`
12
14
 
15
+ ## What it does and who it is for
16
+
17
+ It is for traders, researchers and developers who use an AI agent to look at crypto data. With this skill the agent knows which vike tool to call for wallets, tokens, smart money, Hyperliquid perps, Polymarket markets and alerts. It also knows how to read each answer and what the tools cannot do, so it reports real numbers instead of guesses. The data comes from vike.io and a free vike API key is needed.
18
+
13
19
  ---
14
20
 
15
21
  ## Critical Rules
@@ -53,7 +59,7 @@ If the user has no API key yet, tell them:
53
59
  >
54
60
  > Per-key default cap: 2000 requests/hour. Most calls return in <500ms.
55
61
 
56
- If using the MCP server directly (without the CLI), send the key as a header:
62
+ If using the MCP server directly (without the CLI), authenticate with the key in this header:
57
63
  ```
58
64
  X-API-KEY: vk_...
59
65
  ```
@@ -118,22 +124,7 @@ vike wallet summary 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --json
118
124
  vike perp funding --symbol BTC --window 24h --json
119
125
  ```
120
126
 
121
- **B) Via MCP JSON-RPC (recommended when an MCP connector is available).** All 34 tools live at `https://vike.io/mcp`:
122
- ```http
123
- POST https://vike.io/mcp
124
- X-API-KEY: vk_...
125
- Content-Type: application/json
126
-
127
- {
128
- "jsonrpc": "2.0",
129
- "id": 1,
130
- "method": "tools/call",
131
- "params": {
132
- "name": "wallet_summary",
133
- "arguments": {"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "chain": "ethereum"}
134
- }
135
- }
136
- ```
127
+ **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`.
137
128
 
138
129
  Run `vike 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.
139
130
 
@@ -141,17 +132,17 @@ Run `vike schema --pretty` (or call MCP `tools/list`) to see the live arg shape
141
132
 
142
133
  ## Per-service tool reference
143
134
 
144
- For deeper per-tool workflows (multi-step recipes, common pitfalls, output schemas), see the `skills/` directory in this repo. The router lives at [`skills/vike-router/SKILL.md`](skills/vike-router/SKILL.md).
135
+ 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`.
145
136
 
146
137
  ### Tokens
147
138
  Address resolution, transfers, holder cohorts, screening.
148
139
 
149
140
  | Tool | Description | Skill |
150
141
  |---|---|---|
151
- | `token_search` | Symbol/name → contract address + chain + market cap | [vike-token-search](skills/vike-token-search/SKILL.md) |
152
- | `token_transfers` | Recent transfers with USD values; supports `--min-usd`, time windows | [vike-token-transfers](skills/vike-token-transfers/SKILL.md) |
153
- | `token_holders` | Top holders + concentration metrics | [vike-token-holders](skills/vike-token-holders/SKILL.md) |
154
- | `token_screener` | Filter tokens by smart-money inflow, age, liquidity, sector | [vike-token-screener](skills/vike-token-screener/SKILL.md) |
142
+ | `token_search` | Symbol/name → contract address + chain + market cap | `vike-token-search` |
143
+ | `token_transfers` | Recent transfers with USD values; supports `--min-usd`, time windows | `vike-token-transfers` |
144
+ | `token_holders` | Top holders + concentration metrics | `vike-token-holders` |
145
+ | `token_screener` | Filter tokens by smart-money inflow, age, liquidity, sector | `vike-token-screener` |
155
146
 
156
147
  **Key chains:** `ethereum`, `bsc`, `base`, `arbitrum`, `hyperevm` (EVM); `bitcoin`, `solana`, `tron`, `xmr`, `zec`, `dash` (non-EVM, limited tool support).
157
148
 
@@ -162,16 +153,16 @@ Profile, PnL, transactions, comparison, tracing, counterparty graph.
162
153
 
163
154
  | Tool | Description | Skill |
164
155
  |---|---|---|
165
- | `wallet_summary` | One-call profile: PnL, top holdings, recent activity, labels | [vike-wallet-summary](skills/vike-wallet-summary/SKILL.md) |
166
- | `wallet_discover` | Leaderboard of top wallets by PnL/inflow on a token | [vike-wallet-discover](skills/vike-wallet-discover/SKILL.md), [vike-smart-money-discovery](skills/vike-smart-money-discovery/SKILL.md) |
167
- | `wallet_transactions` | Raw recent transactions (tx_hash, ts, from, to, token, usd) | [vike-wallet-transactions](skills/vike-wallet-transactions/SKILL.md) |
168
- | `wallet_compare` | Side-by-side metrics for 2+ wallets | [vike-wallet-compare](skills/vike-wallet-compare/SKILL.md) |
169
- | `wallet_trace` | BFS funds tracing N hops from a starting wallet | [vike-wallet-trace](skills/vike-wallet-trace/SKILL.md) |
170
- | `wallet_counterparties` | Top counterparties (who they send to / receive from) | [vike-wallet-counterparties](skills/vike-wallet-counterparties/SKILL.md) |
171
- | `wallet_pnl_history` | Daily PnL timeseries over `--days N` | [vike-wallet-pnl-history](skills/vike-wallet-pnl-history/SKILL.md) |
172
- | `wallet_token_balances` | Current token balances (Moralis-backed) | [vike-wallet-balances](skills/vike-wallet-balances/SKILL.md) |
173
- | `wallet_ens` | ENS name ↔ address (local cache: 477K wallets pre-resolved) | [vike-wallet-ens](skills/vike-wallet-ens/SKILL.md) |
174
- | `wallet_batch_labels` | Bulk-label up to 100 addresses in one call | [vike-wallet-batch](skills/vike-wallet-batch/SKILL.md) |
156
+ | `wallet_summary` | One-call profile: PnL, top holdings, recent activity, labels | `vike-wallet-summary` |
157
+ | `wallet_discover` | Leaderboard of top wallets by PnL/inflow on a token | `vike-wallet-discover`, `vike-smart-money-discovery` |
158
+ | `wallet_transactions` | Raw recent transactions (tx_hash, ts, from, to, token, usd) | `vike-wallet-transactions` |
159
+ | `wallet_compare` | Side-by-side metrics for 2+ wallets | `vike-wallet-compare` |
160
+ | `wallet_trace` | BFS funds tracing N hops from a starting wallet | `vike-wallet-trace` |
161
+ | `wallet_counterparties` | Top counterparties (who they send to / receive from) | `vike-wallet-counterparties` |
162
+ | `wallet_pnl_history` | Daily PnL timeseries over `--days N` | `vike-wallet-pnl-history` |
163
+ | `wallet_token_balances` | Current token balances (Moralis-backed) | `vike-wallet-balances` |
164
+ | `wallet_ens` | ENS name ↔ address (local cache: 477K wallets pre-resolved) | `vike-wallet-ens` |
165
+ | `wallet_batch_labels` | Bulk-label up to 100 addresses in one call | `vike-wallet-batch` |
175
166
 
176
167
  **Address shape:** always full 0x-prefixed hex (42 chars). Never truncate when reporting back to the user.
177
168
 
@@ -182,7 +173,7 @@ Wallet label provenance.
182
173
 
183
174
  | Tool | Description | Skill |
184
175
  |---|---|---|
185
- | `wallet_label_provenance` | Why a wallet got a given label (sources + confidence) | [vike-wallet-label-provenance](skills/vike-wallet-label-provenance/SKILL.md) |
176
+ | `wallet_label_provenance` | Why a wallet got a given label (sources + confidence) | `vike-wallet-label-provenance` |
186
177
 
187
178
  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.
188
179
 
@@ -193,8 +184,8 @@ Vike's label cascade is multi-source — when an answer hinges on "is this reall
193
184
 
194
185
  | Tool | Description | Skill |
195
186
  |---|---|---|
196
- | `perp_funding` | Funding rates per symbol per venue + 24h/7d averages | [vike-perp-funding-arb](skills/vike-perp-funding-arb/SKILL.md) |
197
- | `perp_spreads` | Mark-price spreads of the same symbol across venues | [vike-perp-spread-arb](skills/vike-perp-spread-arb/SKILL.md), [vike-cross-venue-perps](skills/vike-cross-venue-perps/SKILL.md) |
187
+ | `perp_funding` | Funding rates per symbol per venue + 24h/7d averages | `vike-perp-funding-arb` |
188
+ | `perp_spreads` | Mark-price spreads of the same symbol across venues | `vike-perp-spread-arb`, `vike-cross-venue-perps` |
198
189
 
199
190
  ---
200
191
 
@@ -203,10 +194,10 @@ On-chain perps data: snapshots, fills, ledger, funding, attribution.
203
194
 
204
195
  | Tool | Description | Skill |
205
196
  |---|---|---|
206
- | `hl_perp_top_traders` | Top HL traders by PnL/volume over a window | [vike-hl-top-traders](skills/vike-hl-top-traders/SKILL.md), [vike-hl-trader-profile](skills/vike-hl-trader-profile/SKILL.md) |
207
- | `hl_position_match` | Reverse-lookup: share-card details (coin/side/lev/entry) → wallet holding that open position | [vike-hl-position-match](skills/vike-hl-position-match/SKILL.md) |
197
+ | `hl_perp_top_traders` | Top HL traders by PnL/volume over a window | `vike-hl-top-traders`, `vike-hl-trader-profile` |
198
+ | `hl_position_match` | Reverse-lookup: share-card details (coin/side/lev/entry) → wallet holding that open position | `vike-hl-position-match` |
208
199
 
209
- For per-symbol HL screening / individual trader deep-dive, use [vike-perp-screener](skills/vike-perp-screener/SKILL.md) and [vike-hl-trader-profile](skills/vike-hl-trader-profile/SKILL.md).
200
+ For per-symbol HL screening / individual trader deep-dive, use `vike-perp-screener` and `vike-hl-trader-profile`.
210
201
 
211
202
  ---
212
203
 
@@ -215,8 +206,8 @@ Historical OHLCV from venues whose data is on-chain.
215
206
 
216
207
  | Tool | Description | Skill |
217
208
  |---|---|---|
218
- | `hl_ohlcv` | Hyperliquid perp or spot candles, 1m–1d, built from HL's own executed fills (also HIP-3 builder DEXs) | [vike-candles](skills/vike-candles/SKILL.md) |
219
- | `polymarket_ohlcv` | Candles for ONE Polymarket outcome token (price = probability, 0–1); needs `token_id`, not a condition_id | [vike-candles](skills/vike-candles/SKILL.md) |
209
+ | `hl_ohlcv` | Hyperliquid perp or spot candles, 1m–1d, built from HL's own executed fills (also HIP-3 builder DEXs) | `vike-candles` |
210
+ | `polymarket_ohlcv` | Candles for ONE Polymarket outcome token (price = probability, 0–1); needs `token_id`, not a condition_id | `vike-candles` |
220
211
 
221
212
  ---
222
213
 
@@ -225,10 +216,10 @@ Prediction markets — markets, traders, smart-money.
225
216
 
226
217
  | Tool | Description | Skill |
227
218
  |---|---|---|
228
- | `polymarket_markets` | Active markets sorted by volume / liquidity / volatility | [vike-polymarket-markets](skills/vike-polymarket-markets/SKILL.md), [vike-polymarket-screener](skills/vike-polymarket-screener/SKILL.md) |
229
- | `polymarket_market_detail` | Single market: outcomes, holders, recent trades, time-to-resolution | [vike-polymarket-market-detail](skills/vike-polymarket-market-detail/SKILL.md) |
230
- | `polymarket_wallet` | One trader's positions, PnL, win rate | [vike-polymarket-trader](skills/vike-polymarket-trader/SKILL.md) |
231
- | `polymarket_smart_money` | Top-PnL Polymarket traders + their current open positions | [vike-polymarket-smart-money](skills/vike-polymarket-smart-money/SKILL.md) |
219
+ | `polymarket_markets` | Active markets sorted by volume / liquidity / volatility | `vike-polymarket-markets`, `vike-polymarket-screener` |
220
+ | `polymarket_market_detail` | Single market: outcomes, holders, recent trades, time-to-resolution | `vike-polymarket-market-detail` |
221
+ | `polymarket_wallet` | One trader's positions, PnL, win rate | `vike-polymarket-trader` |
222
+ | `polymarket_smart_money` | Top-PnL Polymarket traders + their current open positions | `vike-polymarket-smart-money` |
232
223
 
233
224
  ---
234
225
 
@@ -237,12 +228,12 @@ Create + manage alerts; deliver to email, Telegram, Discord, Webhook.
237
228
 
238
229
  | Tool | Description | Skill |
239
230
  |---|---|---|
240
- | `alerts_list` | List user's existing alerts | [vike-alerts-setup](skills/vike-alerts-setup/SKILL.md) |
241
- | `alerts_create` | Create a new price/transfer/funding alert | [vike-alerts-setup](skills/vike-alerts-setup/SKILL.md) |
242
- | `alerts_edit` | Edit an existing alert | [vike-alerts-setup](skills/vike-alerts-setup/SKILL.md) |
243
- | `alerts_delete` | Delete an alert | [vike-alerts-setup](skills/vike-alerts-setup/SKILL.md) |
244
- | `alerts_list_channels` | List user's registered delivery channels | [vike-alerts-setup](skills/vike-alerts-setup/SKILL.md) |
245
- | `alerts_register_webhook` | Register an HTTPS webhook (HMAC-signed deliveries) | [vike-alerts-webhook](skills/vike-alerts-webhook/SKILL.md) |
231
+ | `alerts_list` | List user's existing alerts | `vike-alerts-setup` |
232
+ | `alerts_create` | Create a new price/transfer/funding alert | `vike-alerts-setup` |
233
+ | `alerts_edit` | Edit an existing alert | `vike-alerts-setup` |
234
+ | `alerts_delete` | Delete an alert | `vike-alerts-setup` |
235
+ | `alerts_list_channels` | List user's registered delivery channels | `vike-alerts-setup` |
236
+ | `alerts_register_webhook` | Register an HTTPS webhook (HMAC-signed deliveries) | `vike-alerts-webhook` |
246
237
 
247
238
  Alerts fire on a 2-minute cron cycle (not streaming). Don't recommend WebSocket / push streaming — it's not how the platform works.
248
239
 
package/skills/vike-hl-position-match/SKILL.md CHANGED
@@ -81,6 +81,6 @@ The response includes `tolerance_used` so the caller knows which band matched (`
81
81
 
82
82
  ## Pairs well with
83
83
 
84
- - [vike-wallet-summary](../vike-wallet-summary/SKILL.md) — once you have the address, get the trader's HL profile + multi-chain identity.
85
- - [vike-hl-top-traders](../vike-hl-top-traders/SKILL.md) — check if the matched wallet is on a leaderboard.
86
- - [vike-wallet-label-provenance](../vike-wallet-label-provenance/SKILL.md) — find out if the wallet is a known CEX/fund/MM rather than a retail trader.
84
+ - `vike-wallet-summary` — once you have the address, get the trader's HL profile + multi-chain identity.
85
+ - `vike-hl-top-traders` — check if the matched wallet is on a leaderboard.
86
+ - `vike-wallet-label-provenance` — find out if the wallet is a known CEX/fund/MM rather than a retail trader.
package/src/commands/init.js CHANGED
@@ -33,7 +33,7 @@ export function registerInit(program) {
33
33
 
34
34
  console.log('Verifying connection to vike.io/mcp ...');
35
35
  const { status, body } = await ping({ apiKey: key });
36
- if (status !== 200) {
36
+ if (status !== 200 || body?.error) {
37
37
  console.error(`Endpoint returned HTTP ${status}: ${JSON.stringify(body)}`);
38
38
  process.exitCode = 1;
39
39
  return;
package/src/mcp-client.js CHANGED
@@ -1,4 +1,4 @@
1
- import { requireApiKey, getEndpoint, getApiKey } from './auth.js';
1
+ import { requireApiKey, getEndpoint } from './auth.js';
2
2
 
3
3
  let _id = 0;
4
4
  function nextId() { return ++_id; }
@@ -78,14 +78,13 @@ export async function listTools(opts = {}) {
78
78
  }
79
79
 
80
80
  export async function ping(opts = {}) {
81
- // initialize doesn't require auth — useful for `vike doctor`
81
+ // /mcp authenticates every method, initialize included: no key gets a
82
+ // JSON-RPC "Invalid or missing API key" error (soon HTTP 401), so fail early.
82
83
  const endpoint = opts.endpoint ?? getEndpoint();
83
- const apiKey = opts.apiKey ?? getApiKey();
84
- const headers = { 'Content-Type': 'application/json' };
85
- if (apiKey) headers['X-API-KEY'] = apiKey;
84
+ const apiKey = opts.apiKey ?? requireApiKey();
86
85
  const resp = await fetch(endpoint, {
87
86
  method: 'POST',
88
- headers,
87
+ headers: { 'Content-Type': 'application/json', 'X-API-KEY': apiKey },
89
88
  body: JSON.stringify({
90
89
  jsonrpc: '2.0', id: nextId(), method: 'initialize', params: {},
91
90
  }),