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. 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. 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.
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.
4. For each ticker, compute volume anomaly per 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.
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. Emit the top N (default 15).

Foundations used

• 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, adapted for crypto signals per 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.