{"components":{"schemas":{"CorporateActionsResponse":{"properties":{"actions":{"items":{"properties":{"action_id":{"type":"string"},"action_type":{"example":"SPLIT","type":"string"},"announcement_date":{"nullable":true,"type":"string"},"effective_date":{"example":"2020-08-31","type":"string"},"new_value":{"nullable":true,"type":"string"},"old_value":{"nullable":true,"type":"string"},"ratio":{"example":4.0,"type":"number"},"status":{"example":"EFFECTIVE","type":"string"}},"type":"object"},"type":"array"},"entity":{"nullable":true,"properties":{"cik":{"example":"0000320193","type":"string"},"cusip":{"example":"037833100","type":"string"},"entity_id":{"example":"AAPL_INC","type":"string"},"figi":{"example":"BBG000B9XRY4","type":"string"},"legal_name":{"example":"Apple Inc.","type":"string"}},"type":"object"},"symbol_timeline":{"items":{"properties":{"symbol":{"type":"string"},"valid_from":{"type":"string"},"valid_to":{"nullable":true,"type":"string"}},"type":"object"},"type":"array"},"ticker":{"example":"AAPL","type":"string"}},"required":["ticker","actions"],"type":"object"},"ErrorResponse":{"properties":{"error":{"example":"Could not retrieve data","type":"string"}},"required":["error"],"type":"object"},"InstitutionalAnalyticsResponse":{"properties":{"macro_conditioning":{"properties":{"betas":{"properties":{"bear_beta":{"example":0.95,"type":"number"},"bull_beta":{"example":1.25,"type":"number"},"overall":{"example":1.15,"type":"number"}},"type":"object"},"cpi_yoy":{"example":2.8,"type":"number"},"downside_capture":{"example":0.88,"type":"number"},"fed_funds_rate":{"example":4.5,"type":"number"},"is_inverted":{"example":false,"type":"boolean"},"regime":{"example":"NEUTRAL_EXPANSION","type":"string"},"upside_capture":{"example":1.12,"type":"number"},"yield_curve_2s10s":{"example":0.35,"type":"number"}},"type":"object"},"microstructure":{"properties":{"amihud_illiquidity":{"type":"number"},"corwin_schultz_spread":{"example":0.0042,"type":"number"},"roll_effective_spread":{"example":0.0038,"type":"number"},"squeeze_risk_level":{"example":"MODERATE","type":"string"},"squeeze_risk_score":{"example":45.0,"type":"number"},"vpin":{"example":0.28,"type":"number"}},"type":"object"},"permutation_test":{"description":"Block-bootstrap permutation null test: the same strategy rerun on block-shuffled copies of the return series. p_value is the bias-corrected fraction of null Sharpes >= the real Sharpe, so its floor is 1/(n_permutations+1), never exactly 0.","properties":{"n_permutations":{"example":100,"type":"integer"},"null_mean":{"example":0.12,"type":"number"},"null_std":{"example":0.78,"type":"number"},"p_value":{"example":0.0396,"type":"number"},"real_sharpe":{"example":1.65,"type":"number"}},"type":"object"},"sec_8k_events":{"items":{"properties":{"accession_number":{"type":"string"},"description":{"type":"string"},"filing_date":{"type":"string"},"items":{"items":{"type":"string"},"type":"array"},"primary_category":{"type":"string"}},"type":"object"},"type":"array"},"signals_backtest":{"properties":{"annualized_sharpe":{"example":1.65,"type":"number"},"benchmark_return_pct":{"example":15.2,"type":"number"},"max_drawdown_pct":{"example":-8.4,"type":"number"},"total_return_pct":{"example":28.5,"type":"number"},"trade_count":{"example":42,"type":"integer"},"win_rate_pct":{"example":58.2,"type":"number"}},"type":"object"},"ticker":{"example":"AAPL","type":"string"}},"required":["ticker","microstructure","macro_conditioning","signals_backtest","sec_8k_events"],"type":"object"},"OptionsAnalysisResponse":{"properties":{"atm_iv":{"example":23.4,"type":"number"},"days_to_expiration":{"type":"integer"},"expected_move_bs":{"example":12.8,"type":"number"},"expected_move_straddle":{"example":13.1,"type":"number"},"hv30":{"example":18.5,"type":"number"},"hv90":{"example":21.2,"type":"number"},"iv_percentile":{"example":68.0,"type":"number"},"iv_rank":{"example":62.5,"type":"number"},"max_pain":{"example":220.0,"type":"number"},"oi_pcr":{"example":0.92,"type":"number"},"selected_expiration":{"type":"string"},"spot_price":{"example":225.5,"type":"number"},"strategy_rationale":{"type":"string"},"strategy_recommendation":{"example":"Sell Premium (Strangle / Iron Condor)","type":"string"},"ticker":{"example":"AAPL","type":"string"},"vol_pcr":{"example":0.85,"type":"number"}},"type":"object"},"OptionsGreeksResponse":{"properties":{"days_to_expiration":{"example":33,"type":"integer"},"expirations":{"items":{"type":"string"},"type":"array"},"options":{"items":{"properties":{"call_ask":{"type":"number"},"call_bid":{"type":"number"},"call_delta":{"example":0.52,"type":"number"},"call_gamma":{"example":0.035,"type":"number"},"call_iv":{"type":"number"},"call_last":{"type":"number"},"call_theta":{"example":-0.082,"type":"number"},"call_vega":{"example":0.24,"type":"number"},"put_ask":{"type":"number"},"put_bid":{"type":"number"},"put_delta":{"example":-0.48,"type":"number"},"put_iv":{"type":"number"},"put_last":{"type":"number"},"strike":{"example":225.0,"type":"number"}},"type":"object"},"type":"array"},"selected_expiration":{"example":"2026-09-18","type":"string"},"spot_price":{"example":225.5,"type":"number"},"ticker":{"example":"AAPL","type":"string"}},"required":["ticker","expirations","selected_expiration","spot_price","days_to_expiration","options"],"type":"object"},"SECFiling":{"properties":{"acceptanceDateTime":{"type":"string"},"accessionNumber":{"type":"string"},"act":{"type":"string"},"fileNumber":{"type":"string"},"filingDate":{"example":"2026-02-14","format":"date","type":"string"},"form":{"example":"8-K","type":"string"},"isInlineXBRL":{"type":"integer"},"isXBRL":{"type":"integer"},"items":{"example":"2.02,7.01","type":"string"},"primaryDocDescription":{"type":"string"},"primaryDocument":{"type":"string"},"reportDate":{"format":"date","type":"string"},"size":{"type":"integer"},"url":{"format":"uri","type":"string"}},"type":"object"}},"securitySchemes":{"BearerAuth":{"bearerFormat":"Token","scheme":"bearer","type":"http"}}},"info":{"contact":{"name":"Quantitative Systems Team"},"description":"Production-grade Quantitative & Institutional Analytics REST API. Provides point-in-time corporate action resolution, market microstructure (VPIN, Roll/Corwin-Schultz spreads), macro regime conditional betas, walk-forward algorithmic backtesting, SEC 8-K event classification, and Black-Scholes higher-order derivatives Greeks.","license":{"name":"MIT"},"title":"Ticker-change Quantitative Engine API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/api/active-tickers":{"get":{"description":"Returns distinct equity symbols stored in the SQLite daily_prices table.","responses":{"200":{"content":{"application/json":{"schema":{"items":{"example":"AAPL","type":"string"},"type":"array"}}},"description":"Array of active symbols"},"403":{"description":"Unauthorized access when WARM_CACHE_TOKEN is enforced"}},"summary":"List Tracked Database Tickers","tags":["System & Cache Operations"]}},"/api/analytics/{ticker}":{"get":{"description":"Returns forward analyst estimates, distribution statistics, historical drawdown, and valuation multiples.","parameters":[{"in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Full analytics payload"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Analytics unavailable"}},"summary":"Comprehensive Fundamental & Statistical Analytics","tags":["Market Data & Analytics"]}},"/api/chart-data/{ticker}":{"get":{"description":"Fetches structured historical OHLCV data array with optional start_date and end_date filtering.","parameters":[{"in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}},{"in":"query","name":"start_date","required":false,"schema":{"example":"2025-01-01","format":"date","type":"string"}},{"in":"query","name":"end_date","required":false,"schema":{"example":"2026-01-01","format":"date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"close":{"items":{"type":"number"},"type":"array"},"dates":{"items":{"type":"string"},"type":"array"},"high":{"items":{"type":"number"},"type":"array"},"low":{"items":{"type":"number"},"type":"array"},"open":{"items":{"type":"number"},"type":"array"},"volume":{"items":{"type":"number"},"type":"array"}},"type":"object"}}},"description":"OHLCV array for charting"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Chart data unavailable"}},"summary":"Historical OHLCV Chart Series","tags":["Market Data & Analytics"]}},"/api/config":{"get":{"description":"Returns a boolean flag indicating whether a Finnhub API key is configured server-side. No key material is exposed.","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"has_finnhub":{"type":"boolean"}},"type":"object"}}},"description":"Configuration object"}},"summary":"Returns whether a Finnhub key is configured","tags":["System & Cache Operations"]}},"/api/corporate-actions/{ticker}":{"get":{"description":"Resolves entity identification (CIK, FIGI, CUSIP) as-of a specific date and returns chronological corporate actions (splits, symbol changes, mergers).","parameters":[{"description":"Ticker symbol to look up","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}},{"description":"Point-in-time date (YYYY-MM-DD) for historical entity resolution","in":"query","name":"as_of","required":false,"schema":{"example":"2020-08-30","format":"date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorporateActionsResponse"}}},"description":"Entity details, symbol history, and corporate action log"}},"summary":"Point-in-Time Corporate Actions & Entity Timeline","tags":["Corporate Actions & Identity"]}},"/api/heatmap":{"get":{"description":"Sector-grouped S&P 500 treemap payload: per-constituent daily % change (colour), trailing average dollar volume (tile size), plus breadth counts and universe coverage. Served from cache; returns status 'warming' with empty tiles while the universe is still downloading.","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Heatmap payload"}},"summary":"S&P 500 Heatmap","tags":["Market Data & Analytics"]}},"/api/institutional/{ticker}":{"get":{"description":"Computes high-frequency microstructure metrics (VPIN, Corwin-Schultz, Roll spread, Squeeze risk), macro-financial conditioning (Bull/Bear dual betas, upside/downside capture ratios, yield curve spread), walk-forward momentum/mean-reversion signals backtest, and parsed SEC 8-K material event classifications.","parameters":[{"description":"Equity ticker symbol (e.g. AAPL, NVDA, SPY)","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstitutionalAnalyticsResponse"}}},"description":"Comprehensive institutional analytics report"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Ticker not found or insufficient pricing data"}},"summary":"Institutional Quantitative Suite","tags":["Institutional & Quantitative Analytics"]}},"/api/options-ai-report/{ticker}":{"get":{"description":"Synthesizes dealer positioning, GEX profile, and volatility term structure into an actionable market report.","parameters":[{"in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}},{"in":"query","name":"expiration","schema":{"type":"string"}},{"in":"query","name":"rf_rate","schema":{"default":0.045,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"html":{"type":"string"}},"type":"object"}}},"description":"HTML or markdown formatted AI narrative"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"AI synthesis generation failed"}},"summary":"LLM Generated Options Volatility Synthesis","tags":["Options & Derivatives"]}},"/api/options-analysis/{ticker}":{"get":{"description":"Computes Put-Call Ratio (PCR), Max Pain, ATM Implied Volatility, IV Rank, IV Percentile, Expected Move, and Dealer Gamma Exposure (GEX).","parameters":[{"description":"Underlying ticker symbol","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}},{"description":"Expiration date (YYYY-MM-DD)","in":"query","name":"expiration","required":false,"schema":{"format":"date","type":"string"}},{"description":"Risk-free interest rate","in":"query","name":"rf_rate","required":false,"schema":{"default":0.045,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionsAnalysisResponse"}}},"description":"Quantitative options analysis synthesis"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Failed to compute options analysis"}},"summary":"Options Posture, GEX & Volatility Analysis","tags":["Options & Derivatives"]}},"/api/options-greeks/{ticker}":{"get":{"description":"Returns full options chain strikes with calculated First and Second order Greeks (Delta, Gamma, Theta, Vega, Rho) and implied volatility.","parameters":[{"description":"Underlying equity ticker symbol","in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}},{"description":"Expiration date (YYYY-MM-DD). Defaults to nearest expiration.","in":"query","name":"expiration","required":false,"schema":{"example":"2026-09-18","format":"date","type":"string"}},{"description":"Annualized risk-free interest rate","in":"query","name":"rf_rate","required":false,"schema":{"default":0.045,"example":0.045,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionsGreeksResponse"}}},"description":"Options chain greeks grid"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Options data unavailable for ticker"}},"summary":"Options Chain & Black-Scholes Greeks","tags":["Options & Derivatives"]}},"/api/positioning/{ticker}":{"get":{"description":"Assembles institutional 13F holders, insider trading transactions, Finnhub monthly MSPR sentiment, and consensus analyst targets.","parameters":[{"in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Positioning breakdown"}},"summary":"Market Positioning & Institutional Sentiment","tags":["Market Positioning & SEC Filings"]}},"/api/raw-sec-filings/{ticker}":{"get":{"description":"Retrieves recent Form 3, 4, 8-K, 10-Q, 10-K, and 13F filings from SEC EDGAR API.","parameters":[{"in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SECFiling"},"type":"array"}}},"description":"List of recent filings"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Error fetching filings from EDGAR"}},"summary":"Raw SEC EDGAR Filings","tags":["Market Positioning & SEC Filings"]}},"/api/stock/{ticker}":{"get":{"description":"Fetches current market quotes, multi-period percentage returns, and technical indicators.","parameters":[{"in":"path","name":"ticker","required":true,"schema":{"example":"AAPL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Current quote and metrics"}},"summary":"Consolidated Stock Fundamentals & Pricing","tags":["Market Data & Analytics"]}},"/api/warm-cache":{"post":{"description":"Triggers asynchronous background refresh of options chains for all tracked tickers.","responses":{"202":{"description":"Warming job accepted and dispatched in background"},"403":{"description":"Unauthorized invalid bearer token"},"503":{"description":"WARM_CACHE_TOKEN not configured on server"}},"security":[{"BearerAuth":[]}],"summary":"Trigger EOD Options Chain Warmer","tags":["System & Cache Operations"]}},"/health":{"get":{"description":"Returns 200 OK if the web server is healthy.","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"status":{"example":"ok","type":"string"}},"type":"object"}}},"description":"Service is operational"}},"summary":"Health Check Probe","tags":["System & Cache Operations"]}}},"servers":[{"description":"Current Environment Server","url":"/"}],"tags":[{"description":"Microstructure, macro conditioning, CAR event studies, and walk-forward simulations","name":"Institutional & Quantitative Analytics"},{"description":"Point-in-time CIK/FIGI/CUSIP resolution, splits, symbol changes, and mergers","name":"Corporate Actions & Identity"},{"description":"Black-Scholes Greeks, IV Smile/Skew, GEX Gamma Exposure, and AI Options Reports","name":"Options & Derivatives"},{"description":"OHLCV historical charts, fundamental stats, forward estimates, and momentum metrics","name":"Market Data & Analytics"},{"description":"Finnhub recommendations, insider sentiment (MSPR), institutional 13F holders, raw SEC filings","name":"Market Positioning & SEC Filings"},{"description":"Health checks, configuration, active ticker discovery, and EOD options cache warming","name":"System & Cache Operations"}]}