# GET /api/mcp/data/relative-value-scan

> Whose IV is stretched versus SPY, and which pairs look rich against cheap?

Returns names whose IV ratio to SPY is far from its one-year average (z-score above the threshold) with the direction, or a pairs view of rich against cheap names.

- **Family:** Screeners (https://apexvol.com/developers/screeners-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:** iv_percentile 0 to 100; ratios unitless; z_score in standard deviations; vrp in points.
- **Basis:** iv_spy_ratio is 30-day IV divided by SPY's; the average is one year.
- **MCP tools:** `scan_relative_value`
- **Background:** https://apexvol.com/learn/volatility-arbitrage

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `view` | query | mean_reversion | mean_reversion or pairs | Which scan. |
| `limit` | query | 20 | 1 to 50 | Rows. |
| `threshold` | query | 1.5 | z-score | Minimum stretch. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/relative-value-scan?limit=5"
```

## 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": {
    "results": [
      {
        "avg_opt_volume": 1062.0,
        "chg_1w": 0.09,
        "days_to_earnings": null,
        "direction": "rich",
        "iv_percentile": 98.0,
        "iv_spy_ratio": 18.6563,
        "iv_spy_ratio_avg_1y": 0.26,
        "market_cap": 105418148000.0,
        "price": 100.47,
        "sector": "N/A",
        "ticker": "SGOV",
        "vrp": 1.61,
        "z_score": 55.2216
      },
      {
        "avg_opt_volume": 16.0,
        "chg_1w": -1.32,
        "days_to_earnings": null,
        "direction": "rich",
        "iv_percentile": 43.0,
        "iv_spy_ratio": 3.8661,
        "iv_spy_ratio_avg_1y": 0.21,
        "market_cap": 549319000.0,
        "price": 8.23,
        "sector": "Real Estate",
        "ticker": "ILPT",
        "vrp": -22.38,
        "z_score": 13.4584
      },
      {
        "avg_opt_volume": 149.0,
        "chg_1w": 8.04,
        "days_to_earnings": null,
        "direction": "rich",
        "iv_percentile": 56.0,
        "iv_spy_ratio": 3.7184,
        "iv_spy_ratio_avg_1y": 0.21,
        "market_cap": 6150466000.0,
        "price": 2.15,
        "sector": "Utilities",
        "ticker": "CIG",
        "vrp": -31.59,
        "z_score": 12.9078
      }
    ],
    "threshold": 1.5,
    "total_matches": 5,
    "total_scanned": 5963
  }
}
```

## Fields

- `results[].ticker, iv_spy_ratio, iv_spy_ratio_avg_1y, z_score, direction`: The stretch.
- `results[].iv_percentile, vrp, days_to_earnings`: Context.
- `total_matches, total_scanned, threshold`: What ran.

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

- Which stocks have IV stretched relative to SPY?
- Find rich-versus-cheap vol pairs.
- Show relative-value stretches above 2 standard deviations.

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