@vike-io/cli 0.13.1 → 0.15.0

package/skills/vike-smart-money-discovery/SKILL.md

@@ -1,74 +1,68 @@
 ---
 name: vike-smart-money-discovery
-description: Multi-signal smart money discovery — find wallets currently accumulating a token, ranked by realized PnL track record. Use when the user asks "is smart money buying X" / "find smart money on Y chain" / "any alpha wallets in Z".
+description: Smart-money discovery on Ethereum — which tokens the smart-money cohort is flowing into, and who the biggest net buyers of one token are. Use when the user asks "is smart money buying X" / "find smart money" / "any alpha wallets in Z".
 allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-smart-money-discovery
 
-Composite playbook — combines wallet leaderboards + token-side buyer list + label inspection.
+Composite playbook built on `token screener --smart-money-only`. Smart money here means the cohort behind the screener's `smart_inflow` and `--smart-money-only`, which exist for **Ethereum only** (a 400 on bsc and base).
+
+**What this can and cannot say.** It can say which tokens the cohort is flowing into and how much, and who the biggest net buyers of a token are. It cannot list which of those buyers belong to the cohort: no tool returns cohort membership. State that limit in the answer.
 
 ## Workflow
 
-### A. Top realized-PnL wallets on a chain
+### A. Which tokens is the cohort buying?
 
 ```bash
-vike-data wallet discover --sort pnl --window 90d --chain ethereum --size 20 --json
+vike-data token screener --chain ethereum --window 7d --sort smart_inflow --smart-money-only --limit 100 --json
 ```
 
-Keep only rows where:
-- `realized_pnl_usd > 100_000` (real conviction, not noise)
-- `tx_count > 20` (not a single lucky trade)
-- `label` is empty OR not a known CEX (these are real wallets, not exchanges)
-
-That set = your "smart money universe" for the next step.
-
-### B. Cross-reference with a specific token
+- Skip the row `0x0000000000000000000000000000000000000000`: it is the native coin, not a token you can drill into.
+- Rows carry `token_address` (the `symbol` is often blank): identify tokens by address, and resolve names with `vike-data token search`.
+- If the user named a token: resolve it (`vike-data token search <symbol> --limit 3 --json`) and look for its `token_address` in the rows. Present means the cohort moved it; absent from the top 100 means no visible cohort inflow in that window.
 
-If the user asks about a specific token, resolve it first:
+### B. Who is accumulating it?
 
 ```bash
-vike-data token search <symbol> --chain <chain> --limit 3 --json
+vike-data token transfers <addr> --tab bought --period 7d --json
 ```
 
-Then list its recent buyers:
+The list is the **top 10 by volume**, not the cohort. **Rank on `net_tokens`**, not `bought`: `bought` counts every inbound transfer, flash-loan and router round trips included. Keep rows with a clearly positive `net_tokens`; drop rows where `net_tokens` is near zero.
+
+### C. Strip the intermediaries
 
 ```bash
-vike-data token transfers <addr> --tab bought --period 7d --chain <chain> --json
+vike-data wallet batch <addr1> <addr2> ... --json
 ```
 
-**Intersect** the buyer addresses with your smart-money universe from step A. Any overlap = a smart-money wallet currently accumulating this token.
-
-### C. Profile each match
+Drop rows labelled `cex`, `dex`, router or contract. What is left are the real net buyers of the token.
 
-For every overlap address, run:
+### D. Profile the survivors (cap at 5)
 
 ```bash
 vike-data wallet summary <addr> --json
 ```
 
-Report:
-- Address
-- Known label (if any)
-- 90d realized PnL
-- 7d net flow on this token
-- 30d total volume
+Report address, label (if any), the token's `net_tokens` and `net_usd` over the window, and the wallet's 30d volume.
 
 ## Verdict template
 
-> **Smart-money take on $TOKEN:** N of top-20 90d-PnL wallets (>$100k realized) bought $TOKEN in the last 7 days. Strongest names: `<addr1> (+$X PnL, label?)`, `<addr2> ...`. Aggregate net flow into $TOKEN from this cohort: $Y. **Read: accumulation / churn / no-signal.**
+> **Smart-money take on $TOKEN (7d):** the cohort's `smart_inflow` into $TOKEN is $Y (screener rank #R by `smart_inflow`). Among the top-10 net buyers, N survive the label filter; the largest are `<addr1> (net_tokens X, label?)`. **Read: accumulation / churn / no-signal.** The cohort members themselves are not listed by any tool.
 
 ## Anti-patterns
 
