Whale Hunting

Scans option chains for institutional-sized trades using a two-pass approach: first it flags anomalous daily volume across the chain via Yahoo Finance, then drills down with per-second bars from the Massive API to pinpoint exact block trades. You get JSON with timestamps, invested dollars, and call/put flow ratios. Requires a Massive API key for the good stuff, otherwise it falls back to daily data only. Useful when you need to see where the smart money moved today rather than just reading about unusual activity in a newsletter tomorrow. The modified Z-score detection on per-second data is solid for catching single-transaction blocks, which tend to be the cleanest institutional signals.

GitHub stars: 248
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add staskh/trading_skills --skill whale-hunting --agent claude-code

Installs into .claude/skills of the current project.

Files

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