/whale-hunting

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: 1. **Crude scan** (Yahoo Finance) — finds contracts with anomalous daily investment vs the rest of the chain. 2. **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 symbol
• `trading_date` — Date analyzed
• `source` — `"massive"` (per-second data) or `"yahoo only"` (daily chain data)
• `total_whales` — Total whale events found
• `total_call_invested` — Sum of invested dollars in call whale events
• `total_put_invested` — Sum of invested dollars in put whale events
• `call_put_ratio` — Call invested / put invested (null if no puts)
• `directional_call_invested` — Call invested where break-even is ≥ 1.5% above spot
• `directional_put_invested` — Put invested where break-even is ≥ 1.5% below spot
• `directional_call_put_ratio` — Directional call / directional put invested (null if no directional puts)
• `whales` — List of whale events:
• `timestamp`, `ticker`, `type`, `strike`, `spot` (underlying price at trade time), `expiry`
• `close`, `volume`, `transactions`, `invested`, `break_even`, `pct_from_spot` (break-even distance from spot, %)
• `summary` *(present only when `--summary` is passed)* — List of per-ticker aggregates:
• `ticker`, `type`, `strike`, `expiry`, `whale_count`, `total_invested`, `break_even`

Examples

# Hunt whales for AAPL (latest trading day)
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py AAPL

# Hunt whales for NVDA on a specific date
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py NVDA --date 2026-03-13

# With per-ticker summary
uv run python .claude/skills/whale-hunting/scripts/whale_hunting.py HOOD --months 3 --summary

# Looser detection threshold
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} > Directional (≥1.5% B/E from spot) — Calls: ${directional_call_invested:,.0f} | Puts: ${directional_put_invested:,.0f} | C/P ratio: {directional_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 API
• `source: "yahoo only"` — Fallback; daily-level data (Massive API key missing or no intraday data)
• Judge direction by `directional_call_put_ratio`, not `call_put_ratio` — trades with break-even within 1.5% of spot (deep ITM stock replacement, hedges) carry no directional signal
• Low directional C/P ratio (< 0.5) — Bearish institutional positioning
• High directional 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.