-- Don't accept any wallet labeled as a CEX (binance/coinbase/bybit/etc.) as "smart money" — they're aggregators.
-- Don't lower the PnL threshold to <$50k just to find more matches; below that, signal-to-noise is poor.
-- Single-token wallets (`unique_tokens < 3`) are usually airdrop-flippers, not strategic.
+- Don't rank wallets by `wallet discover --sort pnl` and intersect them with a token's buyers: `realized_pnl` is stored wrongly for many wallets and is only an ordering key, and the overlap with a 10-row buyer list is almost always empty.
+- Don't accept any wallet labeled as a CEX (binance/coinbase/bybit/etc.) as "smart money": they are aggregators.
+- Don't use `--window 24h` for the screen: smart money usually positions before the 24h window.
+- Single-token wallets (`tokens_traded < 3` in `wallet summary`) are usually airdrop-flippers, not strategic.
 
 ## Cost note
 
-3 calls per discovery: 1× `wallet discover`, 1× `token transfers`, then 1× `wallet summary` per match (cap at 5).
+Screener (3 credits) + `token transfers` (2) + `wallet batch` (2) + up to 5 × `wallet summary` (2).
 
 ## Pairs well with
 
+- `vike-token-screener` for the filters and the column meanings
 - `vike-token-research` for the price/flow context
-- `vike-perp-funding-arb` if the token has a perp listing (positioning bias)
+- `vike-perp-funding` if the token has a perp listing (positioning bias)

