@vike-io/cli 0.13.0 → 0.14.0

package/skills/vike-wallet-discover/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vike-wallet-discover
 description: Rank wallets by volume / inflow / outflow / pnl / net_flow / tx_count across a time window. Use when the user asks "top wallets on X" / "best traders by PnL" / "biggest buyers last 7d".
-allowed-tools: Bash(vike:*)
+allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-wallet-discover
@@ -14,7 +14,7 @@ vike-data wallet discover
   [--sort volume|inflow|outflow|net_flow|tx_count|pnl]
   [--order asc|desc]
   [--chain ethereum|bsc]
-  [--size N]      # max 20
+  [--size N]      # default 10, max 20
   [--json]
 ```
 
@@ -24,26 +24,33 @@ vike-data wallet discover
 |---|---|
 | "Top whales by volume this week" | `--sort volume --window 7d` |
 | "Biggest accumulators last 30d" | `--sort net_flow --window 30d --order desc` |
-| "Top realized-PnL traders all-time" | `--sort pnl --window all` |
 | "Wallets dumping the most this 24h" | `--sort outflow --window 24h` |
 | "Most active traders last 7d" | `--sort tx_count --window 7d` |
+| "Best PnL" | `--sort pnl --window all`: an ordering only, see below |
 
-## Output columns
+## Output
 
-`address`, `label` (when known), `volume_usd`, `inflow_usd`, `outflow_usd`, `net_flow_usd`, `tx_count`, `realized_pnl_usd`.
+An object `{ "wallets": [...], "total": N }`. `total` is the size of the matching population, not the number of rows.
+
+Each wallet: `address`, `volume`, `inflow`, `outflow`, `net_flow`, `tx_count`, `tokens_traded`, `first_seen`, `last_active`, `realized_pnl`, `tokens_profitable`, `pnl_available`. USD columns are already plain dollars.
+
+There is **no label column** and no `*_usd` suffix. To name the wallets, pass the addresses to `vike-data wallet batch`.
 
 ## Reading tips
 
-- Labeled wallets first — `label = "binance_cold_t1"` means it's a CEX hot/cold wallet, not a discretionary trader.
-- Always filter mentally for unlabeled wallets first if the user wants "real traders" (not exchanges).
-- For PnL sort, realized PnL only — open positions are NOT counted. Use `vike-data perp top-traders` for HL perps PnL (which includes unrealized).
+- **`realized_pnl` is a ranking key, not a dollar figure.** Stored values are wrong for many wallets (a measurement found 233 of 500 sampled Ethereum leaderboard wallets at 10× or more above the rebuilt value, and the top rows can show a profit thousands of times the wallet's own volume). Use `--sort pnl` only to order wallets against each other, never quote `realized_pnl`, and never call `pnl_available: 1` a guarantee. It is computed from on-chain transfers; Hyperliquid PnL is a different dataset (`vike-data perp top-traders`, realized PnL only: open positions are not included).
+- `first_seen` here is not a lifetime first-seen (it disagrees with `wallet summary`); read it as "first seen in this dataset".
+- Labeled wallets first: after `wallet batch`, `entity = "binance"` / `wallet_type = "cex"` means a CEX hot or cold wallet, not a discretionary trader. Filter those out if the user wants "real traders".
+- Top volume wallets are almost always bots, routers and venues. `net_flow` is the more informative sort for "who is accumulating", and even then check the wallet type.
 
 ## Anti-patterns
 
-- `--size > 20` is silently clamped to 20. Run a second call with offset (not currently supported — limit applies hard) if you need more.
-- `--sort pnl` is only meaningful on `--window 30d` or longer; 24h PnL is noise.
+- `--size > 20` is silently clamped to 20, and there is no offset: the tool is a top-of-leaderboard view. Don't promise a deeper list.
+- Don't build "smart money" lists on `--sort pnl` (see `vike-smart-money-discovery` for the supported route).
+- Don't use this for a single wallet: `wallet summary` is the right call.
 
 ## Pairs well with
 
+- `vike-data wallet batch <addr...>` to label the rows
 - `vike-data wallet summary <address>` to drill into any interesting row
-- `vike-smart-money-discovery` for a composite multi-signal read
+- `vike-smart-money-discovery` for the smart-money read

package/skills/vike-wallet-ens/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vike-wallet-ens
 description: Reverse ENS lookup — turn a 0x address into a human-readable name like `vitalik.eth`. Cheap, single API call. Use whenever you have an address and want to display a friendlier identifier alongside it.
-allowed-tools: Bash(vike:*)
+allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-wallet-ens
@@ -16,23 +16,27 @@ vike-data wallet ens <address> [--json]
 
 ```bash
 vike-data wallet ens 0xd8da6bf26964af9d7eed9e03e53415d37aa96045
