Unusual Whales API - Ticker Positioning endpoints

Layer mapping: L1 LOAD-BEARING. Ten endpoints covering positional metrics: max pain, NOPE (Net Options Pricing Effect), OI by strike / expiry / change, full chains, options volume, premium tick stream, and price-level views.

This is the pinning + positioning substrate for the Setup Hunter. Together with uw-api-ticker-flow (the flow side) and uw-api-ticker-iv-greeks (the vol side), it forms the three-pillar per-ticker dataset.

1. Endpoint matrix

#	Path	Purpose
1	`GET /api/stock/{ticker}/max-pain`	Per-expiry max pain strike
2	`GET /api/stock/{ticker}/nope`	Net Options Pricing Effect (intraday)
3	`GET /api/stock/{ticker}/oi-change`	OI changes day-over-day, per contract
4	`GET /api/stock/{ticker}/oi-per-expiry`	OI rolled by expiry
5	`GET /api/stock/{ticker}/oi-per-strike`	OI rolled by strike
6	`GET /api/stock/{ticker}/option-chains`	Full option chain snapshot
7	`GET /api/stock/{ticker}/option-price-level`	Option price-level distribution
8	`GET /api/stock/{ticker}/vol-oi-per-expiry`	Volume + OI rolled by expiry
9	`GET /api/stock/{ticker}/options-volume`	Daily options volume history
10	`GET /api/stock/{ticker}/net-prem-ticks`	Net premium tick-by-tick stream

2. Base contract

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

3. `GET /api/stock/{ticker}/max-pain` (LOAD-BEARING)

Max pain strike per expiry.

Path: ticker.

Query parameters:

Param	Type	Required	Default
`date`	date	no	last trading date

Response:

{
  "data": [
    { "expiry": "2024-03-04", "max_pain": "473" },
    { "expiry": "2024-03-05", "max_pain": "475" }
  ],
  "date": "2024-03-04"
}

What is max pain. The strike at which option writers (dealers) lose the least if the underlying closes there at expiry. Computed from OI + strike + payoff math. Strong pinning candidate for 0DTE: SPY price has a documented tendency to drift toward max pain into the close, especially on low-flow days.

Use (L1, load-bearing for Setup Hunter):

spy_max_pain_strike_today (today’s 0DTE max pain)
spy_price_to_max_pain_distance = (underlying - max_pain) / max_pain
spy_max_pain_drift_setup = a named Setup Hunter setup that triggers when price is 0.3-0.8% above max pain in the last hour and tide is neutral or negative (dealer pinning regime).

Important caveat. Max pain is a pinning hypothesis, not a guarantee. On high-flow days (heavy directional aggression, sweep clusters, news events) the pinning force is overwhelmed and SPY runs through max pain. Set conditional gates - only use as a setup-trigger when complementary flow signals confirm pinning regime.

4. `GET /api/stock/{ticker}/nope`

Net Options Pricing Effect (intraday timeseries).

Path: ticker.

Query parameters:

Param	Type	Required	Default
`date`	date	no	most recent trading date

Response per timestamped row:

Field	Type	Description
`timestamp`	ISO 8601	Minute timestamp
`nope`	decimal	NOPE score (composite)
`nope_fill`	decimal	NOPE for filled orders only
`call_delta`	decimal	Aggregate call delta exposure
`call_fill_delta`	decimal	Filled call delta
`call_vol`	int	Call volume
`put_delta`	decimal	Aggregate put delta exposure
`put_fill_delta`	decimal	Filled put delta
`put_vol`	int	Put volume
`stock_vol`	int	Underlying stock volume

What is NOPE. A widely-watched 0DTE indicator that estimates the net delta-equivalent shares created by today’s options activity relative to stock volume. Conceptually: (call_delta - put_delta) / stock_volume, scaled. Designed for SPY 0DTE specifically.

Use (L1, load-bearing):

spy_nope_latest (newest minute’s value)
spy_nope_zscore_60m (z-score vs trailing 60-min mean)
spy_nope_sign_change_today (count of sign flips)

Directional reading.

