# ApexVol API & MCP — Reference for Claude

> Self-contained reference for the ApexVol options-analytics API. Save this file in your project (e.g. as `apexvol-api.md`, or next to your `CLAUDE.md`) so Claude can implement against it.

- **Base URL:** `https://apexvol.com`
- **Auth:** send `Authorization: Bearer avmcp_<token>` on every request (any paid or trial plan from Basic; each endpoint follows the same tier as the web app)
- **Docs version:** 1.17
- **Updated:** 8 September 2026

## Overview

Two ways to reach the same data, both using one API token from any paid or trial plan:

- **REST API** — Bearer-token HTTP endpoints under `/api/mcp/data/*`. Call them from any language.
- **MCP server** — the `apexvol-mcp` client that exposes those endpoints to Claude as natural-language tools. It calls the same REST API under the hood, so anything below you can also just ask Claude for.

## Authentication

- Every request: `Authorization: Bearer avmcp_…`
- Tokens require an active **Pro** subscription — create and manage them yourself under **Account → API Access** on apexvol.com.
- Pasting your token into your local Claude config (or a private setup chat) is the intended, safe way to wire this up. You only need to rotate a token if it is exposed somewhere **public** — a committed file, a shared screenshot, or a public post.
- Create or rotate tokens any time under **Account → API Access**; a revoked token returns `401` immediately, so generate a fresh one and update `APEXVOL_API_TOKEN`.

## Response format & errors

- **Success:** `{ "success": true, "data": { … } }`
- **Error:** `{ "success": false, "error": "message" }` with an HTTP status:

| Status | Meaning |
|--------|---------|
| `401` | Missing, malformed, expired, or revoked token |
| `403` | Valid token but not entitled — `beta_required` (no API access) or `tier_required: pro` (not on Pro) |
| `426` | `upgrade_required` — your `apexvol-mcp` client is below the minimum supported version |
| `429` | Rate limit (60/min or 1000/hr per token), or `budget_exceeded` (monthly API capacity reached) |
| `5xx` | Server error |

**Rate limits:** 60 requests/minute and 1000/hour per token, plus an aggregate monthly usage cap. Back off and retry on `429`.

## Index symbols (SPX, NDX, RUT, VIX, XSP, DJX)

Cash-settled index symbols are supported, but behave differently from equities — two gotchas to handle if you build against them (e.g. an SPX pre-market brief):

- **Price is a forward, not spot.** The price field returned on chain/strike data is the parity-implied **forward** for that expiration, not the index spot. On an index this can sit **20–30 points above spot**. Use the **nearest expiration's** value as your spot/ATM proxy, and don't compare it directly to a live index quote.
- **Use the index root, not an ETF proxy.** Query `SPX` (not `SPY`) when you want the cash index; the two have different levels, multipliers, and settlement.

## Using it in Claude (MCP)

Install the client from PyPI:

```bash
pipx install apexvol-mcp   # or: pip install apexvol-mcp
```

To update later, `pipx upgrade apexvol-mcp` (or `pip install -U apexvol-mcp`). A `426 upgrade_required` response means your client is below the minimum supported version — upgrade to fix.

Add to Claude Code (`.mcp.json`) or Claude Desktop config:

```json
{
  "mcpServers": {
    "apexvol": {
      "command": "apexvol-mcp",
      "env": { "APEXVOL_API_TOKEN": "avmcp_YOUR_TOKEN_HERE" }
    }
  }
}
```

Then ask Claude, e.g. *"What's the IV rank for SPY?"* or *"Build an iron condor on AAPL."*

## Calling the REST API directly (Python)

A minimal client that handles the three conventions every endpoint shares — the `Bearer` header, `429` back-off, and unwrapping `data` / raising on `success: false`. Build your own helpers on top of `get()`.

```python
import os, time, requests


class ApexVolClient:
    """Minimal client for the ApexVol token API."""
    BASE = "https://apexvol.com/api/mcp/data"

    def __init__(self, token):
        self.s = requests.Session()
        self.s.headers["Authorization"] = f"Bearer {token}"

    def get(self, path, **params):
        for attempt in range(4):
            r = self.s.get(f"{self.BASE}{path}", params=params, timeout=30)
            if r.status_code == 429:              # rate limited -> back off and retry
                time.sleep(2 ** attempt)          # 1s, 2s, 4s, 8s
                continue
            r.raise_for_status()                  # 401 / 403 / 5xx -> exception
            body = r.json()
            if not body.get("success"):           # {"success": false, "error": "..."}
                raise RuntimeError(body.get("error", "request failed"))
            return body["data"]                   # hand back just the payload
        raise RuntimeError("rate-limited after retries")


client = ApexVolClient(os.environ["APEXVOL_API_TOKEN"])
gex = client.get("/gex/SPX")            # one endpoint
ivr = client.get("/iv-rank/AAPL")       # another
# now write your own logic (e.g. spx_premarket_brief) on top of client.get()
```

## Claude tools

In Claude, the integration exposes these tools (each maps to an endpoint below):

| Category | Tools |
|----------|-------|
| Options chain | `get_options_chain, get_expirations, get_options_by_delta, get_stock_price, calculate_expected_move, get_historical_chain` |
| Volatility | `get_iv_rank, get_volatility_cone, get_volatility_risk_premium, get_term_structure, find_iv_opportunities, get_vix_snapshot, get_monies_surface` |
| Greeks & GEX | `get_gex, get_charm_exposure, get_third_order_greeks, get_greeks_heatmap, get_cross_index_gex` |
| Options flow | `get_options_flow, get_smart_money_flow, scan_volatility_arb` |
| Strategy | `build_strategy, analyze_strategy, optimize_strategy, simulate_option_chain, calculate_probability_of_profit` |
| Risk | `calculate_portfolio_greeks, run_scenario_analysis, generate_stress_tests, get_hedge_recommendations` |
| Events & screening | `get_earnings_calendar, analyze_earnings_history, screen_market, get_market_overview, get_economic_calendar` |
| Ticker analytics | `get_ticker_analytics (skew, dividends, borrow_rate, correlation, hv_regimes, price_context, relative_value, greeks_exposure), get_earnings_move_analysis (mispricing, historical_moves, expected_vs_actual, verdict, seasonality, post_drift, iv_crush), get_max_pain, get_volume_profile, get_zero_dte, get_orats_cores, search_tickers, scan_relative_value` |

## Endpoints

60 endpoints. All paths are relative to `https://apexvol.com` and require the Bearer header.

### `GET /api/mcp/data/`

Endpoint index: every endpoint with its method, path, plan, parameter summary, docs URL and a working example request, plus the family list and links to the OpenAPI spec and the Markdown reference. Read from the endpoint records behind the developer pages. No market-data cost.

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

Response (GET /api/mcp/data/, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "endpoint_count": 60,
    "version": 1,
    "updated": "2026-09-08",
    "docs": "https://apexvol.com/docs/api",
    "openapi": "https://apexvol.com/docs/api/openapi.json",
    "markdown": "https://apexvol.com/llms-full.txt",
    "families": [
      {
        "slug": "implied-volatility-api",
        "name": "Implied volatility",
        "endpoint_count": 11,
        "docs": "https://apexvol.com/developers/implied-volatility-api"
      },
      {
        "slug": "options-chain-api",
        "name": "Options chain",
        "endpoint_count": 7,
        "docs": "https://apexvol.com/developers/options-chain-api"
      },
      {
        "slug": "options-greeks-api",
        "name": "Options Greeks",
        "endpoint_count": 3,
        "docs": "https://apexvol.com/developers/options-greeks-api"
      }
    ],
    "endpoints": [
      {
        "method": "GET",
        "path": "/api/mcp/data/hv-regimes/{ticker}",
        "family": "implied-volatility-api",
        "one_liner": "Historical volatility across windows, its term structure and the regime crossovers.",
        "tier": "premium",
        "params": "view=dashboard, days=252",
        "docs": "https://apexvol.com/developers/implied-volatility-api/hv-regimes",
        "example": "GET /api/mcp/data/hv-regimes/NVDA"
      },
      {
        "method": "GET",
        "path": "/api/mcp/data/iv-opportunities/{ticker}",
        "family": "implied-volatility-api",
        "one_liner": "IV mean-reversion read: z-score, reversion target and the expected IV change.",
        "tier": "premium",
        "params": "",
        "docs": "https://apexvol.com/developers/implied-volatility-api/iv-opportunities",
        "example": "GET /api/mcp/data/iv-opportunities/NVDA"
      },
      {
        "method": "GET",
        "path": "/api/mcp/data/iv-rank/{ticker}",
        "family": "implied-volatility-api",
        "one_liner": "IV rank and IV percentile against the last year, with the range they were measured on.",
        "tier": "premium",
        "params": "lookback_days=252",
        "docs": "https://apexvol.com/developers/implied-volatility-api/iv-rank",
        "example": "GET /api/mcp/data/iv-rank/NVDA"
      }
    ]
  }
}
```

### `GET /api/mcp/data/chain/<ticker>`

Formatted options chain(s). {ticker, stock_price, expirations, chains, strike_window}. Defaults to the nearest expiration and a near-the-money strike window; strike_window.truncated tells you when rows were trimmed.

**Parameters:** expiration (optional, YYYY-MM-DD; overrides num_expirations) · num_expirations (optional, default 1, max 10) · strikes_around (optional, default 20 strikes per side of the money; 0 = full chain)

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

Response (GET /api/mcp/data/chain/NVDA?num_expirations=1, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "chains": {
      "2026-09-09": [
        {
          "Call Ask": 4.55,
          "Call Bid": 4.45,
          "Delta Call": 0.6607,
          "Delta Put": -0.3393,
          "Epsilon Call": -0.0208,
          "Epsilon Put": -0.0208,
          "Extrinsic Call": 1.7,
          "Extrinsic Put": 1.62,
          "Gamma Call": 0.0509,
          "Gamma Put": 0.0509,
          "IV Call": 0.266,
          "IV Put": 0.2645,
          "IVx Call": 0.7382,
          "IVx Put": 1.9192,
          "OI Call": 5032,
          "OI Put": 1774,
          "Put Ask": 1.64,
          "Put Bid": 1.61,
          "Rho Call": 0.0202,
          "Rho Put": -0.0109,
          "Strike": 227.5,
          "Theta Call": -0.2734,
          "Theta Put": -0.2734,
          "Vega Call": 0.1003,
          "Vega Put": 0.1003,
          "Volume Call": 5829,
          "Volume Put": 17517
        },
        {
          "Call Ask": 3.0,
          "Call Bid": 2.92,
          "Delta Call": 0.5266,
          "Delta Put": -0.4734,
          "Epsilon Call": -0.0166,
          "Epsilon Put": -0.0166,
          "Extrinsic Call": 2.66,
          "Extrinsic Put": 2.62,
          "Gamma Call": 0.0568,
          "Gamma Put": 0.0568,
          "IV Call": 0.258,
          "IV Put": 0.2594,
          "IVx Call": 1.155,
          "IVx Put": 1.2679,
          "OI Call": 20341,
          "OI Put": 1454,
          "Put Ask": 2.65,
          "Put Bid": 2.58,
          "Rho Call": 0.0162,
          "Rho Put": -0.0153,
          "Strike": 230.0,
          "Theta Call": -0.2871,
          "Theta Put": -0.2871,
          "Vega Call": 0.1074,
          "Vega Put": 0.1074,
          "Volume Call": 34581,
          "Volume Put": 35665
        },
        {
          "Call Ask": 1.85,
          "Call Bid": 1.81,
          "Delta Call": 0.3856,
          "Delta Put": -0.6144,
          "Epsilon Call": -0.0122,
          "Epsilon Put": -0.0122,
          "Extrinsic Call": 1.83,
          "Extrinsic Put": 1.75,
          "Gamma Call": 0.0552,
          "Gamma Put": 0.0552,
          "IV Call": 0.2561,
          "IV Put": 0.254,
          "IVx Call": 1.7499,
          "IVx Put": 0.7599,
          "OI Call": 7568,
          "OI Put": 226,
          "Put Ask": 4.0,
          "Put Bid": 3.9,
          "Rho Call": 0.0119,
          "Rho Put": -0.0199,
          "Strike": 232.5,
          "Theta Call": -0.2719,
          "Theta Put": -0.2719,
          "Vega Call": 0.1021,
          "Vega Put": 0.1021,
          "Volume Call": 46211,
          "Volume Put": 24057
        }
      ]
    },
    "data_type": "LIVE",
    "expirations": [
      "2026-09-09"
    ],
    "stock_price": 230.3,
    "strike_window": {
      "note": "Chain trimmed to strikes nearest the money; pass strikes_around=0 for the full chain.",
      "strikes_around": 20,
      "truncated": true
    },
    "ticker": "NVDA"
  }
}
```

### `GET /api/mcp/data/chain-at-time/<ticker>`

Historical EOD chain snapshot for a past trade date — how the chain was priced on that day.

**Parameters:** expiration (required, YYYY-MM-DD) · trade_date (required, YYYY-MM-DD)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/chain-at-time/AAPL"
```

Response (GET /api/mcp/data/chain-at-time/SPY?expiration=2026-08-21&trade_date=2026-08-14, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "calls": [
      {
        "ask": 4.75,
        "bid": 4.69,
        "delta": 0.5747,
        "epsilon": -0.0857,
        "expiration": "2026-08-21",
        "gamma": 0.0436,
        "implied_vol": 0.0895,
        "open_interest": 54326,
        "rho": 0.0848,
        "right": "C",
        "strike": 775,
        "theta": -0.3008,
        "underlying_price": 776.07,
        "vega": 0.4203,
        "volume": 6045
      },
      {
        "ask": 4.14,
        "bid": 4.12,
        "delta": 0.5315,
        "epsilon": -0.0792,
        "expiration": "2026-08-21",
        "gamma": 0.0452,
        "implied_vol": 0.0885,
        "open_interest": 5227,
        "rho": 0.0785,
        "right": "C",
        "strike": 776,
        "theta": -0.2954,
        "underlying_price": 776.07,
        "vega": 0.4277,
        "volume": 8446
      },
      {
        "ask": 3.59,
        "bid": 3.57,
        "delta": 0.486,
        "epsilon": -0.0724,
        "expiration": "2026-08-21",
        "gamma": 0.0462,
        "implied_vol": 0.0874,
        "open_interest": 5722,
        "rho": 0.0718,
        "right": "C",
        "strike": 777,
        "theta": -0.2877,
        "underlying_price": 776.07,
        "vega": 0.427,
        "volume": 15012
      }
    ],
    "expiration": "2026-08-21",
    "puts": [
      {
        "ask": 3.13,
        "bid": 3.12,
        "delta": -0.4253,
        "epsilon": -0.0857,
        "expiration": "2026-08-21",
        "gamma": 0.0436,
        "implied_vol": 0.09,
        "open_interest": 6989,
        "rho": -0.0637,
        "right": "P",
        "strike": 775,
        "theta": -0.3008,
        "underlying_price": 776.07,
        "vega": 0.4203,
        "volume": 17977
      },
      {
        "ask": 3.55,
        "bid": 3.53,
        "delta": -0.4685,
        "epsilon": -0.0792,
        "expiration": "2026-08-21",
        "gamma": 0.0452,
        "implied_vol": 0.0889,
        "open_interest": 1969,
        "rho": -0.0702,
        "right": "P",
        "strike": 776,
        "theta": -0.2954,
        "underlying_price": 776.07,
        "vega": 0.4277,
        "volume": 8064
      },
      {
        "ask": 4.0,
        "bid": 3.98,
        "delta": -0.514,
        "epsilon": -0.0724,
        "expiration": "2026-08-21",
        "gamma": 0.0462,
        "implied_vol": 0.0877,
        "open_interest": 2999,
        "rho": -0.0771,
        "right": "P",
        "strike": 777,
        "theta": -0.2877,
        "underlying_price": 776.07,
        "vega": 0.427,
        "volume": 8247
      }
    ],
    "ticker": "SPY",
    "time_of_day": "EOD",
    "trade_date": "2026-08-14",
    "underlying_price": 776.07
  }
}
```

### `GET /api/mcp/data/cores/<ticker>`

Raw our institutional data feed cores analytics — 340+ pre-computed fields per ticker (IV summary metrics, IV/HV stats, slope/contango, earnings-move components, borrow rates, betas, percentiles). Defaults to the curated ~45-field subset the platform screens on. Note: the row contains a NUMERIC field literally named "error" (an smooth volatility model-fit statistic) — it is not a failure signal.

**Parameters:** fields (optional: comma-separated field names, "all" for the entire row, empty = curated subset)

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

