Options Flow

options-flow

You hand over a watchlist. The skill scans each name's options chain, filters for unusual activity (high volume vs 30-day avg, volume above open interest, premium thresholds), classifies each print as a sweep or block, infers direction from where the trade printed in the NBBO, and emits a Cheddar Flow / FlowAlgo-style stream of the top N most actionable prints.

This is the "what's smart money doing right now" workflow. Unlike a chain viewer or screener, options-flow ranks prints by signal quality rather than raw volume, ships the methodology with the output, and emits both JSON and human-readable formats from one analysis.

When to invoke

• A trader is starting their session and wants the day's unusual flow
• A PM is checking whether options activity confirms a thesis
• The user says "what's the flow on NVDA today", "any unusual options activity in TSLA", or "scan flow on my watchlist"
• A discretionary trader is hunting for sympathy plays off a major print

What you need

• A watchlist of tickers (default: AAPL, NVDA, TSLA, AMD, SPY)
• MASSIVE_API_KEY exported in the environment
• Options Developer plan minimum (Options Business for real-time)

The skill runs at three fidelity tiers. The chosen tier is flagged in the output JSON as tier.

• Tier A (real-time): Options Business + Stocks Business. Tape is live, sweeps detected within seconds, IV and OI fresh. The output matches what Cheddar Flow / FlowAlgo show their subscribers.
• Tier B (15-min delayed): Options Developer + Stocks Starter. Same methodology, same per-print fields, but the prints are at least 15 minutes old. Useful for end-of-day review or postmortems.
• Tier C (free Basic): Documented but not actively supported. Free Basic doesn't include options snapshot or trades; the skill warns and exits.

What you get back

The skill ships two output layers from one analysis.

Layer 1: canonical JSON matching output-schema.json. Per-print fields include the OCC contract ID, kind (sweep/block/other), premium, volume, volume vs 30-day avg, volume vs OI (signals opening/closing), price vs NBBO (above_ask / at_mid / below_bid), inferred direction (bullish/bearish/neutral), spot at print, IV at print, and the contributing trades. UIs, alert pipelines, and downstream agents consume this.

Layer 2: rendered stream in Cheddar Flow style. See references/rendering.md for the format rules. Three lines per print plus optional ↳ continuation lines for context (clustering, prior prints, dealer notes). Compact, scanable, key:value pairs. Claude Code users read this.

How it works

1. For each ticker in the watchlist, pull the options chain snapshot filtered to expiries within the next ~60 days and strikes within ±10% of spot. This caps the chain at the slice where actionable flow lives.
2. For each contract, compute the unusual activity score per references/unusual-activity-detection.md: volume / 30-day avg, volume / OI (signals opening vs closing interest), premium dollar value, and percentage of chain volume.
3. Pull recent trades for the top-ranked contracts. Classify each as sweep or block per references/sweep-vs-block.md: the Massive trade conditions field carries condition 219 (Intermarket Sweep Order) when the print swept multiple exchanges.
4. Infer direction per references/directional-inference.md: compare trade price to the NBBO at the time of print (above ask = aggressive buy, below bid = aggressive sell, at mid = negotiated). Apply the call/put overlay for bullish vs bearish read.
5. Distinguish opening from closing per references/opening-vs-closing.md: trade volume materially above OI = new interest opening; under OI = likely closing existing positions.
6. Rank all qualifying prints by score and emit the top N (default 20).

Foundations used

• massive-api-patterns for REST auth, rate limiting, and the best-price fallback chain for spot

Output mode: stream

Stream mode is the format Cheddar Flow / FlowAlgo / Unusual Whales use for live flow. Each print is a self-contained block; the reader scans top to bottom and stops when they see one they want to act on. references/rendering.md is the canonical format reference for any future stream-mode skill (news-scanner, crypto-vol-scanner).

Endpoints used

• GET /v3/snapshot/options/{ticker}: paginated options chain with per-contract day volume, OI, IV, greeks, last quote (NBBO).
• GET /v3/trades/{occ_ticker}?timestamp.gte={start_ns}&timestamp.lte={end_ns}: tick-level trades for a contract over today's session window. Returns size, price, conditions array (219 = ISO sweep), and exchange. Used to classify sweep vs block. Real-time on Options Business; 15-min delayed on Options Developer.
• GET /v3/quotes/{occ_ticker}?timestamp.lte={trade_ns}: NBBO at each contributing trade's sip_timestamp, used for direction inference per-trade rather than against a single most-recent quote.
• GET /v2/aggs/ticker/{occ_ticker}/range/1/day/{from}/{to}: per-day volume aggregates for the contract's recent history, used to compute 30-day average volume.
• GET /v2/snapshot/locale/us/markets/stocks/tickers/{ticker}: spot price snapshot, with the best-price fallback chain.

Doesn't handle (yet)

• Multi-leg detection (spreads, condors, butterflies). Massive's trade feed marks them via conditions 232-245, which the script excludes from sweep/block classification. Constructing the underlying strategy requires linking the legs by sequence_number, which the v1 skill doesn't attempt.
• Dealer positioning / GEX. The skill documents the methodology in references/dealer-positioning.md but doesn't compute it. v2 candidate.
• Real-time WebSocket streaming. v1 is REST-polled. Use the massive-websockets foundation for live stream interop in a future variant of this skill.
• Dark pool prints on the underlying. Surfacing dark prints alongside options flow is a known complement; left for a separate skill.

These are clean PR extensions and welcome contributions.