IV/HV Premium

Your agent turns that into the day's implied-versus-realized comparison, converts it into a ranking across the liquid universe, and pulls the settled history behind whichever names it surfaces.

Implied is the forecast. Realized is what happened.

Implied volatility is the amount of future movement option prices are charging for, quoted as an annualized percentage. Realized volatility is the amount of movement the stock actually delivered over a recent window, quoted the same way. This dataset puts the two side by side for every liquid US equity, every trading day. Implied comes from the at-the-money option (the strike closest to where the stock is trading) in the listed expiry nearest 30 calendar days out. Realized comes from the last 30 trading days of closing prices.

The gap between them is the volatility risk premium, and the dataset expresses it two ways. iv_hv_spread is implied minus realized, which answers how many volatility points apart they are. iv_hv_ratio is implied divided by realized, where above 1 means options are rich relative to recent movement and below 1 means they are cheap. Every field is also served as a daily percentile rank and a z-score, so a value can be read against the rest of the market on the same date rather than in isolation.

Sell premium only where the premium is actually there.

The published study on this dataset sorted 294,503 settled rows into quintiles by iv_hv_ratio and measured what a volatility seller earned in each one. The result is monotonic: seller edge climbs from -9.4 vol points in the cheapest quintile to +5.1 in the richest, a 14.5 vol point spread between the two ends, with the win rate rising from 27% to 53%. That is the case for treating this dataset as a conditioner rather than a screen. The question is not whether to sell volatility, it is where.

The two measures answer different questions and both are served. Use iv_hv_spread when the thing you care about is volatility points earned, because a 5 point premium is worth the same whether the name trades at 20% or 60% vol. Use iv_hv_ratio when comparing names with different vol levels, because a 5 point premium on a 20% name is a much larger proportional cushion than the same 5 points on a 60% name. The ranked and z-scored versions add the third question: is this reading unusual today, or is the whole market rich at once.

• Screen the richest decile in one call with min_ratio_rank=0.9, then check tradability with notional_volume_ranked.
• Pair a rich name against a cheap one using iv_hv_ratio_z, so the comparison is standardized to that day's dispersion.
• Condition an existing short-premium book: take the trade only when iv_hv_ratio_ranked sits in the top band.
• Screen the cheap end with max_iv_hv_ratio for names where buying convexity costs less than the stock's own recent movement.
• Backtest with only_final=true so no intraday value ever leaks into a historical signal.

Solved daily from listed option prices, then frozen.

For each ticker on each trading day, the pipeline picks the listed expiry closest to 30 calendar days out, takes the at-the-money call, and solves for implied volatility against the underlying fair value. The strike, the expiry, the spot used, and the actual calendar days to expiry are all served on the row (atm_strike, exp_date, spot, days_to_exp), so any solve can be checked. Realized volatility is computed from the trailing 30 trading days of close-to-close returns and annualized to sit on the same scale. Percentile ranks and z-scores are then computed across that day's liquid US-equity universe. Exactly one row per date and ticker is guaranteed.

Today's row is live. Through the session it is refreshed roughly every 30 minutes between 09:30 and 16:00 ET and carries is_final = 0, marking a provisional value that can still move. After the close, around 16:30 ET, the settled value is written with is_final = 1, and from that point the date is fixed and never retroactively altered. Every past date is always 1. By default the endpoint returns the latest value per date and ticker, which during the session means today's provisional number; pass only_final=true to get settled rows only. That distinction is what keeps research honest: a backtest built on only_final rows can never see a number that did not exist at the time.

Two numbers, and four ways to read the gap between them.

The headline fields below are a subset. Every field, with exact types and semantics, is documented in the API reference.

One call ranks the whole universe by richness.

One key works across the REST API, the hosted MCP server, and this dashboard. Every response is JSON with a { count, data } envelope.

import requests

url = "https://api.alphanume.com/v1/iv-hv-premium"
params = {
    "date": "2026-06-12",
    "min_ratio_rank": 0.9,
    "only_final": "true",
    "api_key": "alp_abc123"
}

r = requests.get(url, params=params)
print(r.json())

curl "https://api.alphanume.com/v1/iv-hv-premium?date=2026-06-12&min_ratio_rank=0.9&only_final=true&api_key=alp_abc123"

{
  "count": 1,
  "data": [
    {
      "date": "2026-06-12",
      "ticker": "AAPL",
      "iv": 0.1795,
      "hv": 0.2333,
      "iv_hv_spread": -0.0538,
      "iv_hv_ratio": 0.769,
      "iv_ranked": 0.22,
      "hv_ranked": 0.61,
      "iv_hv_spread_ranked": 0.18,
      "iv_hv_ratio_ranked": 0.31,
      "iv_z": -0.42,
      "hv_z": 0.55,
      "iv_hv_spread_z": -0.60,
      "iv_hv_ratio_z": -0.48,
      "notional_volume": 8410000000,
      "notional_volume_ranked": 0.99,
      "notional_volume_z": 4.1,
      "days_to_exp": 31,
      "exp_date": "2026-07-17",
      "atm_strike": 290,
      "spot": 291.36,
      "is_final": 1,
      "last_updated": "2026-06-12 16:31:22"
    }
  ]
}

What this data does not claim.

• iv comes from the listed expiry nearest 30 calendar days, not a constant-maturity 30-day surface. days_to_exp gives the maturity actually used, and it shifts as expiries roll.
• One at-the-money implied vol is not a volatility surface. There is no skew and no term structure in this data, so a name can look cheap here while its puts are expensive.
• Ranks and z-scores are cross-sectional only, computed against that day's universe. Where a name sits inside its own history is a different question, answered by the IV/HV Rank dataset.
• Rows carrying is_final = 0 are today's provisional intraday value and can move before the close. Anything used for research should be pulled with only_final=true.
• The universe is point-in-time liquid US equities, so names enter and leave it. A ticker missing on a given day was not in that day's universe rather than having a gap in coverage.