@vike-io/cli 0.13.1 → 0.14.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-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
 

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

@@ -1,6 +1,6 @@
 ---
 name: vike-wallet-batch
-description: Bulk label + 30d summary lookup for up to 100 addresses in one call. Use when the user pastes a CSV of addresses, asks "enrich this list with labels", or wants to quickly screen many wallets for entity / risk / activity.
+description: Bulk label + 30d summary lookup for up to 100 addresses in one call, per chain. Use when the user pastes a CSV of addresses, asks "enrich this list with labels", or wants to quickly screen many wallets for entity / risk / activity.
 allowed-tools: Bash(vike-data:*)
 ---
 
@@ -10,7 +10,7 @@ allowed-tools: Bash(vike-data:*)
 
 ```bash
 vike-data wallet batch <addr1> <addr2> <addr3> ...
-  [--chain ethereum|bsc|base]
+  [--chain ethereum|bsc|base]     # default ethereum; labels and flows are read from THAT chain's tables
   [--json]
 ```
 
@@ -24,32 +24,36 @@ vike-data wallet batch 0xd8da... 0xabc... 0xdef... --json
 
 ## Output
 
-One row per INPUT address (preserves input order — useful when joining back to a source CSV):
+One row per INPUT address (preserves input order — useful when joining back to a source CSV). Each row echoes its own `wallet`, lower-cased: compare case-insensitively.
 
 ```json
 [
-  { "wallet": "0xd8da...", "entity": null,       "wallet_type": "user", "confidence": "Medium", "risk_flag": null,    "net_30d_usd": 12000, "volume_30d_usd": 50000, "tx_30d": 42, "tokens_30d_count": 8, "found": true },
-  { "wallet": "0xabc...",  "entity": "Binance",  "wallet_type": "cex",  "confidence": "High",   "risk_flag": null,    "net_30d_usd": -5e9,  "volume_30d_usd": 9e9,   "tx_30d": 2000, "tokens_30d_count": 80, "found": true },
-  { "wallet": "0xdef...",  "entity": null,       "wallet_type": null,   "confidence": null,     "risk_flag": null,    "net_30d_usd": 0,     "volume_30d_usd": 0,     "tx_30d": 0,    "tokens_30d_count": 0,  "found": false }
+  { "wallet": "0xd8da...", "entity": "vitalik buterin", "wallet_type": "dex", "confidence": "medium", "risk_flag": "", "net_30d_usd": -70023.25, "volume_30d_usd": 70046.75, "tx_30d": 454, "tokens_30d_count": 157, "found": true },
+  { "wallet": "0xabc...",  "entity": "binance", "wallet_type": "cex", "confidence": "high", "risk_flag": "", "net_30d_usd": -5e9, "volume_30d_usd": 9e9, "tx_30d": 2000, "tokens_30d_count": 80, "found": true },
+  { "wallet": "0xdef...",  "entity": null, "wallet_type": null, "confidence": null, "risk_flag": null, "net_30d_usd": null, "volume_30d_usd": null, "tx_30d": null, "tokens_30d_count": null, "found": false }
 ]
 ```
 
-`found: false` = address has no labels AND no 30d activity in our DB (might be brand-new wallet or one we haven't indexed).
+## Chain behaviour
+
+- `--chain` picks the label table and the 30-day flow table. Before 2026-10-19 it was accepted and ignored (`bsc` and `base` returned Ethereum labels), so earlier results for those chains are Ethereum's.
+- **The four 30-day fields (`net_30d_usd`, `volume_30d_usd`, `tx_30d`, `tokens_30d_count`) are `null`, not 0,** where we hold no flow data: every `bsc` address, and any address we have no label for (`found: false`). Don't report null as zero activity.
+- `found: false` = the address is not in that chain's label table. It is not proof the wallet is new or clean.
 
 ## Reading
 
 - Filter to `wallet_type = "user"` to find real-people addresses worth investigating further
-- Any `risk_flag != null` → flag prominently in any user-facing report
-- High `volume_30d_usd` but `tx_30d = 0` shouldn't happen — if it does, indicates stale aggregate; recompute
-- `entity = "Binance"` + `wallet_type = "cex"` rows in a "smart money" list = false positives (CEX deposits aren't traders)
+- Any `risk_flag` that is non-empty → flag prominently in any user-facing report
+- `entity = "binance"` + `wallet_type = "cex"` rows in a "smart money" list = false positives (CEX deposits aren't traders)
+- Use it to label the output of `token transfers`, `wallet counterparties`, `wallet discover` or `token holders` in one call
 
 ## Anti-patterns
 
-- Don't run individual `vike-data wallet summary` in a loop for >5 addresses — this batch is ~20× faster
-- Don't pass mixed-case addresses inconsistently — they're normalised but cleaner CSVs help readers
-- Don't expect lifetime data — this is 30d window. For lifetime use the individual `wallet summary`
+- Don't run individual `vike-data wallet summary` in a loop for >5 addresses — this batch is far faster for labels and 30d activity
+- Don't pass a mix of chains in one call: pick the chain the addresses were seen on
+- Don't expect lifetime data — this is a 30d window. For lifetime use `wallet summary`
 
 ## Pairs well with
 
-- `vike-data labels <addr>` — drill into any address showing high-confidence labels
+- `vike-data labels <addr>` — drill into any Ethereum address with high-confidence labels (source attribution)
 - `vike-data wallet compare <a> <b>` — pick two interesting batch results and diff them

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

@@ -16,6 +16,8 @@ vike-data wallet compare <address_a> <address_b>
   [--json]
 ```
 
+Compares exactly two wallets. `--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 shared activity".
+
 ## Output
 
 ```json

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

@@ -16,6 +16,8 @@ vike-data wallet counterparties <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".
+
 ## Example
 
 ```bash
@@ -28,6 +30,8 @@ vike-data wallet counterparties 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --win
 
 ## Reading
 
+- `sent_usd` / `received_usd` are from the QUERIED wallet's side: `sent_usd` is what it sent to that counterparty.
+- `first_seen` is the first contact inside the window, not the first ever (widening the window moves it).
 - **Sent + Received roughly equal** = active trading partner (DEX router, MM, regular counterparty)
 - **Sent >> Received** = wallet pays this counterparty (deposit address, contract call)
 - **Received >> Sent** = wallet receives from this counterparty (funding source, employer, airdrop)
@@ -37,7 +41,7 @@ vike-data wallet counterparties 0xd8da6bf26964af9d7eed9e03e53415d37aa96045 --win
 
 ## Anti-patterns
 
-- Don't claim two wallets are "controlled by the same person" from counterparties alone — many people deposit to the same Binance address. Pair with `vike-wallet-clustering` (deferred) or manual investigation.
+- Don't claim two wallets are "controlled by the same person" from counterparties alone — many people deposit to the same Binance address. There is no clustering tool; use `vike-data wallet compare` (shared counterparties and tokens) and `vike-data wallet trace` as evidence, and say it is only evidence.
 - Window matters: a 24h view captures recent activity but misses long-standing relationships. Default to 30d, expand to `all` for full history.
 - For tokens with high churn (memecoins), top counterparties will be dominated by Uniswap routers; filter mentally for non-DEX rows for human counterparties.