VRP Analytics API - Volatility Risk Premium Dashboard | FlashAlpha
  1. VRP Analytics

VRP Analytics API

Real-time Volatility Risk Premium dashboard - VRP spreads across windows, z-scores, directional VRP, GEX-conditioned regime analysis, strategy suitability scores, and dealer flow risk.

α Alpha+ Plan Required

These endpoints require the Alpha+ plan. View pricing →

New to VRP? The Practical Guide to Trading VRP covers z-scores, directional decomposition, GEX-conditioned regimes, and strategy selection.

Endpoint

GET /v1/vrp/{symbol}
Auth required (X-Api-Key) Rate Limited: Yes Plan: Alpha+

Parameters

Name In Type Required Default Description
symbol path string required - Underlying symbol (e.g. SPY, TSLA, AAPL)
date query date - Historical date (yyyy-MM-dd). Returns the persisted VRP snapshot for that date instead of the live dashboard; 404 if no snapshot exists. Invalid values return 400 invalid_date.
Works with CME futures. Pass ES=F or NQ=F and URL-encode the = as %3D - e.g. /v1/vrp/ES%3DF. Options-on-futures are priced with Black-76 using the CME multiplier ($50/pt ES, $20/pt NQ); CME futures are Growth plan. See the futures hub.

Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/vrp/SPY"
import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/vrp/SPY",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
resp.raise_for_status()
data = resp.json()
print(f"VRP 30d: {data['vrp']['vrp_30d']}%")
print(f"Z-score: {data['vrp']['z_score']}")
print(f"Regime: {data['regime']['gamma']}")
const resp = await fetch(
  "https://lab.flashalpha.com/v1/vrp/SPY",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();
console.log(`VRP 30d: ${data.vrp.vrp_30d}%`);
console.log(`Z-score: ${data.vrp.z_score}`);
console.log(`Regime: ${data.regime.gamma}`);

Try it live

Runs on live market data and uses 1 request from your daily quota.

GET

Response

{
  "symbol": "SPY",
  "underlying_price": 760.36,
  "as_of": "2026-10-30T13:46:36.3988673Z",
  "market_open": true,
  "vrp": {
    "atm_iv": 15.62,
    "rv_5d": 8.89,
    "rv_10d": 11.3,
    "rv_20d": 10.1,
    "rv_30d": 10.03,
    "vrp_5d": 6.73,
    "vrp_10d": 4.32,
    "vrp_20d": 5.52,
    "vrp_30d": 5.59,
    "z_score": 0.92,
    "percentile": 86,
    "history_days": 239
  },
  "variance_risk_premium": 0.014197,
  "convexity_premium": 4.18,
  "fair_vol": 19.8,
  "directional": {
    "put_wing_iv_25d": 18.66,
    "call_wing_iv_25d": 12.39,
    "downside_rv_20d": 7.28,
    "upside_rv_20d": 2.48,
    "downside_vrp": 11.38,
    "upside_vrp": 9.91
  },
  "term_vrp": [
    {
      "dte": 7,
      "iv": 14.47,
      "rv": 11.3,
      "vrp": 3.17
    },
    {
      "dte": 14,
      "iv": 15.04,
      "rv": 10.54,
      "vrp": 4.5
    }
  ],
  "gex_conditioned": {
    "regime": "negative_gamma",
    "harvest_score": 0.18,
    "interpretation": "Dealers short gamma - rich premium may reflect genuine tail risk."
  },
  "vanna_conditioned": {
    "outlook": "Mixed - vol compression fading",
    "interpretation": "Positive vanna but spot below flip: compression weakening. Reduced harvest confidence."
  },
  "regime": {
    "gamma": "negative_gamma",
    "vrp_regime": "toxic_short_vol",
    "net_gex": -15511562823,
    "gamma_flip": 769.0849,
    "gamma_flip_status": "available"
  },
  "strategy_scores": {
    "short_put_spread": 55,
    "short_strangle": 59,
    "iron_condor": 62,
    "calendar_spread": 28
  },
  "net_harvest_score": 51,
  "dealer_flow_risk": 42,
  "warnings": [
    "negative_gamma"
  ],
  "macro": {
    "vix": 17.2,
    "vix_3m": 19.37,
    "vix_term_slope": 1.1262,
    "dgs10": 5.05,
    "hy_spread": 3.14,
    "fed_funds": 3.75
  },
  "endpoint_version": "2026.09.30",
  "data_as_of": {
    "node": "fa5",
    "equity_feed": "2026-10-30T13:46:35.754Z",
    "equity_options_feed": "2026-10-30T13:46:34Z",
    "index_feed": "2026-10-30T13:46:35.112Z",
    "index_options_feed": "2026-10-30T13:46:34Z",
    "futures_feed": "2026-10-30T13:46:35.496Z",
    "futures_options_feed": "2026-10-30T13:46:30.458Z",
    "flow_feed": "2026-10-30T13:46:00Z",
    "oi_feed": "2026-10-29T20:00:00Z",
    "macro_feed": "2026-10-29T21:00:20Z"
  }
}

Sending request…

See this endpoint on live data

Send this exact request and the real response shows up here, right next to the example.

Response Fields

Field Type Description
symbolstringUnderlying symbol
underlying_pricenumberUnderlying price used for the calculation
as_ofstringTimestamp of the data (ISO 8601, UTC)
market_openbooleantrue during US market hours
vrpobjectATM IV, realized vol and VRP across 4 windows - see Fields of vrp below
variance_risk_premiumnumberVRP in variance space (IV^2 - RV^2), per Carr & Wu (2009) - see VRP
convexity_premiumnumberConvexity premium: fair vol (OI-weighted) minus ATM IV - positive = wings are rich
fair_volnumberFair vol: OI-weighted average IV across ±20% moneyness
directionalobjectPut-side vs call-side VRP - see directional VRP
directional.put_wing_iv_25dnumber25-delta put IV (%)
directional.call_wing_iv_25dnumber25-delta call IV (%)
directional.downside_rv_20dnumber20-day RV from negative returns only (downside semivariance)
directional.upside_rv_20dnumber20-day RV from positive returns only
directional.downside_vrpnumberPut-side VRP: put-wing IV minus downside RV
directional.upside_vrpnumberCall-side VRP: call-wing IV minus upside RV
term_vrparrayTerm VRP by expiry bucket (7, 14, 30, 60 DTE)
term_vrp[].dtenumberDays to expiry
term_vrp[].ivnumberATM IV for this tenor
term_vrp[].rvnumberTerm-matched realized vol
term_vrp[].vrpnumberVRP spread for this tenor
gex_conditionedobjectGEX-conditioned VRP read. Null when gamma flip or VRP inputs are unavailable.
gex_conditioned.regimestringpositive_gamma or negative_gamma when the block is available.
gex_conditioned.harvest_scorenumber0-1 harvestability score (higher = safer to sell premium)
gex_conditioned.interpretationstringHuman-readable regime interpretation for VRP context
vanna_conditionedobjectVanna-driven vol outlook. Null when gamma flip or required VRP inputs are unavailable.
vanna_conditioned.outlookstringVol compression/expansion outlook
vanna_conditioned.interpretationstringHow vanna flows affect premium selling
regimeobjectRegime
regime.gammastringGamma regime: positive_gamma, negative_gamma, or unknown when the flip is unavailable.
regime.vrp_regimestringharvestable, event_only, toxic_short_vol, cheap_convexity, or surface_distorted
regime.net_gexnumberNet gamma exposure ($)
regime.gamma_flipnumberPublished underlying-price boundary of aggregate repriced GEX; null when withheld.
regime.gamma_flip_statusstringavailable when the level is certified. A numeric gamma_flip with any of sensitive_root, uncertain_root_path, quality_budget, uncertain_gamma_variance, insufficient_local_coverage or insufficient_quote_quality is an unverified level: the root exists but failed that publication gate, and regime is unknown. Any other status means no supportable root and gamma_flip is null.
strategy_scoresobjectStrategy scores (0-100) per strategy
strategy_scores.short_put_spreadnumberShort put spread suitability; null without a published gamma flip.
strategy_scores.short_stranglenumberShort strangle suitability; null without a published gamma flip.
strategy_scores.iron_condornumberIron condor suitability; null without a published gamma flip.
strategy_scores.calendar_spreadnumberCalendar spread suitability
net_harvest_scorenumberHarvest score, 0-100 composite; null when gamma flip or required VRP inputs are unavailable. The screener exposes the same value as harvest_score; this is distinct from the 0-1 gex_conditioned.harvest_score sub-score.
dealer_flow_risknumberDealer flow risk score (0-100) - higher means more dealer hedging amplification risk
warningsarray of stringActive warning flags: event_risk, negative_gamma, poor_wing_liquidity, term_inversion, credit_stress, extreme_vrp
macroobjectMacro
macro.vixnumberVIX spot
macro.vix_3mnumberVIX3M (3-month VIX)
macro.vix_term_slopenumberVIX3M/VIX ratio (>1 = contango, <1 = backwardation)
macro.dgs10number10-Year Treasury yield
macro.hy_spreadnumberICE BofA High Yield OAS (credit stress indicator)
macro.fed_fundsnumberFederal Funds rate
endpoint_version, data_as_ofstring, objectResponse envelope, see Response envelope.

Fields of vrp

Field Type Description
vrp.atm_ivnumberATM implied volatility (%, from BSM on live options via Thetadata)
vrp.rv_5dnumberRealized volatility, 5-day window (%)
vrp.rv_10dnumberRealized volatility, 10-day window (%)
vrp.rv_20dnumberRealized volatility, 20-day window (%)
vrp.rv_30dnumberRealized volatility, 30-day window (%)
vrp.vrp_5dnumberATM IV minus 5-day RV (percentage points)
vrp.vrp_10dnumberATM IV minus 10-day RV (percentage points)
vrp.vrp_20dnumberATM IV minus 20-day RV (percentage points)
vrp.vrp_30dnumberATM IV minus 30-day RV (percentage points)
vrp.z_scorenumberVRP z-score of vrp_20d vs up to 252 trailing days of history (null if < 5 days history)
vrp.percentilenumberPercentile rank of current VRP (0-100, null if insufficient history)
vrp.history_daysnumberDays of VRP history available for the z-score / percentile

Errors

Status Error When
400invalid_datedate is not a valid yyyy-MM-dd date.
401-Missing or invalid X-Api-Key. The body is empty; check the status code before parsing JSON.
403tier_restrictedYour plan is below Alpha. The body includes current_plan and required_plan.
404symbol_not_foundNo data for the symbol (unknown symbol, or no live data). Outside US market hours the message also says the market is closed.
404no_snapshotNo persisted VRP snapshot for the symbol on date. Snapshot history starts in late March 2026.
429Quota exceededDaily quota used up. Retry-After gives the seconds until the reset at 00:00 UTC. Rejected requests (including 403) count toward the quota.

Use Cases

  • Time premium-selling entries - read the VRP z_score and percentile to fire short-vol structures only when the premium is statistically rich
  • Pick the richer side - compare upside vs downside VRP to decide whether to sell puts or calls and lean skew trades the right way
  • Gate on the gamma regime - pair the VRP spread with the GEX-conditioned regime to confirm whether dealers are suppressing or amplifying realized vol before sizing
  • Avoid trading into trapped risk - check the dealer risk level and warnings array to skip names where the premium reflects genuine event risk, not edge
  • Frame against macro - use the macro context (dgs10, hy_spread, fed_funds) to size short-vol exposure for the rate and credit backdrop
  • Seed your own history - archive daily /v1/vrp snapshots via cron to build a backtestable VRP time series, or read VRP History directly

Research

Related reading

Complementary endpoints

  • sell-window - whether to sell today at each expiry, plus suggested positions
  • VRP History - the daily VRP time series for charting and backtesting
  • Realized Volatility - the RV leg of the spread across windows
  • Volatility - IV, IV-RV spreads, skew, and term structure context
  • Expected Move - the straddle-implied move the premium is paying for

Ready to build with FlashAlpha?

Get your free API key and start pulling live options data in 60 seconds.

No credit card required Setup in 60 seconds Secure & reliable