- API
- Earnings API
Earnings API
Earnings moves,
priced and scored.
What the options market is pricing for the next report, what the stock has actually done on the last twelve, how the straddle would have paid, and one verdict that weighs them. Plus the calendar to find the next one.
A real response
This is what
comes back.
Captured from the live endpoint on 2026-09-07, lists cut to a few rows so it fits on a page. The shape is exactly what your code receives.
{
"edge": {
"avg_straddle_return": 8.0,
"edge_interpretation": "Moderate edge",
"edge_score": 47.9,
"historical_avg_move_pct": 3.83,
"implied_move_expiration": "2026-11-20",
"implied_move_pct": 5.21,
"implied_move_straddle_price": 32.4,
"move_ratio": 1.36,
"straddle_hit_rate": 16.6667,
"straddle_mispricing_pct": 38.2
},
"ticker": "NVDA",
"timestamp": "2026-09-07T16:53:32.075464",
"timing": {
"atm_iv": 32.0,
"days_to_earnings": 72,
"earnings_date": "2026-11-18",
"earnings_exp_atm_iv": 38.08,
"expected_move_pct": 11.96,
"is_earnings_play": false,
"iv_rank": 12.0,
"stock_price": 230.3
},
"verdict": {
"confidence": 33,
"preliminary": true,
"reasons": [
"Report is 72 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"
]
}
}Every response is wrapped as {"success": true, "data": {...}}. Errors use the same envelope with an error string and a status code that means what it says.
Call it three ways. Same token, same JSON.
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
"https://apexvol.com/api/mcp/data/earnings-verdict/NVDA"import requests
r = requests.get("https://apexvol.com/api/mcp/data/earnings-verdict/NVDA",
headers={"Authorization": "Bearer avmcp_YOUR_TOKEN"})
d = r.json()["data"]
print(d["edge"]["implied_move_pct"], d["edge"]["historical_avg_move_pct"], d["verdict"]["signal"])
Is NVDA's earnings straddle overpriced compared with how much the stock usually moves?
The assistant calls calculate_expected_move and answers from the JSON above.More prompts for this family in the prompt library. Set the server up in Claude Desktop, Claude Code, Cursor, ChatGPT, VS Code, Windsurf or Gemini CLI.
Field by field
What each
number means.
timing.earnings_date, days_to_earnings- The next report and how far out it is. preliminary is true when the read is early.
timing.expected_move_pct, atm_iv, earnings_exp_atm_iv- The move priced through the earnings expiration and the IV on either side of it.
edge.implied_move_pct- The event move isolated from the chain, not the whole-expiry straddle.
edge.historical_avg_move_pct, move_ratio- The average past gap and the ratio of priced to historical. Above one, the market is paying up.
edge.straddle_hit_rate, avg_straddle_return- How often the straddle buyer would have won over the last quarters, and by how much on average.
edge.edge_score, edge_interpretation- A 0 to 100 score and its label.
verdict.signal, confidence, reasons- BUY_STRADDLE, SELL_STRADDLE or NO_CLEAR_EDGE with the reasons written out.
verdict.suggested_strategies- The structures that fit the verdict.
The family
9 endpoints,
one prefix.
All under https://apexvol.com/api/mcp/data. Parameters are bounded and the docs say the bounds; out-of-range values are clamped or rejected, never silently changed. The reference has every response field.
| Method | Path | Parameters | Returns |
|---|---|---|---|
GET | /expected-move/{ticker} | expiration | The straddle-implied move in dollars and percent with upper and lower bounds and days to expiry. |
GET | /earnings-verdict/{ticker} | none | The priced event move against the historical average, straddle hit rate and return, and a scored verdict with reasons. |
GET | /earnings-calendar | days_ahead 1 to 90 | Upcoming reports, each with the implied move against that name's average. |
GET | /earnings-history/{ticker} | num_quarters 1 to 40 | Quarter by quarter: the move, the gap, and how the straddle did. |
GET | /iv-crush/{ticker} | days_before, days_after | IV build into earnings and the drop after, averaged over past events. |
GET | /expected-vs-actual/{ticker} | none | Implied versus realized move over past events. |
GET | /post-earnings-drift/{ticker} | quarters | Whether the move continues or fades in the days after. |
GET | /historical-moves/{ticker} | periods CSV | The distribution of moves over rolling windows, event or not. |
GET | /mispricing-assessment/{ticker} | none | IV rank, VRP and expected-versus-actual combined into a premium buy or sell read. |
The same data, in plain English
4 MCP tools
wrap this family.
Connect the ApexVol MCP server and an assistant can call these by name. One URL, a sign-in, no token to paste.
- calculate_expected_move
- get_earnings_calendar
- analyze_earnings_history
- get_earnings_move_analysis
Set it up in:
What people build
Three things
this is for.
Access
- Auth
- Bearer token, prefix
avmcp_, created under Account, then API Access. Shown once, hashed at rest, rotates in one click. - Limits
- 60 requests a minute and 1,000 an hour per token, with a 10,000-request monthly budget per account. Every response carries the remaining counts in headers.
- Plans
- Included with every paid plan from $55 a month. Each endpoint follows the tier of its web feature; Pro unlocks the full surface.
- Spec
- OpenAPI 3.1 at /docs/api/openapi.json and the whole reference as one Markdown file at /docs/api/apexvol-api.md.
Questions
Asked before
the first call.
How is the expected move calculated?
From the at-the-money straddle for the expiration named, as dollars and a percent of spot. The earnings endpoints go further and isolate the event move from the rest of the expiry's variance, which the response reports as implied_move_pct with its source labelled.
What does the historical move measure?
The close-to-open gap on the session after the report, which is the move an earnings straddle is exposed to. Close-to-close moves are reported alongside because the two can differ a lot.
What does the verdict mean?
BUY_STRADDLE means the priced move looks small against history and the straddle's record; SELL_STRADDLE the reverse; NO_CLEAR_EDGE that the components disagree or the report is too far out. The confidence and reasons are always returned so the label can be checked.
How far ahead does the calendar go?
Up to 90 days. Each row carries the implied move and the historical average so the calendar is already a ranking, not a list of dates.
Included with
every paid plan.
From $55 a month, tier-matched: your token queries the data your plan includes and Pro unlocks the full surface.
Real market data, not a sandbox. See it live on AAPL.