High positive NOPE = heavy call-delta accumulation against modest stock volume = dealers short gamma; supports trend continuation.
High negative NOPE = heavy put-delta accumulation = dealers long gamma on the downside; supports mean-reversion or downside drift.
NOPE near zero = balanced positioning, no clear dealer hedge bias.

Caveat. Contrarian-aggressor sign-flip caveat applies again: the per-ticker findings showed top-decile OTM call flow is contrarian. NOPE aggregates that flow into a single number, so it inherits the same potential sign flip. Empirically validate before treating positive NOPE as bullish.

5. `GET /api/stock/{ticker}/oi-change`

OI change day-over-day, per contract (per-ticker filtered).

Distinct from uw-api-market /oi-change which is cross-market.

Path: ticker.

Query parameters (inferred): date, limit, order.

Response per record (likely same shape as the market-wide endpoint): option_symbol, curr_oi, last_oi, oi_change, oi_diff_plain, volume / quote context.

6. `GET /api/stock/{ticker}/oi-per-strike` (LOAD-BEARING)

OI rolled by strike for the ticker.

Path: ticker.

Query parameters (inferred): date, optionally expiry.

Response per row (inferred): strike, call_oi, put_oi, net_oi.

Use (L1, load-bearing): the OI-defined gamma walls. Strikes with the largest combined call_oi + put_oi are dealer hedging-magnet levels. Combined with uw-api-gex-greeks dealer positioning, this gives complete picture of dealer book structure.

Derived feature: spy_top_oi_strikes_today = list of 5 strikes with highest OI today. These are SPY’s pin levels + resistance/support candidates.

7. `GET /api/stock/{ticker}/oi-per-expiry`

OI rolled by expiry.

Use: which expiries carry the OI. 0DTE OI is typically tiny; weekly + monthly carry the bulk. Useful for understanding rollover dynamics.

8. `GET /api/stock/{ticker}/option-chains`

Full option chain snapshot.

Use: complete reference. For deep analysis. Probably too big to poll routinely - use uw-api-option-contract /option-contracts with filters for narrower queries.

9. `GET /api/stock/{ticker}/option-price-level`

Option price-level distribution.

Response (inferred): volume / open interest aggregated to price level bands.

Use: infrequent. Niche analytical view.

10. `GET /api/stock/{ticker}/vol-oi-per-expiry`

Volume + OI rolled by expiry.

Use: combined view of #4 and #7. Confirms whether high-OI expiries are also high-volume today (active rebalancing) or stale (slow positioning).

11. `GET /api/stock/{ticker}/options-volume`

Daily options volume history for the ticker.

Use: macro context. Pull 60 days at session start; flag today as high / low / normal volume regime.

12. `GET /api/stock/{ticker}/net-prem-ticks`

Net premium tick-by-tick stream (intraday).

Response per record (inferred): timestamp, net_premium, call_premium, put_premium.

Use: the highest-frequency net-premium view. Higher resolution than the per-minute uw-api-ticker-flow /flow-per-strike-intraday.

13. Cross-endpoint workflow for SPY hunter

