whale-hunting

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)
• whales — List of whale events:
• timestamp, ticker, type, strike, expiry
• close, 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

# 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}

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)
• 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.