# GET /api/mcp/data/relative-value/{ticker}

> Is NVDA's IV rich or cheap relative to SPY and its sector?

Returns the IV ratios to SPY and the sector ETF with their one-month and one-year averages, percentiles, z-scores, sigma bands, a signal and the ratio time series.

- **Family:** Stock analytics (https://apexvol.com/developers/stock-analytics-api)
- **Plan:** Pro and above. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access.
- **Units:** IVs in percentage points; ratios unitless; percentiles 0 to 100; vrp in points.
- **Basis:** Ratios use 30-day IV. The signal compares the current ratio to its one-year distribution.
- **MCP tools:** `get_ticker_analytics`
- **Background:** https://apexvol.com/learn/volatility-arbitrage

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `days` | query | 252 | 20 to 1000 | History length for the series. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/relative-value/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": {
    "avg_opt_volume": 3290793.0,
    "best_etf": "XLK",
    "correlation": {
      "beta": 1.93,
      "etf_1m": 0.52,
      "etf_1y": 0.27,
      "spy_1m": 0.49,
      "spy_1y": 0.41
    },
    "earnings": {
      "days_to_next": null,
      "implied_move": 4.8,
      "implied_move_sigma": 6.0
    },
    "hv20d": 44.92,
    "iv30d": 33.05,
    "market_cap": 5561054100000.0,
    "momentum": {
      "chg_1m": 5.05,
      "chg_1w": 5.86
    },
    "percentiles": {
      "own": 12.0,
      "vs_etf": 48.0,
      "vs_spy": 62.0
    },
    "price": 228.45,
    "ratios": {
      "iv_etf_ratio": 1.44,
      "iv_etf_ratio_avg_1m": 1.94,
      "iv_etf_ratio_avg_1y": 1.28,
      "iv_hv_ratio": 1.03,
      "iv_hv_ratio_1m": 0.91,
      "iv_hv_ratio_1y": 0.9,
      "iv_spy_ratio": 2.78,
      "iv_spy_ratio_avg_1m": 2.71,
      "iv_spy_ratio_avg_1y": 2.37
    },
    "sector": "Technology",
    "sigma_bands": {
      "mean": 2.6624,
      "sigma_1_lower": 2.3332,
      "sigma_1_upper": 2.9916,
      "sigma_2_lower": 2.004,
      "sigma_2_upper": 3.3208
    },
    "signal": "CHEAP",
    "skew": {
      "slope_pctile": null
    },
    "ticker": "NVDA",
    "timeseries": [
      {
        "date": "2025-09-05",
        "iv_etf_ratio": 1.83,
        "iv_hv_ratio": 1.18,
        "iv_spy_ratio": 2.77
      },
      {
        "date": "2025-09-08",
        "iv_etf_ratio": 1.81,
        "iv_hv_ratio": 1.13,
        "iv_spy_ratio": 2.7
      },
      {
        "date": "2025-09-09",
        "iv_etf_ratio": 1.81,
        "iv_hv_ratio": 1.12,
        "iv_spy_ratio": 2.71
      }
    ],
    "vrp": -11.87,
    "z_scores": {
      "etf_ratio_z": -0.2152,
      "spy_ratio_z": 0.3573
    }
  }
}
```

## Fields

- `signal`: RICH, CHEAP or NEUTRAL versus the market.
- `ratios.iv_spy_ratio, iv_spy_ratio_avg_1y, iv_etf_ratio`: The ratios.
- `z_scores.spy_ratio_z, etf_ratio_z, percentiles`: How stretched.
- `timeseries[]`: The ratios through time.

## Errors

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

## Ask it in an MCP client

- Is NVDA IV rich or cheap versus SPY?
- How does AAPL's IV compare with the tech sector ETF?
- Show the IV-to-SPY ratio history for TSLA.

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