-# → { "address": "0xd8da...", "ens": "vitalik.eth" }
+# → { "address": "0xd8da...", "ens": "vitalik.eth", "source": "local" }
 
 vike-data wallet ens 0x28c6c06298d514db089934071355e5743bf21d60
-# → { "address": "0x28c6...", "ens": null }      (most exchange wallets have no ENS)
+# → { "address": "0x28c6...", "ens": null, "source": "local" }      (most exchange wallets have no ENS)
 ```
 
 ## When to use
 
 - Right after any tool returns a wallet address — show ENS as a secondary label
-- When the user pastes an address and asks "who is this"
+- When the user pastes an address and asks "what is its ENS name" (for "who is this", start with `vike-data labels <addr>`; ENS is a display name, not an identity)
 - When you're about to display a leaderboard with addresses — enrich each row with ENS if available
 
+## Direction
+
+**Reverse only: address → name.** There is no name → address lookup: if the user gives `vitalik.eth`, say the tool cannot resolve it and ask for the address. The only parameter is `address`.
+
 ## Anti-patterns
 
 - Don't replace the address with the ENS name in tool output — show BOTH. The address is canonical; ENS is a display layer that can change ownership.
 - Don't ENS-lookup hundreds of addresses in a leaderboard at once — credits add up. Usually ENS-lookup only the top 5-10 rows the user is likely to act on.
-- A `null` response is normal, not an error. Most wallets don't have ENS.
+- A `null` response is normal, not an error. Most wallets don't have ENS. The exception: `ens: null` with `source: "rpc"` may only mean the resolvers were unreachable, so retry once before saying the wallet has no name.
 
 ## Pairs well with
 

package/skills/vike-wallet-label-provenance/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vike-wallet-label-provenance
-description: Multi-source label cascade for any ETH wallet — shows what every upstream label provider AND our in-house heuristic classifier says about an address, with consensus entity/type and per-source attribution. Use when the user asks "who is this address" / "what do you know about this wallet" / "is this address labeled".
-allowed-tools: Bash(vike:*)
+description: Multi-source label cascade for an Ethereum wallet — shows what each upstream label source AND our in-house heuristic classifier says about an address, with consensus entity/type and per-source attribution. Use when the user asks "who is this address" / "what do you know about this wallet" / "is this address labeled" / "why is this wallet labeled X".
+allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-wallet-label-provenance
@@ -14,6 +14,8 @@ The headline differentiator: we don't just show a label, we show **which sources
 vike-data labels <address> [--json]
 ```
 
+Ethereum wallets only. For another chain, or many addresses, use `vike-data wallet batch --chain ethereum|bsc|base`, which reads each chain's own label table.
+
 ## Example
 
 ```bash
@@ -27,37 +29,44 @@ vike-data labels 0x28C6c06298d514Db089934071355E5743bf21d60     # Binance Hot Wa
   "address": "0x...",
   "found": true,
   "consensus": {
-    "entity": "Binance",
+    "entity": "binance",
     "wallet_type": "cex",
-    "cex_product": "spot",
-    "user_subtype": "",
-    "risk_flag": "",
-    "confidence": "High"
+    "cex_product": "retail",
+    "user_subtype": "active",
+    "risk_flag": null,
+    "confidence": "medium"
   },
   "sources": [
-    { "source": "provider_a", "label": "Binance 14",        "entity": "Binance", "category": "CEX" },
-    { "source": "provider_b", "label": "Binance Hot Wallet" },
-    { "source": "provider_c", "label": "Binance: Hot Wallet 14" },
-    { "source": "provider_d", "label": "Binance" },
-    { "source": "heuristic:cold_t1", "confidence": 0.94 }
+    { "source": "provider_a", "label": "Binance: Hot Wallet (0x28C)", "entity": "Binance", "category": "Hot Wallet" },
+    { "source": "provider_b", "label": "Binance 14", "entity": "binance", "category": null },
+    { "source": "provider_c", "label": "Binance: Hot Wallet", "entity": "binance", "category": "exchange" },
+    { "source": "provider_d", "label": "binance", "entity": "binance", "category": null },
+    { "source": "heuristic:cold_t1", "label": "binance", "confidence": 0.94 }
   ],
   "source_count": 5
 }
 ```
 