Response (GET /api/mcp/data/cores/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "absAvgErnMv": 5.561,
    "assetType": 3,
    "atmIvM1": 32.01,
    "atmIvM2": 33.46,
    "atmIvM3": 37.99,
    "atmIvM4": 37.7,
    "available_field_count": 340,
    "avgOptVolu20d": 3290792.75,
    "beta1m": 3.08,
    "beta1y": 1.93,
    "borrow2yr": 3.32,
    "borrow30": 3.42,
    "cOi": 8454385,
    "cVolu": 3549509,
    "clsHv20d": 44.92,
    "clsHvXern20d": 33.94,
    "contango": 1.26,
    "correlSpy1m": 0.49,
    "correlSpy1y": 0.41,
    "daysToNextErn": 0,
    "divYield": 0.4,
    "dlt25Iv30d": 32.6,
    "dlt75Iv30d": 34.55,
    "dtExM1": 15,
    "dtExM2": 43,
    "dtExM3": 78,
    "dtExM4": 106,
    "ernMvStdv": 4.4168,
    "exErnIv30d": 33.05,
    "impErnMv": 7.82,
    "impliedEarningsMove": 6,
    "iv30d": 33.05,
    "iv60d": 35.83,
    "ivHvXernRatio": 1.03,
    "ivHvXernRatio1y": 0.9,
    "ivHvXernRatioStdv1y": 6.49,
    "ivPctile1y": 12,
    "ivSpyRatio": 2.7984,
    "ivSpyRatioAvg1y": 2.37,
    "mktCap": 5561054100,
    "nextErn": "0000-00-00",
    "orHv20d": 37.86,
    "pOi": 7571013,
    "pVolu": 1906366,
    "pxCls": 228.45,
    "sectorName": "Technology",
    "slope": 1.2147,
    "slopeavg1y": 2.1043,
    "slopepctile": 25.79,
    "stkPxChng1m": 5.05,
    "stkPxChng1wk": 5.86,
    "stkVolu": 6443150,
    "ticker": "NVDA",
    "tkOver": 0,
    "tradeDate": "2026-09-04"
  }
}
```

### `GET /api/mcp/data/expirations/<ticker>`

Available expiration dates.

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

Response (GET /api/mcp/data/expirations/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "expirations": [
      "2026-09-09",
      "2026-09-11",
      "2026-09-14"
    ]
  }
}
```

### `GET /api/mcp/data/search`

Ticker search / validation over the platform's coverage universe — resolve company names to symbols and check support before deeper calls.

**Parameters:** q (required) · limit (default 8, max 20)

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

Response (GET /api/mcp/data/search?q=nvidia, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "count": 1,
    "exact_match": null,
    "query": "nvidia",
    "results": [
      {
        "market_cap_tier": "Mega Cap",
        "name": "NVIDIA Corporation",
        "sector": "Technology",
        "symbol": "NVDA"
      }
    ],
    "supported": false
  }
}
```

### `GET /api/mcp/data/options-by-delta/<ticker>`

The contract closest to a target delta: strike, actual delta, IV, bid/ask/mid. iv is the chain row's decimal (0.2592) and is declared as iv_units: decimal; iv_pct carries the same value in percentage points (25.92).

**Parameters:** delta (default 0.30), option_type ∈ call | put (default call), expiration (optional)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/options-by-delta/AAPL"
```

Response (GET /api/mcp/data/options-by-delta/NVDA?delta=0.30&option_type=call, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "actual_delta": 0.2609,
    "ask": 1.08,
    "bid": 1.05,
    "expiration": "2026-09-09",
    "iv": 0.2569,
    "iv_pct": 25.69,
    "iv_units": "decimal",
    "mid": 1.065,
    "option_type": "call",
    "stock_price": 230.3,
    "strike": 235.0,
    "target_delta": 0.3,
    "ticker": "NVDA"
  }
}
```

### `GET /api/mcp/data/stock/<ticker>`

Current price (live quote mid) and company stats. Carries company_name from the coverage registry when the ticker is known; bid/ask are not part of this payload (price is the mid of the nearest-expiration parity quote).

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

Response (GET /api/mcp/data/stock/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "beta": "1.93",
    "company_name": "NVIDIA Corporation",
    "earnings_date": null,
    "industry": "Technology",
    "market_cap": "$5.56T",
    "price": 230.3,
    "sector": "Technology",
    "volume": "6,443,150"
  }
}
```

### `GET /api/mcp/data/expected-move/<ticker>`

Expected move from straddle pricing: $ and %, upper/lower bounds, DTE.

**Parameters:** expiration (optional; skips same-day expiry)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/expected-move/AAPL"
```

Response (GET /api/mcp/data/expected-move/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "dte": 1,
    "expected_move_dollars": 5.58,
    "expected_move_percent": 2.42,
    "expiration": "2026-09-09",
    "lower_bound": 224.73,
    "stock_price": 230.3,
    "ticker": "NVDA",
    "upper_bound": 235.88
  }
}
```

### `GET /api/mcp/data/iv-rank/<ticker>`

IV rank and percentile. Carries iv_basis (the IV-rank series), iv30d (the platform's 30-day constant-maturity IV, for reconciling with /vrp) and iv_percentile_source; iv_percentile equals iv_percentile_1y (cores ivPctile1y).

**Parameters:** lookback_days (default 252; 20 to 1260, clamped)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/iv-rank/AAPL"
```

Response (GET /api/mcp/data/iv-rank/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "current_iv": 34.43,
    "data_source": "iv_rank_1y",
    "historical_data_points": 252,
    "is_full_year": true,
    "iv30d": 33.05,
    "iv_basis": "vendor_ivrank_series",
    "iv_max_52w": 48.38,
    "iv_mean": 38.53,
    "iv_median": 38.39,
    "iv_min_52w": 32.01,
    "iv_percentile": 12.0,
    "iv_percentile_1m": 66.67,
    "iv_percentile_1y": 12,
    "iv_percentile_source": "cores_ivPctile1y",
    "iv_rank": 14.79,
    "iv_rank_1m": 54.08,
    "iv_rank_1y": 14.79,
    "iv_state": "VERY_LOW",
    "iv_std": 3.31,
    "iv_stdv_from_mean": -1.49,
    "iv_units": "percentage_points",
    "lookback_days": 252,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T05:06:35.749922"
  }
}
```

### `GET /api/mcp/data/volatility-cone/<ticker>`

Volatility cone data. Per-tenor IVs are chain-interpolated (iv_basis); iv30d carries the vendor 30-day figure for reconciliation; each tenor row has earnings_in_window and rv_ex_earnings, and the top level has realized_vol_30d_ex_earnings.

**Parameters:** periods (CSV, default 10,20,30,60,90; each 2 to 252, at most 8)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/volatility-cone/AAPL"
```

Response (GET /api/mcp/data/volatility-cone/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "current_iv": 33.73,
    "earnings_in_window": true,
    "hv_basis": "close_to_close_log_returns_annualized_252",
    "iv30d": 33.05,
    "iv_basis": "chain_interpolated_per_tenor",
    "iv_units": "percentage_points",
    "realized_vol_30d": 45.0597,
    "realized_vol_30d_ex_earnings": 38.2226,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T07:49:01.919949",
    "volatility_cone": {
      "10d": {
        "current_rv": 58.3175,
        "difference": -25.9975,
        "earnings_in_window": true,
        "iv": 32.32,
        "iv_to_rv_ratio": 0.5542,
        "max": 58.9167,
        "mean_rv": 38.6147,
        "median_rv": 39.1835,
        "min": 16.5158,
        "p10": 25.6954,
        "p25": 31.1498,
        "p75": 45.0427,
        "p90": 51.8898,
        "period": 10,
        "rv": 58.3175,
        "rv_ex_earnings": 39.8305
      },
      "20d": {
        "current_rv": 44.8025,
        "difference": -12.3025,
        "earnings_in_window": true,
        "iv": 32.5,
        "iv_to_rv_ratio": 0.7254,
        "max": 47.3461,
        "mean_rv": 39.23,
        "median_rv": 39.0719,
        "min": 25.8829,
        "p10": 33.2992,
        "p25": 35.8786,
        "p75": 43.5439,
        "p90": 45.5091,
        "period": 20,
        "rv": 44.8025,
        "rv_ex_earnings": 33.7829
      },
      "30d": {
        "current_rv": 45.0597,
        "difference": -11.3297,
        "earnings_in_window": true,
        "iv": 33.73,
        "iv_to_rv_ratio": 0.7486,
        "max": 47.4467,
        "mean_rv": 39.283,
        "median_rv": 39.2371,
        "min": 31.5777,
        "p10": 34.3931,
        "p25": 36.8516,
        "p75": 41.6358,
        "p90": 44.5353,
        "period": 30,
        "rv": 45.0597,
        "rv_ex_earnings": 38.2226
      },
      "60d": {
        "current_rv": 40.5623,
        "difference": -2.1623,
        "earnings_in_window": true,
        "iv": 38.4,
        "iv_to_rv_ratio": 0.9467,
        "max": 42.965,
        "mean_rv": 39.3644,
        "median_rv": 40.1113,
        "min": 34.9747,
        "p10": 36.5381,
        "p25": 37.2865,
        "p75": 40.9827,
        "p90": 41.8987,
        "period": 60,
        "rv": 40.5623,
        "rv_ex_earnings": 37.6954
      },
      "90d": {
        "current_rv": 42.1894,
        "difference": -4.1694,
        "earnings_in_window": true,
        "iv": 38.02,
        "iv_to_rv_ratio": 0.9012,
        "max": 42.9185,
        "mean_rv": 39.4155,
        "median_rv": 39.3601,
        "min": 36.2709,
        "p10": 37.9139,
        "p25": 38.6209,
        "p75": 40.1866,
        "p90": 40.704,
        "period": 90,
        "rv": 42.1894,
        "rv_ex_earnings": 40.3067
      }
    }
  }
}
```

### `GET /api/mcp/data/vrp/<ticker>`

Volatility risk premium (IV − RV). IV is cores iv30d (iv_basis); realized vol is the std of exactly lookback_days close-to-close log returns (hv_basis, hv_window); earnings_in_window plus realized_volatility_ex_earnings and volatility_risk_premium_ex_earnings when a report sits inside the window.

**Parameters:** lookback_days (default 30; 5 to 252)

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

Response (GET /api/mcp/data/vrp/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

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

### `GET /api/mcp/data/vrp/<ticker>/timeseries`

IV vs HV time series — the volatility risk premium through time. Values in percentage points (iv_units). Same bases as /vrp (iv_basis, hv_basis keys).

**Parameters:** lookback_days (optional, default 60; 10 to 504) · hv_period (optional, default 30; 5 to 252)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/vrp/AAPL/timeseries"
```

Response (GET /api/mcp/data/vrp/NVDA/timeseries?lookback_days=60, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "as_of": "2026-09-08T08:07:00.490425",
    "current": {
      "hv": 45.06,
      "hv_period": 30,
      "iv": 33.05,
      "vrp": -12.01
    },
    "hv_basis": "close_to_close_log_returns_annualized_252",
    "iv_basis": "iv30d_constant_maturity_eod",
    "iv_units": "percentage_points",
    "ticker": "NVDA",
    "timeseries": [
      {
        "date": "2026-07-24",
        "hv": 36.17,
        "iv": 40.05,
        "vrp": 3.88
      },
      {
        "date": "2026-07-27",
        "hv": 38.63,
        "iv": 44.02,
        "vrp": 5.39
      },
      {
        "date": "2026-07-28",
        "hv": 38.64,
        "iv": 44.53,
        "vrp": 5.89
      }
    ]
  }
}
```

### `GET /api/mcp/data/vrp/<ticker>/expirations`

VRP broken down per expiration — where on the curve the premium sits.

**Parameters:** max_expirations (optional, default 10; 1 to 30)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/vrp/AAPL/expirations"
```

Response (GET /api/mcp/data/vrp/NVDA/expirations?max_expirations=6, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "as_of": "2026-09-08T08:06:55.731276",
    "avg_vrp": -10.47,
    "iv_units": "percentage_points",
    "regime": "UNDERPRICED",
    "regime_desc": "Options are significantly underpriced relative to historical moves.",
    "stock_price": 230.3,
    "ticker": "NVDA",
    "vrp_by_expiration": [
      {
        "dte": 1,
        "expiration": "2026-09-09",
        "hv": 27.24,
        "iv": 25.87,
        "signal": "NEUTRAL",
        "vrp": -1.37,
        "vrp_pct": -5.0
      },
      {
        "dte": 3,
        "expiration": "2026-09-11",
        "hv": 27.24,
        "iv": 30.44,
        "signal": "NEUTRAL",
        "vrp": 3.2,
        "vrp_pct": 11.7
      },
      {
        "dte": 6,
        "expiration": "2026-09-14",
        "hv": 27.24,
        "iv": 28.78,
        "signal": "NEUTRAL",
        "vrp": 1.54,
        "vrp_pct": 5.6
      }
    ]
  }
}
```

### `GET /api/mcp/data/vix`

VIX snapshot: level, change, and term-structure state.

**Parameters:** None

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

Response (GET /api/mcp/data/vix, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "change": 0.46,
    "change_pct": 3.0065,
    "close": 15.76,
    "high": 15.76,
    "low": 15.55,
    "open": 15.56,
    "prev_close": 15.3,
    "price": 15.76,
    "timestamp": "2026-09-08T08:06:51.441954"
  }
}
```

### `GET /api/mcp/data/term-structure/<ticker>`

IV term structure across expirations.

**Parameters:** — · num_expirations (default 8; 1 to 20)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/term-structure/AAPL"
```

Response (GET /api/mcp/data/term-structure/SPY, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "as_of": "2026-09-08T07:48:58.063902",
    "iv_units": "percentage_points",
    "stock_price": 770.25,
    "term_structure": [
      {
        "atm_iv": 5.92,
        "atm_strike": 770.0,
        "dte": 0,
        "expected_move_dollar": 3.82,
        "expected_move_pct": 0.5,
        "expiration": "2026-09-08",
        "iv_expected_move_dollar": 0.0,
        "iv_expected_move_pct": 0.0,
        "lower_1sigma": 766.43,
        "lower_2sigma": 762.61,
        "straddle_call": 1.98,
        "straddle_price": 3.82,
        "straddle_put": 1.84,
        "upper_1sigma": 774.07,
        "upper_2sigma": 777.89
      },
      {
        "atm_iv": 7.09,
        "atm_strike": 770.0,
        "dte": 1,
        "expected_move_dollar": 5.12,
        "expected_move_pct": 0.66,
        "expiration": "2026-09-09",
        "iv_expected_move_dollar": 2.86,
        "iv_expected_move_pct": 0.37,
        "lower_1sigma": 765.14,
        "lower_2sigma": 760.02,
        "straddle_call": 2.66,
        "straddle_price": 5.12,
        "straddle_put": 2.45,
        "upper_1sigma": 775.36,
        "upper_2sigma": 780.48
      },
      {
        "atm_iv": 8.06,
        "atm_strike": 770.0,
        "dte": 2,
        "expected_move_dollar": 6.38,
        "expected_move_pct": 0.83,
        "expiration": "2026-09-10",
        "iv_expected_move_dollar": 4.6,
        "iv_expected_move_pct": 0.6,
        "lower_1sigma": 763.88,
        "lower_2sigma": 757.5,
        "straddle_call": 3.3,
        "straddle_price": 6.38,
        "straddle_put": 3.08,
        "upper_1sigma": 776.62,
        "upper_2sigma": 783.0
      }
    ],
    "ticker": "SPY"
  }
}
```

### `GET /api/mcp/data/iv-opportunities/<ticker>`

IV mean-reversion opportunities.

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/iv-opportunities/AAPL"
```

Response (GET /api/mcp/data/iv-opportunities/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "current_iv": 34.43,
    "expected_iv_move": 0,
    "expected_pct_change": 0.0,
    "iv_percentile": 12.0,
    "iv_rank": 14.79,
    "iv_units": "percentage_points",
    "mean_iv": 38.53,
    "opportunity": "NO_EXTREME",
    "reversion_target": 34.43,
    "std_iv": 3.31,
    "term_structure": [
      {
        "expiration": "2026-09-09",
        "iv": 25.87,
        "z_score": -3.8248
      },
      {
        "expiration": "2026-09-11",
        "iv": 30.44,
        "z_score": -2.4441
      },
      {
        "expiration": "2026-09-14",
        "iv": 28.78,
        "z_score": -2.9456
      }
    ],
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:06:45.029743",
    "z_score": -1.2387
  }
}
```

### `GET /api/mcp/data/gex/<ticker>`

Gamma exposure data. Under compact detail gex_by_strike and gex_profile are windowed around spot; window says what was trimmed.

**Parameters:** expiration (optional), aggregate (default true) · detail (compact | full; default compact for MCP clients, full for REST) · strikes_around (default 25 per side under compact; 0 = all)

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

Response (GET /api/mcp/data/gex/SPY?detail=compact&strikes_around=8, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "by_expiration": [
      {
        "call_gex": 1132995456.8335,
        "expiration": "2026-09-08",
        "flip_level": null,
        "max_gamma_strike": 770,
        "min_gamma_strike": 771,
        "put_gex": -1178772712.3059,
        "stock_price": 770.25,
        "total_gex": -45777255.4724
      },
      {
        "call_gex": 631787389.7441,
        "expiration": "2026-09-09",
        "flip_level": null,
        "max_gamma_strike": 766,
        "min_gamma_strike": 769,
        "put_gex": -735739062.8266,
        "stock_price": 770.25,
        "total_gex": -103951673.0825
      },
      {
        "call_gex": 488040962.8352,
        "expiration": "2026-09-10",
        "flip_level": 777.7584,
        "max_gamma_strike": 775,
        "min_gamma_strike": 770,
        "put_gex": -396093609.9746,
        "stock_price": 770.25,
        "total_gex": 91947352.8606
      }
    ],
    "call_gex": 12388200841.1688,
    "expirations_horizon_days": 90,
    "expirations_included": 16,
    "expirations_selected": [
      "2026-09-08",
      "2026-09-09",
      "2026-09-10"
    ],
    "expirations_through": "2026-11-20",
    "expirations_total": 32,
    "flip_degenerate": false,
    "flip_level": null,
    "gamma_flip": null,
    "gex_by_strike": [
      {
        "gex": -133889311.3072,
        "oi": 27515,
        "strike": 769
      },
      {
        "gex": -52445836.8019,
        "oi": 121480,
        "strike": 770
      },
      {
        "gex": -73315508.5296,
        "oi": 23312,
        "strike": 771
      }
    ],
    "gex_profile": [
      {
        "call_gex": 237808150.3447494,
        "net_gex": -133889311.30720633,
        "put_gex": -371697461.6519557,
        "strike": 769
      },
      {
        "call_gex": 980618910.3369881,
        "net_gex": -52445836.80189216,
        "put_gex": -1033064747.1388803,
        "strike": 770
      },
      {
        "call_gex": 253439508.7709778,
        "net_gex": -73315508.52959651,
        "put_gex": -326755017.3005743,
        "strike": 771
      }
    ],
    "gex_ratio": 0.7932,
    "implications": {
      "directional_bias": "Balanced (call/put GEX 0.79)",
      "net_to_gross": -0.1153,
      "pin_at_spot": false,
      "positioning": "largest strike $760.00 (-1.3%); call wall $775.00 (+0.6%); put wall $760.00 (-1.3%)",
      "regime_code": "negative",
      "support_resistance": "--",
      "volatility_regime": "Negative GEX (dealers amplify moves)"
    },
    "key_levels": {
      "call_wall": 775.0,
      "call_wall_unconstrained": false,
      "call_wall_value": 969364047.7614,
      "flip_degenerate": false,
      "flip_level": null,
      "key_strike": 760.0,
      "key_strike_net": 1376738203.7852,
      "max_pain": null,
      "put_wall": 760.0,
      "put_wall_unconstrained": false,
      "put_wall_value": 1809628588.0631,
      "spot": 770.25
    },
    "max_gex_strike": 760,
    "put_gex": -15618693641.3721,
    "stock_price": 770.25,
    "ticker": "SPY",
    "total_gex": -3230492800.2033,
    "total_gex_billions": -3.2305,
    "window": {
      "detail": "compact",
      "lists": {
        "gex_by_strike": {
          "rows_returned": 17,
          "rows_total": 329,
          "truncated": true
        },
        "gex_profile": {
          "rows_returned": 17,
          "rows_total": 329,
          "truncated": true
        }
      },
      "strikes_around": 8
    }
  }
}
```

