Historical trader context: expiry impact and income diagnostics

Historical routes and scope

Use historical.flashalpha.com, an Alpha or Enterprise API key, and a required at for analytics replay. Naive timestamps use Eastern wall time; an explicit UTC offset is converted to Eastern. Date-only exposure requests use 15:55 ET to preserve same-day Greeks; income and full-volatility requests use 16:00 ET. Use the same explicit timestamp to compare routes, and specify an actual session time on an early close.

Release availability: term structure and full volatility already exist; their new context fields and the new routes require the corresponding Historical API release. Local production-data captures establish the tested responses; they do not establish that the additions are deployed. Missing archive inputs remain explicit errors or unavailable fields.

Expiry impact and strike dependency

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://historical.flashalpha.com/v1/exposure/expiry-impact/SPY?at=2026-10-12T15:55:00&limit=5"
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://historical.flashalpha.com/v1/exposure/strike-dependency/SPY?at=2026-10-12T15:55:00&strike=670"

Optional expiry=yyyy-MM-dd chooses a maturity; otherwise selection uses the next eligible expiry. limit is 1–20 and limits displayed ranked strikes, not whole-chain totals. Strike dependency requires an exact positive observed strike; it does not round to a nearby contract.

excluding_expiry.gross_gex_usd = current.gross_gex_usd - excluded_expiry.gross_gex_usd
excluding_expiry.net_gex_usd   = current.net_gex_usd - excluded_expiry.net_gex_usd
removed_gross_share_pct       = 100 * excluded_expiry.gross_gex_usd / current.gross_gex_usd

GEX uses USD delta notional per 1% underlying move, with calls positive and puts negative. Gross shares are percentages of gross magnitude, not net GEX. Zero denominators produce unavailable shares. net_sign_changed compares the two modeled totals.

Removal holds spot, Greeks and all other maturities fixed. It describes sensitivity to excluding a slice, not the next session's forecast, observed dealer inventory or a simulated future settlement. Check data_status, reasons, pricing_basis, quote_at and greeks_oldest_at/greeks_newest_at. Gamma metadata retains oi_as_of=null and oi_vintage_status=unknown; the new income response separately exposes its archived settlement OI date. Original OI revision timing remains unverified.

Research: these replays were run on every 2022-2025 SPY and QQQ session in Does expiring gamma move the market? (pack trader-context-spy-qqq-2022-2025-v2-34105d743fac).

Income replay and cash arithmetic

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://historical.flashalpha.com/v1/strategies/yield-enhancement/SPY?at=2026-10-12T15:55:00&structure=cash_secured_put&feesPerContract=1"

structure is covered_call or cash_secured_put. Optional expiry fixes maturity; otherwise selection preserves the live endpoint's full-chain nearest-absolute-target-delta policy. Quote diagnostics and roll context use the selected contract's expiry, strike and right. targetDelta defaults to 0.25 (valid range greater than zero through one), minOpenInterest to 250 (nonnegative), and excludeEarningsBeforeExpiry to true. stockCostBasis is positive USD per share and feesPerContract a nonnegative USD opening fee.

metrics.income_diagnostics uses the quoted bid for one assumed standard 100-share contract. For a cash-secured put, gross credit is bid × 100, collateral is strike × 100 before credit, gross period return is 100 × credit / collateral, and gross breakeven is strike − bid. Net credit subtracts the supplied opening fee only. Unknown fees leave net fields null. Covered-call return and total-return cap require the caller's stock basis; spot is not substituted.

Legacy premium and rankings use mid. assignment_probability is an absolute-delta proxy, not a calibrated exercise probability; annualized yield is arithmetic extrapolation, not a sustainable-return forecast. Bid diagnostics do not establish a fill, and deliverables remain an explicitly unverified standard-contract assumption. An empty archived root and a 100-share multiplier do not identify strike-adjusted series, so adjusted contracts can qualify. Verify contract adjustments before treating the candidate as a standard unadjusted contract. Quote timestamp and OI vintage statuses accompany the response.

SPY/QQQ report earnings_risk_status=not_applicable_etf. Other equities have an unknown historical earnings calendar: the default earnings exclusion returns an insufficient-data decision rather than silently declaring the calendar clear. Setting excludeEarningsBeforeExpiry=false requests selection without that filter; it does not reconstruct earnings. No historical earnings API is added.

Snapshot replay versus daily series

The SPY/QQQ gamma additions and full-volatility replay, plus income replay, read timestamp-bounded raw quotes, bypassing daily last-quote views. Full-volatility replay for other symbols keeps its existing loader path. This does not certify every raw historical day. The skew, term, VRP-history and expected-move daily reconstructions remain disabled until their materialized sources are repaired and verified. Disabled, invalid or unverifiable sources return HTTP 503 with error=historical_source_unhealthy and a reason; affected days must not enter ranks or observation counts.

For replay volatility reference rows, both SnapshotDate < replay.Date and CreatedAt <= replay UTC instant are required. Later-created backfills are excluded. Existing in-place revisions have no complete version history, so original point-in-time integrity is not fully established.

Expected errors

• 400: malformed timestamps, expiry, strike, limit or income inputs.
• 403: insufficient subscription tier.
• 404: no archived data, missing observed strike or unavailable pack/artifact.
• 422: unsupported gamma symbol or unsupported income contract.
• 503: invalid spot, missing required gamma OI, unhealthy daily source or failed artifact integrity. An income response can instead retain diagnostic fields with an insufficient-data decision.

Use research packs to inspect a strategy-family backtest. The first study fixes monthly 28–35 DTE selection; it does not backtest the endpoint's default full-chain target-delta selection.