+Sources are anonymised on the wire (`provider_a`, `provider_b`, ...). There are at most 6 raw sources (Arkham, OLI, Blockscout, Dune, the MEW darklist, Etherscan tags), plus the heuristic classifier as a `heuristic:*` source. `source_count` includes the heuristic.
+
 ## Reading
 
-- **5+ sources agree** → very high confidence; ship the label without caveats
-- **2-3 sources agree on same entity** → high confidence
-- **Only 1 source + heuristic** → moderate; mention "labeled by X"
-- **0 sources, only heuristic** → low; mention "predicted by heuristic"
-- **0 sources, no heuristic** → genuinely unknown wallet (most retail addresses)
+- **4+ raw sources agree on the entity** → very high confidence; ship the label without caveats. Six is the ceiling, and most labelled wallets have 1-3.
+- **2-3 sources agree on the same entity** → high confidence
+- **Only 1 source (± heuristic)** → moderate; mention "labeled by one source"
+- **Only the heuristic** → low; mention "predicted by heuristic"
+- **`found: true` with no sources** → the wallet is in our label table but no raw source labels it
+- **`found: false`** → the wallet is missing from our labelled-wallet table, and no source is consulted at all. It does NOT prove that no provider labels it. Say "not in our label table", not "unlabeled" or "clean".
+
+Early answers (before 2026-10-19) carried only the Arkham-derived source and the heuristic, so older transcripts undercount sources.
 
 ## Anti-patterns
 
 - Don't quote any single provider's category field as "the category" — provider taxonomies vary; the `consensus.wallet_type` is the unified field.
 - A `risk_flag` of `scam` / `sanctioned` / `phishing` is high-stakes — always mention it explicitly, never bury it.
+- Don't use this for a BSC or Base address: it reads Ethereum tables only.
 
 ## Pairs well with
 
 - `vike-data wallet summary <addr>` — for the flow metrics of the labeled wallet
+- `vike-data wallet batch <addr...>` — label many addresses, or another chain

package/skills/vike-wallet-pnl-history/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vike-wallet-pnl-history
 description: Daily net-flow series for a wallet over the last N days — a directional proxy for daily PnL. Use when the user asks "how has wallet X done over time" / "show me daily flows for Y" / "is this wallet trending up or down".
-allowed-tools: Bash(vike:*)
+allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-wallet-pnl-history
@@ -15,6 +15,8 @@ vike-data wallet pnl-history <address>
   [--json]
 ```
 
+`--chain base` is accepted, but per-wallet transfer data is documented for Ethereum and BSC: treat an empty Base result as "not covered", not "no activity".
+
 ## Output
 
 ```json
@@ -35,10 +37,11 @@ vike-data wallet pnl-history <address>
 
 **This is NET INFLOW USD, not realized PnL.** True realized PnL requires WAC (weighted-average cost) accounting per token, which we don't do in this fast tool. A wallet that bought $10K and sold $10K of the same token at the SAME price would show $0 here — but if they sold higher, true PnL would be positive (and this tool wouldn't reflect that). Use this for direction + trend, not for tax-grade PnL.
 
-For lifetime realized PnL: `vike-data wallet discover --sort pnl --window all`.
+There is no reliable realized-PnL figure for a wallet in the CLI: `wallet discover` carries a `realized_pnl` column, but it is only an ordering key (many stored values are wrong), so never quote it as dollars.
 
 ## Reading
 
+- The series is **sparse**: one point per day that had activity, not one per day of the range. Zero-fill the calendar before charting or diffing.
 - `cumulative_net_flow_usd` ramping up = wallet has been accumulating $
 - Big positive day with high `tx_count` = single large buy (deposit / acquisition / token purchase)
 - Big negative day with high `tx_count` = sell-down or large transfer out

package/skills/vike-wallet-portfolio/SKILL.md

@@ -1,34 +1,36 @@
 ---
 name: vike-wallet-portfolio
-description: Composite wallet portfolio view — combines ENS + labels + ERC-20 balances + DeFi positions + recent net flow in one report. Use when the user gives a wallet address and asks for a complete picture ("full report on X" / "everything about this wallet" / "wallet snapshot").
-allowed-tools: Bash(vike:*)
+description: Composite wallet view — combines ENS + labels + token balances + recent flow + top counterparties in one report. Use when the user gives a wallet address and asks for a complete picture ("full report on X" / "everything about this wallet" / "wallet snapshot" / "who is this wallet").
+allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-wallet-portfolio
 
