Options API How-To

How to Use Options Data for Earnings Research

A developer workflow for turning a known earnings timestamp into an options research artifact with listed expirations, exact OCC contracts, bid/ask validation, and replayable evidence.

Get API key Browse tools

Quick answerLast verified June 4, 2026

Start with an external earnings timestamp, discover listed expirations, select the event-window chain, reconstruct the point-in-time contracts, and validate every implied-move or post-event fill with quotes, trades, and aggregate bars.

Event source

External calendar

Use a dedicated earnings calendar for the date and time, then join CuteMarkets options data around it.

Core data

Chain + quotes

The chain gives candidates; bid/ask history decides whether the candidate was tradable.

Research output

Replay artifact

Store the contract, timestamp window, spread, quote age, open interest, and reject reason.

Event setup

Anchor the event before touching the chain

Treat the earnings date as a separate input, then use Expirations to find listed option expiration dates that cover the announcement. For after-close earnings, the relevant option surface is usually the session before the report and the first regular session after it; for before-open earnings, the pre-event chain and the next opening quote window matter more than the previous close.

The first technical failure mode is selecting a contract from the wrong date. Use Contracts with `as_of` when you need the historical universe, because an event replay should not see strikes, weeklies, adjusted options, or delisted contracts that were unavailable at the decision timestamp.

Surface construction

Build the pre-event option surface

Pull the Options Chain API for one expiration at a time and keep the exact OCC ticker, expiration, strike, call/put side, multiplier, open interest, implied volatility, delta, gamma, theta, vega, bid, ask, and last trade fields together. That gives the research notebook enough context to separate an at-the-money straddle, a skew trade, a calendar spread, or a far-out-of-the-money lottery contract.

For implied-move research, rank candidate calls and puts by moneyness first, then reject contracts with stale quotes, no-bid exits, crossed markets, or spread percent above your threshold. Midpoint, quote age, spread percent, open interest, volume, trade condition, and aggregate bar all belong inside the scoring logic because they determine whether the event result is usable.

ATM straddle

Use the closest call and put by strike, then calculate the straddle midpoint divided by the underlying reference price.

Output: implied move percent.

Skew read

Compare put and call implied volatility, delta buckets, and spread percent before the report.

Output: downside/upside premium bias.

Event replay

Join quotes, trades, and aggregates around entry and exit windows so the post-event result has fill evidence.

Output: replay artifact.

Execution evidence

Validate the result after the announcement

Use Quotes for bid/ask validation and Trades for print context, then use Aggregates to describe the contract price path. Aggregates are useful for visualizing OHLC, VWAP, and volume, but the fill model should still reference the quote window when deciding whether the option could be bought or sold.

A strong earnings result should include rejected candidates beside the winners. Store reject reasons such as missing quote window, stale quote, wide spread, no-bid exit, low open interest, and incomplete pagination so the next research pass can separate market behavior from data-quality noise.

Earnings research request order

Each later request depends on a validated date, contract, or timestamp window from the previous step.

Step	Endpoint family	Why it matters
1. Event calendar	External source	Defines the earnings timestamp and whether the event is before open, during market hours, or after close.
2. Expirations	Listed expirations	Prevents the workflow from assuming a weekly or monthly date that is not listed for the underlying.
3. Chain	Current chain snapshot	Builds the candidate surface with strike, side, open interest, Greeks, IV, bid, ask, and last trade context.
4. Contracts	Historical contracts with as_of	Reconstructs the tradable universe for historical earnings events and avoids look-ahead contract selection.
5. Quotes and trades	Historical quote and trade windows	Validates midpoint, bid/ask spread, quote age, trade condition, and plausible entry or exit fills.
6. Aggregates	Historical OHLC bars	Summarizes price path, volume, VWAP, and post-event movement for charts and reporting.

What to store in the research artifact

