- Live API Reference
- Volatility Analytics
- 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.
These endpoints require the Alpha+ plan. View pricing →
Endpoint
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. |
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.
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 |
|---|---|---|
symbol | string | Underlying symbol |
underlying_price | number | Underlying price used for the calculation |
as_of | string | Timestamp of the data (ISO 8601, UTC) |
market_open | boolean | true during US market hours |
vrp | object | ATM IV, realized vol and VRP across 4 windows - see Fields of vrp below |
variance_risk_premium | number | VRP in variance space (IV^2 - RV^2), per Carr & Wu (2009) - see VRP |
convexity_premium | number | Convexity premium: fair vol (OI-weighted) minus ATM IV - positive = wings are rich |
fair_vol | number | Fair vol: OI-weighted average IV across ±20% moneyness |
directional | object | Put-side vs call-side VRP - see directional VRP |
directional.put_wing_iv_25d | number | 25-delta put IV (%) |
directional.call_wing_iv_25d | number | 25-delta call IV (%) |
directional.downside_rv_20d | number | 20-day RV from negative returns only (downside semivariance) |
directional.upside_rv_20d | number | 20-day RV from positive returns only |
directional.downside_vrp | number | Put-side VRP: put-wing IV minus downside RV |
directional.upside_vrp | number | Call-side VRP: call-wing IV minus upside RV |
term_vrp | array | Term VRP by expiry bucket (7, 14, 30, 60 DTE) |
term_vrp[].dte | number | Days to expiry |
term_vrp[].iv | number | ATM IV for this tenor |
term_vrp[].rv | number | Term-matched realized vol |
term_vrp[].vrp | number | VRP spread for this tenor |
gex_conditioned | object | GEX-conditioned VRP read. Null when gamma flip or VRP inputs are unavailable. |
gex_conditioned.regime | string | positive_gamma or negative_gamma when the block is available. |
gex_conditioned.harvest_score | number | 0-1 harvestability score (higher = safer to sell premium) |
gex_conditioned.interpretation | string | Human-readable regime interpretation for VRP context |
vanna_conditioned | object | Vanna-driven vol outlook. Null when gamma flip or required VRP inputs are unavailable. |
vanna_conditioned.outlook | string | Vol compression/expansion outlook |
vanna_conditioned.interpretation | string | How vanna flows affect premium selling |
regime | object | Regime |
regime.gamma | string | Gamma regime: positive_gamma, negative_gamma, or unknown when the flip is unavailable. |
regime.vrp_regime | string | harvestable, event_only, toxic_short_vol, cheap_convexity, or surface_distorted |
regime.net_gex | number | Net gamma exposure ($) |
regime.gamma_flip | number | Published underlying-price boundary of aggregate repriced GEX; null when withheld. |
regime.gamma_flip_status | string | available 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_scores | object | Strategy scores (0-100) per strategy |
strategy_scores.short_put_spread | number | Short put spread suitability; null without a published gamma flip. |
strategy_scores.short_strangle | number | Short strangle suitability; null without a published gamma flip. |
strategy_scores.iron_condor | number | Iron condor suitability; null without a published gamma flip. |
strategy_scores.calendar_spread | number | Calendar spread suitability |
net_harvest_score | number | Harvest 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_risk | number | Dealer flow risk score (0-100) - higher means more dealer hedging amplification risk |
warnings | array of string | Active warning flags: event_risk, negative_gamma, poor_wing_liquidity, term_inversion, credit_stress, extreme_vrp |
macro | object | Macro |
macro.vix | number | VIX spot |
macro.vix_3m | number | VIX3M (3-month VIX) |
macro.vix_term_slope | number | VIX3M/VIX ratio (>1 = contango, <1 = backwardation) |
macro.dgs10 | number | 10-Year Treasury yield |
macro.hy_spread | number | ICE BofA High Yield OAS (credit stress indicator) |
macro.fed_funds | number | Federal Funds rate |
endpoint_version, data_as_of | string, object | Response envelope, see Response envelope. |
Fields of vrp
| Field | Type | Description |
|---|---|---|
vrp.atm_iv | number | ATM implied volatility (%, from BSM on live options via Thetadata) |
vrp.rv_5d | number | Realized volatility, 5-day window (%) |
vrp.rv_10d | number | Realized volatility, 10-day window (%) |
vrp.rv_20d | number | Realized volatility, 20-day window (%) |
vrp.rv_30d | number | Realized volatility, 30-day window (%) |
vrp.vrp_5d | number | ATM IV minus 5-day RV (percentage points) |
vrp.vrp_10d | number | ATM IV minus 10-day RV (percentage points) |
vrp.vrp_20d | number | ATM IV minus 20-day RV (percentage points) |
vrp.vrp_30d | number | ATM IV minus 30-day RV (percentage points) |
vrp.z_score | number | VRP z-score of vrp_20d vs up to 252 trailing days of history (null if < 5 days history) |
vrp.percentile | number | Percentile rank of current VRP (0-100, null if insufficient history) |
vrp.history_days | number | Days of VRP history available for the z-score / percentile |
Errors
| Status | Error | When |
|---|---|---|
400 | invalid_date | date 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. |
403 | tier_restricted | Your plan is below Alpha. The body includes current_plan and required_plan. |
404 | symbol_not_found | No data for the symbol (unknown symbol, or no live data). Outside US market hours the message also says the market is closed. |
404 | no_snapshot | No persisted VRP snapshot for the symbol on date. Snapshot history starts in late March 2026. |
429 | Quota exceeded | Daily 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_scoreandpercentileto 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
warningsarray 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/vrpsnapshots via cron to build a backtestable VRP time series, or read VRP History directly
Related
Research
- Are covered calls worth it? -
directional.upside_vrp, the VIX term structure and realized-vol rules tested as covered-call filters
Related reading
- Realized vs implied volatility & the risk premium - the foundation for why VRP exists and how to read the spread
- VRP z-score timing: a statistical edge for premium selling - turn the
z_scoreinto disciplined entry and exit rules
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
Unlock DEX, VEX and CHEX with Basic
Everything in Free, plus:
- DEX, VEX and CHEX exposure
- Full max pain
- ETF & index symbols SPY, QQQ, SPX, VIX
Go full-chain with Growth
Everything in Basic, plus:
- Full-chain GEX Every expiration
- 0DTE analytics
- Exposure summary & AI narrative
- CME futures & live screener
Add history and vol surfaces with Alpha
Everything in Growth, plus:
- Historical API replay Since 2017
- SVI vol surfaces
- VRP analytics
- Greeks surfaces Vanna, charm, volga and speed grids