Unusual Whales API - Net Flow endpoint (NetFlowController)

Unusual Whales API - Net Flow endpoint

Layer mapping: L1 load-bearing. Single endpoint with a expiration=zero_dte filter - the most directly named feed for the 0DTE SPY hunter. Returns cross-market net flow groups organized by expiry.

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/net-flow/expiry

Cross-market net flow data grouped by expiry, with rich filters.

Query parameters:

Param	Type	Required	Default	Allowed values
date	date	no	last trading date	-
moneyness	array	no	[all]	all, itm, otm, atm
tide_type	array	no	[all]	all, equity_only, etf_only, index_only
expiration	array	no	[weekly, zero_dte]	weekly, zero_dte

Response (top-level):

Field	Type	Description
date	string	Trading date
expiration	array	Applied expiration filters
moneyness	array	Applied moneyness filters
tide_type	array	Applied tide_type filters
data	array	Net flow group records

Per-group record (inferred shape - first real fetch needs to verify): likely includes expiration_class, moneyness_class, tide_type_class, plus tide-style fields (net_call_premium, net_put_premium, net_volume, timestamp).

3. The 0DTE-specific call

For the SPY hunter:

GET /api/net-flow/expiry?
  expiration[]=zero_dte&
  moneyness[]=otm&
  tide_type[]=index_only&
  tide_type[]=etf_only

Translation: “give me the 0DTE OTM net flow on index + ETF products”. This is the most directly relevant slice of the entire UW API for 0DTE SPY work.

Compare with weekly to see the relative pull (0DTE vs near-week) of dealer hedging.

4. MK3 use (L1)

Poll every minute during RTH.

Derived features:

Feature	Definition
zero_dte_otm_etf_net_premium_1m	Latest bucket value
zero_dte_otm_etf_net_premium_zscore_60m	z-score vs trailing 60m
zero_dte_vs_weekly_dominance	(0DTE net_premium) / (weekly net_premium) - high = 0DTE-driven tape
itm_vs_otm_concentration	(itm net_premium) / (otm net_premium) at zero_dte - high = informed money
etf_only_vs_equity_only	direct macro vs single-name flow split

Contrarian-flip caveat. Same as the uw-api-tide family: the 2026-05-22-uw-historical-findings OTM-contrarian finding was at the per-ticker level. Whether it extends to aggregated cross-market flows at zero_dte scope is untested. Empirical test required before treating bullish zero_dte OTM ETF flow as a fade signal.

5. Nautilus integration shape

• Custom data class: UWNetFlowExpiryGroup with discriminator on (expiration, moneyness, tide_type).
• Polling Actor: UWNetFlowActor polls the four combinations of interest every minute:
  1. expiration=zero_dte, moneyness=otm, tide_type=etf_only
  2. expiration=zero_dte, moneyness=otm, tide_type=index_only
  3. expiration=weekly, moneyness=otm, tide_type=etf_only
  4. expiration=zero_dte, moneyness=itm, tide_type=etf_only
• Each combination publishes its own snapshot stream.

6. Comparison to neighboring endpoints

Endpoint	Scope	What it adds
uw-api-tide market_tide	Whole-market	Single aggregate, no expiry split
uw-api-tide etf_tide on SPY	SPY only	SPY-specific, no expiry split
uw-api-net-flow/expiry	Cross-market with expiry + moneyness + class filters	0DTE-specific OTM ETF/index slice
uw-api-gex-greeks family 2	Per-ticker option flow	Per-ticker, can pick expiry, no cross-market aggregation
uw-api-group-flow	Sector / mag7 aggregation	Sector-rolled, not expiry-rolled

The unique value of net-flow/expiry is the multi-filter expiry slice - none of the other endpoints offer the zero_dte cut at a cross-market scope.

7. Known gaps

• Per-group response shape is partly inferred. First real fetch should confirm field names and types.
• tide_type allowed values overlap with sector_tide GICS sectors on naming but the semantics differ (this is asset-class filtering: equity vs ETF vs index). Don’t confuse them.
• No weekly definition. Is “weekly” 1-7 DTE? 1-14 DTE? Verify.
• No realtime push. Polling only.

8. Source URL

• https://api.unusualwhales.com/docs/operations/PublicApi.NetFlowController.expiry

cortana-north-star uw-api-tide uw-api-gex-greeks uw-api-group-flow 2026-05-22-uw-historical-findings 2026-05-15-mk3-setup-hunter-architecture