### `GET /api/mcp/data/charm/<ticker>`

Charm (delta-decay) exposure.

**Parameters:** expiration (optional)

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

Response (GET /api/mcp/data/charm/SPY, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "call_charm": 10023682.817,
    "charm_by_strike": [
      {
        "charm_exposure": 18249098.4446,
        "oi": 2372,
        "strike": 769
      },
      {
        "charm_exposure": 16525084.9209,
        "oi": 9544,
        "strike": 770
      },
      {
        "charm_exposure": -28726617.7301,
        "oi": 4457,
        "strike": 771
      }
    ],
    "data_status": "LIVE",
    "detailed": [
      {
        "charm": 17.7856,
        "charm_exposure": 10989702.8596,
        "iv": 0.0568,
        "oi": 6179,
        "strike": 770,
        "type": "C"
      },
      {
        "charm": 16.4499,
        "charm_exposure": 5535382.0614,
        "iv": 0.0615,
        "oi": 3365,
        "strike": 770,
        "type": "P"
      },
      {
        "charm": -67.7526,
        "charm_exposure": -9824127.9754,
        "iv": 0.0556,
        "oi": 1450,
        "strike": 771,
        "type": "C"
      }
    ],
    "dte": 0,
    "expiration": "2026-09-08",
    "put_charm": -4591755.8741,
    "stock_price": 770.25,
    "ticker": "SPY",
    "total_charm": 5431926.943
  }
}
```

### `GET /api/mcp/data/third-order-greeks/<ticker>`

Speed, zomma, color, vomma, ultima.

**Parameters:** expiration (optional)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/third-order-greeks/AAPL"
```

Response (GET /api/mcp/data/third-order-greeks/SPY, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "data_status": "LIVE",
    "definitions": {
      "charm": "dDelta/dTime - Delta decay over time",
      "color": "dGamma/dTime - How gamma changes as time passes",
      "speed": "dGamma/dSpot - Rate of change of gamma with spot price",
      "ultima": "dVomma/dVol - Third derivative wrt volatility",
      "vanna": "dDelta/dVol - Delta sensitivity to volatility",
      "vomma": "dVega/dVol - Convexity of vega (volga)",
      "zomma": "dGamma/dVol - Sensitivity of gamma to volatility changes"
    },
    "detailed": [
      {
        "charm": 17.7874,
        "color": -87.5795,
        "iv": 0.0568,
        "speed": -0.0285,
        "strike": 770,
        "type": "C",
        "ultima": -3.5317,
        "vanna": -1.2757,
        "vomma": 0.0677,
        "zomma": -4.129
      },
      {
        "charm": 16.4516,
        "color": -81.4013,
        "iv": 0.0615,
        "speed": -0.0226,
        "strike": 770,
        "type": "P",
        "ultima": -2.5843,
        "vanna": -1.0907,
        "vomma": 0.0535,
        "zomma": -3.552
      },
      {
        "charm": -67.758,
        "color": -65.5505,
        "iv": 0.0556,
        "speed": 0.0641,
        "strike": 771,
        "type": "C",
        "ultima": -18.3207,
        "vanna": 2.8936,
        "vomma": 0.3634,
        "zomma": -3.3136
      }
    ],
    "dte": 0,
    "expiration": "2026-09-08",
    "greeks_by_strike": [
      {
        "charm": 76.9258,
        "color": -30.0987,
        "speed": -0.0772,
        "strike": 769,
        "ultima": -32.2742,
        "vanna": -3.7337,
        "vomma": 0.8049,
        "zomma": -1.2163
      },
      {
        "charm": 17.1195,
        "color": -84.4904,
        "speed": -0.0256,
        "strike": 770,
        "ultima": -3.058,
        "vanna": -1.1832,
        "vomma": 0.0606,
        "zomma": -3.8405
      },
      {
        "charm": -65.3123,
        "color": -64.6529,
        "speed": 0.0567,
        "strike": 771,
        "ultima": -15.6858,
        "vanna": 2.6714,
        "vomma": 0.3219,
        "zomma": -3.1162
      }
    ],
    "stock_price": 770.25,
    "ticker": "SPY"
  }
}
```

### `GET /api/mcp/data/greeks-heatmap/<ticker>`

Greeks heatmap across strikes and expirations (all Greeks; pick the one you need from the result).

**Parameters:** option_type (default calls)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/greeks-heatmap/AAPL"
```

Response (GET /api/mcp/data/greeks-heatmap/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "aggregates": {
      "charm": {
        "by_expiration": [
          -92401.1106,
          -242908.5109,
          -7145.8524
        ],
        "by_strike": [
          5190.4907,
          76.8262,
          9861.3066
        ]
      },
      "delta": {
        "by_expiration": [
          3546428.01,
          10557890.51,
          727504.27
        ],
        "by_strike": [
          1090601.21,
          15281.14,
          2807343.01
        ]
      },
      "gamma": {
        "by_expiration": [
          375676.8438,
          725053.3309,
          53555.5989
        ],
        "by_strike": [
          251.0156,
          2.0766,
          1635.0796
        ]
      },
      "rho": {
        "by_expiration": [
          108122.08,
          337183.04,
          38718.26
        ],
        "by_strike": [
          71678.42,
          670.55,
          198218.26
        ]
      },
      "theta": {
        "by_expiration": [
          -2007981.62,
          -4739399.08,
          -290533.85
        ],
        "by_strike": [
          -4464.65,
          -29.7,
          -22074.51
        ]
      },
      "vanna": {
        "by_expiration": [
          657303.858,
          4607537.5648,
          228262.6166
        ],
        "by_strike": [
          -145440.2013,
          -1200.6728,
          -370078.0536
        ]
      },
      "vega": {
        "by_expiration": [
          725724.59,
          2246953.63,
          211792.29
        ],
        "by_strike": [
          2597.99,
          13.2,
          12797.51
        ]
      }
    },
    "as_of": "2026-09-08T07:49:22.291337+00:00",
    "data_points": 192,
    "earnings_date": null,
    "expirations": [
      "Sep 09 (1 DTE)",
      "Sep 11 (3 DTE)",
      "Sep 14 (6 DTE)"
    ],
    "expirations_raw": [
      "2026-09-09",
      "2026-09-11",
      "2026-09-14"
    ],
    "greek_matrices": {
      "charm": [
        [
          0.035,
          0.0008,
          0.0367
        ],
        [
          0.0242,
          0.0287,
          0.0065
        ],
        [
          0.0158,
          null,
          0.0059
        ]
      ],
      "delta": [
        [
          0.9998,
          0.9998,
          0.9998
        ],
        [
          1.0,
          1.0,
          1.0
        ],
        [
          0.9976,
          null,
          0.9923
        ]
      ],
      "gamma": [
        [
          0.0,
          0.0,
          0.0
        ],
        [
          0.0,
          0.0,
          0.0
        ],
        [
          0.0007,
          null,
          0.0014
        ]
      ],
      "iv": [
        [
          1.9166,
          1.0773,
          1.6971
        ],
        [
          1.4744,
          1.5669,
          0.85
        ],
        [
          1.4007,
          null,
          0.6896
        ]
      ],
      "rho": [
        [
          0.0253,
          0.0257,
          0.026
        ],
        [
          0.0,
          0.0,
          0.0
        ],
        [
          0.0077,
          null,
          0.0157
        ]
      ],
      "theta": [
        [
          -0.0,
          -0.0,
          -0.0
        ],
        [
          -0.0,
          -0.0,
          -0.0
        ],
        [
          -0.0055,
          null,
          -0.017
        ]
      ],
      "vanna": [
        [
          -0.0366,
          -0.0016,
          -0.0433
        ],
        [
          -0.099,
          -0.1104,
          -0.0459
        ],
        [
          -0.1363,
          null,
          -0.1033
        ]
      ],
      "vega": [
        [
          0.0,
          0.0,
          0.0
        ],
        [
          0.0,
          0.0,
          0.0
        ],
        [
          0.003,
          null,
          0.0073
        ]
      ]
    },
    "greek_matrix": [
      [
        0.9998,
        0.9998,
        0.9998
      ],
      [
        1.0,
        1.0,
        1.0
      ],
      [
        0.9976,
        null,
        0.9923
      ]
    ],
    "greek_type": "delta",
    "levels": {
      "max_pain": 222.5,
      "max_pain_expiration": "2026-09-09",
      "oi_call_wall": 240.0,
      "oi_put_wall": 200.0
    },
    "option_type": "calls",
    "stock_price": 230.3,
    "strikes": [
      185.0,
      187.5,
      190.0
    ],
    "ticker": "NVDA"
  }
}
```

### `GET /api/mcp/data/cross-index-gex`

GEX comparison across indices.

**Parameters:** tickers (CSV, default SPY,QQQ,IWM,DIA)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/cross-index-gex?ticker=AAPL"
```

Response (GET /api/mcp/data/cross-index-gex, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "comparison": {
      "DIA": {
        "flip_level": 549.4243,
        "normalized_gex": 109665.9343,
        "stock_price": 533.74,
        "total_gex": 58533095.7487
      },
      "IWM": {
        "flip_level": null,
        "normalized_gex": -7440286.7267,
        "stock_price": 295.82,
        "total_gex": -2200985619.4867
      },
      "QQQ": {
        "flip_level": null,
        "normalized_gex": -32228.4822,
        "stock_price": 718.88,
        "total_gex": -23168411.3125
      },
      "SPY": {
        "flip_level": null,
        "normalized_gex": -4194083.4797,
        "stock_price": 770.25,
        "total_gex": -3230492800.2033
      }
    },
    "indices": {
      "DIA": {
        "call_gex": 408125500.9471,
        "expirations_horizon_days": 90,
        "expirations_included": 9,
        "expirations_through": "2026-11-20",
        "expirations_total": 20,
        "flip_degenerate": false,
        "flip_level": 549.4243,
        "gamma_flip": 549.4243,
        "gex_ratio": 1.1674,
        "implications": {
          "directional_bias": "Balanced (call/put GEX 1.17)",
          "net_to_gross": 0.0772,
          "pin_at_spot": false,
          "positioning": "largest strike $540.00 (+1.2%); call wall $540.00 (+1.2%); put wall $530.00 (-0.7%); flip $549.42 (+2.9%)",
          "regime_code": "balanced",
          "support_resistance": "Flip at $549.42 (2.9% above spot): hedging amplifies moves below it, dampens above",
          "volatility_regime": "Balanced GEX (net 7.7% of gross, no dominant side)"
        },
        "key_levels": {
          "call_wall": 540.0,
          "call_wall_unconstrained": false,
          "call_wall_value": 75356308.6812,
          "flip_degenerate": false,
          "flip_level": 549.4243,
          "key_strike": 540.0,
          "key_strike_net": 68976896.8278,
          "max_pain": null,
          "put_wall": 530.0,
          "put_wall_unconstrained": false,
          "put_wall_value": 44256843.2937,
          "spot": 533.74
        },
        "max_gex_strike": 540.0,
        "normalized_gex": 109665.9343,
        "put_gex": -349592405.1984,
        "stock_price": 533.74,
        "ticker": "DIA",
        "total_gex": 58533095.7487,
        "total_gex_billions": 0.0585
      },
      "IWM": {
        "call_gex": 2098181483.3277,
        "expirations_horizon_days": 90,
        "expirations_included": 16,
        "expirations_through": "2026-11-20",
        "expirations_total": 30,
        "flip_degenerate": false,
        "flip_level": null,
        "gamma_flip": null,
        "gex_ratio": 0.488,
        "implications": {
          "directional_bias": "Put-heavy (call/put GEX 0.49)",
          "net_to_gross": -0.344,
          "pin_at_spot": false,
          "positioning": "largest strike $290.00 (-2.0%); call wall $300.00 (+1.4%); put wall $290.00 (-2.0%)",
          "regime_code": "negative",
          "support_resistance": "--",
          "volatility_regime": "Negative GEX (dealers amplify moves)"
        },
        "key_levels": {
          "call_wall": 300.0,
          "call_wall_unconstrained": false,
          "call_wall_value": 354716869.761,
          "flip_degenerate": false,
          "flip_level": null,
          "key_strike": 290.0,
          "key_strike_net": 609426189.0504,
          "max_pain": null,
          "put_wall": 290.0,
          "put_wall_unconstrained": false,
          "put_wall_value": 720542331.6019,
          "spot": 295.82
        },
        "max_gex_strike": 290,
        "normalized_gex": -7440286.7267,
        "put_gex": -4299167102.8144,
        "stock_price": 295.82,
        "ticker": "IWM",
        "total_gex": -2200985619.4867,
        "total_gex_billions": -2.201
      },
      "QQQ": {
        "call_gex": 7556293659.4015,
        "expirations_horizon_days": 90,
        "expirations_included": 16,
        "expirations_through": "2026-11-20",
        "expirations_total": 31,
        "flip_degenerate": false,
        "flip_level": null,
        "gamma_flip": null,
        "gex_ratio": 0.9969,
        "implications": {
          "directional_bias": "Balanced (call/put GEX 1.00)",
          "net_to_gross": -0.0015,
          "pin_at_spot": false,
          "positioning": "largest strike $700.00 (-2.6%); call wall $730.00 (+1.5%); put wall $700.00 (-2.6%)",
          "regime_code": "balanced",
          "support_resistance": "--",
          "volatility_regime": "Balanced GEX (net 0.2% of gross, no dominant side)"
        },
        "key_levels": {
          "call_wall": 730.0,
          "call_wall_unconstrained": false,
          "call_wall_value": 666241251.0777,
          "flip_degenerate": false,
          "flip_level": null,
          "key_strike": 700.0,
          "key_strike_net": 670370841.253,
          "max_pain": null,
          "put_wall": 700.0,
          "put_wall_unconstrained": false,
          "put_wall_value": 936624637.4421,
          "spot": 718.88
        },
        "max_gex_strike": 700,
        "normalized_gex": -32228.4822,
        "put_gex": -7579462070.714,
        "stock_price": 718.88,
        "ticker": "QQQ",
        "total_gex": -23168411.3125,
        "total_gex_billions": -0.0232
      },
      "SPY": {
        "call_gex": 12388200841.1688,
        "expirations_horizon_days": 90,
        "expirations_included": 16,
        "expirations_through": "2026-11-20",
        "expirations_total": 32,
        "flip_degenerate": false,
        "flip_level": null,
        "gamma_flip": null,
        "gex_ratio": 0.7932,
        "implications": {
          "directional_bias": "Balanced (call/put GEX 0.79)",
          "net_to_gross": -0.1153,
          "pin_at_spot": false,
          "positioning": "largest strike $760.00 (-1.3%); call wall $775.00 (+0.6%); put wall $760.00 (-1.3%)",
          "regime_code": "negative",
          "support_resistance": "--",
          "volatility_regime": "Negative GEX (dealers amplify moves)"
        },
        "key_levels": {
          "call_wall": 775.0,
          "call_wall_unconstrained": false,
          "call_wall_value": 969364047.7614,
          "flip_degenerate": false,
          "flip_level": null,
          "key_strike": 760.0,
          "key_strike_net": 1376738203.7852,
          "max_pain": null,
          "put_wall": 760.0,
          "put_wall_unconstrained": false,
          "put_wall_value": 1809628588.0631,
          "spot": 770.25
        },
        "max_gex_strike": 760,
        "normalized_gex": -4194083.4797,
        "put_gex": -15618693641.3721,
        "stock_price": 770.25,
        "ticker": "SPY",
        "total_gex": -3230492800.2033,
        "total_gex_billions": -3.2305
      }
    }
  }
}
```

### `GET /api/mcp/data/flow/<ticker>`

Options flow and unusual activity. Under compact detail the row lists are capped; window says what was trimmed. The summary block is never trimmed.

**Parameters:** detail (compact | full; default compact for MCP clients, full for REST) · limit (all_flow rows under compact, default 25; largest_flows and unusual_activity capped at 10)

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

Response (GET /api/mcp/data/flow/NVDA?detail=compact&limit=5, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "all_flow": [
      {
        "ask": 10.15,
        "bid": 10.05,
        "delta": -0.4599,
        "dte": 38,
        "expiration": "2026-10-16",
        "is_unusual": false,
        "mid": 10.100000000000001,
        "moneyness": "OTM",
        "oi": 6669,
        "premium": 11948300.000000002,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.681049",
        "type": "PUT",
        "volume": 11830,
        "volume_oi_ratio": 1.773879142300195
      },
      {
        "ask": 4.0,
        "bid": 3.95,
        "delta": 0.5173,
        "dte": 3,
        "expiration": "2026-09-11",
        "is_unusual": false,
        "mid": 3.975,
        "moneyness": "ITM",
        "oi": 32787,
        "premium": 10783380.0,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.542239",
        "type": "CALL",
        "volume": 27128,
        "volume_oi_ratio": 0.8274011040961357
      },
      {
        "ask": 6.05,
        "bid": 5.95,
        "delta": 0.5225,
        "dte": 10,
        "expiration": "2026-09-18",
        "is_unusual": false,
        "mid": 6.0,
        "moneyness": "ITM",
        "oi": 57448,
        "premium": 10345800.0,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.600692",
        "type": "CALL",
        "volume": 17243,
        "volume_oi_ratio": 0.3001497005988024
      }
    ],
    "data_freshness": "EOD",
    "is_market_hours": false,
    "largest_flows": [
      {
        "ask": 10.15,
        "bid": 10.05,
        "delta": -0.4599,
        "dte": 38,
        "expiration": "2026-10-16",
        "is_unusual": false,
        "mid": 10.1,
        "moneyness": "OTM",
        "oi": 6669,
        "premium": 11948300.0,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.681049",
        "type": "PUT",
        "volume": 11830,
        "volume_oi_ratio": 1.7739
      },
      {
        "ask": 4.0,
        "bid": 3.95,
        "delta": 0.5173,
        "dte": 3,
        "expiration": "2026-09-11",
        "is_unusual": false,
        "mid": 3.975,
        "moneyness": "ITM",
        "oi": 32787,
        "premium": 10783380.0,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.542239",
        "type": "CALL",
        "volume": 27128,
        "volume_oi_ratio": 0.8274
      },
      {
        "ask": 6.05,
        "bid": 5.95,
        "delta": 0.5225,
        "dte": 10,
        "expiration": "2026-09-18",
        "is_unusual": false,
        "mid": 6.0,
        "moneyness": "ITM",
        "oi": 57448,
        "premium": 10345800.0,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.600692",
        "type": "CALL",
        "volume": 17243,
        "volume_oi_ratio": 0.3001
      }
    ],
    "message": "Market is closed. Showing end-of-day data from the most recent trading session.",
    "stock_price": 230.3,
    "success": true,
    "summary": {
      "call_put_ratio": 1.9932,
      "net_premium": 172969531.5,
      "put_call_ratio": 0.5017,
      "sentiment": "BULLISH",
      "total_call_premium": 317997531.0,
      "total_call_volume": 1172710.0,
      "total_flow_count": 342,
      "total_put_premium": 145027999.5,
      "total_put_volume": 588346.0
    },
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:24.702149",
    "top_expirations": [
      [
        "2026-09-18",
        {
          "premium": 100034602.0,
          "volume": 283452
        }
      ],
      [
        "2026-09-11",
        {
          "premium": 98571641.0,
          "volume": 539458
        }
      ],
      [
        "2026-10-16",
        {
          "premium": 87886168.0,
          "volume": 170080
        }
      ]
    ],
    "top_strikes": [
      [
        230.0,
        {
          "calls": 100849,
          "premium": 91238806.0,
          "puts": 87969,
          "volume": 188818
        }
      ],
      [
        235.0,
        {
          "calls": 194678,
          "premium": 76153200.5,
          "puts": 30408,
          "volume": 225086
        }
      ],
      [
        232.5,
        {
          "calls": 101063,
          "premium": 42516519.0,
          "puts": 37409,
          "volume": 138472
        }
      ]
    ],
    "unusual_activity": [
      {
        "ask": 2.65,
        "bid": 2.58,
        "delta": -0.4734,
        "dte": 1,
        "expiration": "2026-09-09",
        "is_unusual": true,
        "mid": 2.615,
        "moneyness": "OTM",
        "oi": 1454,
        "premium": 9326397.5,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.518008",
        "type": "PUT",
        "volume": 35665,
        "volume_oi_ratio": 24.5289
      },
      {
        "ask": 3.8,
        "bid": 3.75,
        "delta": -0.4827,
        "dte": 3,
        "expiration": "2026-09-11",
        "is_unusual": true,
        "mid": 3.775,
        "moneyness": "OTM",
        "oi": 2231,
        "premium": 8328782.5,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.542254",
        "type": "PUT",
        "volume": 22063,
        "volume_oi_ratio": 9.8893
      },
      {
        "ask": 4.0,
        "bid": 3.9,
        "delta": -0.6144,
        "dte": 1,
        "expiration": "2026-09-09",
        "is_unusual": true,
        "mid": 3.95,
        "moneyness": "ITM",
        "oi": 226,
        "premium": 9502515.0,
        "strike": 232.5,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.518071",
        "type": "PUT",
        "volume": 24057,
        "volume_oi_ratio": 106.4469
      }
    ],
    "window": {
      "detail": "compact",
      "limit": 5,
      "lists": {
        "all_flow": {
          "rows_returned": 5,
          "rows_total": 100,
          "truncated": true
        },
        "largest_flows": {
          "rows_returned": 5,
          "rows_total": 20,
          "truncated": true
        },
        "unusual_activity": {
          "rows_returned": 5,
          "rows_total": 20,
          "truncated": true
        }
      }
    }
  }
}
```

