# Implied volatility API

11 endpoints under `https://apexvol.com/api/mcp/data`. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access. Web version: https://apexvol.com/developers/implied-volatility-api

| Endpoint | Plan | What it answers |
|---|---|---|
| `GET /hv-regimes/{ticker}` | Premium | What realized-vol regime is NVDA in, and are the short windows above or below the long ones? |
| `GET /iv-opportunities/{ticker}` | Premium | Is NVDA's IV stretched far enough from its mean to expect reversion? |
| `GET /iv-rank/{ticker}` | Premium | Is NVDA's implied volatility high or low for NVDA right now? |
| `GET /monies/{ticker}` | Pro | What does the smoothed vol surface say about SPY at each delta and expiration? |
| `GET /skew/{ticker}` | Pro | How steep is NVDA's put skew today compared with its own history and its sector? |
| `GET /term-structure/{ticker}` | Premium | Is SPY's IV curve in contango or inverted, and what move does each expiration price? |
| `GET /vix` | Premium | Where is the VIX right now and how much did it move today? |
| `GET /volatility-cone/{ticker}` | Premium | How does NVDA's implied vol at each tenor compare with what the stock has actually realized over the same windows? |
| `GET /vrp/{ticker}` | Premium | Is NVDA's implied vol paying more than the stock actually moves? |
| `GET /vrp/{ticker}/expirations` | Premium | Where on NVDA's curve is the premium over realized sitting? |
| `GET /vrp/{ticker}/timeseries` | Premium | How has the gap between NVDA's implied and realized vol moved over the last few months? |

## GET /hv-regimes/{ticker}

Returns close-to-close realized vol at 5 to 252 day windows as a time series, the HV term structure with the vendor's alternative estimator, and a forecast block. Other views return the signals, the decomposition, or an ex-earnings series.

- **Units:** All volatilities are annualised percentage points.
- **Basis:** cls_hv is close-to-close; or_hv is the data feed's intraday-range estimator. view=ex_earnings recomputes the 30-day tenor from daily closes with earnings reaction sessions dropped.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/hv-regimes.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `view` | query | dashboard | dashboard, signals, decomposition, ex_earnings | Which block to return. |
| `days` | query | 252 | 20 to 1000 | History length. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/hv-regimes/NVDA"
```

- `timeseries[].clsHv5d to clsHv252d`: Realized vol per window per day.
- `term_structure[].window, cls_hv, or_hv`: The HV term structure.
- `forecast`: Vendor forecast of 20-day and long-run vol when available.

## GET /iv-opportunities/{ticker}

Compares current IV with its mean and standard deviation, returns the z-score, a reversion target and the expected IV move, and labels whether an extreme is present.

- **Units:** IVs are annualised percentage points; z_score is in standard deviations; expected_pct_change is percent.
- **Basis:** Mean and standard deviation are taken over the IV series behind /iv-rank.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/iv-opportunities.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/iv-opportunities/NVDA"
```

- `current_iv, mean_iv, std_iv`: Today's IV and its distribution.
- `z_score`: How far IV is from its mean, in standard deviations.
- `reversion_target, expected_iv_move`: Where IV would go if it reverted.
- `opportunity`: SELL_VOL, BUY_VOL or NO_EXTREME.
- `term_structure[].z_score`: The same read per expiration.

## GET /iv-rank/{ticker}

Returns where today's implied volatility sits inside its own 52-week range (iv_rank, 0 to 100) and the share of days that closed with lower IV (iv_percentile), plus the min, max, mean and state label the numbers were built from.

