Unusual Whales

Options flow, dark pool, Congress trades, insider activity, Greek exposure, IV analytics, and market sentiment via the Unusual Whales API.

Unusual Whales provides institutional-grade options flow data, dark pool prints, Congress and insider trading disclosures, Greek exposure analytics, and volatility surfaces.

Setup

1. Get an API key

   Sign up at unusualwhales.com/pricing and get your API key from the API dashboard.

2. Set environment variable

   export UNUSUAL_WHALES_API_KEY="your-api-key"
   
3. Start using

   from horizon.providers import UnusualWhalesProvider as UW
   
   flow = UW.options_flow(ticker="AAPL", min_premium=100000)
   

Options Flow

The core feature — detect unusual options activity, sweeps, and large premium prints.

Python

from horizon.providers import UnusualWhalesProvider as UW

# All unusual flow
flow = UW.options_flow(limit=50)

# Filtered: AAPL call sweeps, $100k+ premium
flow = UW.options_flow(
    ticker="AAPL",
    is_sweep=True,
    is_call=True,
    min_premium=100000,
)

# Flow for a specific ticker
recent = UW.stock_flow("TSLA", min_premium=50000)

CLI

# All unusual flow
horizon providers uw flow

# Filtered
horizon providers uw flow --ticker AAPL --sweep --calls --min-premium 100000

# Per-ticker flow
horizon providers uw stock-flow TSLA

Filter parameters:

Parameter	Description
ticker	Filter by ticker symbol
min_premium	Minimum premium in dollars
is_sweep	Only sweep orders
is_call / is_put	Filter by option type
is_otm	Only out-of-the-money
min_dte / max_dte	Days to expiration range
limit	Number of results (default 50)

Dark Pool

Institutional block trades executed off-exchange.

Python

# Market-wide dark pool prints
prints = UW.dark_pool_recent()

# Per-ticker with size filter
nvda_dp = UW.dark_pool("NVDA", min_size=10000)

CLI

# Market-wide
horizon providers uw dark-pool

# Per-ticker
horizon providers uw dark-pool NVDA --min-size 10000

Congress Trades

Track stock trades disclosed by members of Congress (STOCK Act).

Python

# Recent trades
trades = UW.congress_trades(limit=20)

# Filter by ticker
nvda = UW.congress_trades(ticker="NVDA")

# Specific member
pelosi = UW.congress_trader("Pelosi")

CLI

horizon providers uw congress
horizon providers uw congress --ticker NVDA
horizon providers uw congress --name "Pelosi"

Insider Transactions

SEC Form 4 filings — officer, director, and 10% owner trades.

Python

# Large insider buys
insiders = UW.insider_trades(min_value=1000000, limit=20)

# Per-ticker, officers only
aapl = UW.insider_trades(ticker="AAPL", is_officer=True)

CLI

horizon providers uw insiders --min-value 1000000
horizon providers uw insiders --ticker AAPL --officer

Greek Exposure & IV

Options positioning analytics — gamma exposure (GEX), delta exposure (DEX), IV rank, and term structure.

Python

# Aggregate Greek exposure
gex = UW.greek_exposure("SPY")

# By strike
gex_strikes = UW.greek_exposure_by_strike("SPY")

# IV rank (percentile)
iv = UW.iv_rank("TSLA")

# Term structure
term = UW.vol_term_structure("AAPL")

# Max pain
pain = UW.max_pain("SPY")

CLI

horizon providers uw greeks SPY
horizon providers uw greeks SPY --by-strike
horizon providers uw iv TSLA
horizon providers uw max-pain SPY

Short Interest

Short interest, short volume, and failures to deliver.

Python

si = UW.short_interest("GME")
vol = UW.short_volume("AMC")
ftds = UW.ftd("TSLA")

CLI

horizon providers uw shorts GME

Market Sentiment

Proprietary market-wide indicators.

Python

# Market Tide (net premium flow)
tide = UW.market_tide()

# SPIKE volatility indicator
spike = UW.spike()

CLI

horizon providers uw tide
horizon providers uw spike

Screeners

Scan stocks and option chains for setups.

Python

# Stock screener
stocks = UW.screener_stocks()

# Hottest option chains
options = UW.screener_options(min_premium=500000, is_otm=True)

CLI

horizon providers uw screener --type stocks
horizon providers uw screener --type options --min-premium 500000

Calendars & Earnings

Economic events, FDA catalysts, and earnings schedules.

Python

econ = UW.economic_calendar()
fda = UW.fda_calendar()
earnings = UW.earnings("AAPL")
premarket = UW.earnings_premarket()

CLI

horizon providers uw calendar --type economic
horizon providers uw calendar --type fda
horizon providers uw earnings AAPL
horizon providers uw earnings --schedule premarket

Additional Endpoints

Function	Description
UW.stock_info(ticker)	Stock information (price, market cap, sector)
UW.stock_state(ticker)	Current stock state
UW.option_chains(ticker)	Full option chains
UW.institutions()	List tracked institutions
UW.institution_holdings(name)	Holdings for an institution
UW.institution_ownership(ticker)	Institutional ownership of a ticker
UW.etf_holdings(ticker)	ETF holdings breakdown
UW.etf_flow(ticker)	ETF inflow/outflow
UW.seasonality(ticker)	Monthly return seasonality
UW.news()	Financial news headlines
UW.prediction_whales()	Prediction market whales
UW.prediction_unusual()	Unusual prediction market activity
UW.crypto_whales()	Recent crypto whale transactions

Rate Limits

Limit	Value
Daily requests	15,000
Per-minute	120
Daily reset	8 PM ET

Rate limit headers are returned with every response: x-uw-daily-req-count, x-uw-req-per-minute-remaining.

MCP Tools

All functions are available via the unusual_whales compound MCP tool with an action parameter:

// Example: get unusual options flow for AAPL
{"action": "options_flow", "params": "{\"ticker\": \"AAPL\", \"min_premium\": 100000}"}

Available actions: options_flow, stock_flow, dark_pool, congress_trades, congress_trader, insider_trades, market_tide, spike, economic_calendar, fda_calendar, stock_info, stock_state, earnings, earnings_schedule, seasonality, greek_exposure, greek_exposure_by_strike, greek_exposure_by_expiry, iv_rank, vol_term_structure, max_pain, option_chains, short_interest, short_volume, ftd, screener_stocks, screener_options, etf_holdings, etf_flow, institutions, institution_holdings, institution_ownership, news, prediction_whales, prediction_unusual, crypto_whales.