### `GET /api/mcp/data/smart-money/<ticker>`

Smart-money / institutional flow.

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/smart-money/AAPL"
```

Response (GET /api/mcp/data/smart-money/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "smart_money_trades": [
      {
        "ask": 4.0,
        "bid": 3.95,
        "criteria": [
          "Large Premium",
          "Opening Position",
          "OTM with Time"
        ],
        "delta": 0.2642,
        "dte": 38,
        "expiration": "2026-10-16",
        "is_unusual": false,
        "mid": 3.975,
        "moneyness": "OTM",
        "oi": 69150,
        "premium": 5400037.5,
        "smart_money_score": 8,
        "strike": 250.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:26.352058",
        "type": "CALL",
        "volume": 13585,
        "volume_oi_ratio": 0.1965
      },
      {
        "ask": 0.74,
        "bid": 0.72,
        "criteria": [
          "Large Premium",
          "Opening Position",
          "Aggressive Entry"
        ],
        "delta": 0.104,
        "dte": 10,
        "expiration": "2026-09-18",
        "is_unusual": false,
        "mid": 0.73,
        "moneyness": "OTM",
        "oi": 87596,
        "premium": 2234457.0,
        "smart_money_score": 7,
        "strike": 250.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:26.279270",
        "type": "CALL",
        "volume": 30609,
        "volume_oi_ratio": 0.3494
      },
      {
        "ask": 2.25,
        "bid": 2.19,
        "criteria": [
          "Large Premium",
          "Opening Position",
          "OTM with Time"
        ],
        "delta": 0.1801,
        "dte": 38,
        "expiration": "2026-10-16",
        "is_unusual": false,
        "mid": 2.22,
        "moneyness": "OTM",
        "oi": 31871,
        "premium": 1314240.0,
        "smart_money_score": 8,
        "strike": 260.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:26.352193",
        "type": "CALL",
        "volume": 5920,
        "volume_oi_ratio": 0.1857
      }
    ],
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:26.381762",
    "total_smart_trades": 99
  }
}
```

### `GET /api/mcp/data/vol-arb-scan`

Volatility-arbitrage scan.

**Parameters:** ticker (default SPY)

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

Response (GET /api/mcp/data/vol-arb-scan, captured 2026-09-08. Lists are cut to the rows nearest the money.):

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

### `POST /api/mcp/data/build-strategy`

Builds a strategy from live chain data. Returns the legs (strike, premium, Greeks) plus full analysis (net premium/Greeks, max profit/loss, breakevens, POP, P&L curve).

**Parameters:** JSON: ticker, strategy_type (required); expiration, dte (default 30), width (default 5), target_delta (default 0.30)

```bash
curl -X POST "https://apexvol.com/api/mcp/data/build-strategy" \
     -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "ticker": "AAPL" }'
```

Response (POST /api/mcp/data/build-strategy, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "analysis": {
      "breakevens": [
        752.48,
        787.52
      ],
      "legs_summary": [
        {
          "action": "SELL",
          "expiration": "2026-10-09",
          "iv": 0.1365,
          "premium": 6.36,
          "quantity": 1,
          "strike": 755.0,
          "type": "PUT"
        },
        {
          "action": "SELL",
          "expiration": "2026-10-09",
          "iv": 0.1084,
          "premium": 4.785,
          "quantity": 1,
          "strike": 785.0,
          "type": "CALL"
        },
        {
          "action": "BUY",
          "expiration": "2026-10-09",
          "iv": 0.1062,
          "premium": 3.275,
          "quantity": 1,
          "strike": 790.0,
          "type": "CALL"
        }
      ],
      "max_loss": -248.0,
      "max_profit": 252.0,
      "net_delta": -0.0256,
      "net_premium": -252.0,
      "net_theta": 0.0232,
      "net_vega": -0.1904,
      "pnl_curve": [
        [
          600.0,
          -248.0
        ],
        [
          603.5152,
          -248.0
        ],
        [
          607.0303,
          -248.0
        ]
      ],
      "probability_of_profit": 41.7,
      "risk_reward_ratio": 1.0161,
      "stock_price": 770.25,
      "strategy_name": "Iron Condor",
      "ticker": "SPY"
    },
    "created_at": "2026-09-08T08:06:42.457860",
    "legs": [
      {
        "action": "SELL",
        "delta": -0.3014,
        "expiration": "2026-10-09",
        "iv": 0.1365,
        "premium": 6.36,
        "quantity": 1,
        "strike": 755.0,
        "theta": -0.1785,
        "type": "PUT",
        "vega": 0.8379
      },
      {
        "action": "SELL",
        "delta": 0.297,
        "expiration": "2026-10-09",
        "iv": 0.1084,
        "premium": 4.785,
        "quantity": 1,
        "strike": 785.0,
        "theta": -0.1318,
        "type": "CALL",
        "vega": 0.8329
      },
      {
        "action": "BUY",
        "delta": 0.2281,
        "expiration": "2026-10-09",
        "iv": 0.1062,
        "premium": 3.275,
        "quantity": 1,
        "strike": 790.0,
        "theta": -0.1136,
        "type": "CALL",
        "vega": 0.735
      }
    ],
    "name": "Iron Condor",
    "stock_price": 770.25,
    "ticker": "SPY"
  }
}
```

### `POST /api/mcp/data/analyze-strategy`

Analyzes custom legs: net premium and Greeks, max profit/loss, breakevens, probability of profit, and the P&L curve. Fetches live spot when stock_price is omitted.

**Parameters:** JSON: ticker, legs [{type CALL|PUT, action BUY|SELL, strike, expiration, premium, quantity?, delta?, theta?, vega?, iv?}] — required; stock_price?, name?

```bash
curl -X POST "https://apexvol.com/api/mcp/data/analyze-strategy" \
     -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "ticker": "AAPL" }'
```

Response (POST /api/mcp/data/analyze-strategy, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "breakevens": [
      752.48,
      787.52
    ],
    "legs_summary": [
      {
        "action": "SELL",
        "expiration": "2026-10-09",
        "iv": 0.1365,
        "premium": 6.36,
        "quantity": 1,
        "strike": 755.0,
        "type": "PUT"
      },
      {
        "action": "SELL",
        "expiration": "2026-10-09",
        "iv": 0.1084,
        "premium": 4.785,
        "quantity": 1,
        "strike": 785.0,
        "type": "CALL"
      },
      {
        "action": "BUY",
        "expiration": "2026-10-09",
        "iv": 0.1062,
        "premium": 3.275,
        "quantity": 1,
        "strike": 790.0,
        "type": "CALL"
      }
    ],
    "max_loss": -248.0,
    "max_profit": 252.0,
    "net_delta": -0.0256,
    "net_premium": -252.0,
    "net_theta": 0.0232,
    "net_vega": -0.1904,
    "pnl_curve": [
      [
        600.0,
        -248.0
      ],
      [
        603.5152,
        -248.0
      ],
      [
        607.0303,
        -248.0
      ]
    ],
    "probability_of_profit": 41.7,
    "risk_reward_ratio": 1.0161,
    "stock_price": 770.25,
    "strategy_name": "Iron condor from /build-strategy",
    "ticker": "SPY"
  }
}
```

### `POST /api/mcp/data/optimize-strategy`

Grid-searches strikes (iron_condor and credit_spread) and returns the winning strategy with its analysis.

**Parameters:** JSON: ticker, strategy_type (required); target ∈ max_profit | min_loss | risk_reward | probability (default max_profit; other values optimize net credit)

```bash
curl -X POST "https://apexvol.com/api/mcp/data/optimize-strategy" \
     -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "ticker": "AAPL" }'
```

Response (POST /api/mcp/data/optimize-strategy, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "analysis": {
      "breakevens": [
        743.435,
        793.565
      ],
      "legs_summary": [
        {
          "action": "SELL",
          "expiration": "2026-10-09",
          "iv": 0.1433,
          "premium": 5.155,
          "quantity": 1,
          "strike": 749.0,
          "type": "PUT"
        },
        {
          "action": "SELL",
          "expiration": "2026-10-09",
          "iv": 0.1064,
          "premium": 3.805,
          "quantity": 1,
          "strike": 788.0,
          "type": "CALL"
        },
        {
          "action": "BUY",
          "expiration": "2026-10-09",
          "iv": 0.1014,
          "premium": 0.985,
          "quantity": 1,
          "strike": 804.0,
          "type": "CALL"
        }
      ],
      "max_loss": -1943.5,
      "max_profit": 556.5,
      "net_delta": -0.0046,
      "net_premium": -556.5,
      "net_theta": 0.1098,
      "net_vega": -0.6744,
      "pnl_curve": [
        [
          579.2,
          -1943.5
        ],
        [
          583.0949,
          -1943.5
        ],
        [
          586.9899,
          -1943.5
        ]
      ],
      "probability_of_profit": 49.4,
      "risk_reward_ratio": 0.2863,
      "stock_price": 770.25,
      "strategy_name": "Iron Condor",
      "ticker": "SPY"
    },
    "created_at": "2026-09-08T08:07:39.442751",
    "legs": [
      {
        "action": "SELL",
        "delta": -0.2475,
        "expiration": "2026-10-09",
        "iv": 0.1433,
        "premium": 5.155,
        "quantity": 1,
        "strike": 749.0,
        "theta": -0.1721,
        "type": "PUT",
        "vega": 0.7443
      },
      {
        "action": "SELL",
        "delta": 0.2561,
        "expiration": "2026-10-09",
        "iv": 0.1064,
        "premium": 3.805,
        "quantity": 1,
        "strike": 788.0,
        "theta": -0.121,
        "type": "CALL",
        "vega": 0.7869
      },
      {
        "action": "BUY",
        "delta": 0.1014,
        "expiration": "2026-10-09",
        "iv": 0.1014,
        "premium": 0.985,
        "quantity": 1,
        "strike": 804.0,
        "theta": -0.0655,
        "type": "CALL",
        "vega": 0.4502
      }
    ],
    "name": "Iron Condor",
    "optimization_target": "max_profit",
    "stock_price": 770.25,
    "ticker": "SPY"
  }
}
```

### `POST /api/mcp/data/simulate-chain`

Black-Scholes what-if: re-price a chain at a hypothetical stock price, DTE, and IV shift. Pass chain rows from GET /chain, or just ticker (+ optional expiration) and the server fetches the chain.

**Parameters:** JSON body: sim_price (required) · sim_dte (required) · iv_adjustment (percent, default 0) · chain (rows, optional) · ticker/expiration (used when chain omitted) · strikes_around (default 20)

```bash
curl -X POST "https://apexvol.com/api/mcp/data/simulate-chain" \
     -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "ticker": "AAPL" }'
```

Response (POST /api/mcp/data/simulate-chain, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "chain": [
      {
        "Call Ask": 17.7104,
        "Call Bid": 17.6704,
        "Delta Call": 0.9877,
        "Delta Put": -0.0188,
        "Gamma Call": 0.004,
        "Gamma Put": 0.0053,
        "IV Call": 0.0612,
        "IV Put": 0.0663,
        "IVx Call": 0.1324,
        "IVx Put": 0.0076,
        "Put Ask": 0.0694,
        "Put Bid": 0.0494,
        "Strike": 769.0,
        "Theta Call": -0.112,
        "Theta Put": -0.0179,
        "Vega Call": 0.0414,
        "Vega Put": 0.0599
      },
      {
        "Call Ask": 16.7084,
        "Call Bid": 16.6884,
        "Delta Call": 0.9852,
        "Delta Put": -0.0222,
        "Gamma Call": 0.0048,
        "Gamma Put": 0.0063,
        "IV Call": 0.0596,
        "IV Put": 0.0646,
        "IVx Call": 0.1334,
        "IVx Put": 0.0089,
        "Put Ask": 0.0796,
        "Put Bid": 0.0596,
        "Strike": 770.0,
        "Theta Call": -0.1137,
        "Theta Put": -0.0199,
        "Vega Call": 0.0486,
        "Vega Put": 0.0688
      },
      {
        "Call Ask": 15.7199,
        "Call Bid": 15.6999,
        "Delta Call": 0.9816,
        "Delta Put": -0.0282,
        "Gamma Call": 0.0059,
        "Gamma Put": 0.0078,
        "IV Call": 0.0584,
        "IV Put": 0.0639,
        "IVx Call": 0.1349,
        "IVx Put": 0.0115,
        "Put Ask": 0.1005,
        "Put Bid": 0.0805,
        "Strike": 771.0,
        "Theta Call": -0.116,
        "Theta Put": -0.024,
        "Vega Call": 0.0586,
        "Vega Put": 0.0841
      }
    ],
    "expiration": "2026-09-08",
    "iv_adjustment": 5,
    "sim_dte": 10,
    "sim_price": 785.65
  }
}
```