- **Units:** current_iv, iv30d and the range bounds are annualised IV in percentage points (34.43 means 34.43%). iv_rank and the percentiles are 0 to 100.
- **Basis:** iv_basis names the daily series the rank is measured on; iv30d is the 30-day constant-maturity IV used by the VRP endpoints, so the two can differ slightly. iv_percentile is the one-year percentile from the data feed.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/iv-rank.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `lookback_days` | query | 252 | 20 to 1260, clamped | Days of history behind the rank and the 1y percentile. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/iv-rank/NVDA"
```

- `iv_rank`: Today's IV as a position between the 52-week low (0) and high (100).
- `iv_percentile`: Share of lookback days that closed with IV below today's.
- `current_iv`: The IV the rank was computed from, in percentage points.
- `iv30d`: The 30-day constant-maturity IV, the basis the VRP endpoints use.
- `iv_min_52w, iv_max_52w, iv_mean, iv_std`: The range and distribution behind the rank.
- `iv_state`: VERY_LOW to VERY_HIGH so a caller can branch without picking thresholds.
- `iv_rank_1m, iv_percentile_1m`: The same measures over the last month.

## GET /monies/{ticker}

Returns the ATM IV, slope, curvature and the smile across delta points for each expiration, either as the market's smoothed surface, the vendor forecast, or a rich-versus-cheap comparison of the two.

- **Units:** atm_iv and the smile values are annualised percentage points; slope and curvature are surface parameters.
- **Basis:** Surface points are the data feed's smoothed fit, not raw quotes. Expirations may include the most recent expired date; filter on dte greater than 0.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/monies.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `surface` | query | implied | implied, forecast, comparison | Which surface to return. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/monies/SPY"
```

- `expirations[].expiration, dte, atm_iv`: The ATM point per expiration.
- `expirations[].slope, curvature, smile`: The smile parameters and the values at each delta point.
- `delta_points`: The deltas the smile is sampled at.
- `expirations[].earn_effect`: Earnings contribution to that expiration's IV.

## GET /skew/{ticker}

Returns the current skew slope and its forecast, the smile curvature with an interpretation, where today's slope sits against its one-month and one-year averages, and the ratio to the sector ETF. Other views return the history or the curvature only.

- **Units:** slope and curvature are the data feed's surface parameters (unitless); percentile.current is 0 to 100; market_width.vol is in percentage points.
- **Basis:** Slope is measured on the smoothed vol surface at the 30-day tenor. Read it against percentile.avg_1y rather than as an absolute.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/skew.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `view` | query | analysis | analysis, history, curvature | Which block to return. |
| `days` | query | 252 | 20 to 1000 | History length for view=history. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/skew/NVDA"
```

- `current.slope, slope_forecast`: Today's skew slope and the model forecast.
- `percentile.current, avg_1m, avg_1y, stdv_1y`: Today's slope percentile and the averages it is compared with.
- `curvature.interpretation, mispricing`: What the smile shape says.
- `sector_relative.etf_slope_ratio`: Skew relative to the sector ETF.

## GET /term-structure/{ticker}

One row per expiration with the ATM strike, ATM IV, straddle price and the one and two sigma bounds, so the shape of the curve and the priced move at each date come back in a single array.

- **Units:** atm_iv is annualised percentage points. expected_move_dollar is dollars, expected_move_pct is percent of spot. straddle_* are option prices in dollars.
- **Basis:** ATM IV is the chain IV at the strike nearest spot. expected_move comes from the straddle price; iv_expected_move is the sigma-based figure from IV and time.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/term-structure.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `num_expirations` | query | 8 | 1 to 20 | How many expirations to return, nearest first. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/term-structure/SPY"
```

- `term_structure[].expiration, dte`: The expiration and days to it.
- `term_structure[].atm_iv`: At-the-money implied vol for that expiration.
- `term_structure[].straddle_price`: ATM call plus put, the market's price for the move.
- `term_structure[].expected_move_pct, expected_move_dollar`: The priced move to that date.
- `term_structure[].upper_1sigma, lower_1sigma`: The one-sigma range from the straddle.
- `as_of`: Trade date of the chain.

## GET /vix

The current VIX print with open, high, low, previous close and the change in points and percent.

- **Units:** VIX points; change_pct is percent.
- **Basis:** Quote from the market data feed, updated intraday.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/vix.md

No parameters.

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/vix"
```

- `price, close, prev_close`: The level now and at the last close.
- `change, change_pct`: Move since the previous close.
- `open, high, low`: Today's range.

## GET /volatility-cone/{ticker}

For each requested window (10, 20, 30, 60, 90 days by default) returns the current realized vol, its historical min, percentiles, mean and max, and the interpolated implied vol at that tenor, so a caller can see whether options are rich or cheap along the curve.

- **Units:** All volatilities are annualised percentage points. iv_to_rv_ratio is a plain ratio.
- **Basis:** Per-tenor IVs are interpolated from the chain (iv_basis). Realized vol is close-to-close over the window (hv_basis). Each tenor flags earnings_in_window and carries rv_ex_earnings with the earnings reaction sessions removed.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/volatility-cone.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `periods` | query | 10,20,30,60,90 | CSV of 2 to 252, at most 8 values | Windows in trading days. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/volatility-cone/NVDA"
```

