# Data contract — verified against the live FinData OS API on 2026-11-02 (see DATA_AUDIT.md)
findata:
  base_url: https://findata.spboucher.ai/api/v1
  openapi: /openapi.json
  datasets:
    bars_1m: market_bars.stock.1m.raw          # raw, bar-open timestamps in UTC, 04:00-20:00 ET, zero-volume minutes absent
    bars_1m_etf: market_bars.etf.1m.raw        # SPY used as market proxy
    bars_1d: market_bars.stock.1d.raw          # INCOMPLETE vs 1m (fewer symbols) -> daily bars are rebuilt from 1m
    fundamentals: fundamentals.financials      # Postgres-backed; GET /fundamentals/{entity}
    earnings: fundamentals.earnings            # Postgres table earnings_events (no API route yet) -> documented exception
  limits:
    bars_1m_days_per_call: 31
    rows_per_page: 10000
    export_years_per_request: 12
    export_symbols_per_request: 500
    query_timeout_s: 30
    query_max_rows: 100000
    rate_limit_per_min: 600
    fundamentals_limit_max: 20000
  bars_schema_version: 1
  timestamp_convention: bar_open
  timezone_storage: UTC
  exchange_tz: America/New_York
  regular_session: ["09:30", "16:00"]        # the 16:00 bar is the closing print
  extended_session: ["04:00", "20:00"]
  license_class: frd-private
pit:
  available_at_policy: "filing_date + 1 day 00:00 America/New_York (vendor proxy; fallback period_end + 91 d flagged pit_fallback)"
  revision_semantics: "revision_id=1 observed 2026-11-01/02; no pre-ingestion restatement history (vendor limitation)"
  reveal_date: "earnings_events.event_date (press release), release_time in {before_open, after_close, null}"
universe:
  entity_source: fundamentals entities (5,451 active tickers as of 2026-11-01; NO delisted entities -> survivorship caveat)
  min_quarters: 8
  first_filing_year: 2012
  last_session: 2026-10-30
external:
  sec_company_tickers: https://www.sec.gov/files/company_tickers.json
  sec_submissions: https://data.sec.gov/submissions/CIK{cik:010d}.json
  ff5_daily: https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/ftp/F-F_Research_Data_5_Factors_2x3_daily_CSV.zip
  mom_daily: https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/ftp/F-F_Momentum_Factor_daily_CSV.zip