Skip to content

docs: document the data_as_of response envelope #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tomaszdobrowolski1 merged 2 commits into from
Aug 26, 2026
Merged

docs: document the data_as_of response envelope #1

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
527cf5c
docs: document the data_as_of response envelope
tdobrowolski1 Aug 25, 2026
5673c31
docs: fix impossible OI dates, wrong imports, and an overclaim
tdobrowolski1 Aug 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,44 @@ Key skew metrics:

---

## 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>

## Realized vs Implied Volatility and the Vol Risk Premium

**Realized volatility (RV)** is the standard deviation of log returns over a historical lookback window, scaled to annual terms. Common estimators include close-to-close, Parkinson (high-low), Garman-Klass, and Yang-Zhang. See [theory/realized_volatility_estimators.md](theory/realized_volatility_estimators.md) for a comparison.
Expand Down
Loading