- `volatility_cone.<tenor>.iv`: Implied vol interpolated to that tenor.
- `volatility_cone.<tenor>.current_rv`: Realized vol over the most recent window of that length.
- `volatility_cone.<tenor>.p10 to p90, min, max`: Where realized vol has ranged historically at that tenor.
- `volatility_cone.<tenor>.rv_ex_earnings`: Realized vol with earnings reaction days dropped.
- `realized_vol_30d, realized_vol_30d_ex_earnings`: The 30-day figures at the top level.
- `iv30d`: The vendor 30-day IV for reconciliation with /vrp.

## GET /vrp/{ticker}

Returns implied volatility, realized volatility over exactly lookback_days, their difference (the premium), the ratio, a percentile and a plain assessment. When an earnings report sits inside the window the ex-earnings figures are added.

- **Units:** Volatilities and the premium are annualised percentage points; a premium of -12.0 means IV is 12 points below realized. vrp_ratio is IV divided by realized.
- **Basis:** IV is the 30-day constant-maturity figure (iv_basis). Realized is the standard deviation of close-to-close log returns over lookback_days (hv_basis, hv_window). earnings_in_window says whether a report contaminates the realized figure.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/vrp.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `lookback_days` | query | 30 | 5 to 252 | Length of the realized-vol window in trading days. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/vrp/NVDA"
```

- `implied_volatility`: 30-day constant-maturity IV.
- `realized_volatility`: Close-to-close realized vol over the window.
- `volatility_risk_premium`: IV minus realized, in points. Positive means options are rich to the move.
- `volatility_risk_premium_ex_earnings, realized_volatility_ex_earnings`: The same with earnings reaction days removed.
- `vrp_ratio, vrp_percentile`: IV over realized, and where the premium sits historically.
- `assessment`: A plain label for the premium.

## GET /vrp/{ticker}/expirations

For each of the next expirations returns that expiration's IV, the realized vol over a matching horizon, the premium in points and as a share, and a signal, plus an average and a regime label for the curve.

- **Units:** iv, hv and vrp are annualised percentage points; vrp_pct is the premium as a percentage of realized.
- **Basis:** Per-expiration IV is the ATM chain IV; realized is matched to the days to that expiration.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/vrp-expirations.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `max_expirations` | query | 10 | 1 to 30 | How many expirations to include. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/vrp/NVDA/expirations?max_expirations=6"
```

- `vrp_by_expiration[].expiration, dte`: The expiration and days to it.
- `vrp_by_expiration[].iv, hv, vrp, vrp_pct`: The premium at that date.
- `vrp_by_expiration[].signal`: RICH, CHEAP or NEUTRAL.
- `avg_vrp, regime, regime_desc`: The curve in one line.

## GET /vrp/{ticker}/timeseries

One row per trading day with the 30-day IV, the realized vol over hv_period and the premium, plus a current block, so the premium can be charted or fed to a model.

- **Units:** All values are annualised percentage points (iv_units).
- **Basis:** Same bases as /vrp: iv_basis and hv_basis are returned with the series.
- **Markdown:** https://apexvol.com/developers/implied-volatility-api/vrp-timeseries.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `lookback_days` | query | 60 | 10 to 504 | How many trading days of history. |
| `hv_period` | query | 30 | 5 to 252 | Realized-vol window per point. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/vrp/NVDA/timeseries?lookback_days=60"
```

- `timeseries[].date, iv, hv, vrp`: The daily series.
- `current`: Today's iv, hv, vrp and the hv_period used.
- `as_of`: Last date in the series.

Conventions: https://apexvol.com/developers/conventions. Errors: https://apexvol.com/developers/errors. Whole API in one file: https://apexvol.com/docs/api/apexvol-api.md