Merge pull request #1 from FlashAlpha-lab/docs/data-as-of-provenance

docs: document the data_as_of response envelope

Author: tomaszdobrowolski1

README.md

@@ -147,6 +147,52 @@ Five more end-to-end recipes — pair-by-ticker with equity bars, 0DTE pin-risk
 
 ---
 
+## Data provenance: `data_as_of`
+
+Every FlashAlpha API response carries `data_as_of`, reporting when each upstream feed last
+delivered to the node that answered, plus `endpoint_version` identifying the deployment
+that produced it.
+
+```json
+"endpoint_version": "2026.08.25",
+"data_as_of": {
+  "node": "fa2",
+  "equity_feed": "2026-08-25T18:48:58.204Z",
+  "equity_options_feed": "2026-08-25T18:48:57.900Z",
+  "index_feed": null,
+  "index_options_feed": null,
+  "futures_feed": null,
+  "futures_options_feed": null,
+  "flow_feed": "2026-08-25T18:48:55.100Z",
+  "oi_feed": "2026-08-24T20:00:00.000Z",
+  "macro_feed": "2026-08-25T18:45:00.000Z"
+}
+```
+
+Spot and options are reported separately because they arrive over different pipes and fail
+independently - an index chain can be current while the index level behind it is not, and
+one timestamp cannot express that.
+
+Read each feed against its **own cadence**, not against `as_of`. `oi_feed` at the previous
+session's close is correct: settled open interest is published once per session, so on a
+Monday the newest figure that exists is Friday's. An options feed an hour behind during
+the regular session is not correct. A `null` means that node has not seen that feed, not
+that it is broken.
+
+The field evidences that a feed delivered recently. It does not assert that every contract
+in a chain is equally current: an illiquid strike may not have quoted for hours while its
+feed is healthy.
+
+Full reference: <https://flashalpha.com/docs/lab-api-overview#response-envelope>
+
+
+> **Note on provenance in LEAN.** The underlying REST payloads carry the `data_as_of` /
+> `archive_as_of` envelope described above, but this adapter does not surface it: the LEAN
+> bars map only the analytics fields, so the envelope is dropped at the bridge. If a study
+> needs to gate on archive vintage, read it from `flashalpha-historical` directly rather
+> than from the bar.
+
+
 ## Data catalog
 
 Every bar lives at `https://historical.flashalpha.com/docs/<endpoint>`. Full field tables and side-by-side `OnData` samples are in [docs/data-types.md](docs/data-types.md).

llms.txt

@@ -2,6 +2,18 @@
 
 > FlashAlpha options-flow and dealer-positioning data as native QuantConnect LEAN custom-data bars. Seventeen endpoint families — GEX/DEX/VEX/CHEX, exposure summary/levels, vol surface, 0DTE, max pain, volatility, advanced vol (SVI), VRP, narrative, stock summary/quote, option quote, tickers — exposed as `BaseData` subclasses in C# and `PythonData` subclasses in Python. Works in QC Cloud and self-hosted LEAN. Versioned to the underlying `flashalpha-historical` SDK so schema drift breaks at compile time.
 
+## Data provenance
+
+Every FlashAlpha API response carries `data_as_of`: when each upstream feed last delivered
+to the node that answered - equity and index spot, their option chains, futures and futures
+options, the classified trade tape, settled open interest, and the macro series, each
+reported separately because they arrive over different pipes and fail independently. `null`
+means that node has not seen that feed, not that it is broken. Read each feed against its
+own cadence: settled open interest dated to the previous session's close is correct, while
+an options feed an hour behind during the regular session is not. `endpoint_version`
+identifies the deployment. Full reference:
+https://flashalpha.com/docs/lab-api-overview#response-envelope
+
 ## Docs
 
 - [README](README.md): elevator pitch, install, first algorithm, full data catalog, FAQ