-Multi-call playbook for a complete wallet snapshot.
+Multi-call playbook for a complete wallet snapshot. It reports what the tools return: identity, token balances, flows and counterparties. There is **no DeFi-position data** in any tool, so never report protocol positions.
 
 ## Workflow (run in parallel where possible)
 
 ```bash
 ADDR=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
 
-vike-data wallet ens     $ADDR --json &     # cheap, ~1 credit
-vike-data labels         $ADDR --json &     # cheap, ~1 credit
-vike-data wallet summary $ADDR --json &     # cheap, ~2 credits
-vike-data wallet balances $ADDR --json &    # multi-chain, ~3 credits
-vike-data wallet pnl-history $ADDR --days 30 --json &
+vike-data wallet ens     $ADDR --json &     # 1 credit
+vike-data labels         $ADDR --json &     # 1 credit
+vike-data wallet summary $ADDR --json &     # 2 credits
+vike-data wallet balances $ADDR --json &    # 3 credits (Ethereum and BSC)
+vike-data wallet counterparties $ADDR --window 30d --limit 10 --json &   # 2 credits
 wait
 ```
 
+Then label the counterparties in one call: `vike-data wallet batch <cp1> <cp2> ... --json` (2 credits). A top counterparty that is a CEX tells you which exchange the wallet uses; an unlabelled high-volume counterparty is worth a `wallet compare` or `wallet trace`.
+
 ## Report template
 
 > **`<ENS or 0x...>` — wallet snapshot**
-> - **Identity:** `<ens.eth>` · `<entity (from labels)>` · `<wallet_type>` (confidence: `<H/M/L>`)
-> - **Total ERC-20:** `$X` across `<chains>`. Top 3 by USD: `<symbol1 $X>`, `<symbol2 $Y>`, ...
-> - **DeFi positions:** `$Y` across `<protocols count>` protocols. Top: `<Aave V3 $X>`, ...
-> - **30d net flow:** `+/-$Z` (cumulative)
-> - **Activity:** `<tx_count>` txns last 30d, `<unique_tokens>` unique tokens traded
+> - **Identity:** `<ens.eth>` · `<entity (from labels)>` · `<wallet_type>` (confidence: `<H/M/L>`). If `labels` says `found: false`, say "not in our label table".
+> - **Priced token holdings:** `$X` (floor: unpriced tokens and the native coin are excluded from the total) across `<chains_scanned>`. Top 3 by USD: `<symbol1 $X>`, ... Native balance: `<n ETH/BNB>`.
+> - **30d flow:** `+/-$Z` net (`summary["30d"].net_flow`), one chain.
+> - **Activity:** `<tx_count>` transfers in 30d, `<tokens_traded>` tokens traded all-time.
+> - **Top counterparties:** `<entity or address>` · `$volume`, ...
 > - **Vibe check:** `<saver / trader / farmer / institutional / inactive / fresh>`
 
 ## Vibe-check rubric
@@ -36,17 +38,16 @@ wait
 | Pattern | Label |
 |---|---|
 | `wallet_type = "cex"` or `"market_maker"` | **Institutional** |
-| 80%+ in stablecoins, low tx count | **Saver / dry powder** |
-| 50+ unique tokens 30d, low avg holding USD | **Airdrop farmer** |
-| High tx count, balanced sent/received | **Active trader** |
-| Big DeFi positions, low ERC-20 balance | **DeFi native** |
-| Big ERC-20 holdings, no DeFi | **HODLer** |
-| Zero activity 30d | **Inactive** |
-| First-seen < 30d ago | **Fresh wallet** |
+| 80%+ of priced holdings in stablecoins, low tx count | **Saver / dry powder** |
+| `tokens_traded` 50+, low average holding USD | **Airdrop farmer** |
+| High tx count, balanced inflow / outflow | **Active trader** |
+| Big priced holdings, low tx count | **HODLer** |
+| Zero `tx_count` in `30d` | **Inactive** |
+| `first_seen` (from `all`) < 30d ago | **Fresh wallet** |
 
 ## Cost
 
-~5 parallel calls, ~9 credits total. Use sparingly — only when the user wants the FULL picture, not a single dimension.
+6 calls, about 11 credits. Use sparingly — only when the user wants the FULL picture, not a single dimension.
 
 ## When to use a focused skill instead
 
