{ "openapi": "3.1.0", "info": { "title": "FlashAlpha Historical API", "version": "1.0.0", "summary": "Point-in-time replay of FlashAlpha analytics. Mirrors every live endpoint shape with a required at= parameter. Alpha tier.", "description": "Point-in-time replay of every FlashAlpha live analytics endpoint. Coverage: SPY fully backfilled from 2018-04-16 at 1-minute resolution (6.7B option rows). Other symbols backfill on demand (~48h). All endpoints require Alpha-tier API key; historical requests share the live daily quota bucket.\n\n**Note on response shapes:** most historical responses match the live API shape exactly so the same SDK code works against both with a base-URL swap. A few responses diverge from live — see the schemas for `OptionQuoteResponse` (flat array, not wrapped object), `MaxPainResponse` (`max_pain_by_expiration`, not `_by_expiry`), `StockSummaryResponse` (nested `{value, change, change_pct}` macro objects, plus an `exposure.hedging_estimate.dealer_shares` field that is named `dealer_shares_to_trade` on the standalone `/v1/exposure/summary` endpoint). Treat the schemas in this file as authoritative for historical.\n\n**About the `examples` blocks:** every operation references a real captured response under `https://flashalpha.com/docs/samples/historical-*.json`, fetched live from `historical.flashalpha.com` and frozen at `at=2024-08-05T10:30:00` (the August 2024 carry-unwind / VIX spike). They are NOT illustrative or fabricated — every numeric value is what the API actually returned for that timestamp. Treat them as authoritative for the SHAPE of a response and as a reproducible point fixture for tests, but obviously not as predictions of current market state.\n\nFor the live API spec, see https://lab.flashalpha.com/swagger/v1/swagger.json or https://flashalpha.com/docs/api.md.\n\nFull human-readable spec: https://flashalpha.com/docs/historical.md.", "contact": { "name": "FlashAlpha", "url": "https://flashalpha.com", "email": "hello@flashalpha.com" }, "license": { "name": "FlashAlpha Terms of Service", "url": "https://flashalpha.com/terms" } }, "servers": [ { "url": "https://historical.flashalpha.com", "description": "Historical (point-in-time replay). Alpha tier. Pair with live host https://lab.flashalpha.com for real-time." } ], "externalDocs": { "description": "Historical API documentation (Markdown spec)", "url": "https://flashalpha.com/docs/historical.md" }, "tags": [ { "name": "Coverage", "description": "Symbol inventory and date-range coverage." }, { "name": "Exposure", "description": "Historical dealer-positioning analytics: GEX, DEX, VEX, CHEX, levels, summary, narrative, 0DTE." }, { "name": "Max Pain", "description": "Historical max pain, pain curve, dealer alignment, pin probability." }, { "name": "Volatility", "description": "Historical realized vol, IV term structure, skew, IV-RV spreads, VRP, IV surface." }, { "name": "Market Data", "description": "Historical stock and option quotes with greeks." }, { "name": "Stock Summary", "description": "Composite point-in-time snapshot: price, IV, exposure, macro." } ], "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Alpha-tier API key. Same key works against both lab.flashalpha.com (live) and historical.flashalpha.com (replay)." }, "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "apiKey", "description": "Alternate transport: API key as query parameter. Header is preferred." } }, "parameters": { "PathSymbol": { "name": "symbol", "in": "path", "required": true, "description": "Underlying ticker (e.g. SPY, QQQ, SPX, AAPL).", "schema": { "type": "string", "example": "SPY" } }, "PathTicker": { "name": "ticker", "in": "path", "required": true, "description": "Underlying ticker.", "schema": { "type": "string", "example": "SPY" } }, "QueryAt": { "name": "at", "in": "query", "required": true, "description": "Point-in-time timestamp in ET wall-clock. Accepts `YYYY-MM-DDTHH:mm:ss` (minute precision) or `YYYY-MM-DD` (defaults to 16:00 ET session close). Treated as ET — do NOT shift by UTC offset. Bounded by coverage window (SPY: 2018-04-16 onward).", "schema": { "type": "string", "examples": [ "2024-08-05T10:30:00", "2020-03-16T15:30:00", "2024-08-05" ] } }, "QueryExpiration": { "name": "expiration", "in": "query", "required": false, "description": "Filter to a single option expiration (`YYYY-MM-DD`). Omit for full chain. Used by /v1/exposure/gex,dex,vex,chex,levels and /v1/maxpain.", "schema": { "type": "string", "format": "date" } }, "QueryExpiry": { "name": "expiry", "in": "query", "required": false, "description": "Filter the option chain to a single expiration (`YYYY-MM-DD`). Used by /v1/optionquote (note: the spelling is `expiry`, not `expiration`, on this endpoint — this matches the SDK's `option_quote(..., expiry=...)` argument).", "schema": { "type": "string", "format": "date" } }, "QueryMinOi": { "name": "min_oi", "in": "query", "required": false, "description": "Minimum open interest threshold per strike.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, "QueryStrike": { "name": "strike", "in": "query", "required": false, "description": "Filter to a specific strike price.", "schema": { "type": "number" } }, "QueryOptionType": { "name": "type", "in": "query", "required": false, "description": "Filter to call or put.", "schema": { "type": "string", "enum": [ "C", "P" ] } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TierRestricted": { "description": "API key valid but tier below Alpha. Historical replay requires Alpha plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Daily request quota exceeded (shared with live host).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "OutOfRange": { "description": "`at` parameter outside coverage window for symbol, or symbol not backfilled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "example": "tier_restricted" }, "message": { "type": "string", "example": "Historical replay requires Alpha plan." } } }, "Coverage": { "type": "object", "description": "Coverage inventory for one or more symbols. See sample: /docs/samples/historical-coverage.json.", "properties": { "count": { "type": "integer" }, "tickers": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "coverage": { "type": "object", "properties": { "first": { "type": "string", "format": "date" }, "last": { "type": "string", "format": "date" }, "total_days": { "type": "integer" }, "healthy_days": { "type": "integer" } } }, "tables": { "type": "object", "additionalProperties": { "type": "integer" } }, "gaps": { "type": "object", "additionalProperties": { "type": "integer" } }, "updated_at": { "type": "string" } } } } } }, "GexResponse": { "type": "object", "description": "Historical gamma exposure by strike. Real capture (frozen at at=2024-08-05T10:30:00): /docs/samples/historical-gex.json.", "properties": { "symbol": { "type": "string" }, "underlying_price": { "type": "number" }, "as_of": { "type": "string", "description": "Resolved at-timestamp (ET wall-clock)." }, "as_of_requested": { "type": "string", "description": "Echo of the at parameter exactly as supplied (only present on historical responses)." }, "gamma_flip": { "type": "number" }, "net_gex": { "type": "number" }, "net_gex_label": { "type": "string", "enum": [ "positive", "negative" ] }, "strikes": { "type": "array", "items": { "type": "object", "properties": { "strike": { "type": "number" }, "call_gex": { "type": "number" }, "put_gex": { "type": "number" }, "net_gex": { "type": "number" }, "call_oi": { "type": "integer" }, "put_oi": { "type": "integer" }, "call_volume": { "type": "integer" }, "put_volume": { "type": "integer" }, "call_oi_change": { "type": [ "integer", "null" ], "description": "Day-over-day OI change. Null on historical (T-1 OI not always backfilled)." }, "put_oi_change": { "type": [ "integer", "null" ] } } } } } }, "VrpResponse": { "type": "object", "description": "Historical VRP dashboard with leak-free percentile/z-score. Note: percentile, z_score, and vrp_regime can be null when the at-timestamp falls inside the percentile lookback window (history_days=0). strategy_scores and net_harvest_score are also nullable depending on regime. Real capture (frozen at at=2024-08-05T10:30:00): /docs/samples/historical-vrp.json.", "properties": { "symbol": { "type": "string" }, "underlying_price": { "type": "number" }, "as_of": { "type": "string" }, "market_open": { "type": "boolean" }, "vrp": { "type": "object", "properties": { "atm_iv": { "type": "number" }, "rv_5d": { "type": "number" }, "rv_10d": { "type": "number" }, "rv_20d": { "type": "number" }, "rv_30d": { "type": "number" }, "vrp_5d": { "type": "number" }, "vrp_10d": { "type": "number" }, "vrp_20d": { "type": "number" }, "vrp_30d": { "type": "number" }, "z_score": { "type": [ "number", "null" ], "description": "Null when history_days==0 (insufficient prior data)." }, "percentile": { "type": [ "number", "null" ] }, "history_days": { "type": "integer" } } }, "variance_risk_premium": { "type": "number" }, "convexity_premium": { "type": "number" }, "fair_vol": { "type": "number" }, "directional": { "type": "object", "properties": { "put_wing_iv_25d": { "type": "number" }, "call_wing_iv_25d": { "type": "number" }, "downside_rv_20d": { "type": "number" }, "upside_rv_20d": { "type": "number" }, "downside_vrp": { "type": "number" }, "upside_vrp": { "type": "number" } } }, "term_vrp": { "type": "array", "items": { "type": "object", "properties": { "dte": { "type": "integer" }, "iv": { "type": "number" }, "rv": { "type": "number" }, "vrp": { "type": "number" } } } }, "gex_conditioned": { "type": "object" }, "vanna_conditioned": { "type": "object" }, "regime": { "type": "object", "properties": { "gamma": { "type": "string" }, "vrp_regime": { "type": [ "string", "null" ] }, "net_gex": { "type": "number" }, "gamma_flip": { "type": "number" } } }, "strategy_scores": { "type": [ "object", "null" ] }, "net_harvest_score": { "type": [ "number", "null" ] }, "dealer_flow_risk": { "type": "number" }, "warnings": { "type": "array", "items": { "type": "string" } }, "macro": { "type": "object", "description": "VRP-endpoint macro block uses scalar values (different from stock-summary macro which wraps each in {value,change,change_pct}).", "properties": { "vix": { "type": "number" }, "vix_3m": { "type": "number" }, "vix_term_slope": { "type": "number" }, "dgs10": { "type": "number" }, "hy_spread": { "type": "number" } } } } }, "MaxPainResponse": { "type": "object", "description": "Historical max pain with pain curve, OI distribution, dealer alignment, expected move, pin probability. Real capture (frozen at at=2024-08-05T10:30:00): /docs/samples/historical-max-pain.json.", "properties": { "symbol": { "type": "string" }, "underlying_price": { "type": "number" }, "as_of": { "type": "string" }, "max_pain_strike": { "type": "number" }, "distance": { "type": "object", "properties": { "absolute": { "type": "number" }, "percent": { "type": "number" }, "direction": { "type": "string", "enum": [ "above", "below" ] } } }, "signal": { "type": "string", "enum": ["neutral", "bullish", "bearish"], "description": "Position of spot relative to the max-pain strike (NOT a directional trade recommendation). bullish = spot above max-pain, bearish = below, neutral = within ~0.5% of max-pain." }, "expiration": { "type": "string", "format": "date" }, "put_call_oi_ratio": { "type": "number" }, "pain_curve": { "type": "array", "items": { "type": "object", "properties": { "strike": { "type": "number" }, "call_pain": { "type": "number" }, "put_pain": { "type": "number" }, "total_pain": { "type": "number" } } } }, "oi_by_strike": { "type": "array", "description": "Per-strike OI distribution at the at-timestamp.", "items": { "type": "object", "properties": { "strike": { "type": "number" }, "call_oi": { "type": "integer" }, "put_oi": { "type": "integer" }, "total_oi": { "type": "integer" } } } }, "max_pain_by_expiration": { "type": "array", "description": "Max-pain strike per expiry (note: field is `max_pain_by_expiration`, not `_by_expiry`).", "items": { "type": "object", "properties": { "expiration": { "type": "string", "format": "date" }, "max_pain_strike": { "type": "number" }, "dte": { "type": "integer" }, "total_oi": { "type": "integer" } } } }, "dealer_alignment": { "type": "object", "properties": { "alignment": { "type": "string" }, "description": { "type": "string" }, "gamma_flip": { "type": "number" }, "call_wall": { "type": "number" }, "put_wall": { "type": "number" } } }, "regime": { "type": "string" }, "expected_move": { "type": "object" }, "pin_probability": { "type": "number" } } }, "ExposureSummaryResponse": { "type": "object", "description": "Historical full-Greek exposure summary with regime + dealer hedging. Real capture (frozen at at=2024-08-05T10:30:00): /docs/samples/historical-exposure-summary.json. Note: this endpoint's hedging_estimate uses field name `dealer_shares_to_trade` (the embedded `exposure.hedging_estimate` inside stock-summary uses `dealer_shares` — different field name for the same concept).", "properties": { "symbol": { "type": "string" }, "underlying_price": { "type": "number" }, "as_of": { "type": "string" }, "gamma_flip": { "type": "number" }, "regime": { "type": "string" }, "exposures": { "type": "object", "properties": { "net_gex": { "type": "number" }, "net_dex": { "type": "number" }, "net_vex": { "type": "number" }, "net_chex": { "type": "number" } } }, "interpretation": { "type": "object", "properties": { "gamma": { "type": "string" }, "vanna": { "type": "string" }, "charm": { "type": "string" } } }, "hedging_estimate": { "type": "object", "properties": { "spot_down_1pct": { "type": "object", "properties": { "dealer_shares_to_trade": { "type": "integer" }, "direction": { "type": "string", "enum": [ "buy", "sell" ] }, "notional_usd": { "type": "integer" } } }, "spot_up_1pct": { "type": "object", "properties": { "dealer_shares_to_trade": { "type": "integer" }, "direction": { "type": "string", "enum": [ "buy", "sell" ] }, "notional_usd": { "type": "integer" } } } } }, "zero_dte": { "type": "object", "properties": { "net_gex": { "type": "number" }, "pct_of_total_gex": { "type": "number" }, "expiration": { "type": "string", "format": "date" } } } } }, "OptionQuoteResponse": { "type": "array", "description": "Historical option chain. NOTE: returns a flat array of contracts (not wrapped in an object like the live endpoint). Field names also differ from live: `open_interest` (not `oi`), `implied_vol` (not `iv`), `lastUpdate` (camelCase), plus historical-only fields `iv_bid`/`iv_ask`/`bidSize`/`askSize`/`vanna`/`charm`/`rho`/`svi_vol_gated`. Real capture (frozen at at=2024-08-05T10:30:00): /docs/samples/historical-optionquote.json.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "C", "P" ] }, "expiry": { "type": "string", "format": "date" }, "strike": { "type": "number" }, "bid": { "type": "number" }, "ask": { "type": "number" }, "mid": { "type": "number" }, "bidSize": { "type": "integer" }, "askSize": { "type": "integer" }, "lastUpdate": { "type": "string" }, "implied_vol": { "type": "number", "description": "Mid-IV (not the live endpoint's iv field)." }, "iv_bid": { "type": [ "number", "null" ] }, "iv_ask": { "type": [ "number", "null" ] }, "delta": { "type": "number" }, "gamma": { "type": "number" }, "theta": { "type": "number" }, "vega": { "type": "number" }, "rho": { "type": "number" }, "vanna": { "type": "number" }, "charm": { "type": "number" }, "svi_vol": { "type": [ "number", "null" ], "description": "SVI-smoothed IV. Null when svi_vol_gated indicates the value is not exposed (see svi_vol_gated)." }, "svi_vol_gated": { "type": [ "string", "null" ], "description": "Reason svi_vol is null when applicable, e.g. `backtest_mode`." }, "open_interest": { "type": "integer" }, "volume": { "type": "integer" } } } }, "StockSummaryResponse": { "type": "object", "description": "Historical composite snapshot: price, IV term structure + skew, options flow, exposure (including a nested hedging_estimate using `dealer_shares` — different from the standalone exposure-summary endpoint which uses `dealer_shares_to_trade`), top strikes, macro. Macro entries are nested objects {value, change, change_pct} (different from VRP-endpoint macro which is flat scalars). Real capture (frozen at at=2024-08-05T10:30:00): /docs/samples/historical-stock-summary.json.", "properties": { "symbol": { "type": "string" }, "as_of": { "type": "string" }, "market_open": { "type": "boolean" }, "price": { "type": "object", "properties": { "bid": { "type": "number" }, "ask": { "type": "number" }, "mid": { "type": "number" }, "last": { "type": "number" }, "last_update": { "type": "string" } } }, "volatility": { "type": "object", "properties": { "atm_iv": { "type": "number" }, "hv_20": { "type": "number" }, "hv_60": { "type": "number" }, "vrp": { "type": "number" }, "skew_25d": { "type": "object", "properties": { "expiry": { "type": "string", "format": "date" }, "days_to_expiry": { "type": "integer" }, "put_25d_iv": { "type": "number" }, "atm_iv": { "type": "number" }, "call_25d_iv": { "type": "number" }, "skew_25d": { "type": "number" }, "smile_ratio": { "type": "number" } } }, "iv_term_structure": { "type": "array", "items": { "type": "object", "properties": { "expiry": { "type": "string", "format": "date" }, "iv": { "type": "number" }, "days_to_expiry": { "type": "integer" } } } } } }, "options_flow": { "type": "object", "properties": { "total_call_oi": { "type": "integer" }, "total_put_oi": { "type": "integer" }, "total_call_volume": { "type": "integer" }, "total_put_volume": { "type": "integer" }, "pc_ratio_oi": { "type": "number" }, "pc_ratio_volume": { "type": [ "number", "null" ] }, "active_expirations": { "type": "integer" } } }, "exposure": { "type": "object", "properties": { "net_gex": { "type": "number" }, "net_dex": { "type": "number" }, "net_vex": { "type": "number" }, "net_chex": { "type": "number" }, "gamma_flip": { "type": "number" }, "call_wall": { "type": "number" }, "put_wall": { "type": "number" }, "max_pain": { "type": "number" }, "highest_oi_strike": { "type": "number" }, "regime": { "type": "string" }, "interpretation": { "type": "object" }, "hedging_estimate": { "type": "object", "description": "Stock-summary exposure block uses `dealer_shares` (the standalone /v1/exposure/summary uses `dealer_shares_to_trade`).", "properties": { "spot_down_1pct": { "type": "object", "properties": { "dealer_shares": { "type": "integer" }, "direction": { "type": "string", "enum": [ "buy", "sell" ] }, "notional_usd": { "type": "integer" } } }, "spot_up_1pct": { "type": "object", "properties": { "dealer_shares": { "type": "integer" }, "direction": { "type": "string", "enum": [ "buy", "sell" ] }, "notional_usd": { "type": "integer" } } } } }, "zero_dte": { "type": "object", "properties": { "net_gex": { "type": "number" }, "pct_of_total": { "type": "number" }, "expiration": { "type": "string", "format": "date" } } }, "top_strikes": { "type": "array", "items": { "type": "object", "properties": { "strike": { "type": "number" }, "net_gex": { "type": "number" }, "call_oi": { "type": "integer" }, "put_oi": { "type": "integer" }, "total_oi": { "type": "integer" } } } }, "oi_weighted_dte": { "type": "number" } } }, "macro": { "type": "object", "description": "Each scalar series is wrapped in a {value, change, change_pct} object. vix_term_structure has its own structure ({levels: {...}, near_slope_pct, structure}). vix_futures and fear_and_greed may be null.", "properties": { "vix": { "$ref": "#/components/schemas/MacroSeries" }, "vvix": { "$ref": "#/components/schemas/MacroSeries" }, "skew": { "$ref": "#/components/schemas/MacroSeries" }, "spx": { "$ref": "#/components/schemas/MacroSeries" }, "move": { "$ref": "#/components/schemas/MacroSeries" }, "vix_term_structure": { "type": "object", "properties": { "levels": { "type": "object", "properties": { "vix9d": { "type": "number" }, "vix": { "type": "number" }, "vix3m": { "type": "number" }, "vix6m": { "type": "number" } } }, "near_slope_pct": { "type": "number" }, "structure": { "type": "string", "enum": [ "contango", "backwardation" ] } } }, "vix_futures": { "type": [ "object", "null" ] }, "fear_and_greed": { "type": [ "object", "null" ] } } } } }, "MacroSeries": { "type": "object", "properties": { "value": { "type": "number" }, "change": { "type": "number" }, "change_pct": { "type": "number" } } } } }, "security": [ { "ApiKeyHeader": [] }, { "ApiKeyQuery": [] } ], "paths": { "/v1/tickers": { "get": { "tags": [ "Coverage" ], "summary": "Coverage inventory: which symbols are backfilled and through what date.", "description": "Returns the symbol-by-symbol coverage map. No `at` parameter. Use this to discover whether a symbol/date is in scope before issuing replay calls.", "operationId": "getHistoricalCoverage", "parameters": [ { "name": "symbol", "in": "query", "required": false, "description": "Filter to a single ticker; returns the single object instead of the list. 404 `no_coverage` if the symbol has never been backfilled.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Coverage inventory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coverage" }, "examples": { "coverage": { "summary": "Coverage inventory at the most recent backfill point", "externalValue": "https://flashalpha.com/docs/samples/historical-coverage.json" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/exposure/gex/{symbol}": { "get": { "tags": [ "Exposure" ], "summary": "Historical gamma exposure by strike at a specific point in time.", "description": "Same response shape as live `/v1/exposure/gex/{symbol}`. Returns per-strike call/put gamma exposure, OI, volume, gamma flip, and net GEX as they stood at `at`.", "operationId": "getHistoricalGex", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" }, { "$ref": "#/components/parameters/QueryExpiration" }, { "$ref": "#/components/parameters/QueryMinOi" } ], "responses": { "200": { "description": "Historical GEX response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GexResponse" }, "examples": { "spy-2024-08-05": { "summary": "SPY GEX at 2024-08-05T10:30:00 ET (carry-unwind / vol spike)", "externalValue": "https://flashalpha.com/docs/samples/historical-gex.json" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" }, "404": { "$ref": "#/components/responses/OutOfRange" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/exposure/dex/{symbol}": { "get": { "tags": [ "Exposure" ], "summary": "Historical delta exposure by strike.", "operationId": "getHistoricalDex", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" }, { "$ref": "#/components/parameters/QueryExpiration" }, { "$ref": "#/components/parameters/QueryMinOi" } ], "responses": { "200": { "description": "Historical DEX response (same shape as live DEX)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/exposure/vex/{symbol}": { "get": { "tags": [ "Exposure" ], "summary": "Historical vanna exposure by strike.", "operationId": "getHistoricalVex", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" }, { "$ref": "#/components/parameters/QueryExpiration" }, { "$ref": "#/components/parameters/QueryMinOi" } ], "responses": { "200": { "description": "Historical VEX response (same shape as live VEX)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/exposure/chex/{symbol}": { "get": { "tags": [ "Exposure" ], "summary": "Historical charm exposure by strike.", "operationId": "getHistoricalChex", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" }, { "$ref": "#/components/parameters/QueryExpiration" }, { "$ref": "#/components/parameters/QueryMinOi" } ], "responses": { "200": { "description": "Historical CHEX response (same shape as live CHEX)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/exposure/levels/{symbol}": { "get": { "tags": [ "Exposure" ], "summary": "Historical key levels: gamma flip, call wall, put wall, highest-OI strike, 0DTE magnet.", "operationId": "getHistoricalLevels", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" } ], "responses": { "200": { "description": "Historical levels response (same shape as live levels)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/exposure/summary/{symbol}": { "get": { "tags": [ "Exposure" ], "summary": "Historical full exposure summary with regime + dealer hedging.", "operationId": "getHistoricalExposureSummary", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" } ], "responses": { "200": { "description": "Historical exposure summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExposureSummaryResponse" }, "examples": { "spy-2024-08-05": { "summary": "SPY exposure summary at 2024-08-05T10:30:00 ET", "externalValue": "https://flashalpha.com/docs/samples/historical-exposure-summary.json" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/exposure/narrative/{symbol}": { "get": { "tags": [ "Exposure" ], "summary": "Historical verbal narrative analysis (LLM-generated against the at-time exposure state).", "operationId": "getHistoricalNarrative", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" } ], "responses": { "200": { "description": "Historical narrative response (same shape as live narrative)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/exposure/zero-dte/{symbol}": { "get": { "tags": [ "Exposure" ], "summary": "Historical 0DTE analytics: pin risk, expected move, gamma acceleration at the at-minute.", "operationId": "getHistoricalZeroDte", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" } ], "responses": { "200": { "description": "Historical 0DTE response (same shape as live zero-dte)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/maxpain/{symbol}": { "get": { "tags": [ "Max Pain" ], "summary": "Historical max pain with pain curve, dealer alignment, pin probability.", "operationId": "getHistoricalMaxPain", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" }, { "$ref": "#/components/parameters/QueryExpiration" } ], "responses": { "200": { "description": "Historical max pain response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaxPainResponse" }, "examples": { "spy-2024-08-05": { "summary": "SPY max pain at 2024-08-05T10:30:00 ET", "externalValue": "https://flashalpha.com/docs/samples/historical-max-pain.json" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/volatility/{symbol}": { "get": { "tags": [ "Volatility" ], "summary": "Historical realized vol, IV term structure, skew, IV-RV spreads.", "operationId": "getHistoricalVolatility", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" } ], "responses": { "200": { "description": "Historical volatility response (same shape as live volatility)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/vrp/{symbol}": { "get": { "tags": [ "Volatility" ], "summary": "Historical VRP dashboard with leak-free percentile and z-score.", "description": "Returns variance-risk-premium analytics with leak-free percentile and z-score (date-bounded in SQL — backtest at time t only sees data strictly before t).", "operationId": "getHistoricalVrp", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" } ], "responses": { "200": { "description": "Historical VRP response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VrpResponse" }, "examples": { "spy-2024-08-05": { "summary": "SPY VRP at 2024-08-05T10:30:00 ET", "externalValue": "https://flashalpha.com/docs/samples/historical-vrp.json" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/surface/{symbol}": { "get": { "tags": [ "Volatility" ], "summary": "Historical implied volatility surface grid (50x50, SVI-smoothed).", "operationId": "getHistoricalSurface", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" } ], "responses": { "200": { "description": "Historical IV surface response (same shape as live surface)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/adv_volatility/{symbol}": { "get": { "tags": [ "Volatility" ], "summary": "Historical advanced volatility: per-expiry SVI parameters, forward prices, total variance surface, butterfly/calendar arbitrage flags, variance swap fair values, and greeks surfaces (vanna/charm/volga/speed).", "description": "Same response shape as live `/v1/adv_volatility/{symbol}`. Note: SVI fits are stamped end-of-day in the pipeline, so intraday `at=` returns the most recent EOD SVI parameters, not a fresh intraday calibration. Call `at=YYYY-MM-DD` to get the EOD snapshot for a specific date.", "operationId": "getHistoricalAdvVolatility", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" } ], "responses": { "200": { "description": "Historical advanced-volatility response. Top-level keys: symbol, underlying_price, as_of, market_open, svi_parameters[] (one entry per expiry), forward_prices, total_variance_surface, arbitrage_flags, variance_swap_fair_values, greeks_surfaces." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/stockquote/{ticker}": { "get": { "tags": [ "Market Data" ], "summary": "Historical stock quote (bid/ask/mid/last) at the at-minute.", "operationId": "getHistoricalStockQuote", "parameters": [ { "$ref": "#/components/parameters/PathTicker" }, { "$ref": "#/components/parameters/QueryAt" } ], "responses": { "200": { "description": "Historical stock-quote response." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/optionquote/{symbol}": { "get": { "tags": [ "Market Data" ], "summary": "Historical option chain with BSM greeks, IV, OI, plus svi_vol.", "operationId": "getHistoricalOptionQuote", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" }, { "$ref": "#/components/parameters/QueryExpiry" }, { "$ref": "#/components/parameters/QueryStrike" }, { "$ref": "#/components/parameters/QueryOptionType" } ], "responses": { "200": { "description": "Historical option-quote response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptionQuoteResponse" }, "examples": { "spy-2024-08-09-expiry": { "summary": "SPY 2024-08-09 expiry chain at 2024-08-05T10:30:00 ET", "externalValue": "https://flashalpha.com/docs/samples/historical-optionquote.json" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } }, "/v1/stock/{symbol}/summary": { "get": { "tags": [ "Stock Summary" ], "summary": "Historical comprehensive stock snapshot: price, IV, exposure, macro at the at-minute.", "operationId": "getHistoricalStockSummary", "parameters": [ { "$ref": "#/components/parameters/PathSymbol" }, { "$ref": "#/components/parameters/QueryAt" } ], "responses": { "200": { "description": "Historical stock-summary response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockSummaryResponse" }, "examples": { "spy-2024-08-05": { "summary": "SPY stock summary at 2024-08-05T10:30:00 ET", "externalValue": "https://flashalpha.com/docs/samples/historical-stock-summary.json" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/TierRestricted" } } } } } }