Unusual Whales API - Market endpoints (MarketController, non-Tide)

Unusual Whales API - Market endpoints (non-Tide)

The MarketController surfaces the Tide family (uw-api-tide) plus eight more endpoints that don’t fit cleanly into the flow-regime shape. This page documents those eight, organized by L1 use and L3 filing.

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. Endpoint matrix

#	Path	Purpose	Layer
1	GET /api/market/top-net-impact	Ranked tickers by net call-put premium	L1 (load-bearing)
2	GET /api/market/economic-calendar	Forward macro release calendar	L1 (calendar gate)
3	GET /api/market/correlations	Pairwise correlations among supplied tickers	L1 (regime check)
4	GET /api/market/oi-change	Top market-wide OI changes per option contract	L1 (positioning shifts)
5	GET /api/market/total-options-volume	Market-wide aggregate call/put volume history	L1 (macro context)
6	GET /api/market/sector-etfs	Sector-to-ETF map with current metrics	L1 (reference)
7	GET /api/market/fda-calendar	Forward FDA drug approval dates	L3
8	GET /api/market/insider-buy-sells	Market-wide insider buy/sell aggregate	L3

3. GET /api/market/top-net-impact - L1 load-bearing

Ranked tickers by net_premium = net_call_premium - net_put_premium.

Query parameters:

Param	Type	Required	Default	Range
date	date	no	last trading date	-
issue_types[]	array	no	all	Common Stock, ETF, Index, ADR
limit	int	no	20	1 to 100

Response per record:

{ "ticker": "SPY", "net_premium": 2500000.0 }

Sorted by net_premium descending. Negative impacts (net puts) at the bottom.

Use in MK3 (L1): find the tickers driving today’s tape. Compare the top-10 from this endpoint with SPY’s top-25 weights (from uw-api-etfs /holdings). If 4+ of SPY’s top-25 are in the top-10 net-impact, SPY’s flow is being driven by alignment of its biggest constituents - high-conviction direction. If the top-10 net-impact is dominated by names not in SPY’s top-25, SPY may be along for the ride passively.

Pair with issue_types=[ETF] to get the top ETF-level flow movers (SPY, QQQ, IWM, sectors).

4. GET /api/market/economic-calendar - L1 calendar gate

The forward macro release calendar flagged as missing in uw-api-economy. The /api/economy/{indicator} endpoint gives historical series only; THIS endpoint gives the forward dates.

No documented parameters (might support date_from / date_to on a real fetch).

Response per event:

Field	Type	Description
event	string	E.g. "Consumer sentiment (final)", "PCE index"
time	ISO 8601 (UTC)	Event time
forecast	string / null	Consensus expectation
prev	string	Previous reading
reported_period	string	Reference period (e.g. "December")
type	string	E.g. "report"

Use in MK3 (L1): the day-selection gate. Pull at session start. For 0DTE SPY:

• CPI / PPI / NFP / unemployment / retail-sales prints at 08:30 ET bias L1 to flat-into-print or different sizing.
• FOMC at 14:00 ET = full L1 flat-pre + small-size-post regime.
• Empty calendar = normal L1 cadence.

Combine with uw-api-alerts noti_type=economic_release for real-time confirmation that the print actually dropped.

5. GET /api/market/correlations - L1 regime check

Pairwise correlations between supplied tickers over a timeframe.

Query parameters:

Param	Type	Required	Default	Notes
tickers	string	yes	-	Comma-separated; - prefix to exclude
interval	string	no	1Y	YTD, 1D-2D, 1W-2W, 1M-2M, 1Y-2Y
start_date	date	no	-	Overrides interval
end_date	date	no	today	Used with start_date

Response per pair:

Field	Type	Description
fst	string	First ticker
snd	string	Second ticker
correlation	number	Pearson coefficient (-1 to 1)
min_date	ISO date	Range start
max_date	ISO date	Range end
rows	int	Data points used

For N tickers, returns N*(N-1)/2 pairs (upper triangle).

Use in MK3 (L1): session-start regime check. Pull rolling 1M correlations of SPY’s top-7 mag-cap constituents (AAPL, MSFT, NVDA, AMZN, META, GOOGL, GOOG). Average pairwise correlation is the dispersion regime feature - high (close to 1) = mega-caps move together = SPY drives off them; low = internal rotation = SPY moves are smoothed by dispersion. Different setups in each regime.

6. GET /api/market/oi-change - L1 positioning shifts

Top market-wide OI changes per option contract day-over-day.

Query parameters:

Param	Type	Required	Default	Range
date	date	no	last trading date	-
limit	int	no	100	1 to 200
order	enum	no	desc	desc or asc