package/skills/vike-stream/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: vike-stream
+description: Live events over WebSocket with `vike-data stream` - Hyperliquid fills, liquidations, positions, liquidation risk, order walls, closed candles, TWAPs, ledger, leverage changes and funding; HL cohort flow, indices and cohort bias; on-chain transfers on eth, bsc, base and hyperevm; Polymarket trades, resolutions, price moves and new markets - printed as NDJSON, resumed by cursor after any drop. Use when the user wants to "watch", "tail", "follow live", "stream" or "be notified as it happens" rather than query history.
+allowed-tools: Bash(vike-data:*)
+---
+
+# vike-stream
+
+```bash
+vike-data stream <hl|hl-cohorts|onchain|polymarket> --channel <channel...> [--filter key=value ...] [--cursor <cursor>]
+```
+
+Connects to `wss://stream.vike.io/v1/stream/<path>` with the API key in the `X-API-KEY` header, subscribes once per
+`--channel`, and prints one JSON object per line on stdout: every `event` frame and every `gap` frame, exactly as the
+server sent them. Status lines (subscribed, reconnecting, errors) go to stderr. It runs until Ctrl-C.
+
+| Path | Channels |
+|---|---|
+| `hl` | `hl.fills`, `hl.liquidations`, `hl.positions`, `hl.liq_risk`, `hl.order_walls`, `hl.candles`, `hl.twaps`, `hl.ledger`, `hl.leverage`, `hl.funding` |
+| `hl-cohorts` | `hl.cohort_flow`, `hl.indices`, `hl.cohort_bias` |
+| `onchain` | `chain.transfers` |
+| `polymarket` | `pm.trades`, `pm.resolutions`, `pm.price_moves`, `pm.new_markets` |
+
+The server decides what each path serves: `vike-data stream info` prints the current channels and filter keys, and a
+channel the path does not serve is refused with `unknown_channel` and the list. The CLI has no channel list of its own.
+
+`hl.candles` is the Hyperliquid candle stream: closed bars, filtered by `coin`, `interval` (`1m 5m 15m 30m 1h 4h 1d`),
+`market` (`perp` or `spot`) and `dex` (`HL` or a HIP-3 dex). The old `wss://data.vike.io/v1/stream` is closed (410).
+
+## Examples
+
+```bash
+# Hyperliquid BTC and ETH fills of $100k or more, by smart wallets
+vike-data stream hl --channel hl.fills --filter coin=BTC,ETH --filter min_usd=100000 --filter "pnl_cohort=3x smart,2x smart"
+
+# Live 1-minute and 1-hour BTC and ETH perp candles (closed bars)
+vike-data stream hl --channel hl.candles --filter coin=BTC,ETH --filter interval=1m,1h --filter market=perp
+
+# Every liquidation and every fill of one wallet, on one connection
+vike-data stream hl --channel hl.liquidations hl.fills --filter wallet=0x1111111111111111111111111111111111111111
+
+# USDC transfers on base worth $1M+
+vike-data stream onchain --channel chain.transfers --filter chain=base --filter token=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 --filter min_usd=1000000
+
+# Keep only the events, with jq
+vike-data stream polymarket --channel pm.trades --filter min_usd=10000 | jq -c 'select(.type == "event") | .event'
+```
+
+`--filter` applies to every `--channel` of the command; a key the channel does not take is refused by the server
+with the key's name. List keys (`wallet`, `coin`, `token`, `market`, `chain`, cohorts, ...) take comma-separated
+values and repeat; `side`, `direction`, `event`, `axis`, `move`, `role` take one value; `true` / `false` is sent as a yes/no (`contract=false`); `min_usd`, `min_amount`, `min_move`
+take a number. Channel fields and filter keys: https://vike.io/docs/data/reference/stream-channels
+
+## Without a socket
+
+These are MCP calls: they open no connection, so they never replace one.
+
+```bash
+vike-data stream info --json                                    # every path, channel, filter key, limit and close code
+vike-data stream check hl.fills --filter coin=BTC --filter min_usd=50000   # the server's own validator; exit 1 if refused
+vike-data stream events hl.liquidations --filter coin=BTC --since-ms 1793178870000 --json   # stored events (3 days), paged by --cursor
+vike-data stream connections --hours 24 --json                  # your recent connections: who closed whom (4410), events sent
+```
+
+Run `stream check` before a long-running `stream`: it shows the filter exactly as the server will apply it (with
+the `hl.fills` default `min_usd` of 1000 added) or the server's error naming the bad key.
+
+## Reading the output
+
+- Keep the **frame's** `cursor` (the top-level one, not `event.cursor`) of the last line you handled. `--cursor <it>`
+  on the next run resumes from there, up to 3 days back; older is `cursor_expired` and the stream continues from now.
+- The CLI resumes by itself after any drop (restart, network, slow reader) from the last cursor of each subscription.
+  Delivery is at least once: drop a repeated `event.event_id`.
+- A `gap` frame (`reason: channel_idle`) means the channel was not running between `from` and `to` (nobody was
+  subscribed). It does not mean nothing happened; read that window from the REST endpoints or the `hl` / `polymarket`
+  commands. For what a socket missed while the channel was running, `vike-data stream events <channel> --cursor <c>`.
+- `hl.fills` without `min_usd` gets a $1,000 floor; `min_usd=0` is every fill (hundreds per second).
+  `chain.transfers` unfiltered is a firehose; `min_usd` on it drops unpriced transfers.
+
+## One connection per key
+
+On each path, one API key holds one connection; an account holds at most 3. A second program on the same key and
+path takes over, and the first exits with `replaced (4410)` and does not reconnect (two programs reconnecting would
+take the connection from each other forever). Give each program its own key (`VIKE_API_KEY=... vike-data stream ...`).
+`vike-data stream connections` shows which of your connections closed which.
+Exit 1 also on `HTTP 401` / `4401` (the key) and on a refused subscription (`bad_subscription`, `unknown_channel`).
+
+## Anti-patterns
+
+- Don't run two `vike-data stream` processes on the same key and path: they replace each other.
+- Don't treat silence as "nothing happened" in the first minutes: an idle channel starts on demand (up to ~12 minutes
+  for `hl.indices` and `hl.liq_risk`).
+- Don't use the stream for history: it keeps 3 days. Use the query commands.
+
+## Pairs well with
+
+- `vike-alerts-setup`: a stored rule that notifies by webhook without a running process.
+- `vike-hl-top-traders`: pick the wallets to put in a `wallet` filter.

package/skills/vike-token-holders/SKILL.md

@@ -34,7 +34,8 @@ vike-data token holders 0x6982508145454ce325ddbe47a25d4ec3d2311933 --limit 20
 
 ## Anti-patterns
 