### `POST /api/mcp/data/pop`

Probability of profit for a set of option legs (N(d2)-based).

**Parameters:** JSON body: legs (required: option_type, action, strike, iv, premium, quantity) · stock_price (required) · days_to_exp (required)

```bash
curl -X POST "https://apexvol.com/api/mcp/data/pop" \
     -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "ticker": "AAPL" }'
```

Response (POST /api/mcp/data/pop, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "legs_count": 4,
    "probability_of_profit": 41.7
  }
}
```

### `POST /api/mcp/data/portfolio-greeks`

Aggregate portfolio Greeks with summary risk level and per-ticker breakdown.

**Parameters:** JSON: positions [{ticker, position_type STOCK|CALL|PUT, quantity, strike?, expiration?, entry_price?, current_price?, delta?…}] — required

```bash
curl -X POST "https://apexvol.com/api/mcp/data/portfolio-greeks" \
     -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "ticker": "AAPL" }'
```

Response (POST /api/mcp/data/portfolio-greeks, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "portfolio_summary": {
      "daily_decay_pct": 0.0234,
      "delta_exposure_pct": 130.6218,
      "risk_level": "LOW",
      "total_cost_basis": 0,
      "total_delta": 130.14,
      "total_pnl": 76389.0,
      "total_pnl_pct": 0,
      "total_positions": 2,
      "total_theta": 17.85,
      "total_value": 76389.0,
      "total_vega": -83.79,
      "vega_risk_pct": 0.1097
    },
    "positions_by_ticker": {
      "SPY": {
        "delta": 130.14,
        "positions": [
          {
            "charm": 0,
            "current_price": 6.36,
            "delta": -0.3014,
            "entry_price": 0,
            "expiration": "2026-10-09",
            "gamma": 0,
            "iv": 0.1365,
            "position_type": "PUT",
            "quantity": -1,
            "rho": 0,
            "stock_price": 0,
            "strike": 755.0,
            "theta": -0.1785,
            "ticker": "SPY",
            "vanna": 0,
            "vega": 0.8379,
            "vomma": 0
          }
        ],
        "theta": 17.85,
        "value": 76389.0,
        "vega": -83.79
      }
    },
    "success": true,
    "timestamp": "2026-09-08T08:07:44.450169"
  }
}
```

### `POST /api/mcp/data/scenario-analysis`

What-if scenario analysis across supplied price/vol scenarios.

**Parameters:** JSON: positions (required), scenarios []

```bash
curl -X POST "https://apexvol.com/api/mcp/data/scenario-analysis" \
     -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "ticker": "AAPL" }'
```

Response (POST /api/mcp/data/scenario-analysis, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "current_value": 76389.0,
    "scenarios": [
      {
        "days_forward": 5,
        "delta_contribution": -5797.5674,
        "estimated_pnl": -5928.2762,
        "estimated_pnl_pct": -7.7606,
        "iv_change_pct": 20,
        "new_portfolio_value": 70460.7238,
        "scenario_name": "+-5% stock, 20% IV",
        "stock_move_pct": -5,
        "theta_contribution": 70.2965,
        "vega_contribution": -207.3894
      }
    ],
    "success": true,
    "timestamp": "2026-09-08T08:07:45.686052"
  }
}
```

### `POST /api/mcp/data/stress-tests`

Standardized stress-test battery (crash, vol spike, …) with estimated P&L per scenario.

**Parameters:** JSON: positions (required)

```bash
curl -X POST "https://apexvol.com/api/mcp/data/stress-tests" \
     -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "ticker": "AAPL" }'
```

Response (POST /api/mcp/data/stress-tests, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "current_value": 76389.0,
    "scenarios": [
      {
        "days_forward": 1,
        "delta_contribution": -28472.4537,
        "estimated_pnl": -28491.5651,
        "estimated_pnl_pct": -37.298,
        "iv_change_pct": 100,
        "new_portfolio_value": 47897.4349,
        "scenario_name": "Market Crash (-20%)",
        "stock_move_pct": -20,
        "theta_contribution": 13.583,
        "vega_contribution": -1102.4875
      },
      {
        "days_forward": 1,
        "delta_contribution": -13089.1178,
        "estimated_pnl": -13237.0642,
        "estimated_pnl_pct": -17.3285,
        "iv_change_pct": 50,
        "new_portfolio_value": 63151.9358,
        "scenario_name": "Sharp Decline (-10%)",
        "stock_move_pct": -10,
        "theta_contribution": 13.583,
        "vega_contribution": -534.6292
      },
      {
        "days_forward": 1,
        "delta_contribution": -5797.5674,
        "estimated_pnl": -6028.1085,
        "estimated_pnl_pct": -7.8913,
        "iv_change_pct": 25,
        "new_portfolio_value": 70360.8915,
        "scenario_name": "Moderate Decline (-5%)",
        "stock_move_pct": -5,
        "theta_contribution": 13.583,
        "vega_contribution": -260.8316
      }
    ],
    "success": true,
    "timestamp": "2026-09-08T08:07:46.937252"
  }
}
```

### `POST /api/mcp/data/hedge-recommendations`

Delta-hedge recommendations. Computes net portfolio delta and returns a stock hedge plus an option-based alternative on the hedge ticker to reach the target delta. Share-equivalent (not beta-weighted).

**Parameters:** JSON body: positions (required, same schema as /portfolio-greeks), hedge_ticker (optional, default SPY), target_delta (optional, default 0)

```bash
curl -X POST "https://apexvol.com/api/mcp/data/hedge-recommendations" \
     -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "ticker": "AAPL" }'
```

Response (POST /api/mcp/data/hedge-recommendations, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "current_delta": 130.14,
    "delta_gap": -130.14,
    "hedge_ticker": "SPY",
    "hedges": [
      {
        "action": "BUY",
        "contracts": 3,
        "delta_per_contract": -49.4,
        "description": "BUY 3 SPY 2026-09-30 770 puts",
        "details": "~-49 delta per contract at 9.32 mid (est. cost $2,796).",
        "est_cost": 2796.0,
        "expiration": "2026-09-30",
        "option_type": "put",
        "strike": 770.0,
        "ticker": "SPY",
        "type": "option"
      }
    ],
    "note": "Hedges close a -130 share-equivalent delta gap using SPY. Deltas are NOT beta-weighted: hedging single names with an index proxy needs your own beta scaling.",
    "portfolio_greeks": {
      "daily_decay_pct": 0.0234,
      "delta_exposure_pct": 130.6218,
      "risk_level": "LOW",
      "total_cost_basis": 0,
      "total_delta": 130.14,
      "total_pnl": 76389.0,
      "total_pnl_pct": 0,
      "total_positions": 2,
      "total_theta": 17.85,
      "total_value": 76389.0,
      "total_vega": -83.79,
      "vega_risk_pct": 0.1097
    },
    "projected_greeks": {
      "changes": {
        "delta": {
          "change": -130.0,
          "change_pct": -99.8924,
          "current": 130.14,
          "projected": 0.14
        },
        "gamma": {
          "change": 0.0,
          "change_pct": 0.0,
          "current": -1.3185,
          "projected": -1.3185
        },
        "theta": {
          "change": 0.0,
          "change_pct": 0.0,
          "current": 17.85,
          "projected": 17.85
        },
        "vega": {
          "change": 0.0,
          "change_pct": 0.0,
          "current": -83.79,
          "projected": -83.79
        }
      },
      "current_greeks": {
        "charm": 28.4278,
        "delta": 130.14,
        "gamma": -1.3185,
        "rho": 29.8407,
        "theta": 17.85,
        "vanna": 23.8358,
        "vega": -83.79,
        "vomma": -6.3954
      },
      "current_risk_level": "LOW",
      "hedge_cost": 0,
      "hedge_trades": [
        {
          "position_type": "STOCK",
          "quantity": -130,
          "ticker": "SPY"
        }
      ],
      "projected_greeks": {
        "charm": 28.4278,
        "delta": 0.14,
        "gamma": -1.3185,
        "rho": 29.8407,
        "theta": 17.85,
        "vanna": 23.8358,
        "vega": -83.79,
        "vomma": -6.3954
      },
      "projected_risk_level": "LOW",
      "success": true,
      "timestamp": "2026-09-08T08:07:43.195925"
    },
    "target_delta": 0.0
  }
}
```

### `GET /api/mcp/data/earnings-calendar`

Upcoming earnings announcements, each annotated with the implied earnings move vs the average absolute move over the last 12 earnings (implied_move, hist_avg_move, move_ratio). implied_move is the expected absolute move (the feed's one-sigma figure x 0.8, kept as implied_move_sigma) so it shares hist_avg_move's basis; implied_move_basis says so.

**Parameters:** days_ahead (default 7; 1 to 90)

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

Response (GET /api/mcp/data/earnings-calendar?days_ahead=7, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "earnings": [
      {
        "cap_group": "large",
        "company_name": "Kroger Co.",
        "date": "2026-09-11",
        "datetime": "Fri, 11 Sep 2026 00:00:00 GMT",
        "days_until": 3,
        "eps_actual": null,
        "eps_estimate": 1.05,
        "fiscal_quarter": null,
        "hist_avg_move": 4.72,
        "implied_move": 3.87,
        "implied_move_basis": "expected_abs_move",
        "implied_move_sigma": 4.84,
        "market_cap": 35876625000.0,
        "move_ratio": 0.82,
        "revenue_actual": null,
        "revenue_estimate": 34641620000,
        "sector": "Consumer Staples",
        "symbol": "KR",
        "timing": "BMO",
        "updated": "2026-09-08"
      },
      {
        "cap_group": "mega",
        "company_name": "Oracle Corporation",
        "date": "2026-09-10",
        "datetime": "Thu, 10 Sep 2026 00:00:00 GMT",
        "days_until": 2,
        "eps_actual": null,
        "eps_estimate": 1.74,
        "fiscal_quarter": null,
        "hist_avg_move": 12.5,
        "implied_move": 8.02,
        "implied_move_basis": "expected_abs_move",
        "implied_move_sigma": 10.03,
        "market_cap": 456554654000.0,
        "move_ratio": 0.64,
        "revenue_actual": null,
        "revenue_estimate": 19131390000,
        "sector": "Technology",
        "symbol": "ORCL",
        "timing": "AMC",
        "updated": "2026-09-08"
      },
      {
        "cap_group": "mid",
        "company_name": "",
        "date": "2026-09-08",
        "datetime": "Tue, 08 Sep 2026 00:00:00 GMT",
        "days_until": 0,
        "eps_actual": null,
        "eps_estimate": 0.612,
        "fiscal_quarter": null,
        "hist_avg_move": 13.76,
        "implied_move": 8.36,
        "implied_move_basis": "expected_abs_move",
        "implied_move_sigma": 10.45,
        "market_cap": 2654975000.0,
        "move_ratio": 0.61,
        "revenue_actual": null,
        "revenue_estimate": 7705088000,
        "sector": "",
        "symbol": "UNFI",
        "timing": "TBD",
        "updated": "2026-09-08"
      }
    ],
    "from_date": "2026-09-08",
    "success": true,
    "timestamp": "2026-09-08T08:07:48.281034",
    "to_date": "2026-09-15",
    "total_count": 12
  }
}
```

### `GET /api/mcp/data/economic-calendar`

Macro economic-event calendar (CPI, FOMC, jobs reports...).

**Parameters:** from_date (optional, YYYY-MM-DD) · to_date (optional) · country (default US)

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

Response (GET /api/mcp/data/economic-calendar, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "events": [
      {
        "actual": null,
        "change": null,
        "change_pct": 0,
        "country": "US",
        "currency": "USD",
        "date": "2026-09-09",
        "datetime": "Wed, 09 Sep 2026 16:30:00 GMT",
        "estimate": null,
        "event": "API Crude Oil Stock Change (Sep/04)",
        "impact": "Medium",
        "previous": -2.6,
        "time": "4:30 PM",
        "unit": null
      },
      {
        "actual": null,
        "change": null,
        "change_pct": 0,
        "country": "US",
        "currency": "USD",
        "date": "2026-09-09",
        "datetime": "Wed, 09 Sep 2026 07:00:00 GMT",
        "estimate": null,
        "event": "MBA 30-Year Mortgage Rate (Sep/04)",
        "impact": "Medium",
        "previous": 6.79,
        "time": "7:00 AM",
        "unit": "%"
      },
      {
        "actual": null,
        "change": null,
        "change_pct": 0,
        "country": "US",
        "currency": "USD",
        "date": "2026-09-10",
        "datetime": "Thu, 10 Sep 2026 10:00:00 GMT",
        "estimate": 3.99,
        "event": "Existing Home Sales (Aug)",
        "impact": "High",
        "previous": 4.06,
        "time": "10:00 AM",
        "unit": "M"
      }
    ],
    "high_count": 14,
    "medium_count": 38,
    "success": true,
    "total_count": 52
  }
}
```

### `GET /api/mcp/data/earnings-history/<ticker>`

Historical earnings move analysis.

**Parameters:** — · num_quarters (default 8; 1 to 40)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/earnings-history/AAPL"
```

Response (GET /api/mcp/data/earnings-history/NVDA?num_quarters=8, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "earnings_moves": [
      {
        "direction": "up",
        "earnings_date": "2026-08-26",
        "eps_actual": 2.22,
        "eps_estimate": 2.09,
        "gap_move_dollar": 13.2,
        "gap_move_pct": 6.2959,
        "iv_after": null,
        "iv_before": null,
        "iv_crush": null,
        "iv_crush_pct": null,
        "next_open": 222.86,
        "prev_close": 209.66,
        "surprise_direction": "beat",
        "surprise_pct": 6.2201,
        "timing": "AMC"
      },
      {
        "direction": "down",
        "earnings_date": "2026-05-20",
        "eps_actual": 1.87,
        "eps_estimate": 1.76,
        "gap_move_dollar": -1.18,
        "gap_move_pct": -0.5287,
        "iv_after": null,
        "iv_before": null,
        "iv_crush": null,
        "iv_crush_pct": null,
        "next_open": 222.03,
        "prev_close": 223.21,
        "surprise_direction": "beat",
        "surprise_pct": 6.25,
        "timing": "AMC"
      },
      {
        "direction": "down",
        "earnings_date": "2026-02-25",
        "eps_actual": 1.62,
        "eps_estimate": 1.54,
        "gap_move_dollar": -1.29,
        "gap_move_pct": -0.6605,
        "iv_after": null,
        "iv_before": null,
        "iv_crush": null,
        "iv_crush_pct": null,
        "next_open": 194.03,
        "prev_close": 195.32,
        "surprise_direction": "beat",
        "surprise_pct": 5.1948,
        "timing": "AMC"
      }
    ],
    "statistics": {
      "avg_abs_move_pct": 2.9618,
      "avg_beat_move_pct": 2.557,
      "avg_down_move_pct": -0.5397,
      "avg_iv_crush_pct": null,
      "avg_miss_move_pct": null,
      "avg_move_pct": 2.557,
      "avg_up_move_pct": 4.415,
      "beat_count": 8,
      "down_count": 3,
      "max_down_pct": -0.6605,
      "max_up_pct": 6.2959,
      "median_iv_crush_pct": null,
      "miss_count": 0,
      "total_earnings": 8,
      "up_count": 5
    },
    "success": true,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T07:49:39.004196"
  }
}
```

### `GET /api/mcp/data/earnings-verdict/<ticker>`

Combined buy/sell-the-straddle verdict for the next earnings: expected-move pricing vs realized history, IV crush, and drift rolled into one call.

**Parameters:** None

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/earnings-verdict/AAPL"
```

