Unusual Whales API - Option Trade endpoints (OptionTradeController)

Unusual Whales API - Option Trade endpoints

Layer mapping: L1 (0DTE) load-bearing. Three endpoints:

1. /flow-alerts - the pre-classified flow alerts feed (UW has already done the unusual-activity detection for you).
2. /flow-alerts/{id} - a single flow alert lookup.
3. /full-tape/{date} - every options trade for the date.

Plus a reference to the flow-alert rules page: https://unusualwhales.com/option-flow-alerts/rules (main-site, not API docs). This page enumerates the meaning of each alert_rule value; the API endpoint docs only enumerate the names.

1. Base contract

Property	Value
Base URL	https://api.unusualwhales.com
Auth	Authorization: Bearer <token> header
Response envelope	{ "data": [...] }
Status codes	200, 422, 500

2. GET /api/option-trades/flow-alerts - The pre-classified feed

The UW flow-alerts feed. Each record is a cluster of trades that hit one of nine named detection rules.

2.1 Query parameters

Ticker + asset:

Param	Type	Notes
ticker_symbol	string	Comma-separated; - to exclude
issue_types[]	enum	Common Stock, ETF, Index, ADR

Premium + size:

Param	Type	Range
min_premium / max_premium	number	>= 0
min_size / max_size	number	>= 0
min_marketcap / max_marketcap	number	>= 0

Volume + OI:

Param	Type	Range
min_volume / max_volume	number	>= 0
min_open_interest / max_open_interest	number	>= 0
min_volume_oi_ratio / max_volume_oi_ratio	number	>= 0
size_greater_oi	bool	Size > OI flag
vol_greater_oi	bool	Volume > OI flag

Transaction type (all default true):

Param	Meaning
is_floor	Include floor trades
is_sweep	Include intermarket sweeps
is_call	Include calls
is_put	Include puts
is_ask_side	Include ask-side
is_bid_side	Include bid-side
is_multi_leg	Multi-leg only (no default)
all_opening	All transactions opening (no default; set false for RepeatedHits rules)

Rule names (rule_name[] enum array):

Rule	What it captures (per UW’s classification)
FloorTradeSmallCap	Floor trade on a small-cap underlying
FloorTradeMidCap	Floor trade on a mid-cap underlying
FloorTradeLargeCap	Floor trade on a large-cap underlying
RepeatedHits	Repeated trades hitting one contract (cluster)
RepeatedHitsAscendingFill	Repeated hits with ascending fill price
RepeatedHitsDescendingFill	Repeated hits with descending fill price
OtmEarningsFloor	Floor trade on OTM contract pre-earnings
LowHistoricVolumeFloor	Floor trade in a contract with low historic volume
SweepsFollowedByFloor	Sweep cluster followed by floor trade

Detailed rule definitions live on the main-site page: https://unusualwhales.com/option-flow-alerts/rules. Fetch separately to capture the full rule logic - the API docs only enumerate the names.

Contract characteristics:

Param	Type	Notes
min_diff / max_diff	decimal	OTM diff ratio: (strike - underlying) / underlying for calls (inverted for puts)
is_otm	bool	OTM only
min_dte / max_dte	int	DTE range

Sentiment + skew:

Param	Type	Range
min_ask_perc / max_ask_perc	decimal	0 to 1
min_bid_perc / max_bid_perc	decimal	0 to 1
min_bull_perc / max_bull_perc	decimal	0 to 1
min_bear_perc / max_bear_perc	decimal	0 to 1
min_skew / max_skew	decimal	0 to 1

Pricing + greeks:

Param	Type	Range
min_price / max_price	number	>= 0
min_iv_change / max_iv_change	decimal	E.g. 0.01 = +1% IV change
min_spread / max_spread	number	>= 0
min_size_vol_ratio / max_size_vol_ratio	number	>= 0

Earnings windows:

Param	Type	Notes
min_days_between_expiry_and_earnings	int	Negative = before earnings
max_days_between_expiry_and_earnings	int	Positive = after earnings

Pagination:

Param	Type	Notes
newer_than	unix or ISO	Time boundary
older_than	unix or ISO	Time boundary
limit	int	1-200, default 100

2.2 Response per alert (cluster of trades)

Field	Type	Description
alert_rule	string	Triggering rule name
all_opening_trades	bool	All transactions opening
created_at	ISO 8601	UTC timestamp
ticker	string	Underlying
issue_type	string	Asset type
type	string	call or put
expiry	date	Option expiry
expiry_count	int	Distinct expiries in cluster
strike	decimal	Strike price
option_chain	string	OCC symbol (single-chain alerts)
price	decimal	Underlying price
underlying_price	decimal	Current underlying
volume	int	Contract volume at alert
open_interest	int	Contract OI at alert
volume_oi_ratio	decimal	Vol / OI
trade_count	int	Trades in the cluster
total_size	int	Sum of trade sizes
total_premium	string	Combined $ premium
total_ask_side_prem	string	Ask-side $
total_bid_side_prem	string	Bid-side $
has_floor	bool	Cluster contains floor trades
has_sweep	bool	Cluster contains sweeps
has_singleleg	bool	Single-leg trades present
has_multileg	bool	Multi-leg trades present

