Volatility Analysis API

Endpoint

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/volatility/TSLA"

import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/volatility/TSLA",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = resp.json()
print(f"ATM IV: {data['atm_iv']:.1f}%")
print(f"RV 20D: {data['realized_vol']['rv_20d']:.1f}%")
print(f"VRP Assessment: {data['iv_rv_spreads']['assessment']}")

const resp = await fetch(
  "https://lab.flashalpha.com/v1/volatility/TSLA",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log(`ATM IV: ${data.atm_iv.toFixed(1)}%`);
console.log(`RV 20D: ${data.realized_vol.rv_20d.toFixed(1)}%`);
console.log(`Assessment: ${data.iv_rv_spreads.assessment}`);

Response

{
  "symbol": "TSLA",
  "underlying_price": 265.50,
  "as_of": "2026-03-09T15:30:00Z",
  "market_open": true,
  "realized_vol": {
    "rv_5d": 52.31, "rv_10d": 48.12, "rv_20d": 45.80,
    "rv_30d": 44.20, "rv_60d": 42.15
  },
  "atm_iv": 48.50,
  "iv_rv_spreads": {
    "vrp_5d": -3.81, "vrp_10d": 0.38, "vrp_20d": 2.70,
    "vrp_30d": 4.30, "vrp_60d": 6.35,
    "assessment": "moderate_premium"
  },
  "skew_profiles": [
    {
      "expiry": "2026-03-14", "days_to_expiry": 5,
      "put_10d_iv": 62.50, "put_25d_iv": 54.20,
      "atm_iv": 48.50, "call_25d_iv": 45.10, "call_10d_iv": 43.80,
      "skew_25d": 9.10, "smile_ratio": 1.202, "tail_convexity": 2.60
    }
  ],
  "term_structure": {
    "near_slope_pct": 5.20, "far_slope_pct": 3.10, "state": "contango"
  },
  "iv_dispersion": { "cross_expiry": 3.45, "cross_strike": 12.80 },
  "gex_by_dte": [
    { "bucket": "0-7d", "net_gex": 1200000, "pct_of_total": 35.2, "contract_count": 450 },
    { "bucket": "8-30d", "net_gex": 800000, "pct_of_total": 23.5, "contract_count": 1200 },
    { "bucket": "31-60d", "net_gex": 950000, "pct_of_total": 27.9, "contract_count": 800 },
    { "bucket": "60d+", "net_gex": 460000, "pct_of_total": 13.4, "contract_count": 600 }
  ],
  "theta_by_dte": [
    { "bucket": "0-7d", "net_theta": -450000, "contract_count": 450 },
    { "bucket": "8-30d", "net_theta": -320000, "contract_count": 1200 }
  ],
  "put_call_profile": {
    "by_expiry": [
      { "expiry": "2026-03-14", "call_oi": 120000, "put_oi": 95000,
        "pc_ratio_oi": 0.792, "call_volume": 45000, "put_volume": 38000, "pc_ratio_volume": 0.844 }
    ],
    "by_moneyness": {
      "otm_call_oi": 85000, "atm_call_oi": 25000, "itm_call_oi": 10000,
      "otm_put_oi": 60000, "atm_put_oi": 20000, "itm_put_oi": 15000
    }
  },
  "oi_concentration": {
    "top_3_pct": 18.5, "top_5_pct": 28.2, "top_10_pct": 45.0, "herfindahl": 0.032
  },
  "hedging_scenarios": [
    { "move_pct": -5, "dealer_shares": 850000, "direction": "buy", "notional_usd": 225575000 },
    { "move_pct": -2, "dealer_shares": 340000, "direction": "buy", "notional_usd": 90230000 },
    { "move_pct": -1, "dealer_shares": 170000, "direction": "buy", "notional_usd": 45115000 },
    { "move_pct": 1, "dealer_shares": -170000, "direction": "sell", "notional_usd": 45115000 },
    { "move_pct": 2, "dealer_shares": -340000, "direction": "sell", "notional_usd": 90230000 },
    { "move_pct": 5, "dealer_shares": -850000, "direction": "sell", "notional_usd": 225575000 }
  ],
  "liquidity": {
    "atm_avg_spread_pct": 1.85, "wing_avg_spread_pct": 45.20,
    "atm_contracts": 120, "wing_contracts": 340
  }
}

Response Fields

Notes

• Realized vol uses close-to-close log-returns with sample standard deviation (N-1), annualized by √252.
• Skew profiles use delta-to-moneyness approximation: k = ±σ√t × Φ¹(δ). 25-delta uses 0.6745, 10-delta uses 1.2816.
• Tail convexity measures the second difference of the skew. Positive values indicate steep left-wing curvature (crash protection being bid).
• GEX by DTE uses the SpotGamma convention: gamma × OI × 100 × spot² × 0.01.
• Herfindahl index ranges from 1/N (perfectly even) to 1.0 (all OI at one strike). Values above 0.10 suggest high concentration.
• Hedging scenarios assume dealers are net short options. Positive GEX + upward move = dealers sell shares.

What Is the Volatility Analysis Endpoint?

The /v1/volatility/{symbol} endpoint returns a deep volatility profile for any US equity or ETF. It covers realized volatility across 5 windows (5d, 10d, 20d, 30d, 60d), IV-RV spread assessments, delta-based skew profiles per expiry, IV term structure analysis, gamma exposure bucketed by days to expiry, theta decay by DTE, put/call breakdowns by expiry and moneyness, OI concentration metrics (Herfindahl index), multi-move dealer hedging scenarios (±1%, ±2%, ±5%), and options liquidity analysis.

Common Use Cases

• Spot rich or cheap vol - compare realized vol across the 5d/10d/20d/30d/60d windows to ATM IV and trade the IV-RV spread when the regime is stretched
• Price tail risk from skew - read the 10-delta and 25-delta skew profiles per expiry to gauge crash-protection demand before selling puts or buying wings
• Pick the right expiry - use GEX and theta bucketed by DTE to select tenors for calendars, wheels, or diagonals
• Stress dealer hedging - read the multi-move scenarios (±1%, ±2%, ±5%) to anticipate hedging flow into a move
• Budget execution cost - compare ATM vs wing bid-ask spreads from the liquidity block before committing size
• Flag pin and clustering risk - use the OI Herfindahl index and top-strike percentages to spot concentration that drives pinning into expiry
• Trade the term structure - read IV term-structure slope (contango vs backwardation) to time calendar spreads and front-month sales

Related

Related reading

• Implied volatility API: real-time IV at every strike - how IV is sourced per strike and expiry feeding this profile
• Build, visualize & trade the IV surface - turn skew and term structure into a tradeable surface view

Complementary endpoints

• Advanced Volatility (SVI) - arbitrage-free SVI surface, variance, and greeks surfaces
• VRP - the IV-RV spread distilled into a tradeable premium signal
• Skew Term Structure - skew and term structure isolated across expiries
• SVI Parameters - raw SVI coefficients for your own surface models