-- "Top holders" here means cumulative net inflow over all time — NOT current on-chain balance (which would require querying the contract directly). A wallet that bought $10M and sold $9M shows `net_flow_usd = $1M`, even if current balance is zero. **Always call this out** when reporting top holders.
+- "Top holders" here means cumulative net inflow over our recorded transfer history — NOT current on-chain balance. A wallet that bought $10M and sold $9M shows `net_flow_usd = $1M`, even if current balance is zero. The top rows are very often intermediaries (exchange wallets, lending protocols, MEV bots) with huge `volume_usd` against a small net: read this as "who moves the most of this token". **Always call this out** when reporting top holders. For what one specific wallet holds right now use `vike-data wallet balances <addr>` (Ethereum and BSC).
+- There is no concentration metric (top-N share of supply) in the output; don't compute one from `net_flow_usd`.
 - Don't list `tx_count = 1` whales as "smart money" without context — could be an airdrop receiver who never sold.
 - For BSC tokens, pass `--chain bsc` explicitly; default is ethereum.
 

package/skills/vike-token-research/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: vike-token-research
-description: Full token research playbook — search → transfers → chart → flow direction → buyer/seller verdict. Use when the user asks "research <token>" or "what's happening with <token>".
+description: Token research playbook — search → transfers (both sides) → net-flow read → buyer/seller verdict. Use when the user asks "research <token>" or "what's happening with <token>".
 allowed-tools: Bash(vike-data:*)
 ---
 
 # vike-token-research
 
-Multi-call token research workflow.
+Multi-call token research workflow. It characterises WHO is moving the token (the top wallets on each side), not the token's total flow, and it has no price chart.
 
 ## Steps
 
@@ -14,37 +14,45 @@ Multi-call token research workflow.
    ```bash
    vike-data token search <symbol> --chain <chain> --limit 3 --json
    ```
-   Pick the highest-volume match; capture the address.
+   Pick the canonical match; capture the address.
 
 2. **Recent buyers + sellers** (parallel calls)
    ```bash
    vike-data token transfers <addr> --tab bought --period 24h --chain <chain> --json
    vike-data token transfers <addr> --tab sold   --period 24h --chain <chain> --json
    ```
+   Each call returns the top 10 wallets for one side.
 
-## Verdict heuristics
+3. **Read `net_tokens`, not `bought`.** `bought` counts every inbound transfer (flash-loan and router round trips included). Merge the two lists by `address`, then:
+   - drop rows where `|net_tokens|` is below 1% of `max(bought, sold)`: they are round trips, not a position;
+   - label the rest with `vike-data wallet batch <addrs...> --chain <chain>` and drop CEX / router / contract rows if the user wants "real" flow;
+   - split what is left into net accumulators (`net_tokens > 0`) and net distributors (`net_tokens < 0`) and add up each side's `|net_usd|`.
+
+4. **Optional context** (Ethereum only): `vike-data token screener --window 7d --sort smart_inflow --smart-money-only --limit 100 --json` and look for the token's address in the rows to see whether the smart-money cohort is flowing into it.
 
-After step 2, classify direction-of-pressure:
+## Verdict heuristics
 
-| Buyer count vs seller count (24h) | Verdict |
+| Net accumulators' USD vs net distributors' USD (24h) | Verdict |
 |---|---|
-| Buyers > 2× sellers and net inflow > $1M | **Accumulation** |
-| Sellers > 2× buyers and net outflow > $1M | **Distribution** |
-| Roughly even (within 1.5×) | **Churn / range-bound** |
-| Both very low | **Illiquid — skip the read** |
+| Accumulators > 2× distributors and > $1M | **Accumulation among the biggest movers** |
+| Distributors > 2× accumulators and > $1M | **Distribution among the biggest movers** |
+| Within 1.5× of each other | **Churn / range-bound** |
+| Fewer than 3 rows left after dropping round trips, or all CEX / router | **No readable signal** — say the top wallets are intermediaries |
 
-Cross-check against the chart: distribution + falling price = bearish; accumulation + flat price = stealth bid (interesting).
+State the limit with the verdict: "top 10 per side", not "the market".
 
 ## Anti-patterns
 
+- Don't compare the number of buyers to the number of sellers: both lists are always 10 rows.
 - Don't run `transfers --period 30d` first — use 24h to see what's happening *now*; 30d for context only if needed.
 - Don't quote the first row of `token search` blindly — if the symbol has cross-chain collisions (`FUN`, `BEAM`, `LDO`), inspect `chain` + `address` for each result before picking.