2.3 MK3 use (L1 critical)

This is the pre-classified institutional-activity feed for L1. Two query patterns:

1. The SPY 0DTE filter (the primary feed):

GET /api/option-trades/flow-alerts?
  ticker_symbol=SPY&
  max_dte=0&
  min_premium=10000&
  is_sweep=true&
  vol_greater_oi=true

This catches today’s 0DTE SPY clusters with sweep + vol>OI + meaningful premium.

2. The mega-cap cluster filter (constituent context):

GET /api/option-trades/flow-alerts?
  ticker_symbol=AAPL,MSFT,NVDA,AMZN,META,GOOGL,GOOG&
  max_dte=2&
  min_premium=50000&
  rule_name[]=RepeatedHits&
  rule_name[]=SweepsFollowedByFloor

Catches mag7 unusual clusters near-term. Mag7 alerts here often precede SPY moves.

2.4 Important contrarian-flip interaction

Per 2026-05-22-uw-historical-findings: top-decile OTM call flow is CONTRARIAN-bearish for SPY (-3.6 to -8.7 lift). A flow_alert with is_otm=true, is_call=true, heavily ask-side - that’s exactly the pattern that historically fades. Setup Hunter must treat ask-side OTM call cluster alerts as fade candidates, not confirmation.

Sweep-followed-by-floor (SweepsFollowedByFloor) is the most high-conviction rule per UW’s classification - it indicates sequential institutional aggression. Worth distinguishing from purely-aggressive RepeatedHits.

3. GET /api/option-trades/flow-alerts/{id} - Single alert

Lookup one flow alert by ID.

Path: id = alert ID from the feed.

Response: the same record shape as #2. Useful for postmortem analysis (drilling into one alert from a stored ID).

4. GET /api/option-trades/full-tape/{date} - Every options trade

The full tape. Every option trade for the date.

Path: date (YYYY-MM-DD).

Response schema: UW’s docs leave this almost entirely undocumented (the example shows {}). First real fetch needs to catalog the actual response. Expected shape: very large array of per-trade records (trade_id, option_symbol, executed_at, price, size, premium, NBBO context, exchange, trade flags).

4.1 Critical warnings

• Data volume is extreme. US equity options market does ~50M trades/day. The full tape is gigabytes per day.
• No documented pagination - so either the endpoint streams, paginates implicitly, or returns a download URL. First real fetch needed to find out.
• No filter parameters documented - either nothing is supported, or the docs are simply incomplete.
• Rate limits unknown - polling this casually will likely hit a quota fast.

4.2 MK3 use (with extreme care)

Two viable patterns:

1. End-of-day archival. Pull /full-tape/YYYY-MM-DD once after close, write to local Parquet. This becomes the IMPULSE engine substrate going forward, addressing the data-foundation gap from 2026-05-15-mk3-data-foundation-constraint.

2. DO NOT use intraday. This is wrong tool for the live hot path. Use /option-contract/{id}/flow (uw-api-option-contract #4) for real-time per-contract data instead.

Treat this endpoint as a historical recording mechanism, not a live feed. Pair with the existing 1Y UW Parquet bundle on disk to extend the historical corpus forward.

5. Nautilus integration shape

Endpoint	Cadence	Custom data type
/flow-alerts	Every 30s	UWFlowAlert
/flow-alerts/{id}	On demand	UWFlowAlert
/full-tape/{date}	Once after close	Parquet archive, not bus traffic

The flow-alerts feed lives on the MessageBus. The full-tape is a filesystem archive: rolled into the Postgres-cached or catalog-mounted historical store, not streamed to subscribers.

6. Reference: flow-alert rules page

URL: https://unusualwhales.com/option-flow-alerts/rules

This page documents the semantic meaning of each alert_rule value. The API docs only enumerate names. A future fetch should pull the rules page and file a companion concept page (uw-flow-alert-rules.md) with per-rule detail (thresholds, detection logic, examples).

For now, treat the names as descriptive labels (e.g. “RepeatedHits = many trades clustering on one chain”, “Sweep = ISO across multiple exchanges”) and the source-of-truth is the rules page until we have a deeper file.

7. Known gaps

• Detailed rule definitions not in the API docs - fetch the rules page separately.
• Full-tape response schema undocumented - first fetch needs to catalog.
• Full-tape rate limits / pagination undocumented - tread carefully.
• tags field on individual trades (from option-contract /flow) has no published taxonomy.
• The contrarian-flip applies to flow-alerts cluster aggregator too - validated at ticker scope, but verify whether the same flip affects pre-classified clusters specifically.

8. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.flow_alerts
• https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.flow_alert
• https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.full_tape
• https://unusualwhales.com/option-flow-alerts/rules (rule definitions reference)

cortana-north-star uw-api-option-contract uw-api-gex-greeks uw-api-tide uw-api-net-flow 2026-05-15-mk3-data-foundation-constraint 2026-05-22-uw-historical-findings 2026-05-15-mk3-setup-hunter-architecture