Response (GET /api/mcp/data/earnings-verdict/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "confidence": {
      "consistency_label": "Moderate",
      "move_consistency_ratio": 0.79,
      "move_range_max": 16.4,
      "move_range_min": 0.53,
      "move_stddev": 4.42,
      "quarters_analyzed": 12,
      "straddle_return_stddev": 1.8
    },
    "direction": {
      "avg_down_move": -4.07,
      "avg_up_move": 7.65,
      "directional_bias": "slight_bearish",
      "down_count": 7,
      "quarters": [
        {
          "date": "2026-08-26",
          "gap_move_pct": 6.3,
          "move": 8.74,
          "straddle_return": 5.9
        },
        {
          "date": "2026-05-20",
          "gap_move_pct": -0.53,
          "move": -1.77,
          "straddle_return": 6.1
        },
        {
          "date": "2026-02-25",
          "gap_move_pct": -0.66,
          "move": -5.46,
          "straddle_return": 6.1
        }
      ],
      "up_count": 5
    },
    "edge": {
      "avg_straddle_return": 8.0,
      "diffusion_move_pct": 13.07,
      "edge_components": {
        "consistency": 20.8,
        "magnitude": 47.8,
        "mispricing": 50.0,
        "variance": 100.0
      },
      "edge_interpretation": "Moderate edge",
      "edge_score": 47.9,
      "event_variance_share": 0.1371,
      "historical_avg_close_to_close_pct": 5.56,
      "historical_avg_move_basis": "gap",
      "historical_avg_move_pct": 3.83,
      "implied_move_atm_strike": 230.0,
      "implied_move_expiration": "2026-11-20",
      "implied_move_model_pct": 4.8,
      "implied_move_model_sigma_pct": 6.0,
      "implied_move_pct": 5.21,
      "implied_move_source": "chain_event",
      "implied_move_straddle_price": 32.4,
      "move_ratio": 1.36,
      "straddle_dte": 73,
      "straddle_forecast_price": 1.44,
      "straddle_hit_rate": 16.6667,
      "straddle_market_price": 1.99,
      "straddle_mispricing_is_event": false,
      "straddle_mispricing_pct": 38.2,
      "straddle_move_pct": 14.07,
      "straddle_smooth_price": 2.03
    },
    "success": true,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:28.913001",
    "timing": {
      "atm_iv": 32.0,
      "current_rv_annual": 37.9,
      "days_to_earnings": 71,
      "earnings_date": "2026-11-18",
      "earnings_exp_atm_iv": 38.08,
      "estimated_iv_after_event": null,
      "estimated_iv_crush_pct": null,
      "expected_move_pct": 11.96,
      "is_earnings_play": false,
      "iv_hv_xern_ratio_1m": 0.91,
      "iv_hv_xern_ratio_1y": 0.9,
      "iv_premium": -5.9,
      "iv_rank": 12.0,
      "preliminary": true,
      "stock_price": 230.3,
      "straddle_m1_spans_event": false,
      "straddle_price": 32.4
    },
    "verdict": {
      "confidence": 33,
      "preliminary": true,
      "reasons": [
        "Report is 71 days out: the 5.2% priced event move is an early read against a 3.8% average gap and is not scored yet",
        "Straddle buyers won only 17% of the last 12 quarters (gap vs breakeven)"
      ],
      "signal": "NO_CLEAR_EDGE",
      "suggested_strategies": [
        "Wait for better setup",
        "Small position if trading"
      ]
    },
    "wings": {
      "butterfly_25d": {
        "earnings": 0.87,
        "reference": 0.46
      },
      "call_skew_25d": {
        "earnings": -0.31,
        "reference": -0.7
      },
      "chart": {
        "deltas": [
          10,
          15,
          20
        ],
        "earnings_smile": [
          38.33,
          37.92,
          37.75
        ],
        "reference_smile": [
          37.73,
          37.21,
          37.02
        ]
      },
      "decomposition": {
        "deltas": [
          5,
          10,
          15
        ],
        "values": [
          0.37,
          0.6,
          0.71
        ]
      },
      "earnings_atm_iv": 37.99,
      "earnings_dte": 73,
      "earnings_exp": "2026-11-20",
      "historical": {
        "avg_butterfly_shift": -0.02,
        "avg_rr_shift": -0.23,
        "count": 8,
        "quarters": [
          {
            "butterfly_shift": -0.03,
            "days": [
              {
                "butterfly": 0.32,
                "date": "2026-08-19",
                "days_before": 7,
                "put_skew_25d": 1.25,
                "risk_reversal": -1.86
              },
              {
                "butterfly": 1.05,
                "date": "2026-08-20",
                "days_before": 6,
                "put_skew_25d": 1.28,
                "risk_reversal": -0.46
              },
              {
                "butterfly": 0.84,
                "date": "2026-08-21",
                "days_before": 5,
                "put_skew_25d": 0.9,
                "risk_reversal": -0.13
              }
            ],
            "earnings_date": "8/26/2026",
            "rr_shift": 1.39
          },
          {
            "butterfly_shift": -0.27,
            "days": [
              {
                "butterfly": 0.59,
                "date": "2026-05-13",
                "days_before": 7,
                "put_skew_25d": 0.2,
                "risk_reversal": 0.78
              },
              {
                "butterfly": 0.6,
                "date": "2026-05-14",
                "days_before": 6,
                "put_skew_25d": -0.62,
                "risk_reversal": 2.45
              },
              {
                "butterfly": 0.54,
                "date": "2026-05-15",
                "days_before": 5,
                "put_skew_25d": 0.16,
                "risk_reversal": 0.76
              }
            ],
            "earnings_date": "5/20/2026",
            "rr_shift": 0.77
          },
          {
            "butterfly_shift": 0.0,
            "days": [
              {
                "butterfly": 0.68,
                "date": "2026-02-18",
                "days_before": 7,
                "put_skew_25d": 4.19,
                "risk_reversal": -7.02
              },
              {
                "butterfly": 0.51,
                "date": "2026-02-19",
                "days_before": 6,
                "put_skew_25d": 3.95,
                "risk_reversal": -6.89
              },
              {
                "butterfly": 0.6,
                "date": "2026-02-20",
                "days_before": 5,
                "put_skew_25d": 4.11,
                "risk_reversal": -7.03
              }
            ],
            "earnings_date": "2/25/2026",
            "rr_shift": -0.7
          }
        ]
      },
      "per_wing_premium": {
        "call": 0.5,
        "put": 0.6
      },
      "put_skew_25d": {
        "distortion": 0.44,
        "earnings": 2.06,
        "reference": 1.62,
        "signal": "Normal skew shape: symmetric risk pricing"
      },
      "reference_atm_iv": 37.7,
      "reference_dte": 101,
      "reference_exp": "2026-12-18",
      "risk_reversal": {
        "earnings": -2.37,
        "reference": -2.32,
        "signal": "Balanced: no strong directional positioning"
      },
      "steepness": {
        "call": 0.08,
        "put": 1.76
      },
      "summary": "Put wings carry +0.6 pts of earnings premium. Call wings carry +0.5 pts. Event risk is priced roughly symmetrically across wings.",
      "tail_risk": {
        "earnings_call_10d": 0.34,
        "earnings_put_10d": 7.06,
        "reference_call_10d": 0.03,
        "reference_put_10d": 6.33
      },
      "tails_5d": {
        "earnings_call_5d": 1.29,
        "earnings_put_5d": 11.07,
        "reference_call_5d": 1.21,
        "reference_put_5d": 11.19
      },
      "term_structure": [
        {
          "dte": -4,
          "expiration": "2026-09-04",
          "is_earnings": false,
          "is_reference": false,
          "premiums": {
            "5": {
              "call": -22.29,
              "put": -22.49
            },
            "10": {
              "call": -22.18,
              "put": -22.6
            },
            "15": {
              "call": -22.08,
              "put": -22.75
            },
            "20": {
              "call": -21.98,
              "put": -22.99
            },
            "25": {
              "call": -21.91,
              "put": -23.4
            },
            "30": {
              "call": -21.93,
              "put": -24.1
            },
            "35": {
              "call": -22.11,
              "put": -24.77
            },
            "40": {
              "call": -22.6,
              "put": -26.41
            },
            "45": {
              "call": -23.74,
              "put": -29.94
            }
          }
        },
        {
          "dte": 1,
          "expiration": "2026-09-09",
          "is_earnings": false,
          "is_reference": false,
          "premiums": {
            "5": {
              "call": -11.93,
              "put": -12.06
            },
            "10": {
              "call": -11.8,
              "put": -12.08
            },
            "15": {
              "call": -11.66,
              "put": -12.08
            },
            "20": {
              "call": -11.49,
              "put": -12.1
            },
            "25": {
              "call": -11.31,
              "put": -12.16
            },
            "30": {
              "call": -11.12,
              "put": -12.34
            },
            "35": {
              "call": -10.91,
              "put": -12.8
            },
            "40": {
              "call": -10.63,
              "put": -13.84
            },
            "45": {
              "call": -9.91,
              "put": -16.4
            }
          }
        },
        {
          "dte": 3,
          "expiration": "2026-09-11",
          "is_earnings": false,
          "is_reference": false,
          "premiums": {
            "5": {
              "call": -7.58,
              "put": -7.59
            },
            "10": {
              "call": -7.48,
              "put": -7.53
            },
            "15": {
              "call": -7.32,
              "put": -7.42
            },
            "20": {
              "call": -7.11,
              "put": -7.34
            },
            "25": {
              "call": -6.86,
              "put": -7.32
            },
            "30": {
              "call": -6.61,
              "put": -7.46
            },
            "35": {
              "call": -6.4,
              "put": -7.97
            },
            "40": {
              "call": -6.3,
              "put": -9.27
            },
            "45": {
              "call": -6.45,
              "put": -12.56
            }
          }
        }
      ]
    }
  }
}
```

### `GET /api/mcp/data/seasonality/<ticker>`

Monthly/quarterly seasonality of returns and volatility.

**Parameters:** years (optional, default 3; 1 to 10)

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

Response (GET /api/mcp/data/seasonality/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "analysis_years": 3,
    "best_month": 5,
    "monthly_seasonality": {
      "1": {
        "avg_return_pct": 0.2741,
        "median_return_pct": 0.471,
        "month": 1,
        "sample_size": 61,
        "volatility_pct": 3.4418
      },
      "2": {
        "avg_return_pct": 0.4343,
        "median_return_pct": 0.3508,
        "month": 2,
        "sample_size": 58,
        "volatility_pct": 3.6276
      },
      "3": {
        "avg_return_pct": 0.0074,
        "median_return_pct": 0.1223,
        "month": 3,
        "sample_size": 63,
        "volatility_pct": 3.0692
      },
      "4": {
        "avg_return_pct": 0.2274,
        "median_return_pct": 0.2521,
        "month": 4,
        "sample_size": 64,
        "volatility_pct": 4.0456
      },
      "5": {
        "avg_return_pct": 0.8471,
        "median_return_pct": 0.4241,
        "month": 5,
        "sample_size": 63,
        "volatility_pct": 2.6655
      },
      "6": {
        "avg_return_pct": 0.4123,
        "median_return_pct": 0.3537,
        "month": 6,
        "sample_size": 60,
        "volatility_pct": 2.7239
      },
      "7": {
        "avg_return_pct": 0.1496,
        "median_return_pct": 0.2925,
        "month": 7,
        "sample_size": 66,
        "volatility_pct": 3.1089
      },
      "8": {
        "avg_return_pct": 0.1925,
        "median_return_pct": -0.0426,
        "month": 8,
        "sample_size": 64,
        "volatility_pct": 3.0437
      },
      "9": {
        "avg_return_pct": 0.1875,
        "median_return_pct": 0.2386,
        "month": 9,
        "sample_size": 59,
        "volatility_pct": 2.6006
      },
      "10": {
        "avg_return_pct": 0.1858,
        "median_return_pct": 0.5626,
        "month": 10,
        "sample_size": 68,
        "volatility_pct": 2.431
      },
      "11": {
        "avg_return_pct": 0.0999,
        "median_return_pct": 0.3984,
        "month": 11,
        "sample_size": 60,
        "volatility_pct": 2.3957
      },
      "12": {
        "avg_return_pct": 0.1453,
        "median_return_pct": 0.2031,
        "month": 12,
        "sample_size": 63,
        "volatility_pct": 1.8841
      }
    },
    "quarterly_seasonality": {
      "1": {
        "avg_return_pct": 0.2328,
        "median_return_pct": 0.364,
        "quarter": 1,
        "sample_size": 182,
        "volatility_pct": 3.3659
      },
      "2": {
        "avg_return_pct": 0.4955,
        "median_return_pct": 0.2593,
        "quarter": 2,
        "sample_size": 187,
        "volatility_pct": 3.2147
      },
      "3": {
        "avg_return_pct": 0.176,
        "median_return_pct": 0.2371,
        "quarter": 3,
        "sample_size": 189,
        "volatility_pct": 2.9211
      },
      "4": {
        "avg_return_pct": 0.1455,
        "median_return_pct": 0.3515,
        "quarter": 4,
        "sample_size": 191,
        "volatility_pct": 2.2418
      }
    },
    "success": true,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:50.837273",
    "worst_month": 3
  }
}
```

### `GET /api/mcp/data/post-earnings-drift/<ticker>`

Post-earnings drift statistics over recent quarters (does the move continue or fade).

**Parameters:** quarters (optional, default 12; 1 to 40)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/post-earnings-drift/AAPL"
```

Response (GET /api/mcp/data/post-earnings-drift/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "avg_drift_negative_gap": {
      "0": 0.0,
      "1": -1.963,
      "2": -3.551,
      "3": -4.515,
      "5": -5.699,
      "10": -2.35,
      "20": -1.9
    },
    "avg_drift_positive_gap": {
      "0": 0.0,
      "1": -0.684,
      "2": -0.756,
      "3": -0.573,
      "5": -1.203,
      "10": 5.525,
      "20": 4.761
    },
    "events": [
      {
        "direction": "up",
        "drift": {
          "1": -4.575,
          "2": -3.158,
          "3": -4.623,
          "5": 0.206,
          "10": null,
          "20": null
        },
        "earnings_date": "2026-08-26",
        "gap_pct": 6.3,
        "surprise_direction": "beat",
        "timing": "AMC"
      },
      {
        "direction": "down",
        "drift": {
          "1": -1.902,
          "2": -2.116,
          "3": -3.147,
          "5": -3.813,
          "10": -6.454,
          "20": -4.835
        },
        "earnings_date": "2026-05-20",
        "gap_pct": -0.53,
        "surprise_direction": "beat",
        "timing": "AMC"
      },
      {
        "direction": "down",
        "drift": {
          "1": -4.164,
          "2": -1.3,
          "3": -2.616,
          "5": -0.834,
          "10": -0.937,
          "20": -7.376
        },
        "earnings_date": "2026-02-25",
        "gap_pct": -0.66,
        "surprise_direction": "beat",
        "timing": "AMC"
      }
    ],
    "signal": {
      "action": "NEUTRAL",
      "rationale": "No strong directional drift pattern detected."
    },
    "statistics": {
      "avg_20d_drift_after_down": -1.9,
      "avg_20d_drift_after_up": 4.761,
      "avg_5d_drift_after_down": -5.699,
      "avg_5d_drift_after_up": -1.203,
      "continuation_rate_20d": 63.6,
      "continuation_rate_5d": 75.0,
      "negative_gap_count": 5,
      "positive_gap_count": 7,
      "reversal_rate_20d": 40.0,
      "reversal_rate_5d": 0.0,
      "total_events": 12
    },
    "success": true,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T07:49:48.203263"
  }
}
```

### `GET /api/mcp/data/iv-crush/<ticker>`

IV build-up into earnings and crush after, averaged over past events. Values in percentage points.

**Parameters:** days_before (optional, default 30; 1 to 120) · days_after (optional, default 30; 1 to 120)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/iv-crush/AAPL"
```

Response (GET /api/mcp/data/iv-crush/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "atm_iv": 38.3995,
    "current_iv": 34.43,
    "current_rv_annual": 43.4299,
    "days_to_earnings": 71,
    "days_to_expiration": 73,
    "earnings_date": "2026-11-18",
    "estimated_iv_after_event": 38.3995,
    "estimated_iv_crush_pct": 0.0,
    "expected_move": 27.54,
    "expected_move_pct": 11.9583,
    "historical_avg_move_pct": 2.1316,
    "is_earnings_play": false,
    "iv_premium": -8.9999,
    "iv_rank": 14.79,
    "iv_units": "percentage_points",
    "nearest_expiration": "2026-11-20",
    "stock_price": 230.3,
    "straddle_price": 32.4,
    "success": true,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:33.972081"
  }
}
```

### `GET /api/mcp/data/screen`

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.

**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)

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

Response (GET /api/mcp/data/screen?screen_type=high_iv_rank&limit=5, captured 2026-09-08. Lists are cut to the rows nearest the money.):

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

### `GET /api/mcp/data/market-overview`

Market-wide volatility overview.

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

Response (GET /api/mcp/data/market-overview, captured 2026-09-08. Lists are cut to the rows nearest the money.):

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

### `GET /api/mcp/data/historical-moves/<ticker>`

Historical price-move distribution.

**Parameters:** periods (CSV, default 7,14,21,30; each 1 to 252, at most 8)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/historical-moves/AAPL"
```

Response (GET /api/mcp/data/historical-moves/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "current_price": 230.36,
    "move_analysis": {
      "14d": {
        "avg_abs_move_pct": 5.4003,
        "avg_move_pct": 1.7376,
        "max_down_move_pct": -10.5131,
        "max_up_move_pct": 14.8871,
        "median_move_pct": 1.5093,
        "p10": -6.4665,
        "p25": -3.1976,
        "p75": 6.1163,
        "p90": 9.9673,
        "period_days": 14,
        "std_dev_pct": 6.3057
      },
      "21d": {
        "avg_abs_move_pct": 6.7007,
        "avg_move_pct": 2.7348,
        "max_down_move_pct": -12.588,
        "max_up_move_pct": 19.0191,
        "median_move_pct": 3.3738,
        "p10": -8.3477,
        "p25": -1.921,
        "p75": 8.5737,
        "p90": 11.7969,
        "period_days": 21,
        "std_dev_pct": 7.5251
      },
      "30d": {
        "avg_abs_move_pct": 7.1714,
        "avg_move_pct": 2.1683,
        "max_down_move_pct": -17.841,
        "max_up_move_pct": 15.395,
        "median_move_pct": 2.5263,
        "p10": -10.2469,
        "p25": -4.2495,
        "p75": 8.7686,
        "p90": 11.9596,
        "period_days": 30,
        "std_dev_pct": 8.2063
      },
      "7d": {
        "avg_abs_move_pct": 4.7327,
        "avg_move_pct": 1.1532,
        "max_down_move_pct": -10.7926,
        "max_up_move_pct": 18.5403,
        "median_move_pct": 0.5243,
        "p10": -5.6893,
        "p25": -2.9056,
        "p75": 5.0021,
        "p90": 8.8667,
        "period_days": 7,
        "std_dev_pct": 5.9155
      }
    },
    "success": true,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:32.717088"
  }
}
```