Response per record (key fields):

Field	Type	Description
option_symbol	string	OCC option symbol
underlying_symbol	string	Underlying equity
curr_oi / last_oi	int	Today’s vs prior OI
oi_change	decimal	% change
oi_diff_plain	int	Absolute change
avg_price, volume, trades	decimal/int	Today’s activity
last_bid, last_ask, last_fill	decimal	Last day’s quotes
prev_*_volume (bid/ask/mid/neutral/multi_leg/stock_multi_leg)	int	Prior-day volume breakdown
prev_total_premium	decimal	Prior total premium
percentage_of_total	decimal	Share of total market OI changes
rnk	int	Ranking position

Use in MK3 (L1): at session start, pull limit=100 for the prior trading day. Filter to SPY’s underlying option symbols. Build a “yesterday’s positioning shift” snapshot - which SPY strikes saw the biggest OI change overnight. These are the strikes dealers and institutions are newly leaning on / unwinding.

Combine with uw-api-gex-greeks /greek-exposure/strike to confirm where today’s gamma walls sit relative to yesterday’s OI shifts.

7. GET /api/market/total-options-volume - L1 macro context

Market-wide aggregate call/put volume + premium time series, daily.

Query parameters:

Param	Type	Required	Default	Range
limit	int	no	1	1 to 500

Response per record:

Field	Type	Description
date	date	Trading date
call_volume	int	Market-wide call volume
put_volume	int	Market-wide put volume
call_premium	decimal	Total call $ premium
put_premium	decimal	Total put $ premium

Use in MK3 (L1): macro environment indicator. Pull limit=60 at session start for 60-day history. Features:

• total_options_volume_60d_pct_today - is today running hot or light?
• pcr_volume_60d - put/call volume ratio rolling 60d (regime fingerprint)
• total_call_premium_zscore - z-score of today vs trailing N days

Low-volume days = low conviction in any direction = Setup Hunter should require higher conviction to fire.

8. GET /api/market/sector-etfs - L1 reference

Maps each US sector to its representative ETF with current metrics.

No documented parameters.

Response per sector ETF:

Field	Type	Description
ticker	string	ETF ticker (XLK, XLC, XLF, …)
full_name	string	Sector name
open, high, low, close, prev_close	decimal	Today’s OHLC
volume, avg30_stock_volume	int	Today’s + 30d avg volume
week_52_high, week_52_low	decimal	52-week range
call_volume, put_volume	int	Today’s option volumes
call_premium, put_premium	decimal	Today’s option premium
bullish_premium, bearish_premium	decimal	UW-classified directional
avg_30_day_call_volume, avg_30_day_put_volume	int	30d avg
avg_7_day_call_volume, avg_7_day_put_volume	int	7d avg
marketcap	decimal	AUM

Standard sector ETF mapping:

Sector	ETF
Technology	XLK
Communication Services	XLC
Financial Services	XLF
Healthcare	XLV
Consumer Cyclical	XLY
Consumer Defensive	XLP
Industrials	XLI
Energy	XLE
Utilities	XLU
Real Estate	XLRE
Basic Materials	XLB

Use in MK3 (L1): session-start reference. Cache the mapping once; use it to drive etf-tide lookups on XLK + XLC (the two sector ETFs that proxy ~39% of SPY by weight).

9. GET /api/market/fda-calendar - L3

Forward FDA drug approval / advisory committee dates.

L3 only. Per-biotech catalyst calendar. Not in MK3 scope.

10. GET /api/market/insider-buy-sells - L3

Market-wide aggregate insider buy/sell activity over time.

L3 only. Macro-level insider sentiment. Per uw-api-insiders the per-ticker / per-sector versions are also L3. Filed for L3 trend strategies, not in MK3 scope.

11. Nautilus integration shape (L1 endpoints only)

Endpoint	Cadence	Custom data type
/top-net-impact	Every 5 min RTH	UWTopNetImpact snapshot
/economic-calendar	Session start + after every release	UWEconomicCalendar snapshot
/correlations	Session start	UWCorrelationMatrix snapshot
/oi-change	Session start	UWOiChangeSnapshot
/total-options-volume	Session start	UWTotalVolumeHistory
/sector-etfs	Session start (refresh on price moves)	UWSectorETFs snapshot

12. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.top_net_impact
• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.events (economic-calendar)
• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.correlations
• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.oi_change
• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.total_options_volume
• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.sector_etfs
• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.fda_calendar
• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.insider_buy_sells

cortana-north-star uw-api-tide uw-api-gex-greeks uw-api-etfs uw-api-economy uw-api-net-flow 2026-05-15-mk3-setup-hunter-architecture