Unusual Whales API - Tide family (Market Tide + Sector Tide + ETF Tide)

Unusual Whales API - Tide family

Layer mapping: L1 (0DTE) load-bearing. User-flagged as IMPORTANT.

The “Tide” family is the flow-regime indicator hierarchy:

Scope	Endpoint	Path
Whole market	Market Tide	GET /api/market/market-tide
One GICS sector	Sector Tide	GET /api/market/{sector}/sector-tide
One ETF	ETF Tide	GET /api/market/{ticker}/etf-tide

All three return identical record shape at minute or 5-minute granularity: net_call_premium, net_put_premium, net_volume, timestamp. The difference is scope: market-wide, sector-aggregated, or ETF-specific.

For the SPY hunter, the load-bearing combination is:

• Market Tide = the macro flow regime (whole US options market)
• ETF Tide on SPY = SPY-specific flow
• Sector Tide on Technology + Sector Tide on Communication Services = top-weight-sector flow (combined ~37% of SPY)

1. Base contract

Property	Value
Base URL	https://api.unusualwhales.com
Auth	Authorization: Bearer <token> header
Response envelope	{ "data": [ ... ] }
Status codes	200, 422, 500
Numeric format	Strings (decimal), parse to float
Hours	RTH only (09:30 - 16:00 ET)
Rate limits	Not specified

2. Common record shape (all three endpoints)

Field	Type	Description
date	string (YYYY-MM-DD)	Trading date
timestamp	ISO 8601	Tick time with timezone offset
net_call_premium	decimal (string)	Call $ flow imbalance (signed)
net_put_premium	decimal (string)	Put $ flow imbalance (signed)
net_volume	integer	Total options volume in the bucket

Interpretation:

• net_call_premium > 0 and growing → bullish call accumulation
• net_put_premium > 0 and growing → bearish put accumulation
• Net = net_call_premium - net_put_premium gives a directional score
• net_volume is throughput, not direction

Critical caveat from 2026-05-22-uw-historical-findings: At the per-ticker level, OTM call-buying was contrarian-bearish (-3.6 to -8.7 lift). Whether the same flip applies at the tide level (which is broader aggregation) is untested in the corpus. Do not assume directional inference until verified. The sign of tide flow may simply be directional, OR may invert the same way ticker flow does. Empirical test required before fading bullish market tide.

3. GET /api/market/market-tide - Whole market

Query parameters:

Param	Type	Required	Default	Notes
date	date	no	last trading date
otm_only	bool	no	false	Restrict to OTM transactions
interval_5m	bool	no	true	5-min buckets; false for 1-min

Scope: entire US equity options market, all tickers aggregated.

Use in MK3 (L1): the macro flow context. Poll every 5 minutes (or 1 minute with interval_5m=false) during RTH.

Recommended derived features:

Feature	Definition
market_tide_net_premium_5m	net_call_premium - net_put_premium (latest bucket)
market_tide_net_premium_zscore_60m	z-score vs trailing 60-min mean
market_tide_otm_flow_sign	sign of net flow with otm_only=true
market_tide_regime	trending positive vs negative vs choppy

4. GET /api/market/{sector}/sector-tide - GICS sector

Path parameter:

Param	Required	Allowed values
sector	yes	Basic Materials, Communication Services, Consumer Cyclical, Consumer Defensive, Energy, Financial Services, Healthcare, Industrials, Real Estate, Technology, Utilities

Query parameters:

Param	Type	Required	Default
date	date	no	last trading date

Note: sector names have spaces - URL-encode (Communication%20Services).

SPY-relevant sectors (by current SPY weight):

Sector	SPY weight (approx)	Tide focus
Technology	~30%	Primary
Communication Services	~9%	Primary
Financial Services	~13%	Secondary
Healthcare	~13%	Secondary
Consumer Cyclical	~10%	Secondary
Consumer Defensive	~6%	Reference
All others (~19% combined)	reference	Skip

Use in MK3 (L1): sector-breadth feature. If Tech tide is heavily positive but Communication Services tide is heavily negative, SPY is being pulled in two directions; reduce conviction. If all four SPY-driving sectors point the same way, that’s a regime alignment signal.

5. GET /api/market/{ticker}/etf-tide - One ETF

Path parameter:

Param	Required	Notes
ticker	yes	Comma-separated; prefix first with - to exclude. E.g. SPY or SPY,QQQ or -SPY,QQQ.

Query parameters:

Param	Type	Required	Default
date	date	no	last trading date

Use in MK3 (L1): SPY-specific flow. Cleaner than market_tide because it isolates SPY’s own options book from the rest of the market.

Important pairing. Compare:

• etf-tide on SPY vs market-tide vs sector-tide on Technology

If SPY ETF tide is bullish but market tide is bearish, SPY is being relatively favored even in a weak market - high-conviction setup. If all three diverge, conviction is low; sit on hands.

6. Cross-endpoint workflow

RTH every 5 minutes:
  -> GET /api/market/market-tide
  -> GET /api/market/SPY/etf-tide
  -> GET /api/market/Technology/sector-tide
  -> GET /api/market/Communication%20Services/sector-tide

Derived features (per bucket):
  - market_tide_net_premium
  - spy_etf_tide_net_premium
  - tech_sector_tide_net_premium
  - comm_sector_tide_net_premium
  - spy_vs_market_relative_strength = spy_etf - market
  - sector_alignment_score = sign agreement across SPY-driving sectors

7. Nautilus integration shape

• Custom data class: UWTideSnapshot with a scope discriminator (market / sector:NAME / etf:TICKER).
• Polling Actor: UWTideActor polls all four (market + SPY etf + Tech sector + Comm sector) every 5 min in parallel.
• Publishes one snapshot per scope per bucket to the MessageBus.
• Signal Actor computes derived alignment / relative-strength features.

Per nautilus-custom-data determinism rules: ts_event from timestamp, ts_init from receive time. Numeric strings coerced.

8. Realtime upgrade path

The market_tide docs reference a WebSocket market tide stream. Not in this REST surface - flagged for future fetch (the WS docs URLs would let us avoid 5-min polling latency).

9. Known gaps / footguns

• otm_only=true is only on market_tide. Sector and ETF tide don’t have the flag. If you want OTM-only at sector or ETF scope, fall back to per-ticker uw-api-gex-greeks family 2 or uw-api-group-flow.
• Sector names are GICS-style with spaces - always URL-encode.
• Contrarian-flip applicability at tide scope is UNTESTED. This is the most important open empirical question. Do not assume.
• No volume breakout by direction - net_volume is total bucket volume, not “directional volume”. For directional volume, derive from net_call_premium sign + volume.

10. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.market_tide
• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.sec_indst (sector tide, despite the name)
• https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.etf_tide

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