### `GET /api/mcp/data/expected-vs-actual/<ticker>`

Options-implied expected move vs historical actual moves.

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/expected-vs-actual/AAPL"
```

Response (GET /api/mcp/data/expected-vs-actual/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "assessment": "FAIRLY_PRICED",
    "days_to_expiration": 8,
    "difference_pct": 1.9203,
    "expected_move_pct": 4.5484,
    "expiration": "2026-09-16",
    "historical_avg_move_pct": 4.4627,
    "straddle_price": 10.475,
    "success": true,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:31.458555"
  }
}
```

### `GET /api/mcp/data/mispricing-assessment/<ticker>`

Composite assessment combining IV rank, VRP, and expected-vs-actual: returns a BUY_PREMIUM / SELL_PREMIUM / NEUTRAL signal with a −100…+100 score, confidence, and all components. components.current_iv is on the VRP basis (cores iv30d) and the block carries iv_basis, hv_basis and earnings_in_window.

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/mispricing-assessment/AAPL"
```

Response (GET /api/mcp/data/mispricing-assessment/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "components": {
      "current_iv": 33.05,
      "earnings_in_window": true,
      "expected_move_pct": 4.55,
      "historical_avg_move_pct": 4.46,
      "hv_basis": "close_to_close_log_returns_annualized_252",
      "iv_basis": "iv30d_constant_maturity_eod",
      "iv_percentile": 12.0,
      "iv_rank": 14.8,
      "options_assessment": "FAIRLY_PRICED",
      "realized_vol": 45.06,
      "vrp": -12.01
    },
    "confidence": 100.0,
    "historical_moves": {
      "14d": {
        "avg_abs_move_pct": 5.4003,
        "avg_move_pct": 1.7376,
        "max_down_move_pct": -10.5131,
        "max_up_move_pct": 14.8871,
        "median_move_pct": 1.5093,
        "p10": -6.4665,
        "p25": -3.1976,
        "p75": 6.1163,
        "p90": 9.9673,
        "period_days": 14,
        "std_dev_pct": 6.3057
      },
      "21d": {
        "avg_abs_move_pct": 6.7007,
        "avg_move_pct": 2.7348,
        "max_down_move_pct": -12.588,
        "max_up_move_pct": 19.0191,
        "median_move_pct": 3.3738,
        "p10": -8.3477,
        "p25": -1.921,
        "p75": 8.5737,
        "p90": 11.7969,
        "period_days": 21,
        "std_dev_pct": 7.5251
      },
      "30d": {
        "avg_abs_move_pct": 7.1714,
        "avg_move_pct": 2.1683,
        "max_down_move_pct": -17.841,
        "max_up_move_pct": 15.395,
        "median_move_pct": 2.5263,
        "p10": -10.2469,
        "p25": -4.2495,
        "p75": 8.7686,
        "p90": 11.9596,
        "period_days": 30,
        "std_dev_pct": 8.2063
      },
      "7d": {
        "avg_abs_move_pct": 4.7327,
        "avg_move_pct": 1.1532,
        "max_down_move_pct": -10.7926,
        "max_up_move_pct": 18.5403,
        "median_move_pct": 0.5243,
        "p10": -5.6893,
        "p25": -2.9056,
        "p75": 5.0021,
        "p90": 8.8667,
        "period_days": 7,
        "std_dev_pct": 5.9155
      }
    },
    "mispricing_score": -55.2,
    "signal": "BUY_PREMIUM",
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:35.431474+00:00"
  }
}
```

### `GET /api/mcp/data/skew/<ticker>`

Volatility skew decomposition: put/call skew, curvature, and regime bands.

**Parameters:** view (optional: 'analysis' default, 'history', 'curvature') · days (history view, default 252; 20 to 1000)

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

Response (GET /api/mcp/data/skew/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "current": {
      "slope": 1.2147,
      "slope_forecast": 1.0845,
      "slope_forecast_inf": 1.0637,
      "slope_inf": 0.9391
    },
    "curvature": {
      "deriv": 0.0594,
      "deriv_forecast": 0.0391,
      "deriv_forecast_inf": 0.0532,
      "deriv_inf": 0.058,
      "interpretation": "smile",
      "mispricing": 0.0203
    },
    "market_width": {
      "vol": 0.58,
      "vol_inf": 0.63
    },
    "percentile": {
      "avg_1m": 0.9104,
      "avg_1y": 2.1043,
      "current": 25.79,
      "stdv_1y": 1.29
    },
    "price": 230.3,
    "sector": "Technology",
    "sector_relative": {
      "etf_slope_ratio": 0.4
    },
    "ticker": "NVDA"
  }
}
```

### `GET /api/mcp/data/relative-value/<ticker>`

IV percentile vs SPY and sector, plus ratio mean-reversion signal.

**Parameters:** days (default 252; 20 to 1000)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/relative-value/AAPL"
```

Response (GET /api/mcp/data/relative-value/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

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

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

Market-wide relative-value scans: IV/SPY mean-reversion stretches or rich-vs-cheap pairs.

**Parameters:** view (optional: 'mean_reversion' default, 'pairs') · limit (default 20, max 50) · threshold (mean_reversion z-score, default 1.5)

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

Response (GET /api/mcp/data/relative-value-scan?limit=5, captured 2026-09-08. Lists are cut to the rows nearest the money.):

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

### `GET /api/mcp/data/zero-dte/<ticker>`

0DTE analytics: gamma flip, max pain, by-strike gamma, and theta decay. Under compact detail by_strike and chain_table are windowed around spot; window says what was trimmed.

**Parameters:** detail (compact | full; default compact for MCP clients, full for REST) · strikes_around (default 30 per side under compact; 0 = all)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/zero-dte/AAPL"
```

Response (GET /api/mcp/data/zero-dte/SPY?detail=compact&strikes_around=5, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "by_strike": [
      {
        "call_delta": 0.604,
        "call_gamma": 77.9032,
        "call_iv": 5.8,
        "call_mid": 2.59,
        "call_oi": 1200,
        "call_theta": -0.244,
        "call_volume": 25628,
        "moneyness": "ATM",
        "net_gamma": 1.29,
        "put_delta": -0.396,
        "put_gamma": -77.9032,
        "put_iv": 6.3,
        "put_mid": 1.45,
        "put_oi": 1172,
        "put_theta": -0.244,
        "put_volume": 57197,
        "strike": 769.0
      },
      {
        "call_delta": 0.525,
        "call_gamma": 83.8045,
        "call_iv": 5.7,
        "call_mid": 1.98,
        "call_oi": 6179,
        "call_theta": -0.243,
        "call_volume": 82391,
        "moneyness": "ATM",
        "net_gamma": 139.91,
        "put_delta": -0.474,
        "put_gamma": -83.8045,
        "put_iv": 6.2,
        "put_mid": 1.84,
        "put_oi": 3365,
        "put_theta": -0.243,
        "put_volume": 82894,
        "strike": 770.0
      },
      {
        "call_delta": 0.44,
        "call_gamma": 86.3498,
        "call_iv": 5.6,
        "call_mid": 1.46,
        "call_oi": 1450,
        "call_theta": -0.232,
        "call_volume": 61672,
        "moneyness": "ATM",
        "net_gamma": -79.77,
        "put_delta": -0.56,
        "put_gamma": -86.3498,
        "put_iv": 6.1,
        "put_mid": 2.34,
        "put_oi": 3007,
        "put_theta": -0.232,
        "put_volume": 43463,
        "strike": 771.0
      }
    ],
    "data_status": "PRE-MARKET",
    "edge_score": {
      "components": {
        "em_hit_rate": {
          "score": 6,
          "value": 68.3,
          "weight": 0.2
        },
        "em_rv": {
          "score": 4,
          "value": 0.81,
          "weight": 0.25
        },
        "gamma_regime": {
          "score": 5,
          "value": "negative",
          "weight": 0.1
        },
        "iv_forecast": {
          "score": 3,
          "value": -3.3,
          "weight": 0.15
        },
        "vrp": {
          "score": 6,
          "value": 3.5,
          "weight": 0.3
        }
      },
      "edge_label": "No Clear Edge",
      "edge_type": "neutral",
      "total": 5.0
    },
    "em_hit_rate": {
      "assessment": "reliable",
      "avg_actual_pct": 0.62,
      "avg_em_pct": 0.81,
      "current_em_pct": 0.5,
      "em_vs_avg": "below",
      "hit_rate": 68.3,
      "hits": 69,
      "total_days": 101
    },
    "error": null,
    "expiration": "2026-09-08",
    "gamma_regime": {
      "regime": "negative",
      "total_net_gex": -45.78
    },
    "is_next_expiry": false,
    "iv_forecast": {
      "assessment": "underpriced",
      "atm_forecast": 9.2,
      "atm_implied": 5.9,
      "diff": -3.3,
      "earn_effect": 0.0,
      "signal": "IV 3.3pts below the feed's forecast: favor buying"
    },
    "key_levels": {
      "abs_gamma": 770.0,
      "call_wall": 775.0,
      "em_lower": 766.43,
      "em_upper": 774.07,
      "gamma_flip": null,
      "max_pain": 769.0,
      "put_wall": 770.0
    },
    "metrics": {
      "atm_iv": 6.0,
      "call_oi": 66864,
      "expected_move": 0.5,
      "expected_move_dollars": 3.82,
      "gamma_flip": null,
      "max_pain": 769.0,
      "net_gamma": -45.78,
      "put_call_ratio": 1.42,
      "put_oi": 95102,
      "total_oi": 161966,
      "total_theta": 1269368.0
    },
    "mispricing_chain": {
      "assessment": "FAIR",
      "assessment_band_dollars": 7.7,
      "avg_spread": -1.9,
      "base_hv": 8.1,
      "hv_window": "20d",
      "overpriced_count": 0,
      "underpriced_count": 0
    },
    "skew_signal": {
      "assessment": "heavy_put_skew",
      "call_10d_iv": 5.3,
      "call_10d_strike": 776.0,
      "put_10d_iv": 8.1,
      "put_10d_strike": 762.0,
      "signal": "Downside fear elevated: puts expensive vs calls",
      "skew_points": 2.8,
      "skew_ratio": 1.53
    },
    "stock_price": 770.25,
    "theta_burn": {
      "by_category": {
        "atm": {
          "current": 0.49,
          "decay": [
            {
              "hour": "09:30",
              "remaining": 0.49
            },
            {
              "hour": "10:00",
              "remaining": 0.47
            },
            {
              "hour": "10:30",
              "remaining": 0.45
            }
          ],
          "strike": 770.0
        },
        "near_atm": {
          "current": 0.42,
          "decay": [
            {
              "hour": "09:30",
              "remaining": 0.42
            },
            {
              "hour": "10:00",
              "remaining": 0.4
            },
            {
              "hour": "10:30",
              "remaining": 0.39
            }
          ],
          "strike": 766.0
        },
        "otm_calls": {
          "current": 0.0,
          "decay": [
            {
              "hour": "09:30",
              "remaining": 0.0
            },
            {
              "hour": "10:00",
              "remaining": 0.0
            },
            {
              "hour": "10:30",
              "remaining": 0.0
            }
          ],
          "strike": 786.0
        },
        "otm_puts": {
          "current": 0.04,
          "decay": [
            {
              "hour": "09:30",
              "remaining": 0.04
            },
            {
              "hour": "10:00",
              "remaining": 0.04
            },
            {
              "hour": "10:30",
              "remaining": 0.04
            }
          ],
          "strike": 754.0
        }
      },
      "current_theta": 0.49
    },
    "ticker": "SPY",
    "time_to_close": "Opens in 9h 5m",
    "window": {
      "detail": "compact",
      "lists": {
        "by_strike": {
          "rows_returned": 11,
          "rows_total": 165,
          "truncated": true
        },
        "chain_table": {
          "rows_returned": 11,
          "rows_total": 61,
          "truncated": true
        }
      },
      "strikes_around": 5
    }
  }
}
```

### `GET /api/mcp/data/dividend/<ticker>`

Dividend history, implied vs actual, and ex-date behavior.

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

Response (GET /api/mcp/data/dividend/AAPL, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "cagr": 0.0763,
    "current": {
      "annual_actual": 1.08,
      "annual_implied": 0,
      "div_amount": 0.27,
      "div_freq": "Quarterly",
      "div_growth": 0.0,
      "div_yield": 0.3,
      "implied_vs_actual": -1.08,
      "next_div_date": "2026-11-10",
      "next_div_implied": 0,
      "price": 320.07
    },
    "history": [
      {
        "amount": 0.27,
        "decl_date": null,
        "ex_date": "2026-11-10",
        "frequency": 91,
        "pay_date": null,
        "type": null
      },
      {
        "amount": 0.27,
        "decl_date": null,
        "ex_date": "2026-08-10",
        "frequency": 91,
        "pay_date": null,
        "type": null
      },
      {
        "amount": 0.27,
        "decl_date": null,
        "ex_date": "2026-05-12",
        "frequency": 91,
        "pay_date": null,
        "type": null
      }
    ],
    "pays_dividends": true,
    "sector": "Technology",
    "ticker": "AAPL"
  }
}
```

### `GET /api/mcp/data/borrow-rate/<ticker>`

Borrow-rate time series and hard-to-borrow signal.

**Parameters:** days (default 252; 20 to 1000)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/borrow-rate/AAPL"
```

Response (GET /api/mcp/data/borrow-rate/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "current": {
      "avg_opt_volume": 3290793.0,
      "best_etf": "XLK",
      "borrow2yr": 3.5445,
      "borrow30": 3.9024,
      "borrow_class": "ELEVATED",
      "borrow_pctile": 98.8,
      "chg_1m": 5.05,
      "chg_1w": 5.86,
      "iv_percentile": 12.0,
      "market_cap": 5561054100000.0,
      "open_interest": 16025398.0,
      "options_volume": 5455875,
      "price": 230.3,
      "put_call_ratio": 0.5371,
      "residualRate": null,
      "sector": "Technology",
      "stock_loan_revenue": 898.72,
      "stock_volume": 6443150.0,
      "synthetic_short_cost": 8.68,
      "term_spread": 0.3579,
      "vrp": -11.87
    },
    "earnings_dates": [
      "2025-11-19",
      "2026-02-25",
      "2026-05-20"
    ],
    "next_earnings": null,
    "sector_comparison": {
      "sector_avg": 4.8474,
      "sector_count": 488,
      "sector_rank": 297,
      "vs_sector_ratio": 0.81
    },
    "spike_detected": false,
    "spike_ratio": 1.2836,
    "spike_severity": "MODERATE",
    "spike_z_score": 1.92,
    "squeeze_score": 26,
    "ticker": "NVDA",
    "timeseries": [
      {
        "borrow2yr": 2.8857,
        "borrow30": 3.3621,
        "borrow30_ma20": null,
        "date": "2025-09-05",
        "is_spike": false,
        "residualRate": null,
        "term_spread": 0.4764
      },
      {
        "borrow2yr": 2.7273,
        "borrow30": 3.1602,
        "borrow30_ma20": null,
        "date": "2025-09-08",
        "is_spike": false,
        "residualRate": null,
        "term_spread": 0.4329
      },
      {
        "borrow2yr": 2.655,
        "borrow30": 3.2406,
        "borrow30_ma20": null,
        "date": "2025-09-09",
        "is_spike": false,
        "residualRate": null,
        "term_spread": 0.5856
      }
    ],
    "velocity": {
      "borrow_chg_1m": 0.6,
      "borrow_chg_1w": 0.95
    }
  }
}
```

### `GET /api/mcp/data/greeks-exposure/<ticker>`

Unified dealer Greek exposure — DEX, gamma, vega, theta, vanna, charm — by strike or aggregated.

**Parameters:** expiration (optional), aggregate (default true)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/greeks-exposure/AAPL"
```

