Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
description: 'Options-analytics API (token surface). Auth: `Authorization: Bearer avmcp_` on every request; tokens are issued to any paid or trial plan from Basic, and each endpoint follows the same tier as the web app. Rate limits: 60/min and 1,000/hr per token, plus a monthly allowance per account measured in upstream data requests, by plan. The remaining counts come back in the X-RateLimit-* and X-Monthly-Budget-Remaining headers on every response, and GET /api/mcp/data/me/usage returns the month''s meter with a per-endpoint breakdown. IV values are percentage points unless a payload says otherwise (`iv_units`). The same endpoints power the ApexVol MCP server for AI assistants: `pipx install apexvol-mcp` (PyPI), setup at https://apexvol.com/mcp. Docs: https://apexvol.com/docs/api.'
title: ApexVol Screeners API
version: '1.30'
servers:
- url: https://apexvol.com
security:
- bearerAuth: []
tags:
- name: Screeners
paths:
/api/mcp/data/market-overview:
get:
description: 'Market-wide volatility overview.
**Query parameters:** —
**Response shape:**
```json
{
"success": true,
"data": {
"earnings_this_week": [
{
"capGroup": "large",
"days_to_earnings": 0,
"hv20d": 34.0,
"iv30d": 48.3,
"iv_percentile": 98.0,
"market_cap": "$28.0B",
"next_earnings": "2026-09-08",
"price": 755.96,
"sector": "C. Defensive",
"ticker": "CASY",
"vrp": 14.2
},
{
"capGroup": "mid",
"days_to_earnings": 0,
"hv20d": 22.4,
"iv30d": 52.2,
"iv_percentile": 52.0,
"market_cap": "$8.6B",
"next_earnings": "2026-09-08",
"price": 19.19,
"sector": "C. Cyclical",
"ticker": "GME",
"vrp": 29.8
},
{
"capGroup": "mid",
"days_to_earnings": 0,
"hv20d": 28.9,
"iv30d": 67.6,
"iv_percentile": 71.0,
"market_cap": "$2.7B",
"next_earnings": "2026-09-08",
"price": 43.87,
"sector": "C. Defensive",
"ticker": "UNFI",
"vrp": 38.8
}
],
"index_prices": {
"DJX": {
"chg1m": -1.87,
"chg1w": -0.43,
"chg_today": 0,
"iv30d": 11.2,
"name": "Dow Jones",
"price": 53686.0
},
"NDX": {
"chg1m": -0.01,
"chg1w": 0.17,
"chg_today": 0,
"iv30d": 16.4,
"name": "Nasdaq 100",
"price": 29482.32
},
"SPX": {
"chg1m": -0.08,
"chg1w": 0.07,
"chg_today": 0,
"iv30d": 11.2,
"name": "S&P 500",
"price": 7747.71
},
"VIX": {
"chg1m": -8.67,
"chg1w": 0.07,
"chg_today": 0,
"iv30d": 77.8,
"name": "VIX",
"price": 14.32
}
},
"market_stats": {
"avg_contango": -0.06,
"avg_iv30d": 45.8,
"avg_iv_percentile": 36.1,
"avg_put_call_ratio": 0.67,
"avg_vrp": 6.3,
"market_regime": "Normal",
"median_iv_percentile": 33.0,
"pct_high_iv": 12.4,
"regime_color": "green",
"total_options_oi": 583148513,
"total_options_vol": 76063634,
"total_tickers": 4011
},
"put_skew": {
"avg_skew_pctile": 39.4,
"avg_slope": 0.85,
"avg_slope_1y": 1.37
},
"scan_time": "2026-09-08T05:01:41",
"sector_heatmap": [
{
"avg_contango": -0.21,
"avg_iv30d": 39.6,
"avg_iv_percentile": 45.1,
"avg_vrp": 3.8,
"sector": "C. Defensive",
"ticker_count": 118
},
{
"avg_contango": -0.32,
"avg_iv30d": 29.6,
"avg_iv_percentile": 42.6,
"avg_vrp": 4.1,
"sector": "Utilities",
"ticker_count": 86
},
{
"avg_contango": 0.32,
"avg_iv30d": 60.5,
"avg_iv_percentile": 40.0,
"avg_vrp": 3.5,
"sector": "Technology",
"ticker_count": 422
}
],
"top_movers": [
{
"capGroup": "mega",
"iv30d": 33.2,
"iv_percentile": 100.0,
"market_cap": "$237.5B",
"price": 439.35,
"sector": "Healthcare",
"ticker": "AMGN",
"vrp": 12.0
},
{
"capGroup": "small",
"iv30d": 22.0,
"iv_percentile": 100.0,
"market_cap": "$493M",
"price": 50.91,
"sector": "N/A",
"ticker": "AMZA",
"vrp": 2.7
},
{
"capGroup": "mid",
"iv30d": 143.5,
"iv_percentile": 100.0,
"market_cap": "$3.1B",
"price": 39.55,
"sector": "Healthcare",
"ticker": "CLDX",
"vrp": null
}
],
"treasury_rates": {
"^FVX": {
"chg_bps": 4.1,
"name": "5-Year",
"yield": 4.55
},
"^TNX": {
"chg_bps": 2.2,
"name": "10-Year",
"yield": 4.784
},
"^TYX": {
"chg_bps": 0.3,
"name": "30-Year",
"yield": 5.246
}
},
"vol_breadth": {
"pct_contango_positive": 60.6,
"pct_iv_above_hv": 76.4,
"pct_iv_pctile_above_50": 27.8
}
}
}
```'
operationId: get_market_overview
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/GetMarketOverviewResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: Market-wide volatility overview
tags:
- Screeners
/api/mcp/data/relative-value-scan:
get:
description: 'Market-wide relative-value scans: IV/SPY mean-reversion stretches or rich-vs-cheap pairs.
**Query parameters:** view (optional: ''mean_reversion'' default, ''pairs'') · limit (default 20, max 50) · threshold (mean_reversion z-score, default 1.5)
**Response shape:**
```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
}
}
```'
operationId: get_relative_value_scan
parameters:
- description: 'Which scan. Range: mean_reversion or pairs.'
in: query
name: view
required: false
schema:
default: mean_reversion
enum:
- mean_reversion
- pairs
type: string
- description: 'Rows. Range: 1 to 50.'
in: query
name: limit
required: false
schema:
default: 20
maximum: 50
minimum: 1
type: integer
- description: 'Minimum stretch. Range: z-score.'
in: query
name: threshold
required: false
schema:
default: 1.5
type: number
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/GetRelativeValueScanResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: 'Market-wide relative-value scans: IV/SPY mean-reversion stretches or…'
tags:
- Screeners
/api/mcp/data/screen:
get:
description: 'Market screener over the full universe via bulk data (1-2 upstream calls). Preset catalog: high_iv_rank, low_iv_rank, high_vrp, earnings_this_week, high_skew, steep_contango, mean_reversion, vol_pairs, decorrelation, unusual_volume, pin_risk. screen_type=list returns the catalog with descriptions.
**Query parameters:** screen_type (default high_iv_rank; "list" for catalog) · limit (default 20, max 200) · min_market_cap (dollars, default 1e9) · exclude_earnings_days (default 0; 0 to 60)
**Response shape:**
```json
{
"success": true,
"data": {
"results": [
{
"asset_type": "Stock",
"avg_opt_volume": 181.0,
"beta": 0.64,
"chg_1m": 11.05,
"chg_1w": 14.47,
"contango": -30.8,
"days_to_earnings": 57,
"hv20d": 34.5,
"imp_earn_move": 16.18,
"iv30d": 243.0,
"iv60d": 177.2,
"iv_percentile": 100,
"market_cap": "$1.7B",
"market_cap_raw": 1703777000.0,
"next_earnings": "2026-11-04",
"price": 24.86,
"sector": "Healthcare",
"skew_pctile": 78.0,
"stock_volume": 44616,
"ticker": "TYRA",
"vrp": null
},
{
"asset_type": "Stock",
"avg_opt_volume": 76.0,
"beta": 1.34,
"chg_1m": 7.87,
"chg_1w": -6.13,
"contango": 5.76,
"days_to_earnings": 58,
"hv20d": 36.3,
"imp_earn_move": 15.12,
"iv30d": 113.4,
"iv60d": 115.7,
"iv_percentile": 100,
"market_cap": "$2.2B",
"market_cap_raw": 2196446000.0,
"next_earnings": "2026-11-05",
"price": 47.65,
"sector": "Healthcare",
"skew_pctile": 46.0,
"stock_volume": 6826,
"ticker": "RAPP",
"vrp": 77.1
},
{
"asset_type": "ETF",
"avg_opt_volume": 14.0,
"beta": 0.61,
"chg_1m": 7.91,
"chg_1w": 1.71,
"contango": -1.08,
"days_to_earnings": null,
"hv20d": 13.7,
"imp_earn_move": 0.0,
"iv30d": 25.0,
"iv60d": 25.0,
"iv_percentile": 100,
"market_cap": "$5.2B",
"market_cap_raw": 5212689000.0,
"next_earnings": null,
"price": 79.29,
"sector": "Materials",
"skew_pctile": 57.0,
"stock_volume": 7381,
"ticker": "GNR",
"vrp": 11.4
}
],
"scan_time": "2026-09-08T07:50:11",
"screen_description": "Tickers with elevated IV: selling premium opportunities",
"screen_name": "High IV Rank",
"screen_type": "high_iv_rank",
"total_results": 298,
"total_scanned": 5963,
"universe_size": 2318
}
}
```'
operationId: get_screen
parameters:
- description: 'Which preset. Range: 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.'
in: query
name: screen_type
required: false
schema:
default: high_iv_rank
enum:
- 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
type: string
- description: 'Rows. Range: 1 to 200.'
in: query
name: limit
required: false
schema:
default: 20
maximum: 200
minimum: 1
type: integer
- description: 'Floor on size. Range: dollars.'
in: query
name: min_market_cap
required: false
schema:
default: 1000000000
type: number
- description: 'Drop names reporting within N days. Range: 0 to 60.'
in: query
name: exclude_earnings_days
required: false
schema:
default: 0
maximum: 60
minimum: 0
type: integer
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/GetScreenResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: Market screener over the full universe via bulk data (1-2 upstream calls)
tags:
- Screeners
/api/mcp/data/vol-arb-scan:
get:
description: 'Volatility-arbitrage scan.
**Query parameters:** ticker (default SPY)
**Response shape:**
```json
{
"success": true,
"data": {
"butterfly_mispricings": [
{
"butterfly_cost": 0.655,
"edge": "1326.7% potential return",
"edge_pct": 1326.7176,
"expiration": "2026-09-15",
"lower_strike": 760.0,
"max_profit": 9.345,
"middle_strike": 765.0,
"option_type": "CALL",
"risk_reward": 14.2672,
"strategy": "Buy call butterfly at 765.0",
"ticker": "SPY",
"type": "BUTTERFLY_VALUE",
"upper_strike": 770.0
},
{
"butterfly_cost": 0.765,
"edge": "1107.2% potential return",
"edge_pct": 1107.1895,
"expiration": "2026-09-15",
"lower_strike": 775.0,
"max_profit": 9.235,
"middle_strike": 780.0,
"option_type": "CALL",
"risk_reward": 12.0719,
"strategy": "Buy call butterfly at 780.0",
"ticker": "SPY",
"type": "BUTTERFLY_VALUE",
"upper_strike": 785.0
},
{
"butterfly_cost": 0.77,
"edge": "1098.7% potential return",
"edge_pct": 1098.7013,
"expiration": "2026-09-15",
"lower_strike": 765.0,
"max_profit": 9.23,
"middle_strike": 770.0,
"option_type": "CALL",
"risk_reward": 11.987,
"strategy": "Buy call butterfly at 770.0",
"ticker": "SPY",
"type": "BUTTERFLY_VALUE",
"upper_strike": 775.0
}
],
"calendar_spreads": [],
"put_call_parity_violations": [],
"skew_trades": [
{
"atm_iv": 9.11,
"atm_strike": 770.0,
"edge": "12.5 IV points of skew",
"expiration": "2026-09-15",
"iv_unit": "percentage_points",
"otm_iv": 21.58,
"otm_strike": 710.0,
"skew": 12.47,
"skew_pct": 136.8825,
"strategy": "Sell OTM put skew",
"ticker": "SPY",
"type": "PUT_SKEW_TRADE"
},
{
"atm_iv": 10.1,
"atm_strike": 770.0,
"edge": "11.7 IV points of skew",
"expiration": "2026-09-16",
"iv_unit": "percentage_points",
"otm_iv": 21.81,
"otm_strike": 710.0,
"skew": 11.71,
"skew_pct": 115.9406,
"strategy": "Sell OTM put skew",
"ticker": "SPY",
"type": "PUT_SKEW_TRADE"
},
{
"call_iv": 14.46,
"call_strike": 830.0,
"edge": "7.3 IV points asymmetry",
"expiration": "2026-09-16",
"iv_unit": "percentage_points",
"put_iv": 21.81,
"put_strike": 710.0,
"skew_asymmetry": 7.35,
"strategy": "Sell put / Buy call",
"ticker": "SPY",
"type": "RISK_REVERSAL"
}
],
"success": true,
"ticker": "SPY",
"timestamp": "2026-09-08T08:07:56.079469",
"total_opportunities": 9
}
}
```'
operationId: get_vol_arb_scan
parameters:
- description: 'Which chain to scan. Range: symbol.'
in: query
name: ticker
required: false
schema:
default: SPY
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/GetVolArbScanResponse'
success:
type: boolean
type: object
description: 'Success: payload under `data` with `success: true`.'
'400':
description: A parameter is malformed; the error names it.
'401':
description: Missing, invalid, expired or revoked token.
'403':
description: The endpoint needs a higher plan than the token's owner has (required_tier in the body).
'404':
description: Unknown path (did_you_mean in the body) or a symbol with no listed options.
'424':
description: The data feed did not answer for this symbol; retry.
'429':
description: Per-token rate limit or the monthly allowance (budget_exceeded). Retry-After says how long, in seconds.
summary: Volatility-arbitrage scan
tags:
- Screeners
components:
schemas:
GetRelativeValueScanResponse:
properties:
results:
items:
properties:
avg_opt_volume:
type: number
chg_1w:
type: number
days_to_earnings:
type:
- string
- 'null'
direction:
type: string
iv_percentile:
type: number
iv_spy_ratio:
type: number
iv_spy_ratio_avg_1y:
type: number
market_cap:
type: number
price:
type: number
sector:
type: string
ticker:
type: string
vrp:
type: number
z_score:
type: number
type: object
type: array
threshold:
type: number
total_matches:
type: integer
total_scanned:
type: integer
type: object
GetScreenResponse:
properties:
results:
items:
properties:
asset_type:
type: string
avg_opt_volume:
type: number
beta:
type: number
chg_1m:
type: number
chg_1w:
type: number
contango:
type: number
days_to_earnings:
type: integer
hv20d:
type: number
imp_earn_move:
type: number
iv30d:
type: number
iv60d:
type: number
iv_percentile:
type: integer
market_cap:
type: string
market_cap_raw:
type: number
next_earnings:
type: string
price:
type: number
sector:
type: string
skew_pctile:
type: number
stock_volume:
type: integer
ticker:
type: string
vrp:
type:
- string
- 'null'
type: object
type: array
scan_time:
type: string
screen_description:
type: string
screen_name:
type: string
screen_type:
type: string
total_results:
type: integer
total_scanned:
type: integer
universe_size:
type: integer
type: object
GetVolArbScanResponse:
properties:
butterfly_mispricings:
items:
properties:
butterfly_cost:
type: number
edge:
type: string
edge_pct:
type: number
expiration:
type: string
lower_strike:
type: number
max_profit:
type: number
middle_strike:
type: number
option_type:
type: string
risk_reward:
type: number
strategy:
type: string
ticker:
type: string
type:
type: string
upper_strike:
type: number
type: object
type: array
calendar_spreads:
items: {}
type: array
put_call_parity_violations:
items: {}
type: array
skew_trades:
items:
properties:
atm_iv:
type: number
atm_strike:
type: number
edge:
type: string
expiration:
type: string
iv_unit:
type: string
otm_iv:
type: number
otm_strike:
type: number
skew:
type: number
skew_pct:
type: number
strategy:
type: string
ticker:
type: string
type:
type: string
type: object
type: array
success:
type: boolean
ticker:
type: string
timestamp:
type: string
total_opportunities:
type: integer
type: object
GetMarketOverviewResponse:
properties:
earnings_this_week:
items:
properties:
capGroup:
type: string
days_to_earnings:
type: integer
hv20d:
type: number
iv30d:
type: number
iv_percentile:
type: number
market_cap:
type: string
next_earnings:
type: string
price:
type: number
sector:
type: string
ticker:
type: string
vrp:
type: number
type: object
type: array
index_prices:
properties:
DJX:
properties:
chg1m:
type: number
chg1w:
type: number
chg_today:
type: integer
iv30d:
type: number
name:
type: string
price:
type: number
type: object
NDX:
properties:
chg1m:
type: number
chg1w:
type: number
chg_today:
type: integer
iv30d:
type: number
name:
type: string
price:
type: number
type: object
SPX:
properties:
chg1m:
type: number
chg1w:
type: number
chg_today:
type: integer
iv30d:
type: number
name:
type: string
price:
type: number
type: object
VIX:
properties:
chg1m:
type: number
chg1w:
type: number
chg_today:
type: integer
iv30d:
type: number
name:
type: string
price:
type: number
type: object
type: object
market_stats:
properties:
avg_contango:
type: number
avg_iv30d:
type: number
avg_iv_percentile:
type: number
avg_put_call_ratio:
type: number
avg_vrp:
type: number
market_regime:
type: string
median_iv_percentile:
type: number
pct_high_iv:
type: number
regime_color:
type: string
total_options_oi:
type: integer
total_options_vol:
type: integer
total_tickers:
type: integer
type: object
put_skew:
properties:
avg_skew_pctile:
type: number
avg_slope:
type: number
avg_slope_1y:
type: number
type: object
scan_time:
type: string
sector_heatmap:
items:
properties:
avg_contango:
type: number
avg_iv30d:
type: number
avg_iv_percentile:
type: number
avg_vrp:
type: number
sector:
type: string
ticker_count:
type: integer
type: object
type: array
top_movers:
items:
properties:
capGroup:
type: string
iv30d:
type: number
iv_percentile:
type: number
market_cap:
type: string
price:
type: number
sector:
type: string
ticker:
type: string
vrp:
type: number
type: object
type: array
treasury_rates:
properties:
^FVX:
properties:
chg_bps:
type: number
name:
type: string
yield:
type: number
type: object
^TNX:
properties:
chg_bps:
type: number
name:
type: string
yield:
type: number
type: object
^TYX:
properties:
chg_bps:
type: number
name:
type: string
yield:
type: number
type: object
type: object
vol_breadth:
properties:
pct_contango_positive:
type: number
pct_iv_above_hv:
type: number
pct_iv_pctile_above_50:
type: number
type: object
type: object
securitySchemes:
bearerAuth:
description: ApexVol API token (avmcp_...) from apexvol.com/account, API Access.
scheme: bearer
type: http