| name | whale-hunting |
| description | Detect institutional whale activity in options for a given underlying. Use when the user asks about unusual options activity, large block trades, whale trades, or institutional options flow for a specific symbol. |
| dependencies | ["trading-skills"] |
Whale Hunting
Scans option chains for a given underlying to identify institutional-sized trades using a two-step approach:
- Crude scan (Yahoo Finance) — finds contracts with anomalous daily investment vs the rest of the chain.
- Precise drill-down (Massive API) — fetches per-second bars for each candidate and flags seconds with outlier dollar invested.
Instructions
Note: If uv is not installed or pyproject.toml is not found, replace uv run python with python in all commands below.
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py SYMBOL [--months N] [--date YYYY-MM-DD] [--sigma F] [--sigma-z F] [--summary]
Arguments
SYMBOL — Underlying ticker (e.g. AAPL, NVDA, SPY)--months — Max months until option expiration to consider (default: 2)--date — Trading date to analyze in YYYY-MM-DD format (default: latest trading day)--sigma — Std-deviation multiplier for crude outlier threshold (default: 3.0)--sigma-z — Modified Z-Score threshold for per-second small-sample detection (default: 3.5)--summary — Also compute per-ticker summary and include it in the JSON output
Output
Returns JSON with:
underlying — The scanned symboltrading_date — Date analyzedsource — "massive" (per-second data) or "yahoo only" (daily chain data)total_whales — Total whale events foundtotal_call_invested — Sum of invested dollars in call whale eventstotal_put_invested — Sum of invested dollars in put whale eventscall_put_ratio — Call invested / put invested (null if no puts)whales — List of whale events:
timestamp, ticker, type, strike, expiryclose, volume, transactions, invested, break_even
summary (present only when --summary is passed) — List of per-ticker aggregates:
ticker, type, strike, expiry, whale_count, total_invested, break_even
Examples
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py AAPL
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py NVDA --date 2026-03-13
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py HOOD --months 3 --summary
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py SPY --sigma 2.0
Reporting
After running the script, present the results as follows.
Header line:
Whale activity for {underlying} on {trading_date} — source: {source}
Call flow: ${total_call_invested:,.0f} | Put flow: ${total_put_invested:,.0f} | C/P ratio: {call_put_ratio:.2f}
When --summary was requested, render the summary array as a table:
| Time (ET) | Ticker | Type | Strike | Expiry | # Events | Total Invested | Break Even |
|---|
| {timestamp} | {ticker} | {type} | {strike} | {expiry} | {whale_count} | ${total_invested:,.0f} | {break_even} |
Sort by total_invested descending. For multi-event rows use the time range of first–last event (e.g. 11:46–12:33).
Interpretation guidance:
source: "massive" — High-confidence; per-second block trade data from Massive APIsource: "yahoo only" — Fallback; daily-level data (Massive API key missing or no intraday data)- Low C/P ratio (< 0.5) — Bearish institutional positioning
- High C/P ratio (> 2.0) — Bullish institutional positioning
transactions: 1 — Single block trade; strongest whale signal
Requirements
MASSIVE_API_KEY environment variable for per-second data. Without it, falls back to Yahoo Finance daily data.
Timezone
All timestamps and time-based calculations must use the America/New_York timezone. All JSON output must include generated_at (NY time string) and data_delay fields.
