VIX State API

Endpoint

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/macro/vix-state"

import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/macro/vix-state",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = resp.json()
print(f"State: {data['state']}")

const resp = await fetch(
  "https://lab.flashalpha.com/v1/macro/vix-state",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log("State: " + data.state);

Response

{
  "as_of": "2026-05-30T15:30:00Z",
  "vix": 18.4,
  "spx_rv_20d": 11.2,
  "spread": 7.2,
  "ratio": 1.6428,
  "state": "overvixing",
  "interpretation": "VIX trades 7.2pp above SPX 20d realized - premium rich, favours short-vol setups."
}

Key Response Fields

Errors

About

VIX State produces an "overvixing / undervixing" regime label for the index complex by comparing spot VIX against SPX 20-day realized vol. The signed spread drives the classification: overvixing when the spread is at least 5 vol points, undervixing when it is at or below 0, and neutral in between.

Thresholds are calibrated against typical regimes: around 4pp average premium in quiet markets, and roughly 0pp or inverted in crashes when realized vol catches up to implied. This is a single-snapshot classifier; for a time series of the state, build on top of /v1/vrp/{symbol}/history for SPX.

Methodology

The classifier compares two directly observable numbers and avoids any model fit. The implied leg is spot VIX - the market's 30-day forward volatility expectation. The realized leg is spx_rv_20d, the close-to-close realized volatility of SPX over the trailing 20 trading days, computed from log-returns with sample standard deviation and annualized by √252 (the same realized-vol definition used across the Lab API, matching Bloomberg and QuantLib conventions).

The signed spread vix − spx_rv_20d is the volatility risk premium in vol points - how much extra the market charges for forward protection over what the index has actually been delivering. The 5-point and 0-point cutoffs are not arbitrary. In quiet, trending markets that premium sits around 4 points (implied persistently rich), so a spread at or above 5 marks an unusually rich, mean-reversion-prone overvixing state that historically favours short-vol setups. As realized vol catches up to or overtakes implied - the late stage of a selloff - the spread collapses toward 0 or inverts, flagging undervixing where carry no longer compensates for tail risk. The band in between is neutral.

The ratio field (vix / spx_rv_20d) is provided as a scale-free companion for cross-regime comparison and is null when spx_rv_20d is 0. Because the label is computed from a single snapshot, persist it or rebuild it from /v1/vrp/{symbol}/history to study regime transitions rather than a point-in-time reading.

Common Use Cases

• Decide short-vol versus long-vol bias from the state label - overvixing favours short-vol setups, undervixing warns carry no longer compensates for tail risk
• Gate strategy entries on spread crossing the 5-point overvixing threshold so premium-selling only fires when the VRP is genuinely rich
• Use ratio (vix / spx_rv_20d) as a scale-free companion to compare today's richness against prior regimes
• Surface the interpretation string as a one-line market-context banner on a dashboard
• Size or hedge tail exposure when the spread collapses toward 0 or inverts - the late-selloff signature of realized catching up to implied
• Persist the snapshot label or rebuild it from VRP History to study regime transitions rather than a point-in-time reading

Related

Related reading

• Vol-of-vol, convexity & charm dealer flow - reads the VIX-versus-realized regime alongside dealer convexity and charm flow

Complementary endpoints

• VRP - the per-symbol implied-minus-realized premium underneath the regime label
• Volatility - the implied-vol surface behind the VIX leg
• Spot-Vol Correlation - whether the inverse leverage effect still holds within the regime
• Skew Term Structure - whether wing skew is rich while the index is overvixing