CortanaROI Brain

Unusual Whales API - Ticker IV + Greeks endpoints

4 min read

Unusual Whales API - Ticker IV + Greeks endpoints

Layer mapping: L1 LOAD-BEARING. Eight endpoints under TickerController covering implied volatility (term structure, percentile rank, surface interpolation), realized volatility, skew, and aggregate ticker-level Greeks. This is the volatility regime substrate for the Setup Hunter.

Different from uw-api-gex-greeks (which covers per-strike GEX / dealer-positioning Greeks). This page covers ticker-level aggregations + IV measures.

1. Endpoint matrix

#PathPurpose
1GET /api/stock/{ticker}/greeksTicker-level aggregate Greeks
2GET /api/stock/{ticker}/realized-volatilityHistorical realized vol (RV)
3GET /api/stock/{ticker}/volatility/statsVol summary stats (HV, IV, ranks)
4GET /api/stock/{ticker}/volatility/term-structureIV term structure (per DTE bucket)
5GET /api/stock/{ticker}/interpolated-ivInterpolated IV surface
6GET /api/stock/{ticker}/iv-rankIV percentile rank (e.g. 0-100)
7GET /api/stock/{ticker}/historical-risk-reversal-skew25-delta R/R skew time series
8GET /api/stock/{ticker}/atm-chainsATM contracts snapshot

2. Base contract

PropertyValue
Base URLhttps://api.unusualwhales.com
AuthAuthorization: Bearer <token> header
Response envelope{ "data": [...] } or { "data": {...} }
Status codes200, 422, 500

3. GET /api/stock/{ticker}/greeks - Ticker aggregate Greeks

Aggregate Greeks at the ticker level (summed across the chain).

Path: ticker.

Query parameters (inferred): date, possibly expiry.

Response (inferred): per-row daily aggregate delta, gamma, theta, vega, rho across all contracts.

Use: complement to uw-api-gex-greeks. This endpoint gives total exposure; gex-greeks gives the dealer-positioning view broken by strike/expiry.

4. GET /api/stock/{ticker}/realized-volatility

Historical realized vol (RV) time series.

Query parameters (inferred): interval (likely 10d, 30d, 60d, 90d), date_from, date_to.

Response (inferred): per-row date, realized_volatility (annualized).

Use (L1): RV is the “actual” volatility experienced. Pair with IV to compute the IV-RV spread (vol_premium), a key vol-trading feature. high IV / low RV = expensive options, fade vol; low IV / high RV = cheap options, buy vol.

5. GET /api/stock/{ticker}/volatility/stats - Vol summary

Volatility summary statistics.

Path: ticker.

Response (inferred): one record with realized_vol_10d, realized_vol_30d, iv_30d, iv_60d, iv_rank, iv_percentile, historical extremes.

Use (L1): session-start snapshot. One call, full vol context.

6. GET /api/stock/{ticker}/volatility/term-structure (LOAD-BEARING)

IV term structure: per-DTE-bucket IV.

Path: ticker.

Response per row (inferred): dte, iv (or atm_iv), expiry.

Use (L1): the canonical term-structure shape:

ShapeInterpretation
Backwardation (front IV > back IV)Near-term event premium; 0DTE IV will collapse post-event
Contango (back IV > front IV)Normal regime
Steep front-end backwardationMajor catalyst (FOMC, earnings, geopolitical) priced in

Derived feature: spy_iv_term_structure_slope = (iv[0dte] - iv[30dte]) / iv[30dte]. Sharp positive value = event regime.

7. GET /api/stock/{ticker}/interpolated-iv

Interpolated IV surface.

Path: ticker.

Query parameters (inferred): expiry, delta or strike.

Response (inferred): IV at a specific (expiry, strike-or-delta) point, interpolated from the actual chain.

Use: when you need IV at a strike that doesn’t exist in the chain (e.g. for path-dependent calculations). For Setup Hunter, lower priority than the term-structure endpoint.

8. GET /api/stock/{ticker}/iv-rank

IV percentile rank (typically 0-100).

Path: ticker.

Response (inferred): one number, iv_rank (current IV’s percentile vs trailing 1-year history).

Use (L1): dimensionless vol regime indicator. iv_rank > 80 = extreme high vol regime; < 20 = extreme low vol. Setup Hunter sizing scales inversely to iv_rank.

9. GET /api/stock/{ticker}/historical-risk-reversal-skew

25-delta risk-reversal skew time series.

Path: ticker.

Response per row (inferred): date, rr_25d (call IV - put IV at 25-delta), per expiry bucket.

Use (L1): skew is the directional vol bias. Positive skew (call IV > put IV at 25-delta) = call buyers driving the smile - bullish hedging pressure. Negative skew = put demand dominant - bearish hedging pressure.

Important sign discipline. Risk-reversal skew is a flow indicator at the IV level, and the same contrarian-aggressor caveat from 2026-05-22-uw-historical-findings may apply. Untested at skew scope. Verify before fading.

10. GET /api/stock/{ticker}/atm-chains

Snapshot of ATM option contracts.

Path: ticker.

Query parameters (inferred): expiry (single or array).

Response per record (inferred): ATM strike contracts with current quote, IV, volume, OI per expiry.

Use: quick ATM context. For SPY at 580: this endpoint returns the 580 call and put (or 579/581 if 580 doesn’t exist).

11. Cross-endpoint workflow for SPY hunter

Session start (08:00):
  -> GET /api/stock/SPY/volatility/stats          (full vol snapshot)
  -> GET /api/stock/SPY/iv-rank                    (regime indicator)
  -> GET /api/stock/SPY/volatility/term-structure  (event-day check)
  -> GET /api/stock/SPY/realized-volatility?interval=10d
  -> GET /api/stock/SPY/historical-risk-reversal-skew?expiry=TODAY

Intraday (every 5 min):
  -> GET /api/stock/SPY/atm-chains?expiry=TODAY    (ATM 0DTE snapshot)
  -> GET /api/stock/SPY/greeks                     (aggregate Greek context)

Derived features cached for the session:
  - spy_iv_rank (regime gate)
  - spy_iv_rv_spread_10d (vol-premium check)
  - spy_term_structure_slope (event-day indicator)
  - spy_rr_skew_today (directional vol bias)

12. Nautilus integration shape

  • Custom data classes (one per endpoint family):
    • UWVolatilityStats (session-start one-shot)
    • UWIVTermStructure (session-start one-shot + refresh on event days)
    • UWHistoricalSkew (session-start one-shot)
    • UWAtmChainSnapshot (5-min cadence)
    • UWTickerGreeks (5-min cadence)
  • Polling Actor: UWVolatilityActor.

13. Known gaps

  • Several response schemas are inferred. First real fetch should catalog. Particularly:
    • /greeks exact field names
    • /volatility/stats full field set
    • /volatility/term-structure row shape
    • /interpolated-iv query semantics
    • /iv-rank lookback window definition
  • Contrarian-flip applicability at IV / skew scope is untested. Same caveat as tide / group-flow.

14. Source URLs

  • https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.greeks
  • https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.realized_volatility
  • https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.volatility_stats
  • https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.implied_volatility_term_structure
  • https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.interpolated_iv
  • https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.iv_rank
  • https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.historical_risk_reversal_skew
  • https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.atm_chains

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

Graph View

Backlinks