# GET /api/mcp/data/vrp/{ticker}

> Is NVDA's implied vol paying more than the stock actually moves?

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.

- **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:** 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.
- **MCP tools:** `get_volatility_risk_premium`
- **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. |
| `lookback_days` | query | 30 | 5 to 252 | Length of the realized-vol window in trading days. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/vrp/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": {
    "assessment": "NEGATIVE_PREMIUM",
    "earnings_in_window": true,
    "hv_basis": "close_to_close_log_returns_annualized_252",
    "hv_window": 30,
    "implied_volatility": 33.05,
    "iv_basis": "iv30d_constant_maturity_eod",
    "iv_units": "percentage_points",
    "lookback_days": 30,
    "realized_volatility": 45.0597,
    "realized_volatility_ex_earnings": 38.2226,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T07:49:46.909110",
    "volatility_risk_premium": -12.0097,
    "volatility_risk_premium_ex_earnings": -5.1726,
    "vrp_percentile": 1.7857,
    "vrp_ratio": 0.7335
  }
}
```

## Fields

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

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

- What is the volatility risk premium on NVDA, and is it rich or cheap?
- Is AAPL implied vol above or below realized over the last 30 days?
- Which of SPY, QQQ, IWM has the highest premium over realized?

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