# Screeners API

4 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/screeners-api

| Endpoint | Plan | What it answers |
|---|---|---|
| `GET /market-overview` | Premium | What is the volatility regime across the market today? |
| `GET /relative-value-scan` | Pro | Whose IV is stretched versus SPY, and which pairs look rich against cheap? |
| `GET /screen` | Premium | Which stocks have the highest IV rank right now? |
| `GET /vol-arb-scan` | Pro | Are there mispriced butterflies or skew trades on SPY right now? |

## GET /market-overview

One call with the average IV and VRP across the universe, the regime label, a sector heatmap, ETF heatmap, index levels, rates, put skew, vol breadth, top movers, unusual activity and the IV-versus-HV outliers.

- **Units:** IVs in percentage points; VRP in points; changes in percent; yields in percent; OI and volume in contracts.
- **Basis:** Bulk daily data across the covered universe.
- **Markdown:** https://apexvol.com/developers/screeners-api/market-overview.md

No parameters.

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

- `market_stats.market_regime, avg_iv30d, avg_vrp, pct_high_iv`: The regime.
- `sector_heatmap[], etf_heatmap[]`: By sector and ETF.
- `index_prices, treasury_rates`: Levels and rates.
- `vol_breadth, put_skew`: Breadth and skew across names.
- `top_movers[], unusual_activity[], earnings_this_week[]`: The lists.

## GET /relative-value-scan

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.

- **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.
- **Markdown:** https://apexvol.com/developers/screeners-api/relative-value-scan.md

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

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

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

## GET /screen

Runs one of the preset screens over the covered universe in one or two bulk calls and returns the matching rows with price, IV, realized vol, VRP, skew percentile, earnings timing and market cap. screen_type=list returns the catalog.

- **Units:** iv30d, iv60d, hv20d in percentage points; vrp in points; chg_1w and chg_1m in percent; market_cap in dollars.
- **Basis:** Daily bulk data from the feed; iv_percentile is the one-year figure.
- **Markdown:** https://apexvol.com/developers/screeners-api/screen.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `screen_type` | query | high_iv_rank | high_iv_rank, low_iv_rank, high_vrp, earnings_this_week, high_skew, steep_contango, mean_reversion, vol_pairs, decorrelation, unusual_volume, pin_risk, list | Which preset. |
| `limit` | query | 20 | 1 to 200 | Rows. |
| `min_market_cap` | query | 1000000000 | dollars | Floor on size. |
| `exclude_earnings_days` | query | 0 | 0 to 60 | Drop names reporting within N days. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/screen?screen_type=high_iv_rank&limit=5"
```

- `results[].ticker, price, iv30d, hv20d, vrp, iv_percentile`: The row.
- `results[].skew_pctile, contango, days_to_earnings, imp_earn_move`: Extra columns per screen.
- `screen_name, screen_description, total_scanned, universe_size`: What ran.

## GET /vol-arb-scan

Scans the chain of one ticker for butterflies priced below fair, skew trades between ATM and OTM IV, calendar-spread opportunities and put-call parity violations, with the edge for each.

- **Units:** Option prices in dollars; IVs in percentage points (iv_unit); edge_pct in percent.
- **Basis:** Model fair values from the chain IV; each row states its strategy and type.
- **Markdown:** https://apexvol.com/developers/screeners-api/vol-arb-scan.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` | query | SPY | symbol | Which chain to scan. |

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

- `butterfly_mispricings[].lower_strike, middle_strike, upper_strike, butterfly_cost, edge`: Butterflies.
- `skew_trades[].atm_iv, otm_iv, skew, strategy`: Skew trades.
- `calendar_spreads[], put_call_parity_violations[]`: The other checks.
- `total_opportunities`: Count.

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