@@ -56,4 +57,5 @@ wait
 
 ## Pairs well with
 
-- `vike-smart-money-discovery` to put the wallet in context vs the broader top-PnL cohort
+- `vike-wallet-trace` to follow the money out of the wallet
+- `vike-smart-money-discovery` to put a token the wallet trades in context

package/skills/vike-wallet-summary/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vike-wallet-summary
 description: Aggregate metrics for a single wallet — volume, inflow, outflow, net flow, tx count, tokens traded across 24h / 7d / 30d / 90d / all windows. Use when the user gives an address and asks "what's this wallet doing".
-allowed-tools: Bash(vike:*)
+allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-wallet-summary
@@ -12,24 +12,37 @@ allowed-tools: Bash(vike:*)
 vike-data wallet summary <address> [--json]
 ```
 
+No chain flag: one call returns every window, for one chain.
+
 ## Output
 
-Per-window rows: `window`, `volume_usd`, `inflow_usd`, `outflow_usd`, `net_flow_usd`, `tx_count`, `unique_tokens`.
+A JSON object keyed by window: `all`, `90d`, `30d`, `7d`, `24h`. Each window holds:
+
+`total_volume`, `total_inflow`, `total_outflow`, `net_flow` (USD), `tx_count`, `tokens_traded`, `first_seen`, `last_active`.
+
+- **One chain only.** The figures are for the chain where the wallet was most recently active, never summed across chains, and the response does not say which. For a specific chain use `wallet transactions --chain` or `wallet pnl-history --chain`.
+- **`tokens_traded`, `first_seen` and `last_active` are all-time** and repeat in every window: read them from `all` and ignore the copies. There is no per-window token count.
+- A window with no activity is present and zeroed (`24h` often is), not omitted.
+- Refreshed nightly: a wallet active in the last hours may not show yet.
+- It carries no PnL, no holdings, no labels and no Hyperliquid data. For those: `wallet balances`, `labels` / `wallet batch`, and `perp top-traders`.
 
 ## Reading tips
 
-- **Net flow >> 0** = accumulator. Inflow heavy → still buying.
-- **Net flow << 0** = distributor. Outflow heavy → still selling.
-- **Volume high, net flow ≈ 0** = trader/MM (churn). Look at counterparty patterns separately.
-- **Unique tokens high (>50)** = farmer / spray-and-pray. Lower signal per token.
-- **Unique tokens low (<5), high volume** = concentrated conviction.
+- **`net_flow` >> 0** = accumulator. Inflow heavy → still buying.
+- **`net_flow` << 0** = distributor. Outflow heavy → still selling.
+- **Volume high, `net_flow` ≈ 0** = trader/MM (churn). Look at counterparty patterns separately.
+- **`tokens_traded` high (>50)** = farmer / spray-and-pray. Lower signal per token.
+- **`tokens_traded` low (<5), high volume** = concentrated conviction.
+- Lifetime `all` against a quiet `30d` (e.g. 900k lifetime transactions, 18 in 30d) = a long-lived wallet that is quiet now. Don't size a wallet up on `all` alone.
 
 ## Anti-patterns
 
-- Don't claim a wallet is "smart money" based on summary alone — cross-reference with labels and PnL: `vike-data wallet discover --sort pnl` to see if this address is in the top-PnL set.
-- A single big inflow can dominate `net_flow_usd` for a window — eyeball `tx_count` to gauge whether it's one trade or many.
+- Don't claim a wallet is "smart money" based on summary alone: it has no PnL. Check labels with `vike-data labels <addr>` or `vike-data wallet batch`.
+- A single big inflow can dominate `net_flow` for a window — eyeball `tx_count` to gauge whether it's one trade or many.
+- Don't describe the result as "across ETH/BSC/Base": it is one chain.
 
 ## Pairs well with
 
-- `vike-data wallet discover` to see if this wallet ranks in any leaderboard
+- `vike-data labels <addr>` / `vike-data wallet batch` to say who the wallet is
+- `vike-data wallet balances <addr>` for current holdings
 - `vike-data token transfers` after identifying which tokens the wallet trades

package/skills/vike-wallet-trace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vike-wallet-trace
-description: Counterparty graph traversal from a root wallet outward. At each hop, expand to the top N counterparties by USD volume. Use when the user asks "where did funds from X go" / "follow the money 3 hops out" / "trace the network around this wallet" / wallet investigation.
-allowed-tools: Bash(vike:*)
+description: Counterparty graph traversal from a root wallet outward. At each hop, expand to the top N counterparties by USD volume; edges carry the direction of the flow. Use when the user asks "where did funds from X go" / "follow the money 3 hops out" / "trace the network around this wallet" / wallet investigation.
+allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-wallet-trace
@@ -14,10 +14,12 @@ vike-data wallet trace <address>
   [--depth N]    (1-5, default 2)
   [--width N]    (1-10, default 5)
   [--window 24h|7d|30d|90d|all]
-  [--min-usd N]  (default 10000 — prunes noise)
+  [--min-usd N]  (default 10000; 0 selects the default, pass 0.01 to include small transfers)
   [--json]
 ```
 
