| name | options-flow |
| description | Surface unusual options activity across a watchlist as a Cheddar Flow / FlowAlgo-style stream. Each notable print rendered as a three-line block with kind (sweep vs block), premium, volume vs avg, volume vs OI (opening vs closing), price relative to NBBO, and inferred direction. Use when a trader is scanning for unusual flow, monitoring smart money, or hunting for actionable setups. Real-time on Options Business; ~15-min delayed on Options Developer. |
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
- 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.
- 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.
- 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.
- 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.
- Distinguish opening from closing per
references/opening-vs-closing.md:
trade volume materially above OI = new interest opening; under OI =
likely closing existing positions.
- Rank all qualifying prints by score and emit the top N (default 20).
Foundations used
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}×tamp.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.