Session start (08:00):
  -> GET /api/stock/SPY/max-pain                  (today + tomorrow expiries)
  -> GET /api/stock/SPY/oi-per-strike?date=T-1    (yesterday's positioning)
  -> GET /api/stock/SPY/oi-per-expiry?date=T-1
  -> GET /api/stock/SPY/oi-change?date=T-1        (overnight shifts)
  -> GET /api/stock/SPY/options-volume?limit=60   (60d volume context)

Intraday:
  -> GET /api/stock/SPY/nope?date=TODAY           (every minute)
  -> GET /api/stock/SPY/net-prem-ticks?date=TODAY (every minute)
  -> GET /api/stock/SPY/vol-oi-per-expiry?date=TODAY (every 5 min)

14. Setup Hunter named setups using this surface

Setup name	Trigger gates
`MaxPainPin`	Last hour, price within 0.3-0.8% of max pain, NOPE near zero, low flow
`GammaSqueeze`	NOPE > 95th percentile, dealer short gamma (from gex-greeks), price approaching call gamma wall
`Crash`	NOPE < 5th percentile, put OI spike, negative skew, dealer long gamma on downside

These are setup hypotheses per 2026-05-15-mk3-setup-hunter-architecture, not validated edges. Validate in the corpus before promoting.

15. Nautilus integration shape

Custom data classes per endpoint family.
Polling Actor: UWTickerPositioningActor.
High-frequency: NOPE + net-prem-ticks at 1-min.
Mid-frequency: max-pain + oi snapshots at 5-min.
Session-start: oi-per-strike, oi-per-expiry, options-volume.

16. Known gaps

Several inferred schemas - first fetches need to confirm.
NOPE methodology - UW doesn’t publish the exact composite formula. Treat as opaque score; track magnitude + sign, not absolute numbers.
Max pain computation methodology not specified - UW might use unweighted OI, premium-weighted, or with synthetic adjustments.
/option-chains full-chain endpoint is unpaginated in the docs - large responses possible.
Contrarian-flip caveat persists for NOPE specifically.

17. Source URLs

https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.max_pain
https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.nope
https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.oi_change
https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.oi_per_expiry
https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.oi_per_strike
https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.option_chains
https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.option_price_level
https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.vol_oi_per_expiry
https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.options_volume
https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.net_prem_ticks

cortana-north-star uw-api-gex-greeks uw-api-ticker-flow uw-api-ticker-iv-greeks uw-api-option-contract 2026-05-22-uw-historical-findings 2026-05-15-mk3-setup-hunter-architecture

CortanaROI Brain

Explorer

Unusual Whales API - Ticker Positioning endpoints (OI, max pain, NOPE, chains)

Unusual Whales API - Ticker Positioning endpoints

1. Endpoint matrix

2. Base contract

3. `GET /api/stock/{ticker}/max-pain` (LOAD-BEARING)

4. `GET /api/stock/{ticker}/nope`

5. `GET /api/stock/{ticker}/oi-change`

6. `GET /api/stock/{ticker}/oi-per-strike` (LOAD-BEARING)

7. `GET /api/stock/{ticker}/oi-per-expiry`

8. `GET /api/stock/{ticker}/option-chains`

9. `GET /api/stock/{ticker}/option-price-level`

10. `GET /api/stock/{ticker}/vol-oi-per-expiry`

11. `GET /api/stock/{ticker}/options-volume`

12. `GET /api/stock/{ticker}/net-prem-ticks`

13. Cross-endpoint workflow for SPY hunter

14. Setup Hunter named setups using this surface

15. Nautilus integration shape

16. Known gaps

17. Source URLs

Graph View

Table of Contents

Backlinks

CortanaROI Brain

Explorer

Unusual Whales API - Ticker Positioning endpoints (OI, max pain, NOPE, chains)

Unusual Whales API - Ticker Positioning endpoints

1. Endpoint matrix

2. Base contract

3. GET /api/stock/{ticker}/max-pain (LOAD-BEARING)

4. GET /api/stock/{ticker}/nope

5. GET /api/stock/{ticker}/oi-change

6. GET /api/stock/{ticker}/oi-per-strike (LOAD-BEARING)

7. GET /api/stock/{ticker}/oi-per-expiry

8. GET /api/stock/{ticker}/option-chains

9. GET /api/stock/{ticker}/option-price-level

10. GET /api/stock/{ticker}/vol-oi-per-expiry

11. GET /api/stock/{ticker}/options-volume

12. GET /api/stock/{ticker}/net-prem-ticks

13. Cross-endpoint workflow for SPY hunter

14. Setup Hunter named setups using this surface

15. Nautilus integration shape

16. Known gaps

17. Source URLs

Graph View

Table of Contents

Backlinks

3. `GET /api/stock/{ticker}/max-pain` (LOAD-BEARING)

4. `GET /api/stock/{ticker}/nope`

5. `GET /api/stock/{ticker}/oi-change`

6. `GET /api/stock/{ticker}/oi-per-strike` (LOAD-BEARING)

7. `GET /api/stock/{ticker}/oi-per-expiry`

8. `GET /api/stock/{ticker}/option-chains`

9. `GET /api/stock/{ticker}/option-price-level`

10. `GET /api/stock/{ticker}/vol-oi-per-expiry`

11. `GET /api/stock/{ticker}/options-volume`

12. `GET /api/stock/{ticker}/net-prem-ticks`