+`--chain base` is accepted, but per-wallet transfer data is documented for Ethereum and BSC: treat an empty Base result as "not covered", not "no activity".
+
 ## Output
 
 ```json
@@ -25,13 +27,12 @@ vike-data wallet trace <address>
   "root": "0xabc...",
   "depth": 2, "width": 5, "window": "30d", "min_usd": 10000,
   "nodes": [
-    { "address": "0xabc...", "depth": 0, "total_volume_usd": 0.0 },
-    { "address": "0xdef...", "depth": 1, "total_volume_usd": 250000, "label": "Binance", "wallet_type": "cex" },
-    { "address": "0x123...", "depth": 2, "total_volume_usd": 45000, "label": null, "wallet_type": null },
+    { "address": "0xabc...", "depth": 0, "total_volume_usd": 450000, "label": null, "wallet_type": null },
+    { "address": "0xdef...", "depth": 1, "total_volume_usd": 250000, "label": "binance", "wallet_type": "cex" },
     ...
   ],
   "edges": [
-    { "from": "0xabc...", "to": "0xdef...", "volume_usd": 200000, "tx_count": 4 },
+    { "from": "0xabc...", "to": "0xdef...", "volume_usd": 200000, "out_usd": 150000, "in_usd": 50000, "tx_count": 4 },
     ...
   ],
   "stats": { "node_count": 23, "edge_count": 31, "max_depth_reached": 2 }
@@ -40,18 +41,20 @@ vike-data wallet trace <address>
 
 ## Reading the graph
 
-- **Root (depth 0)** = the wallet you traced from. `total_volume_usd` = 0 because it's where edges originate.
+- **Direction lives in `out_usd` / `in_usd`, not in `from` / `to`.** `from` is the side that was expanded first, not the sender. For an edge, `out_usd` flowed `from → to`, `in_usd` flowed `to → from`, and `volume_usd` is their sum. To answer "where did X's money go", rank the root's edges by the outflow side, not by `volume_usd`.
+- **Root (depth 0)** = the wallet you traced from. Its `total_volume_usd` is the sum of its own edges in this graph (not zero, and not its whole activity). The same holds for every node.
 - **Depth 1** = direct counterparties. Most useful layer.
 - **Depth 2-3** = "friend-of-friend" — useful for finding where funds end up.
-- **Edge volume_usd** = the volume between those two specific addresses, NOT cumulative.
+- **Edge `volume_usd`** = the volume between those two specific addresses, NOT cumulative. One edge per wallet pair.
 - **`wallet_type = "cex"`** at depth 1 = funds went to / came from an exchange. Often the END of the trail (anonymous from there).
 - **Unlabeled wallet with high volume at depth 1-2** = potentially related wallet, investigate with `vike-data labels`.
+- Only transfers of at least `--min-usd` count, so an empty or small graph can mean "nothing above the floor".
 
 ## Parameter tuning
 
 | Parameter | Effect | Use when |
 |---|---|---|
-| `--depth 1` | Direct counterparties only | "Who does X trade with" — same as `wallet counterparties` |
+| `--depth 1` | Direct counterparties only | Same data as `wallet counterparties`, plus the direction split |
 | `--depth 2` | One degree of separation | Default. Reveals immediate networks. |
 | `--depth 3+` | Wider net | Investigation / OSINT. Returns much more data; graph gets noisy. |
 | `--width 3` | Top 3 per hop | Cleaner, focused on biggest flows |
@@ -60,13 +63,14 @@ vike-data wallet trace <address>
 
 ## Cost note
 
-Tool credits = 4 per call (heavier than other graph-less tools). Graph explodes exponentially with depth — depth 3 + width 10 = up to 1000 nodes per scan. Use `--depth 2 --width 5` as default.
+4 credits per call (the heaviest tool). Cost grows with depth × width, but the server silently stops after 300 wallet expansions, so a wide, deep trace (for example depth 3 × width 10) is cut rather than unbounded. If `max_depth_reached` is below `--depth`, either the branches ran out under `--min-usd` or the cap cut the graph: say which you cannot tell. Use `--depth 2 --width 5` as the default.
 
 ## Anti-patterns
 
 - Don't trace through CEX deposits. Once funds enter Binance/Coinbase, the trail goes opaque (CEX internal accounting, not on-chain). Note CEX nodes and stop following.
 - Don't depth-5 by default. Graph blows up; results become noise.
 - Don't ignore `min_usd` — without it, dust transfers create false-positive edges.
+- Don't read `from` as the sender.
 
 ## Visual graph (web UI)
 
@@ -80,6 +84,6 @@ Tell them to click the **Graph** tab. It renders the same trace data as a force-
 
 ## Pairs well with
 
-- `vike-data labels <addr>` — identify any interesting node
+- `vike-data labels <addr>` / `vike-data wallet batch <addr...>` — identify the nodes
 - `vike-data wallet compare <addr_a> <addr_b>` — confirm relatedness once trace surfaces candidates
 - `vike-data wallet transactions <addr>` — drill into specific transfers between two nodes

package/skills/vike-wallet-transactions/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vike-wallet-transactions
 description: Raw per-wallet transfer list (individual transactions, not aggregates) with direction, day, USD, and token filters. Use when the user asks "show me recent transfers for X" / "last 100 transactions of Y" / "all USDC moves from this wallet" / any forensic audit query.
-allowed-tools: Bash(vike:*)
+allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-wallet-transactions
@@ -19,6 +19,8 @@ vike-data wallet transactions <address>     # alias: vike-data wallet txs
   [--json]
 ```
 
