# Earnings and expected move API

8 endpoints under `https://apexvol.com/api/mcp/data`. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access. Web version: https://apexvol.com/developers/earnings-expected-move-api

| Endpoint | Plan | What it answers |
|---|---|---|
| `GET /earnings-history/{ticker}` | Pro | How much has NVDA moved on each of its last eight reports? |
| `GET /earnings-verdict/{ticker}` | Pro | Should I buy or sell the NVDA earnings straddle? |
| `GET /expected-move/{ticker}` | Premium | How much does the market expect NVDA to move by the next expiration? |
| `GET /expected-vs-actual/{ticker}` | Pro | Is the move priced into NVDA bigger or smaller than the stock usually makes? |
| `GET /historical-moves/{ticker}` | Pro | How big a move does NVDA typically make over 7, 14, 21 and 30 days? |
| `GET /iv-crush/{ticker}` | Pro | How much IV will NVDA lose after it reports, and what move does the current premium imply? |
| `GET /mispricing-assessment/{ticker}` | Pro | Taking IV rank, VRP and the priced move together, are NVDA options rich or cheap? |
| `GET /post-earnings-drift/{ticker}` | Pro | After NVDA gaps on earnings, does the move continue or fade? |

## GET /earnings-history/{ticker}

Returns one row per past report with the gap move, EPS estimate and actual, the surprise, IV before and after and the crush, plus averages by direction and by beat or miss.

