# Crypto Vol Scanner > crypto-vol-scanner - Skill: `rgourley/crypto-vol-scanner` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add rgourley/crypto-vol-scanner` - Raw SKILL.md: https://api.skillmd.com/api/skills/rgourley/crypto-vol-scanner/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: rgourley (https://skillmd.com/u/rgourley) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/rgourley/crypto-vol-scanner --- # crypto-vol-scanner You hand over a crypto universe and a window. The skill pulls each name's current snapshot, last 200 ticks across exchanges, and 30 days of hourly + daily aggregates, computes realized vol against the trailing 30-day distribution, flags volume anomalies, surfaces cross-exchange basis when prints disagree, z-scores the 24h move against the trailing daily return distribution, ranks every name by a composite impact score, and emits a stream of the most notable events. This is the workflow a crypto desk runs at the open. Ten names, four signal types, ranked by what actually moved or is acting weird right now. Unlike a CoinGecko screener or TradingView heatmap, crypto-vol- scanner ranks by statistical context (percentiles, z-scores, multipliers against trailing distributions) rather than absolute move size, and ships the methodology alongside the output. First crypto skill in the suite. Validates a third asset class beyond stocks and options. ## When to invoke - A crypto trader is starting their session and wants the universe's vol + volume + basis state - A PM is asking "what's the action in crypto today" - The user says "scan crypto vol", "any crypto anomalies", "what's weird in crypto right now" - A discretionary trader is hunting for setups: vol spikes that precede trend resumption, persistent cross-exchange basis that signals exchange-specific flow ## What you need - A crypto universe (default: BTC, ETH, SOL, XRP, ADA, DOGE, AVAX, LINK, DOT, POL). POL is the new ticker for the former MATIC; the skill auto-substitutes - `MASSIVE_API_KEY` exported in the environment - Crypto Starter or higher (Currencies Business covers it). All paid tiers return real-time spot and tick-level trades The skill runs at two fidelity tiers. - **Tier A (Currencies Business or Crypto Developer):** Real-time spot, tick-level trades for cross-exchange basis, full 30d hourly and daily aggregate history. Sub-second updates on the snapshot. This is the default tier. - **Tier B (Crypto Starter):** Same data shapes, but trade history may be 15-min delayed depending on plan specifics. The methodology is identical; only the snapshot freshness differs. Volume and vol numbers are computed from historical aggregates, which are stable. ## What you get back Two output layers from one analysis. **Layer 1: canonical JSON** matching [`output-schema.json`](./output-schema.json). Per-event fields: ticker, base_currency, quote_currency, signal_type (vol_spike | volume_anomaly | cross_exchange | tail_move | quiet | combined), realized_vol_pct, vol_percentile_ttm, vol_vs_avg_ratio, volume_24h_usd, volume_vs_avg_ratio, move_24h_pct, move_zscore, basis_bps (when cross-exchange), exchanges_compared, context_line. UIs, alert pipelines, and downstream agents consume this. **Layer 2: rendered stream** in Bloomberg crypto desk / Cheddar-Flow- for-crypto style. Three lines per event, optional `↳` continuation line. Format rules in [`references/rendering.md`](./references/rendering.md). Compact, scanable, key:value pairs. Claude Code users read this. ## How it works 1. For each ticker in the universe, pull the bulk snapshot via `/v2/snapshot/locale/global/markets/crypto/tickers?tickers=X:BTCUSD,X:ETHUSD,...`. The `prevDay` block is the "last 24h" reference (last completed UTC day); `lastTrade.p` is current spot. POL is auto-substituted for the deprecated MATIC ticker. 2. For each ticker, pull `/v2/aggs/ticker/{X:BASEUSD}/range/1/day/{from}/{to}` over the trailing TTM. Used for the 30-day daily-return distribution and the trailing 30d daily-volume baseline. See [`references/move-zscore.md`](./references/move-zscore.md). 3. For each ticker, pull `/v2/aggs/ticker/{X:BASEUSD}/range/1/hour/{from}/{to}` over the trailing 32 days. Used to compute current 24h realized vol (close-to-close log returns, annualized × sqrt(365 × 24)) and to build the trailing 30-day rolling-24h realized-vol distribution. Methodology in [`references/realized-vol-methodology.md`](./references/realized-vol-methodology.md). 4. For each ticker, compute volume anomaly per [`references/volume-anomalies.md`](./references/volume-anomalies.md): `prevDay.v * prevDay.vw` (USD) vs trailing 30d daily-volume average from the daily aggs. Threshold for flagging: > 2x. 5. For each ticker, pull `/v3/trades/{X:BASEUSD}?limit=200&order=desc` and group by exchange (Coinbase=1, Bitfinex=2, Bitstamp=6, Binance=10, Kraken=23). Compute the max minus min of the per-exchange most-recent price as the cross-exchange basis in bps. Methodology and caveats in [`references/cross-exchange-basis.md`](./references/cross-exchange-basis.md). 6. Compose per-ticker signals. Tag the dominant signal type (`vol_spike`, `volume_anomaly`, `cross_exchange`, `tail_move`, `quiet`, or `combined` when multiple fire). Rank by composite impact = max(vol_zscore, volume_zscore, abs(move_zscore), basis_bps_zscore) per [`references/signal-ranking.md`](./references/signal-ranking.md). Emit the top N (default 15). ## Foundations used - [`massive-api-patterns`](../massive-api-patterns) for REST auth, rate-limit handling, pagination, and the best-price fallback chain for spot ## Output mode: stream Stream mode is the format Bloomberg's crypto desk pages, Cheddar Flow, and Coinbase Institutional desk reports converge on for "here's what's weird right now": per-event blocks, ticker-tagged, signal-typed, compact key:value pairs, scanable top to bottom. Inherited from [`options-flow/references/rendering.md`](../options-flow/references/rendering.md), adapted for crypto signals per [`references/rendering.md`](./references/rendering.md). ## Endpoints used - `GET /v2/snapshot/locale/global/markets/crypto/tickers?tickers=...`: Bulk snapshot. Returns `lastTrade.p`, `day.{o,h,l,c,v,vw}`, `prevDay.{o,h,l,c,v,vw}`, `min.*`, `fmv`, and `todaysChangePerc` per ticker. The `prevDay` block is the canonical "last 24h" reference because `day.*` is the current incomplete UTC day. - `GET /v2/aggs/ticker/{X:BASEUSD}/range/1/day/{from}/{to}`: daily OHLCV aggregates. Used for the trailing 30d daily-volume baseline and the daily-return distribution for the 24h move z-score. - `GET /v2/aggs/ticker/{X:BASEUSD}/range/1/hour/{from}/{to}`: hourly OHLCV aggregates. Used for current 24h realized vol and the rolling-24h realized-vol distribution. - `GET /v3/trades/{X:BASEUSD}?limit=200&order=desc`: most-recent tick-level trades, including the `exchange` field. Used to compute per-exchange basis. Five paid crypto exchanges: Coinbase (1), Bitfinex (2), Bitstamp (6), Binance (10), Kraken (23). ## Doesn't handle (yet) - Perpetual funding rates. Funding rate divergence and basis trade setups are the bread and butter of crypto desks, but Massive's REST surface doesn't expose perp markets in this product. Spot only. - WebSocket streaming. v1 is REST-polled. The `massive-websockets` foundation covers the live-stream pattern for a future variant of this skill. - Cross-quote-currency basis. The skill compares USD pairs only; the BTC-USDT vs BTC-USD basis (which is informative about USDT depeg risk and exchange-specific flow) is a clean v2. - Derivatives implied vol (e.g. Deribit DVOL). Massive doesn't carry Deribit options surface; realized vol is the only vol metric the skill produces. - Sentiment / social flow. DOGE-style social-driven anomalies surface in this skill as volume + vol spikes, but the skill doesn't attribute to a source. Pair with `news-scanner` on the crypto-news tickers (BTC, ETH) for a complete picture. These are clean PR extensions and welcome contributions.