+`--chain base` is accepted, but per-wallet transfer data is documented for Ethereum and BSC: treat an empty Base result as "not covered", not "no activity".
+
 ## Examples
 
 ```bash
@@ -34,7 +36,7 @@ vike-data wallet txs 0xabc... --token 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
 
 ## Output columns
 
-`time`, `tx_hash`, `from_address`, `to_address`, `token_address`, `value_usd`, `direction` (in/out), `block`.
+`time`, `tx_hash`, `from_address`, `to_address`, `token_address`, `usd`, `direction` (in/out), `block`. The USD key is `usd`, and `usd: 0.0` means the transfer is **unpriced**, not worthless: `--min-usd` therefore also hides unpriced transfers. The native coin shows as `token_address` `0x0000000000000000000000000000000000000000`.
 
 Sorted descending by time (most recent first).
 

package/skills.sh.json

@@ -4,16 +4,15 @@
   "groupings": [
     {
       "title": "Quick start",
-      "description": "Start here. The umbrella skill auto-routes user questions to the right specialized skill below.",
+      "description": "Start here. The umbrella skill routes user questions to the right specialized skill below; vike-core covers install and auth.",
       "skills": [
         "vike",
-        "vike-router",
         "vike-core"
       ]
     },
     {
       "title": "Tokens",
-      "description": "Resolve, screen, and research tokens across 11 chains. Smart-money inflow, holders, recent transfers.",
+      "description": "Resolve, screen, and research tokens on Ethereum, BSC and Base. Smart-money inflow (Ethereum), holders, top buyers and sellers.",
       "skills": [
         "vike-token-search",
         "vike-token-research",
@@ -25,7 +24,7 @@
     },
     {
       "title": "Wallets",
-      "description": "Per-wallet profile, PnL, counterparty graphs, ENS, batch labelling, label provenance.",
+      "description": "Per-wallet profile, flows, counterparty graphs, ENS, batch labelling, label provenance.",
       "skills": [
         "vike-wallet-summary",
         "vike-wallet-portfolio",
@@ -43,20 +42,17 @@
     },
     {
       "title": "CEX perps",
-      "description": "Funding-rate arb + cross-venue mark-price spreads across Binance, Bybit, OKX, Aster, Hyperliquid.",
+      "description": "Funding-rate arb and per-symbol venue comparison, plus cross-venue perp price gaps and a market snapshot.",
       "skills": [
-        "vike-perp-funding-arb",
-        "vike-perp-spread-arb",
-        "vike-perp-screener",
-        "vike-cross-venue-perps"
+        "vike-perp-funding",
+        "vike-perp-overview"
       ]
     },
     {
       "title": "Hyperliquid perps",
-      "description": "Deep on-chain HL coverage: top traders, full trader profiles, and share-card reverse-lookup.",
+      "description": "Top traders (and checking one address against the leaderboard) and share-card reverse-lookup.",
       "skills": [
         "vike-hl-top-traders",
-        "vike-hl-trader-profile",
         "vike-hl-position-match"
       ]
     },
@@ -69,18 +65,17 @@
     },
     {
       "title": "Polymarket",
-      "description": "Prediction-market discovery, single-market deep-dives, trader profiles, and smart-money leaderboards.",
+      "description": "Prediction-market discovery, single-market deep-dives, trader profiles, and smart-money signals with a market overview.",
       "skills": [
         "vike-polymarket-markets",
         "vike-polymarket-market-detail",
         "vike-polymarket-trader",
-        "vike-polymarket-smart-money",
-        "vike-polymarket-screener"
+        "vike-polymarket-smart-money"
       ]
     },
     {
       "title": "Alerts",
-      "description": "Create, list, edit, delete price + flow alerts; register HTTPS webhooks with HMAC delivery.",
+      "description": "Create, list, edit, delete on-chain transfer alerts (USD thresholds per token); register HTTPS webhooks with HMAC delivery.",
       "skills": [
         "vike-alerts-setup",
         "vike-alerts-webhook"

package/src/auth.js

@@ -40,7 +40,7 @@ export function clearApiKey() {
 }
 
 export function getEndpoint() {
-  return process.env.VIKE_MCP_URL || 'https://vike.io/mcp';
+  return process.env.VIKE_MCP_URL || 'https://data.vike.io/mcp';
 }
 
 export function requireApiKey() {

package/src/commands/init.js

@@ -31,7 +31,7 @@ export function registerInit(program) {
       const path = saveApiKey(key);
       console.log(`Saved to ${path}`);
 
-      console.log('Verifying connection to vike.io/mcp ...');
+      console.log('Verifying connection to data.vike.io/mcp ...');
       const { status, body } = await ping({ apiKey: key });
       if (status !== 200 || body?.error) {
         console.error(`Endpoint returned HTTP ${status}: ${JSON.stringify(body)}`);

package/src/commands/labels.js

@@ -5,7 +5,7 @@ export function registerLabels(program) {
   // `vike-data labels <address>` — multi-source label provenance for one wallet
   program
     .command('labels <address>')
-    .description('Multi-source label cascade for a wallet (10+ providers + in-house heuristic + consensus view)')
+    .description('Multi-source label cascade for an Ethereum wallet (up to 6 label sources + in-house heuristic + consensus view)')
     .option('--json', 'Emit JSON')
     .action(async (address, opts) => {
       try {

package/src/commands/perp.js

@@ -9,7 +9,7 @@ export function registerPerp(program) {
 
   cmd
     .command('funding')
-    .description('Funding rates per venue, or cross-venue funding-arb opportunities')
+    .description('Funding rates per venue (raw per-interval rate + interval_h), or the top 5 cross-venue funding-arb rows')
     .option('--symbol <s>', 'Specific symbol (e.g. BTC). Omit for top arb opportunities.')
     .option('--json', 'Emit JSON')
     .action(async (opts) => {
@@ -21,8 +21,8 @@ export function registerPerp(program) {
 
   cmd
     .command('spreads')
-    .description('Cross-venue spot-perp spread arbitrage opportunities')
-    .option('--symbol <s>', 'Specific symbol. Omit for full matrix.')
+    .description('Cross-venue perp price gaps: the 10 widest (buy on one venue, sell on another)')
+    .option('--symbol <s>', 'Filter those 10 to one symbol (often empty). Omit for all.')
     .option('--json', 'Emit JSON')
     .action(async (opts) => {
       try {
@@ -43,8 +43,9 @@ export function registerPerp(program) {
     .option('--json', 'Emit JSON')
     .action(async (opts) => {
       try {
+        // The tool renamed `coin` to `symbol` on 2026-10-19; `--coin` stays the flag users know.
         const r = await callTool('hl_position_match', {
-          coin: opts.coin,
+          symbol: opts.coin,
           side: opts.side,
           leverage: Number(opts.leverage),
           entry_price: Number(opts.entry),