+- Don't promise a price chart: there is no candle source for an ERC-20 contract address (`vike-candles` covers Hyperliquid and Polymarket only).
 
 ## Cost note
 
-Step 1: cheap. Step 2: 2× cheap. Step 3: cheap. Total ≈ 4 calls.
+Step 1: free. Step 2: 2 calls × 2 credits. Step 3 labels: 2 credits. Total ≈ 4 calls.
 
 ## Pairs well with
 
-- `vike-smart-money-discovery` to find which smart wallets are involved
-- `vike-perp-funding-arb` if the token has a perp listing (BTC/ETH/SOL/major alts)
+- `vike-smart-money-discovery` to see whether the smart-money cohort is flowing into the token
+- `vike-perp-funding` if the token has a perp listing (BTC/ETH/SOL/major alts)

package/skills/vike-token-screener/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vike-token-screener
-description: Token discovery filter — rank tokens by volume / net inflow / holder count / smart-money inflow within a window, with min-volume and min-holder filters. Use when the user asks "what tokens are trending today" / "find tokens with smart money accumulating" / "rising tokens this week" / token discovery from scratch.
+description: Token discovery filter — rank tokens by volume / net inflow / active-wallet count / smart-money inflow within a window, with min-volume and min-holder filters. Use when the user asks "what tokens are trending today" / "find tokens with smart money accumulating" / "rising tokens this week" / token discovery from scratch.
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -13,70 +13,77 @@ vike-data token screener
   [--chain ethereum|bsc|base]
   [--window 24h|7d|30d|90d]
   [--sort volume|net_inflow|holders|smart_inflow]
-  [--limit N]              (max 100)
-  [--min-volume USD]       (filter dust)
-  [--min-holders N]        (require N+ unique holders)
-  [--smart-money-only]     (restrict to smart-money cohort flows)
+  [--limit N]                (default 20, max 100)
+  [--min-volume USD]         (drop thin tokens)
+  [--min-holders N]          (require N+ distinct wallets active in the window)
+  [--smart-money-only]       (restrict to smart-money cohort flows)
   [--json]
 ```
 
+`--smart-money-only` and `--sort smart_inflow` exist for `--chain ethereum` only; on `bsc` and `base` they are a 400.
+
 ## Examples
 
 ```bash
 # Trending today by volume
 vike-data token screener --window 24h --sort volume --limit 20
 
-# Find tokens smart money is accumulating
+# Tokens the smart-money cohort is flowing into (Ethereum only)
 vike-data token screener --window 7d --sort smart_inflow --smart-money-only
 
-# Rising holders count (organic growth signal)
+# Broad participation: most distinct wallets active in the window
 vike-data token screener --window 30d --sort holders --min-volume 100000
 