Artifact field	Example	Review use
event timestamp	2026-05-12T20:05:00Z	Keeps the options surface aligned to the actual earnings release window.
contract identity	O:NVDA260515C00120000	Preserves the OCC ticker, expiration, strike, side, and multiplier used in the test.
quote evidence	bid, ask, quote age, spread percent	Explains whether the midpoint, bid-side exit, or ask-side entry was plausible.
reject reason	wide-spread, no-bid-exit, stale-quote	Makes the filter auditable instead of silently dropping bad candidates.

API example

Verify the answer with listed data

earnings event request sequence

# 1) Start with an external earnings timestamp, then discover listed expirations.
curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.cutemarkets.com/v1/tickers/expirations/NVDA/"

# 2) Pull the chain that covers the event window.
curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.cutemarkets.com/v1/options/chain/NVDA/?expiration_date=2026-05-15&limit=100"

# 3) Reconstruct the point-in-time contract set for the pre-event session.
curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.cutemarkets.com/v1/options/contracts/?underlying_ticker=NVDA&as_of=2026-05-12&expiration_date=2026-05-15&limit=100"

# 4) Validate fills with bid/ask history and trade history around the event.
curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.cutemarkets.com/v1/options/quotes/O:NVDA260515C00120000/?timestamp.gte=2026-05-12T13:30:00Z&timestamp.lt=2026-05-13T20:00:00Z"
curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.cutemarkets.com/v1/options/trades/O:NVDA260515C00120000/?timestamp.gte=2026-05-12T13:30:00Z&timestamp.lt=2026-05-13T20:00:00Z"

quote-quality straddle filter

from math import isfinite

def midpoint(quote):
    bid = float(quote["bid_price"])
    ask = float(quote["ask_price"])
    if bid <= 0 or ask <= 0 or ask < bid:
        return None
    return (bid + ask) / 2

def spread_pct(quote):
    mid = midpoint(quote)
    if not mid:
        return None
    return (float(quote["ask_price"]) - float(quote["bid_price"])) / mid

def estimate_atm_straddle(chain, underlying_price, max_spread_pct=0.12):
    candidates = []
    for contract in chain["results"]:
        strike = float(contract["strike_price"])
        quote = contract.get("last_quote") or {}
        mid = midpoint(quote)
        spread = spread_pct(quote)
        if mid is None or spread is None or spread > max_spread_pct:
            continue
        candidates.append({
            "ticker": contract["ticker"],
            "side": contract["contract_type"],
            "strike": strike,
            "mid": mid,
            "spread_pct": spread,
            "distance": abs(strike - underlying_price),
        })

    calls = [c for c in candidates if c["side"] == "call"]
    puts = [c for c in candidates if c["side"] == "put"]
    call = min(calls, key=lambda c: c["distance"])
    put = min(puts, key=lambda c: c["distance"])
    implied_move = (call["mid"] + put["mid"]) / underlying_price
    return {"call": call, "put": put, "implied_move_pct": implied_move * 100}

def rank_event_candidates(rows):
    return sorted(
        [row for row in rows if isfinite(row["implied_move_pct"])],
        key=lambda row: (row["quote_reject_count"], -row["open_interest"], row["spread_pct"]),
    )

How to implement

Implementation checklist

Import the event timestamp

Load the earnings date and release timing from a dedicated calendar source, then normalize it to the market session and timestamp window you will test.

Discover listed expirations

Request listed expirations for the underlying and select the nearest event-window expiration or the longer-dated expiration required by the strategy.

Build the chain surface

Pull the chain for each selected expiration and store strike, side, open interest, Greeks, IV, bid, ask, last trade, and snapshot timestamp.

Reconstruct historical contracts

For historical events, request contracts with as_of set to the pre-event decision date so the replay cannot select future listings.

Validate fills and summarize movement

Join quotes, trades, and aggregate bars around entry and exit windows, then record spread percent, quote age, fill price, and reject reason.

Last verified

This guide was last reviewed on June 4, 2026. Date-sensitive market calendars, provider docs, and listed contracts can change, so production workflows should verify the live source before trading or publishing an automated answer.