Response (GET /api/mcp/data/greeks-exposure/SPY, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "expirations": [
      "2026-09-08",
      "2026-09-09",
      "2026-09-10"
    ],
    "expirations_horizon_days": 90,
    "expirations_included": 16,
    "expirations_through": "2026-11-20",
    "expirations_total": 32,
    "exposures": {
      "delta": {
        "call_total": 72779773.41,
        "profile": [
          {
            "call": 662203.97,
            "net": 1341242.2,
            "put": 679038.22,
            "strike": 769.0
          },
          {
            "call": 2953824.91,
            "net": 6035632.44,
            "put": 3081807.53,
            "strike": 770.0
          },
          {
            "call": 526110.77,
            "net": 1175225.88,
            "put": 649115.11,
            "strike": 771.0
          }
        ],
        "put_total": 55361041.47,
        "total": 128140814.88,
        "unit": "delta shares (dealer model: long calls, short puts)"
      },
      "gamma": {
        "call_total": 12387934215.44,
        "delta_adj_call_total": 5113957650.72,
        "delta_adj_crosses_zero": true,
        "delta_adj_flip_degenerate": false,
        "delta_adj_flip_level": 772.75,
        "delta_adj_profile": [
          {
            "call": 133476005.18,
            "net": -25907371.89,
            "put": -159383377.08,
            "strike": 769.0
          },
          {
            "call": 510209139.16,
            "net": 16139188.46,
            "put": -494069950.69,
            "strike": 770.0
          },
          {
            "call": 117857334.76,
            "net": -59060034.5,
            "put": -176917369.26,
            "strike": 771.0
          }
        ],
        "delta_adj_put_total": -4521550270.61,
        "delta_adj_total": 592407380.1,
        "delta_adj_trough": 760.0,
        "flip_degenerate": false,
        "flip_level": null,
        "gex_billions": -3.2308,
        "gex_ratio": 0.79,
        "implications": {
          "directional_bias": "Balanced (call/put GEX 0.79)",
          "net_to_gross": -0.1154,
          "pin_at_spot": false,
          "positioning": "largest strike $760.00 (-1.3%); call wall $775.00 (+0.6%); put wall $760.00 (-1.3%)",
          "regime_code": "negative",
          "support_resistance": "--",
          "volatility_regime": "Negative GEX (dealers amplify moves)"
        },
        "max_strike": 760.0,
        "profile": [
          {
            "call": 237808150.34,
            "net": -133889311.31,
            "put": -371697461.65,
            "strike": 769.0
          },
          {
            "call": 980618910.34,
            "net": -52445836.8,
            "put": -1033064747.14,
            "strike": 770.0
          },
          {
            "call": 253439508.77,
            "net": -73315508.53,
            "put": -326755017.3,
            "strike": 771.0
          }
        ],
        "put_total": -15618693641.37,
        "total": -3230759425.93,
        "unit": "$ gamma per 1% move"
      },
      "vanna": {
        "call_total": 80574246.67,
        "profile": [
          {
            "call": -1333176.63,
            "net": 652095.51,
            "put": 1985272.13,
            "strike": 769.0
          },
          {
            "call": -2543829.43,
            "net": -110258.35,
            "put": 2433571.07,
            "strike": 770.0
          },
          {
            "call": 570174.28,
            "net": -286879.42,
            "put": -857053.69,
            "strike": 771.0
          }
        ],
        "put_total": 286565015.57,
        "total": 367139262.24,
        "unit": "delta shares per vol point"
      }
    },
    "key_levels": {
      "call_wall": {
        "distance_pct": 0.62,
        "gex": 969364047.76,
        "strike": 775.0
      },
      "charm_pressure": {
        "distance_pct": -1.33,
        "exposure": 233669.48,
        "strike": 760.0
      },
      "key_gamma_strike": {
        "distance_pct": -1.33,
        "gex": 1376738203.79,
        "strike": 760.0
      },
      "put_wall": {
        "distance_pct": -1.33,
        "gex": 1809628588.06,
        "strike": 760.0
      },
      "vanna_resistance": {
        "distance_pct": 4.12,
        "exposure": -589551.4,
        "strike": 802.0
      },
      "vanna_support": {
        "distance_pct": -1.33,
        "exposure": 20298821.47,
        "strike": 760.0
      }
    },
    "stock_price": 770.25,
    "ticker": "SPY",
    "units": {
      "charm": "delta shares per day",
      "color": "$ gamma per 1% move, per day",
      "delta": "delta shares (dealer model: long calls, short puts)",
      "gamma": "$ gamma per 1% move",
      "speed": "$ gamma per 1% move, per 1% move",
      "theta": "$ per day",
      "ultima": "$ vega per vol point, per vol point squared",
      "vanna": "delta shares per vol point",
      "vega": "$ per vol point",
      "vomma": "$ vega per vol point, per vol point",
      "zomma": "$ gamma per 1% move, per vol point"
    }
  }
}
```

### `GET /api/mcp/data/volume-profile/<ticker>`

Option volume profile by strike (call vs put volume).

**Parameters:** expiration (optional)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/volume-profile/AAPL"
```

Response (GET /api/mcp/data/volume-profile/SPY, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "expiration": "2026-09-08",
    "put_call_ratio": 1.483,
    "stock_price": 770.25,
    "success": true,
    "ticker": "SPY",
    "timestamp": "2026-09-08T08:07:22.009730",
    "top_oi_strikes": [
      {
        "call_oi": 12.0,
        "call_volume": 528.0,
        "distance_from_spot_pct": -4.3168,
        "moneyness": "ITM",
        "pcr_oi": 454.5833,
        "pcr_volume": 4.6723,
        "put_oi": 5455.0,
        "put_volume": 2467.0,
        "strike": 737.0,
        "total_oi": 5467.0,
        "total_volume": 2995.0
      },
      {
        "call_oi": 6179.0,
        "call_volume": 82391.0,
        "distance_from_spot_pct": -0.0325,
        "moneyness": "ATM",
        "pcr_oi": 0.5446,
        "pcr_volume": 1.0061,
        "put_oi": 3365.0,
        "put_volume": 82894.0,
        "strike": 770.0,
        "total_oi": 9544.0,
        "total_volume": 165285.0
      },
      {
        "call_oi": 4680.0,
        "call_volume": 13232.0,
        "distance_from_spot_pct": 1.2658,
        "moneyness": "ATM",
        "pcr_oi": 0.04,
        "pcr_volume": 0.1359,
        "put_oi": 187.0,
        "put_volume": 1798.0,
        "strike": 780.0,
        "total_oi": 4867.0,
        "total_volume": 15030.0
      }
    ],
    "top_volume_strikes": [
      {
        "call_oi": 1200.0,
        "call_volume": 25628.0,
        "distance_from_spot_pct": -0.1623,
        "moneyness": "ATM",
        "pcr_oi": 0.9767,
        "pcr_volume": 2.2318,
        "put_oi": 1172.0,
        "put_volume": 57197.0,
        "strike": 769.0,
        "total_oi": 2372.0,
        "total_volume": 82825.0
      },
      {
        "call_oi": 6179.0,
        "call_volume": 82391.0,
        "distance_from_spot_pct": -0.0325,
        "moneyness": "ATM",
        "pcr_oi": 0.5446,
        "pcr_volume": 1.0061,
        "put_oi": 3365.0,
        "put_volume": 82894.0,
        "strike": 770.0,
        "total_oi": 9544.0,
        "total_volume": 165285.0
      },
      {
        "call_oi": 1450.0,
        "call_volume": 61672.0,
        "distance_from_spot_pct": 0.0974,
        "moneyness": "ATM",
        "pcr_oi": 2.0738,
        "pcr_volume": 0.7047,
        "put_oi": 3007.0,
        "put_volume": 43463.0,
        "strike": 771.0,
        "total_oi": 4457.0,
        "total_volume": 105135.0
      }
    ],
    "total_call_volume": 424808.0,
    "total_put_volume": 629987.0,
    "volume_profile": [
      {
        "call_oi": 1200.0,
        "call_volume": 25628.0,
        "distance_from_spot_pct": -0.1623,
        "moneyness": "ATM",
        "pcr_oi": 0.9767,
        "pcr_volume": 2.2318,
        "put_oi": 1172.0,
        "put_volume": 57197.0,
        "strike": 769.0,
        "total_oi": 2372.0,
        "total_volume": 82825.0
      },
      {
        "call_oi": 6179.0,
        "call_volume": 82391.0,
        "distance_from_spot_pct": -0.0325,
        "moneyness": "ATM",
        "pcr_oi": 0.5446,
        "pcr_volume": 1.0061,
        "put_oi": 3365.0,
        "put_volume": 82894.0,
        "strike": 770.0,
        "total_oi": 9544.0,
        "total_volume": 165285.0
      },
      {
        "call_oi": 1450.0,
        "call_volume": 61672.0,
        "distance_from_spot_pct": 0.0974,
        "moneyness": "ATM",
        "pcr_oi": 2.0738,
        "pcr_volume": 0.7047,
        "put_oi": 3007.0,
        "put_volume": 43463.0,
        "strike": 771.0,
        "total_oi": 4457.0,
        "total_volume": 105135.0
      }
    ]
  }
}
```

### `GET /api/mcp/data/max-pain/<ticker>`

Max-pain strike and the pain distribution across strikes.

**Parameters:** expiration (optional)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/max-pain/AAPL"
```

Response (GET /api/mcp/data/max-pain/SPY, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "all_strikes": [
      {
        "strike": 769.0,
        "total_pain": 21794400.0
      },
      {
        "strike": 770.0,
        "total_pain": 21842200.0
      },
      {
        "strike": 771.0,
        "total_pain": 22844400.0
      }
    ],
    "distance_from_spot": -1.25,
    "distance_pct": -0.1623,
    "expiration": "2026-09-08",
    "likely_direction": "NEUTRAL",
    "magnet_strength": "WEAK",
    "max_pain_strike": 769.0,
    "max_pain_value": 21794400.0,
    "stock_price": 770.25,
    "success": true,
    "ticker": "SPY",
    "timestamp": "2026-09-08T08:07:20.699304"
  }
}
```

### `GET /api/mcp/data/monies/<ticker>`

our institutional data feed monies vol surface: the market's smoothed implied surface, the provider's forecast surface, or the comparison of the two (model-vs-market rich/cheap spots).

**Parameters:** surface (optional: 'implied' default, 'forecast', 'comparison')

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

Response (GET /api/mcp/data/monies/SPY, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "delta_points": [
      0,
      5,
      10
    ],
    "expirations": [
      {
        "atm_iv": 6.62,
        "confidence": 0.304,
        "curvature": 0,
        "dte": -4,
        "earn_effect": 0,
        "expiration": "2026-09-04",
        "slope": 0,
        "smile": {
          "0": 7.03,
          "5": 7.17,
          "10": 7.31,
          "15": 7.45,
          "20": 7.59,
          "25": 7.73,
          "30": 7.87,
          "35": 8.02,
          "40": 8.16,
          "45": 8.3,
          "50": 8.44,
          "55": 8.58,
          "60": 8.72,
          "65": 8.87,
          "70": 9.01,
          "75": 9.15,
          "80": 9.29,
          "85": 9.43,
          "90": 9.57,
          "95": 9.71,
          "100": 9.86
        },
        "stock_price": 770.25
      },
      {
        "atm_iv": 5.8,
        "confidence": 1,
        "curvature": 0.1178,
        "dte": 0,
        "earn_effect": 0,
        "expiration": "2026-09-08",
        "slope": 4.7079,
        "smile": {
          "0": 6.01,
          "5": 5.54,
          "10": 5.49,
          "15": 5.48,
          "20": 5.5,
          "25": 5.53,
          "30": 5.57,
          "35": 5.63,
          "40": 5.7,
          "45": 5.79,
          "50": 5.89,
          "55": 6.01,
          "60": 6.16,
          "65": 6.33,
          "70": 6.53,
          "75": 6.78,
          "80": 7.09,
          "85": 7.48,
          "90": 8.0,
          "95": 8.79,
          "100": 11.47
        },
        "stock_price": 770.25
      },
      {
        "atm_iv": 6.92,
        "confidence": 1,
        "curvature": 0.1286,
        "dte": 1,
        "earn_effect": 0,
        "expiration": "2026-09-09",
        "slope": 4.5584,
        "smile": {
          "0": 6.65,
          "5": 6.52,
          "10": 6.54,
          "15": 6.55,
          "20": 6.56,
          "25": 6.58,
          "30": 6.6,
          "35": 6.64,
          "40": 6.7,
          "45": 6.79,
          "50": 6.9,
          "55": 7.04,
          "60": 7.23,
          "65": 7.47,
          "70": 7.77,
          "75": 8.15,
          "80": 8.64,
          "85": 9.27,
          "90": 10.16,
          "95": 11.56,
          "100": 16.73
        },
        "stock_price": 770.25
      }
    ],
    "stock_price": 770.25,
    "success": true,
    "ticker": "SPY",
    "timestamp": "2026-09-08T04:24:54.451794"
  }
}
```

### `GET /api/mcp/data/correlation/<ticker>`

Rolling correlation and beta vs SPY and the sector ETF.

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

Response (GET /api/mcp/data/correlation/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "best_etf": "XLK",
    "beta": {
      "beta_1m": 3.08,
      "beta_1y": 1.93
    },
    "correlations": {
      "etf_1m": 0.52,
      "etf_1y": 0.27,
      "spy_1m": 0.49,
      "spy_1y": 0.41
    },
    "iv_spy_ratio": 2.7984,
    "price": 230.3,
    "sector": "Technology",
    "ticker": "NVDA"
  }
}
```

### `GET /api/mcp/data/correlation/<ticker>/compare/<ticker2>`

Pairwise correlation/beta between two tickers.

**Parameters:** days (optional, default 400; 20 to 1000)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/correlation/AAPL/compare/example"
```

Response (GET /api/mcp/data/correlation/NVDA/compare/AMD, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "ticker1": "NVDA",
    "ticker2": "AMD",
    "timeseries": [
      {
        "beta1m": null,
        "correl1m": null,
        "correl1y": null,
        "date": "2025-08-05"
      },
      {
        "beta1m": null,
        "correl1m": null,
        "correl1y": null,
        "date": "2025-08-06"
      },
      {
        "beta1m": null,
        "correl1m": null,
        "correl1y": null,
        "date": "2025-08-07"
      }
    ]
  }
}
```

### `GET /api/mcp/data/hv-regimes/<ticker>`

Historical-volatility windows, HV term structure, and regime crossovers. view=ex_earnings on the hv basis is computed from daily closes at the 30-day tenor with earnings-reaction sessions dropped (tenor, source, reaction_sessions_excluded).

**Parameters:** view (optional: 'dashboard' default, 'signals', 'decomposition', 'ex_earnings') · days (default 252; 20 to 1000)

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/hv-regimes/AAPL"
```

Response (GET /api/mcp/data/hv-regimes/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "days": 252,
    "forecast": {
      "orFcst20d": null,
      "orFcstInf": null
    },
    "term_structure": [
      {
        "cls_hv": 24.54,
        "or_hv": 32.68,
        "window": "5d"
      },
      {
        "cls_hv": 56.32,
        "or_hv": 46.76,
        "window": "10d"
      },
      {
        "cls_hv": 44.38,
        "or_hv": 37.68,
        "window": "20d"
      }
    ],
    "ticker": "NVDA",
    "timeseries": [
      {
        "clsHv10d": 25.76,
        "clsHv120d": 46.85,
        "clsHv20d": 22.91,
        "clsHv252d": 50.25,
        "clsHv30d": 24.9,
        "clsHv5d": 23.98,
        "clsHv60d": 26.55,
        "clsHv90d": 29.17,
        "date": "2025-09-05"
      },
      {
        "clsHv10d": 24.09,
        "clsHv120d": 46.76,
        "clsHv20d": 22.7,
        "clsHv252d": 50.21,
        "clsHv30d": 25.03,
        "clsHv5d": 22.25,
        "clsHv60d": 26.48,
        "clsHv90d": 29.17,
        "date": "2025-09-08"
      },
      {
        "clsHv10d": 24.88,
        "clsHv120d": 46.47,
        "clsHv20d": 23.59,
        "clsHv252d": 50.22,
        "clsHv30d": 24.79,
        "clsHv5d": 22.9,
        "clsHv60d": 26.47,
        "clsHv90d": 29.19,
        "date": "2025-09-09"
      }
    ]
  }
}
```

### `GET /api/mcp/data/price-context/<ticker>`

Multi-timeframe performance and momentum-vs-IV context.

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/price-context/AAPL"
```

Response (GET /api/mcp/data/price-context/NVDA, captured 2026-09-08. Lists are cut to the rows nearest the money.):

```json
{
  "success": true,
  "data": {
    "avg_opt_volume_20d": 3290792,
    "avg_opt_volume_baseline": 3290792,
    "best_etf": "XLK",
    "beta_1m": 3.08,
    "beta_1y": 1.93,
    "borrow_30d": 3.42,
    "call_oi": 8454385,
    "call_volume": 3549509,
    "contango": 1.26,
    "correl_etf_1y": 0.27,
    "correl_spy_1y": 0.41,
    "daily_change": -0.06,
    "daily_change_pct": -0.03,
    "days_since_hi_52w": 117,
    "days_since_lo_52w": 368,
    "days_to_earnings": 71,
    "div_yield": 0.4,
    "earnings_flag": false,
    "essentials_summary": "92% up the 52-week range, option flow 1.7× the 20-day average",
    "flow_sentiment": {
      "color": "emerald",
      "label": "Bullish"
    },
    "forecast_20d": 32.03,
    "forecast_inf": 41.38,
    "hi_52w": 236.26,
    "hv_20d": 37.86,
    "hv_bars": [
      {
        "close": 44.28,
        "label": "5D",
        "open_range": 43.95
      },
      {
        "close": 56.93,
        "label": "10D",
        "open_range": 46.68
      },
      {
        "close": 44.92,
        "label": "20D",
        "open_range": 37.86
      }
    ],
    "implied_earnings_move": 4.8,
    "implied_earnings_move_sigma": 6.0,
    "implied_move": 4.8,
    "is_partial_session": false,
    "iv_30d": 33.05,
    "iv_etf_ratio": 2.8,
    "iv_pctile_1y": 11.9,
    "iv_spy_ratio": 2.8,
    "lo_52w": 163.85,
    "market_cap": 5561054100,
    "market_cap_fmt": "$5.56T",
    "momentum_regime": {
      "color": "green",
      "label": "Bullish"
    },
    "next_earnings": "2026-11-18",
    "pct_from_high": -2.52,
    "pct_from_low": 40.56,
    "price": 230.3,
    "price_1m": 219.22,
    "price_1w": 217.55,
    "price_1y": 171.43,
    "price_6m": 177.6,
    "prior_close": 230.36,
    "put_call_ratio_volume": 0.54,
    "put_oi": 7571013,
    "put_volume": 1906366,
    "quick_take": "NVDA is 3% off its 52-week high, in an extreme low vol regime.",
    "range_position": 91.8,
    "return_1m": 5.05,
    "return_1w": 5.86,
    "return_1y": 34.34,
    "return_6m": 29.67,
    "sector": "Technology",
    "session_progress": null,
    "stock_volume": 6443150,
    "ticker": "NVDA",
    "trade_date": "2026-09-04",
    "vol_regime": {
      "color": "cyan",
      "label": "Extreme Low"
    },
    "volume_as_of": "2026-09-04 20:55:19",
    "vrp": -4.8
  }
}
```