-# Mid-cap tokens with real activity
+# Biggest net inflow among tokens with real activity
 vike-data token screener --min-volume 1000000 --min-holders 100 --sort net_inflow
 ```
 
 ## Output columns
 
-`token_address`, `symbol` (when known), `name`, `volume_usd`, `net_flow_usd`, `in_usd`, `out_usd`, `unique_holders`, `tx_count`.
+`token_address`, `symbol`, `name`, `volume_usd`, `net_flow_usd`, `in_usd`, `out_usd`, `unique_holders`, `tx_count`.
+
+- `symbol` is often blank and `name` null: the screener identifies tokens **by address**. Report the address. Don't invent a symbol, and don't call a blank-symbol row "unknown token" without checking the next point.
+- **`0x0000000000000000000000000000000000000000` is the chain's native coin** (ETH on ethereum, BNB on bsc), not a contract. It ranks high on volume and `smart_inflow`. `vike-data token transfers` returns no buyers for it, so skip it before drilling into a screened token.
+- `unique_holders` counts wallets **active in the window** (that sent or received the token), not wallets that hold it and not growth.
+- `24h` spans yesterday and today (UTC calendar days), not a rolling 24 hours.
 
 ## Sort modes
 
 | Sort | What it surfaces |
 |---|---|
-| `volume` | Most-traded tokens (default) — captures attention-driven action |
-| `net_inflow` | Tokens with biggest accumulation (in > out) — "what's being bought" |
-| `holders` | Tokens gaining unique addresses — organic growth signal |
-| `smart_inflow` | Tokens our smart-money cohort is buying — alpha signal |
+| `volume` | Most-traded tokens (default): attention, not direction |
+| `net_inflow` | Largest `net_flow_usd` first (in > out). There is **no ascending sort**, so the bottom rows are the smallest inflows, not the biggest outflows |
+| `holders` | Most distinct wallets active in the window |
+| `smart_inflow` | Tokens the smart-money cohort is flowing into (Ethereum only) |
 
 ## Reading
 
-- **High volume + balanced in/out** = churn (DEX MM, arb bots). Low signal.
-- **High volume + strong net_inflow** = real demand. Worth investigating.
-- **Strong holder growth + flat volume** = small buys, distribution widening. Often early signal.
-- **`smart_inflow` mode** + high values + low overall volume = cohort is positioned BEFORE retail. Highest-conviction signal in the tool.
+- **High volume + `in_usd` ≈ `out_usd`** = churn (DEX MM, arb bots). Low signal. If `in_usd` equals `out_usd` to the cent and `net_flow_usd` is exactly `0.0`, the figure is almost certainly transfer volume counted on both sides, not a quiet token.
+- **High volume + strong `net_flow_usd`** = real demand. Worth investigating with `vike-data token transfers`.
+- **Many active wallets + flat volume** = small transactions spread widely (airdrop claims also look like this).
+- **`smart_inflow` + high values + low overall volume** = cohort positioned before retail. A screen to start from, not a verdict: confirm with `token transfers`.
 
 ## Filter tips
 
 | Goal | Filters |
 |---|---|
-| "Rising memecoins" | `--window 24h --sort holders --min-holders 50 --min-volume 50000` |
-| "Mid-cap alpha" | `--sort smart_inflow --min-volume 500000 --smart-money-only` |
-| "What's getting dumped" | `--sort net_inflow` then reverse — bottom rows have biggest outflows |
+| "Busy memecoins" | `--window 24h --sort holders --min-holders 50 --min-volume 50000` |
+| "Mid-cap smart-money inflow" | `--sort smart_inflow --min-volume 500000 --smart-money-only` |
+| "What's getting dumped" | **Not answerable from the screener** (no ascending sort, no outflow rank). For one known token use `vike-data token transfers <addr> --tab sold` |
 
 ## Anti-patterns
 
-- Don't quote the symbol as authoritative if `symbol` is null/blank — token hasn't been mapped, identify by address instead
-- Don't use `--window 24h --sort smart_inflow` for hot-new-token discovery — smart money usually positions BEFORE the 24h window; try `--window 7d` for that mode
-- Don't omit `--min-holders` when sorting by holders — junk airdrops with 50,000 1-tx addresses dominate the top otherwise
-- Don't omit `--min-volume` when sorting by net_inflow — tiny tokens with $100 net flow can rank high in % terms
+- Don't use `--window 24h --sort smart_inflow` for hot-new-token discovery: smart money usually positions before the 24h window; try `--window 7d`.
+- Don't omit `--min-holders` when sorting by `holders`: junk airdrops with 50,000 one-transaction addresses dominate the top otherwise.
+- Don't omit `--min-volume` when sorting by `net_inflow`: tiny tokens with $100 net flow can rank high in % terms.
+- Don't use `--smart-money-only` on `bsc` or `base`: it is a 400, not an empty result.
 
 ## Cost note
 
-3 credits per call. Cheaper than `wallet trace` (which is 4) but heavier than per-tool lookups. Use deliberately for discovery, not as a default.
+3 credits per call. Cheaper than `wallet trace` (4) but heavier than per-tool lookups. Use deliberately for discovery, not as a default.
 
 ## Pairs well with
 
-- `vike-data token holders <addr>` — drill into the top holders of any flagged token
-- `vike-data token transfers <addr>` — see WHO is buying/selling once a token is interesting
-- `vike-smart-money-discovery` — composite playbook starting from this screen
+- `vike-data token holders <addr>`: who moves the most of a flagged token
+- `vike-data token transfers <addr>`: WHO is buying/selling once a token is interesting (read `net_tokens`)
+- `vike-smart-money-discovery`: composite playbook starting from this screen

package/skills/vike-token-transfers/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vike-token-transfers
-description: Top buyers or top sellers of a specific token over a window. Use when the user asks "who bought X" / "who sold X" / "is whale Y buying Z".
+description: Top buyers or top sellers of a specific token over a window, with net token and USD flow per wallet. Use when the user asks "who bought X" / "who sold X" / "is whale Y buying Z".
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -10,33 +10,43 @@ allowed-tools: Bash(vike-data:*)
 
 ```bash
 vike-data token transfers <token_address>