- **Units:** Moves in percent and dollars; IVs in percentage points; surprise_pct in percent.
- **Basis:** The move is the previous close to the next open (the gap), not close to close.
- **Markdown:** https://apexvol.com/developers/earnings-expected-move-api/earnings-history.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `num_quarters` | query | 8 | 1 to 40 | How many reports. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/earnings-history/NVDA?num_quarters=8"
```

- `earnings_moves[].earnings_date, gap_move_pct, direction`: The move per report.
- `earnings_moves[].eps_estimate, eps_actual, surprise_pct`: The surprise.
- `earnings_moves[].iv_before, iv_after, iv_crush_pct`: The crush.
- `statistics.avg_abs_move_pct, avg_up_move_pct, avg_down_move_pct, beat_count`: The summary.

## GET /earnings-verdict/{ticker}

Combines the priced event move, the historical move distribution, consistency, IV crush, post-earnings drift and the earnings smile into an edge score and a signal with reasons and suggested structures. Preliminary when the report is far out.

- **Units:** Moves in percent; IVs in percentage points; edge_score and confidence 0 to 100.
- **Basis:** Historical moves are close-to-open gaps on the reaction day. The implied move is the straddle for the expiration after the report.
- **Markdown:** https://apexvol.com/developers/earnings-expected-move-api/earnings-verdict.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |

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

- `verdict.signal, confidence, preliminary, reasons`: The answer and why.
- `edge.edge_score, edge_interpretation, avg_straddle_return`: How the straddle has paid historically.
- `timing.earnings_date, days_to_earnings, expected_move_pct, atm_iv`: The setup.
- `direction, confidence`: Bias and consistency of past moves.
- `wings`: The earnings smile against the reference expiration.

## GET /expected-move/{ticker}

Returns the expected move to the chosen expiration from the ATM straddle, as dollars and percent of spot, with the upper and lower bounds and the days to expiry.

- **Units:** expected_move_dollars and the bounds in dollars; expected_move_percent in percent.
- **Basis:** ATM straddle price (call plus put) at the strike nearest spot. Skips a same-day expiry unless asked.
- **Markdown:** https://apexvol.com/developers/earnings-expected-move-api/expected-move.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `expiration` | query | nearest | YYYY-MM-DD, a listed expiration | Which expiration to use. Defaults to the nearest one. |

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

- `expected_move_dollars, expected_move_percent`: The move.
- `upper_bound, lower_bound`: Spot plus and minus the move.
- `expiration, dte, stock_price`: Context.

## GET /expected-vs-actual/{ticker}

Returns the expected move to the nearest expiration, the historical average move over the same number of days, the difference and a fair-priced assessment.

- **Units:** Moves in percent; straddle_price in dollars.
- **Basis:** Historical average is the mean absolute move over days_to_expiration trading days.
- **Markdown:** https://apexvol.com/developers/earnings-expected-move-api/expected-vs-actual.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |

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

- `expected_move_pct, historical_avg_move_pct, difference_pct`: The comparison.
- `assessment`: OVERPRICED, UNDERPRICED or FAIRLY_PRICED.
- `expiration, days_to_expiration, straddle_price`: Context.

## GET /historical-moves/{ticker}

For each horizon returns the average absolute move, the mean and median, the percentiles and the largest up and down moves, from daily closes.

- **Units:** Percent.
- **Basis:** Rolling close-to-close returns over each horizon across the history the platform holds.
- **Markdown:** https://apexvol.com/developers/earnings-expected-move-api/historical-moves.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `periods` | query | 7,14,21,30 | CSV of 1 to 252, at most 8 | Horizons in trading days. |

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

- `move_analysis.<days>.avg_abs_move_pct, median_move_pct`: Typical size.
- `move_analysis.<days>.p10, p25, p75, p90`: The distribution.
- `move_analysis.<days>.max_up_move_pct, max_down_move_pct`: The tails.

## GET /iv-crush/{ticker}

Returns the current and ATM IV, the estimated IV after the event and the crush in percent, the expected move and the historical average, and whether the nearest expiration is an earnings play.

- **Units:** IVs in percentage points; crush and moves in percent; straddle_price in dollars.
- **Basis:** Crush estimate comes from past reports; expected move from the straddle covering the report.
- **Markdown:** https://apexvol.com/developers/earnings-expected-move-api/iv-crush.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `days_before` | query | 30 | 1 to 120 | Window before the report. |
| `days_after` | query | 30 | 1 to 120 | Window after the report. |

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

- `estimated_iv_after_event, estimated_iv_crush_pct`: The crush.
- `expected_move_pct, historical_avg_move_pct`: Priced versus typical.
- `atm_iv, current_iv, iv_premium`: The IV build.
- `earnings_date, days_to_earnings, is_earnings_play`: Timing.

## GET /mispricing-assessment/{ticker}

Combines IV rank, the volatility risk premium and expected-versus-actual into a signal from -100 to +100 with confidence, and returns every component and the historical move distribution it used.

- **Units:** Score -100 to +100; confidence 0 to 100; IVs in percentage points; moves in percent.
- **Basis:** components.current_iv is on the VRP basis (30-day constant maturity); iv_basis, hv_basis and earnings_in_window are returned.
- **Markdown:** https://apexvol.com/developers/earnings-expected-move-api/mispricing-assessment.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |

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

- `signal, mispricing_score, confidence`: The answer.
- `components.iv_rank, iv_percentile, vrp, expected_move_pct, historical_avg_move_pct`: What drove it.
- `components.earnings_in_window`: Whether a report contaminates realized vol.
- `historical_moves`: The move distribution used.

## GET /post-earnings-drift/{ticker}

Returns the average drift after positive and negative gaps at several horizons, continuation and reversal rates, each past event with its drift path, and a signal with a rationale.

- **Units:** Drift and gaps in percent.
- **Basis:** Gap is the close-to-open reaction; drift is measured from the reaction-day open.
- **Markdown:** https://apexvol.com/developers/earnings-expected-move-api/post-earnings-drift.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `quarters` | query | 12 | 1 to 40 | How many reports. |

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

- `statistics.continuation_rate_5d, continuation_rate_20d`: How often the gap direction held.
- `avg_drift_positive_gap, avg_drift_negative_gap`: Average drift per horizon by gap sign.
- `events[].earnings_date, gap_pct, drift`: Per event.
- `signal.action, rationale`: The read.

Conventions: https://apexvol.com/developers/conventions. Errors: https://apexvol.com/developers/errors. Whole API in one file: https://apexvol.com/docs/api/apexvol-api.md