Unusual Whales API - Lit Flow endpoints (LitFlowController)

Unusual Whales API - Lit Flow endpoints

Layer mapping: L1 (0DTE) load-bearing. “Lit” = publicly displayed order executions on regulated exchanges (NYSE, NASDAQ, etc.), as opposed to dark-pool / ATS trades in uw-api-darkpool. Together, lit-flow + dark-pool give the complete equity tape picture.

For the SPY hunter, lit-flow on SPY itself is the massive-volume firehose. Filter aggressively to block-sized trades; otherwise it’s intractable.

Two endpoints, same record shape, scoped to recent (cross-ticker) or per-ticker.

1. Base contract

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

2. Endpoint matrix

#	Path	Purpose
1	GET /api/lit-flow/recent	Cross-ticker recent lit prints (time-windowed)
2	GET /api/lit-flow/{ticker}	One-ticker lit prints with time windowing + filters

3. Common print schema (both endpoints)

Identical structure to uw-api-darkpool. Same fields, same types. The only difference is the venue - lit prints are on lit order books with NBBO context, dark prints are ATS.

Field	Type	Description
ticker	string	Symbol
price	decimal (string)	Execution price
size	int	Share quantity
premium	decimal (string)	Notional (price * size)
volume	int	Consolidated daily volume at print
executed_at	ISO 8601	Execution timestamp
market_center	string	Exchange code (Q=NASDAQ, N=NYSE, etc.)
nbbo_bid, nbbo_bid_quantity	string / int	NBBO bid + size at print
nbbo_ask, nbbo_ask_quantity	string / int	NBBO ask + size at print
trade_settlement	string	Settlement type
ext_hour_sold_codes	string / null	Extended-hours code
sale_cond_codes	string	Sale condition codes
trade_code	string / null	Trade classification
canceled	bool	Print canceled
tracking_id	int	Unique trade identifier

3.1 Market center codes (lit exchanges)

Code	Venue
N	NYSE
Q	NASDAQ
A	NYSE American
B	NASDAQ BX
C	NSX / National
J	EDGA
K	EDGX
P	NYSE Arca
X	NASDAQ PSX
Y	BYX
Z	BZX

Lit prints carry venue identity (you know which exchange the trade executed on). Useful for venue-specific analysis (e.g. “does NYSE auction print volume signal anything different than ARCA?“).

4. GET /api/lit-flow/recent - Cross-ticker feed

Time-windowed feed of recent lit prints across all tickers.

Query parameters (same as dark-pool /recent):

Param	Type	Required	Default	Range
limit	int	no	100	1 to 200
date	date	no	last trading date	-
min_premium	int	no	0	>= 0
max_premium	int	no	-	-
min_size	int	no	0	>= 0
max_size	int	no	-	-
min_volume	int	no	0	>= 0
max_volume	int	no	-	-

Recommended filters for L1: min_premium=1000000 (cuts noise to $1M+ prints across all tickers). Even then this is a high-throughput feed - cap with limit=200 per poll.

5. GET /api/lit-flow/{ticker} - Per ticker

Same record shape, scoped to one symbol. Higher limit ceiling.

Path parameter: ticker (e.g. SPY).

Query parameters (same as dark-pool /{ticker}):

Param	Type	Required	Default	Range
date	date	no	last trading date	-
newer_than	unix or ISO	no	-	-
older_than	unix or ISO	no	-	-
min_premium	int	no	0	>= 0
max_premium	int	no	-	-
min_size	int	no	0	>= 0
max_size	int	no	-	-
min_volume	int	no	0	>= 0
max_volume	int	no	-	-
limit	int	no	500	1 to 500

Volume warning. SPY lit-flow is extreme. Don’t poll without filters - default min_size >= 10000 (block trades) to keep it sane. Even that is hundreds of records per minute on SPY.

6. MK3 use (L1) - paired with dark-pool

The lit-flow + dark-pool comparison is the load-bearing pattern:

Question	Endpoint	Filter
What is the institutional tape doing now?	lit-flow + dark-pool, blocks only	min_size >= 10000
Is buying happening at the ask (lit aggression)?	lit-flow, derive sign from price vs nbbo_ask	-
Are blocks being placed off-exchange to avoid impact?	dark-pool count + premium at block size	min_size >= 10000
Lit/dark ratio for SPY	both endpoints, count + premium	min_premium >= 100000

Derived features (1-min rolls):

• spy_lit_block_count_1m, _premium_1m
• spy_dark_block_count_1m, _premium_1m
• spy_total_block_premium_1m (lit + dark)
• spy_aggressor_lit_buy_premium_1m (lit prints at ask side)
• spy_lit_to_dark_ratio_1m (low ratio = institutions hiding)

These features sit on the same bus as the GEX/Greek signals and feed into the Setup Hunter scoring. Equity-level aggressor signals LEAD intraday moves (unlike option-flow which is contrarian, per 2026-05-22-uw-historical-findings).

7. Nautilus integration shape

• Custom data class: UWLitFlowPrint (shared shape with UWDarkpoolPrint; consider a parent UWEquityPrint with a venue_type: {lit, dark} discriminator).
• Polling Actor: UWLitFlowActor polls /api/lit-flow/SPY?newer_than=...&min_size=10000 every 30s, de-dupes by tracking_id.
• Signal Actor: rolls lit + dark prints into combined 1-min features.

8. Known gaps / footguns

• Volume. SPY lit flow without size filter will blow the rate limit (whatever it is). Always filter.
• tracking_id collision with dark-pool? Almost certainly UW uses one global ID space, but verify on first fetch.
• No realtime push. Polling only.
• NBBO snapshot precision. nbbo_bid/nbbo_ask are at print time, not pre-trade. Tiny clock difference can flip the aggressor inference at the spread boundary - treat marginal cases as ambiguous.

9. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.LitFlowController.lit_flow_recent
• https://api.unusualwhales.com/docs/operations/PublicApi.LitFlowController.lit_flow_ticker

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