-  [--tab bought|sold]
-  [--period 1h|24h|7d|30d]
+  [--tab bought|sold]            # default sold; ONE side per call
+  [--period 1h|24h|7d|30d]       # default 24h
   [--chain ethereum|bsc|base|all]
   [--json]
 ```
 
+There is no `--limit`: every call returns the top 10 wallets for that side. For both sides, call twice.
+
 ## When to use
 
-- "Who's accumulating X?" → `--tab bought --period 24h`
-- "Who's dumping X?" → `--tab sold --period 24h`
-- "Smart money on X this week" → `--tab bought --period 7d`, then cross-reference labels
+- "Who's accumulating X?" → `--tab bought --period 24h`, then read `net_tokens`
+- "Who's dumping X?" → `--tab sold --period 24h`, then read `net_tokens`
+- "Smart money on X this week" → `--tab bought --period 7d`, label the addresses with `vike-data wallet batch`
 
 ## Output columns
 
-Each row is one wallet: `address`, `qty`, `usd_value`, `label` (if known), `tx_count`.
+Each row is one wallet: `address`, `bought`, `sold`, `net_tokens`, `usd_spent`, `usd_received`, `net_usd`, `chains`. Amounts are whole tokens and plain USD. The remaining fields (`addr_short`, the `*_fmt` strings, `net_usd_raw`, `net_bar_pct`) are pre-rendered for a UI: ignore them.
+
+There is no `qty`, `usd_value`, `label` or `tx_count` column. To label an address use `vike-data wallet batch`.
 
 ## Reading tips
 
-- The same wallet appearing in both `bought` and `sold` lists for the same period = market maker / churn (not a signal).
-- High `usd_value` with low `tx_count` = a single large discretionary trade. Worth investigating with `vike-data wallet summary <address>`.
-- Many small transfers from labeled exchanges = retail flow via that CEX (Binance, Coinbase, etc.).
+- **`bought` is every inbound transfer, not purchases.** It includes flash-loan and router round trips. A wallet at the top of `--tab bought` with `bought ≈ sold` and `net_tokens ≈ 0` is a bot or venue passing tokens through, not a buyer. **Rank and judge by `net_tokens`** (bought − sold): positive = net accumulator, negative = net distributor.
+- **Signs differ by convention.** `net_usd = usd_received − usd_spent`, so a net buyer has `net_tokens > 0` and `net_usd < 0`, and a net seller has `net_usd > 0`. Do not read a positive `net_usd` as "bought".
+- The two sides of the same period are separate top-10 lists. The same wallet in both = market maker / churn, not a signal.
+- The window ends at the token's newest PRICED row, not at the current time. For an illiquid token it can be hours behind "now".
+- Many small transfers from labeled exchanges = retail flow via that CEX.
+- The native coin appears as `0x0000000000000000000000000000000000000000` in the screener and has no buyers here. Pass a contract address.
 
 ## Anti-patterns
 
-- Don't request `--chain all` unless you really need cross-chain — it's slower and returns more rows.
+- Don't call a wallet a buyer or seller from `bought` / `sold` alone. Check `net_tokens`.
+- Don't request `--chain all` unless you really need cross-chain: it maps the address to the token's address on each chain and is slower.
 - 1h period is sparse for low-liquidity tokens. Use 24h as the default starting window.
+- Don't treat the 10 rows as the token's whole market: they are the top 10 by volume on one side.
 
 ## Pairs well with
 
+- `vike-data wallet batch <addr...>` to label the rows and drop CEX / router rows
 - `vike-data wallet summary <addr>` to profile any interesting buyer/seller

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

@@ -1,6 +1,6 @@
 ---
 name: vike-wallet-balances
-description: Current ERC-20 token balances for a wallet across major EVM chains (eth, bsc, base, arbitrum, polygon, optimism). Dust filtered. Use when the user asks "what does this wallet hold" / "current portfolio of X" / "show top holdings".
+description: Current token balances for a wallet on the chains the server scans (Ethereum and BSC today), read from the chain at request time, with a USD value where the token is priced. Use when the user asks "what does this wallet hold" / "current portfolio of X" / "show top holdings".
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -10,15 +10,17 @@ allowed-tools: Bash(vike-data:*)
 
 ```bash
 vike-data wallet balances <address>
