# Historical Options Replay Runbook

A historical options replay is an attempt to reconstruct what a strategy, scanner, or analyst could actually observe and trade at a past decision time. It is stricter than a chart review and more useful than a table of old option prices. The replay must preserve contract identity, timestamp windows, quote evidence, trade evidence, and rejects.

Use this runbook for earnings studies, 0DTE tests, opening range strategies, implied-move reviews, unusual-options-activity backtests, and paper-trading parity checks.

Use it alongside [Historical Options Data API](/historical-options-data-api), [Options Backtesting API](/options-backtesting-api), [Options Data API Evaluation](/docs/options-data-provider-evaluation), and [Why Option Quotes Matter More Than Last Price](/blog/why-option-quotes-matter-more-than-last-price).

## Replay principles

1. Use the exact contract, not a ticker-level idea.
2. Rebuild the contract universe before selecting legs.
3. Use bid/ask quotes for fills.
4. Use trades for activity validation, not automatic execution.
5. Store rejected rows with reasons.
6. Record request URLs and timestamp windows.
7. Keep plan, freshness, and entitlement assumptions visible.

The goal is not to make the backtest pessimistic. The goal is to keep the evidence chain honest enough that a developer can reproduce or debug it. That is the same standard used in [Backtest Options Without Stale Contracts](/blog/backtest-options-without-stale-contract-leakage), [Same-Bar Fill Lookahead](/blog/same-bar-fills-lookahead-intraday-strategies), and [Backtest Artifacts and Launch Contracts](/blog/backtest-artifacts-manifests-launch-contracts).

## Event record

Every replay starts with an event record. For a strategy that does not depend on news, the event can be the signal timestamp. For an earnings workflow, it is the earnings release, call, or first tradable session after the release.

| Field | Example | Reason |
| --- | --- | --- |
| `underlying_ticker` | `NVDA` | Connects stock context to option contracts |
| `event_timestamp` | `2026-05-20T20:05:00Z` | The event anchor |
| `decision_timestamp` | `2026-05-20T19:45:00Z` | Last state the model could observe before entry |
| `entry_window_start` | `2026-05-20T19:40:00Z` | Quote window for entry evidence |
| `entry_window_end` | `2026-05-20T19:50:00Z` | Prevents using later quotes |
| `exit_window_start` | `2026-05-21T13:30:00Z` | Exit evidence starts after the event |
| `exit_window_end` | `2026-05-21T14:00:00Z` | Bounded exit logic |
| `contract_policy` | `7-21 DTE, 0.35-0.65 delta` | Makes selection reproducible |
| `fill_policy` | `long ask in, bid out` | Makes PnL assumptions explicit |

If you cannot write this event record, the replay is probably not ready.

## Request sequence

A minimal CuteMarkets replay follows this order:

```bash
curl "https://api.cutemarkets.com/v1/tickers/expirations/NVDA/" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.cutemarkets.com/v1/options/contracts/?underlying_ticker=NVDA&as_of=2026-05-20&expiration_date.gte=2026-05-22&expiration_date.lte=2026-06-19&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.cutemarkets.com/v1/options/quotes/O:NVDA260522C00180000/?timestamp.gte=2026-05-20T19:40:00Z&timestamp.lt=2026-05-20T19:50:00Z&limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.cutemarkets.com/v1/options/trades/O:NVDA260522C00180000/?timestamp.gte=2026-05-20T19:40:00Z&timestamp.lt=2026-05-21T14:00:00Z&limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The OCC ticker above is a placeholder. In a real replay it must come from contract discovery or a chain response that belongs to the correct time period.

## Contract selection

Contract selection should be deterministic. A replay that searches the whole chain after the outcome is known will find impressive but untrustworthy winners.

Recommended selection fields:

| Field | Use |
| --- | --- |
| Expiration date | Enforces DTE and event-window policy |
| Contract type | Separates calls, puts, and spreads |
| Strike | Preserves the exact leg |
| Moneyness | Prevents arbitrary far-wing selection |
| Delta | Supports target-risk selection when available |
| Open interest | First-pass participation filter |
| Volume | Same-day activity context |
| IV and Greeks | Volatility and risk context |
| Latest quote | Initial spread and freshness check |

Do not let volume alone choose the trade. Volume can come from closing trades, rolls, hedges, cheap far-out-of-the-money speculation, or one-off prints.

## Quote windows

Quote windows are the primary fill evidence.

For each selected contract, compute:

- best available quote inside the entry window
- quote age at decision time
- bid, ask, midpoint, and spread dollars
- spread percent relative to midpoint
- displayed bid and ask size if available
- whether the quote passes the policy
- whether the quote is used for fill or only for diagnostics

Example fill rules:

| Position | Entry | Exit |
| --- | --- | --- |
| Long call | Buy at ask | Sell at bid |
| Long put | Buy at ask | Sell at bid |
| Short call | Sell at bid | Buy at ask |
| Short put | Sell at bid | Buy at ask |
| Long straddle | Buy call ask plus put ask | Sell call bid plus put bid |
| Short straddle | Sell call bid plus put bid | Buy call ask plus put ask |

Midpoint results can be useful as a sensitivity column, but they should not replace executable assumptions unless the study is explicitly theoretical.

## Trade and aggregate validation

Trades answer a different question from quotes: what printed. Use trades to validate participation, price formation, and tape context.

Aggregates answer another question: what the bar-level path looked like. Use aggregates for charting, event windows, and strategy signals.

Do not use either as a substitute for bid/ask fill evidence. A contract can have a trade print and still be too wide or stale for the strategy. An aggregate can show a high or low that was never available at the moment your system needed to act.

## Reject reasons

Rejected rows should be first-class output. A replay that hides rejects is hard to trust.

Common reject reasons:

- contract was not listed at the decision time
- expiration did not match policy
- quote window was missing
- quote was older than the allowed threshold
- spread percent exceeded the maximum threshold
- bid was zero or below the exit threshold
- open interest or volume was below policy
- IV or Greeks were missing when required
- pagination did not load the full surface
- plan did not include the required quote endpoint
- corporate-action adjustment made the contract outside policy

Rejects often explain why a strategy that looked strong in last-price form disappears under quote-aware replay.

## Replay artifact

A useful replay artifact has enough detail for a second developer to rerun the study.

```json
{
  "replay_id": "nvda-earnings-2026-05-20-front-week",
  "underlying": "NVDA",
  "decision_timestamp": "2026-05-20T19:45:00Z",
  "selected_contracts": ["O:NVDA260522C00180000", "O:NVDA260522P00180000"],
  "requests": [
    "/v1/tickers/expirations/NVDA/",
    "/v1/options/contracts/?underlying_ticker=NVDA&as_of=2026-05-20",
    "/v1/options/quotes/O:NVDA260522C00180000/?timestamp.gte=..."
  ],
  "fill_policy": "long ask in, bid out",
  "reject_policy": {
    "max_quote_age_ms": 1000,
    "max_spread_percent": 0.35,
    "min_bid": 0.05
  },
  "rejects": [
    {
      "contract": "O:NVDA260522C00160000",
      "reason": "spread_percent_over_limit"
    }
  ]
}
```

This artifact is more valuable than a pretty chart because it gives support, research, and engineering the same source of truth. It also connects directly to [Paper Trading Bot Operations](/docs/paper-trading-bot-operations) and [Backtest to Paper Trading Parity](/blog/backtest-to-paper-trading-parity-checklist) when a research workflow moves into simulation.

## Related CuteMarkets docs

- [Contracts](/docs/contracts)
- [Quotes](/docs/quotes)
- [Trades](/docs/trades)
- [Aggregates](/docs/aggregates)
- [Options Contract Selection](/docs/options-contract-selection)
- [Backtesting Execution Realism](/docs/backtesting-execution-realism)

## Replay artifact notes

A replay runbook succeeds when the final artifact can be handed to a skeptical developer. Include the research date, signal timestamp, as_of contract request, selected OCC option ticker, quote window, trade window, aggregate bar window, fill rule, rejected candidates, data-quality labels, and the exact code version that produced the result.

Replay also needs a recovery policy. If the quote window is empty, the cursor is incomplete, the contract was not listed, or the entitlement was unavailable, the artifact should show a reject rather than a patched estimate. Use [Backtesting Data Model](/docs/backtesting-data-model), [Backtesting Execution Realism](/docs/backtesting-execution-realism), and [Market Data Ingestion and Caching](/docs/market-data-ingestion-and-caching) to keep the artifact tied to source rows.