# GET /api/mcp/data/volatility-cone/{ticker}

> How does NVDA's implied vol at each tenor compare with what the stock has actually realized over the same windows?

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.

- **Family:** Implied volatility (https://apexvol.com/developers/implied-volatility-api)
- **Plan:** Premium and above. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access.
- **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.
- **MCP tools:** `get_volatility_cone`
- **Background:** https://apexvol.com/learn/volatility-risk-premium

## Parameters

| 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. |

## Request

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

## Response (captured 2026-09-08)

Real response, lists cut to the rows nearest the money. The envelope is `{"success": true, "data": ...}`.

```json
{
  "success": true,
  "data": {
    "current_iv": 33.73,
    "earnings_in_window": true,
    "hv_basis": "close_to_close_log_returns_annualized_252",
    "iv30d": 33.05,
    "iv_basis": "chain_interpolated_per_tenor",
    "iv_units": "percentage_points",
    "realized_vol_30d": 45.0597,
    "realized_vol_30d_ex_earnings": 38.2226,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T07:49:01.919949",
    "volatility_cone": {
      "10d": {
        "current_rv": 58.3175,
        "difference": -25.9975,
        "earnings_in_window": true,
        "iv": 32.32,
        "iv_to_rv_ratio": 0.5542,
        "max": 58.9167,
        "mean_rv": 38.6147,
        "median_rv": 39.1835,
        "min": 16.5158,
        "p10": 25.6954,
        "p25": 31.1498,
        "p75": 45.0427,
        "p90": 51.8898,
        "period": 10,
        "rv": 58.3175,
        "rv_ex_earnings": 39.8305
      },
      "20d": {
        "current_rv": 44.8025,
        "difference": -12.3025,
        "earnings_in_window": true,
        "iv": 32.5,
        "iv_to_rv_ratio": 0.7254,
        "max": 47.3461,
        "mean_rv": 39.23,
        "median_rv": 39.0719,
        "min": 25.8829,
        "p10": 33.2992,
        "p25": 35.8786,
        "p75": 43.5439,
        "p90": 45.5091,
        "period": 20,
        "rv": 44.8025,
        "rv_ex_earnings": 33.7829
      },
      "30d": {
        "current_rv": 45.0597,
        "difference": -11.3297,
        "earnings_in_window": true,
        "iv": 33.73,
        "iv_to_rv_ratio": 0.7486,
        "max": 47.4467,
        "mean_rv": 39.283,
        "median_rv": 39.2371,
        "min": 31.5777,
        "p10": 34.3931,
        "p25": 36.8516,
        "p75": 41.6358,
        "p90": 44.5353,
        "period": 30,
        "rv": 45.0597,
        "rv_ex_earnings": 38.2226
      },
      "60d": {
        "current_rv": 40.5623,
        "difference": -2.1623,
        "earnings_in_window": true,
        "iv": 38.4,
        "iv_to_rv_ratio": 0.9467,
        "max": 42.965,
        "mean_rv": 39.3644,
        "median_rv": 40.1113,
        "min": 34.9747,
        "p10": 36.5381,
        "p25": 37.2865,
        "p75": 40.9827,
        "p90": 41.8987,
        "period": 60,
        "rv": 40.5623,
        "rv_ex_earnings": 37.6954
      },
      "90d": {
        "current_rv": 42.1894,
        "difference": -4.1694,
        "earnings_in_window": true,
        "iv": 38.02,
        "iv_to_rv_ratio": 0.9012,
        "max": 42.9185,
        "mean_rv": 39.4155,
        "median_rv": 39.3601,
        "min": 36.2709,
        "p10": 37.9139,
        "p25": 38.6209,
        "p75": 40.1866,
        "p90": 40.704,
        "period": 90,
        "rv": 42.1894,
        "rv_ex_earnings": 40.3067
      }
    }
  }
}
```

## Fields

- `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.

## Errors

- `401`: no or revoked token
- `429`: Retry-After seconds
- `403`: Premium plan required
- `424`: data feed unavailable, retry
- Full list: https://apexvol.com/developers/errors

## Ask it in an MCP client

- Show me NVDA's volatility cone. Is 30-day IV rich to realized?
- Where does AAPL's realized vol sit in its historical range at 20 and 60 days?
- Compare implied to realized across tenors for TSLA.

Conventions for units, bases and timestamps: https://apexvol.com/developers/conventions