-  [--chains eth,bsc,base,arbitrum,polygon,optimism]  (default = all 6)
-  [--min-usd 1]   (filter dust below this)
+  [--chains ethereum,bsc]   (default: every chain the server scans)
+  [--min-usd 1]             (hide holdings worth less; default 1)
   [--json]
 ```
 
+`vike-data schema --pretty` shows the current chain list. A chain the tool does not scan is not silently skipped: it is named in `chain_errors`.
+
 ## Example
 
 ```bash
-vike-data wallet balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --chains eth,arbitrum
+vike-data wallet balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --chains ethereum
 ```
 
 ## Output
@@ -26,30 +28,34 @@ vike-data wallet balances 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --chains et
 ```json
 {
   "address": "0x...",
-  "total_usd": 123456.78,
-  "chains_scanned": ["eth", "bsc", "base", "arbitrum", "polygon", "optimism"],
+  "total_usd": 10532.82,
+  "chains_scanned": ["ethereum"],
   "holdings": [
-    { "chain": "eth", "symbol": "WETH", "name": "Wrapped Ether", "address": "0xc02a...", "balance": "12.34", "usd_value": 26345.67, "usd_price": 2134.94 },
-    { "chain": "arbitrum", "symbol": "USDC", "address": "0xaf88...", "balance": "5000.00", "usd_value": 5000.00, "usd_price": 1.0 },
-    ...
+    { "chain": "ethereum", "symbol": "ENS", "name": "Ethereum Name Service", "address": "0xc183...", "balance": 1144.04, "balance_raw": "1144036076063671431479", "usd_value": 6843.62, "usd_price": 5.982 },
+    { "chain": "ethereum", "symbol": "WEI", "address": "0x0000...", "balance": 1.0, "balance_raw": "1", "usd_value": null, "usd_price": null },
+    { "chain": "ethereum", "symbol": "ETH", "name": "ETH", "address": null, "balance": 2.5, "balance_raw": "2500000000000000000", "usd_value": null, "usd_price": null }
   ]
 }
 ```
 
-Holdings sorted by `usd_value` descending.
+Holdings are sorted by `usd_value` descending with unpriced rows (the native coin among them) last. `chain_errors` appears only when a requested chain was refused or failed.
 
 ## Reading
 
-- `total_usd` = sum across all chains scanned. Wallet might still hold value on chains not scanned (e.g. zkSync, Linea) — say so when relevant.
+- **`usd_value: null` is a holding, not an error**: the token has no price feed. `total_usd` sums only priced holdings, so read it as a floor, never as net worth, and never infer "worthless" from a null.
+- **The chain's native coin (ETH, BNB) is a row** with `usd_value: null`, and it is **left out of `total_usd`**. Report the native balance from its own `balance` field. It is always listed, whatever `--min-usd` says.
+- **Any `--min-usd` above 0 also drops unpriced holdings** (an unpriced holding cannot show it clears the floor). `--min-usd 0` lists everything, including airdrop spam.
+- `total_usd` covers `chains_scanned` only. The wallet may hold value on chains the tool does not scan: say so when relevant.
 - Stablecoin-heavy wallet → likely waiting for a buy / parked dry powder
 - WETH/WBTC + LSTs (stETH, wstETH, rETH) → "saver" wallet, low-risk
 - 50+ random tokens → airdrop farmer
-- Empty `holdings` array → either no balance OR the address hasn't been indexed yet (very new wallets)
+- Empty `holdings` array → no priced balance above the floor, or a very new wallet we have not seen yet.
 
 ## Anti-patterns
 
-- This is ERC-20 only — does NOT include native ETH/BNB/MATIC (would need separate calls; not in our current tool surface). Mention this when reporting "total holdings".
+- Don't report `total_usd` as the wallet's value without "of priced tokens" and the native balance next to it.
 - For wallets with 100+ tokens, the response is large — use `--min-usd 100` or higher to focus on meaningful holdings.
+- This is a point-in-time read, not history. For how the wallet got here use `wallet pnl-history`.
 
 ## Pairs well with