Skip to content

Accept null data times on summaries, trigger levels and L4 snapshots (1.15.0) - #31

Merged
0xFantomMenace merged 2 commits into
masterfrom
nullable-data-times
Nov 14, 2026
Merged

0xFantomMenace merged 2 commits into
masterfrom
nullable-data-times

Conversation

@0xFantomMenace

@0xFantomMenace 0xFantomMenace commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

In an upcoming API update, a few time fields carry the time of the data instead of the time of the request, and are null when the time of the data is unknown. This release accepts those answers. Answers in today's shape parse exactly as before.

Field Type in 1.14.0 Type in 1.15.0 What it means
CoinSummary.timestamp (get_summary() on Hyperliquid, HIP-3, HIP-4, Lighter, Lighter on Robinhood Chain) datetime Optional[datetime] Time of the market data the summary is built from, not the request time
TriggerLevels.as_of (orders.trigger_levels() on Hyperliquid and HIP-3) str Optional[str] Block time of the newest trigger order event the map reflects, with millisecond precision
TriggerLevels.as_of_block (new) Optional[int] The block the map reflects
WsL4Snapshot.timestamp (l4_diffs, hip3_l4_diffs, spot_l4_diffs, hip4_l4_diffs, orderbook_full, hip3_orderbook_full) int Optional[int] Block time of last_block_number, in Unix milliseconds

Without this release, a null in these fields raises ValidationError on the REST calls, and an l4_snapshot with a null time fails validation and never reaches on_message or on_l4_snapshot.

Also:

  • The trigger_levels() docstring no longer describes as_of as the server read time.
  • The l2_orderbook.get() docstring states that the book's timestamp is its block time as RFC 3339 UTC, or None when unknown.
  • README: the summary example prints the data time; the full-depth section describes the snapshot's timestamp.
  • Version 1.15.0 (a minor release, so the type change is visible in the version), with a dated 1.15.0 changelog entry. Not tagged or published.

Tests

tests/test_nullable_times.py (43 cases): a value, null and a missing field for each field, on every venue that serves it (five summary routes, both trigger-level routes, all six snapshot channels), plus an answer without as_of_block. Both handlers must receive the snapshot. Against 1.14.0's types, 32 of these fail.

Full suite: 599 passed, 17 skipped (the live contract tests, which need a key). ruff is clean on the changed files, and mypy oxarchive reports the same count as on master.

…(1.14.1)

Times that describe market data are the time of the data, and are null when
that time is unknown:

- CoinSummary.timestamp is Optional[datetime]: the time of the market data
  the summary is built from, not the time of the request.
- TriggerLevels.as_of is Optional[str]: the block time of the newest trigger
  order event the map reflects, with millisecond precision. New
  TriggerLevels.as_of_block names that block.
- WsL4Snapshot.timestamp is Optional[int]: the block time of
  last_block_number. A snapshot with a null time no longer fails validation
  and reaches on_message and on_l4_snapshot.

Responses that carry these fields as before still parse. Tests cover a value,
null and a missing field for each, on every venue that serves them.
Times that describe market data can be null (summaries, trigger levels, order book snapshots). Released as a minor version because code that reads those fields as always present needs to handle a missing value.
@0xFantomMenace 0xFantomMenace changed the title Accept null data times on summaries, trigger levels and L4 snapshots (1.14.1) Accept null data times on summaries, trigger levels and L4 snapshots (1.15.0) Nov 14, 2026
@0xFantomMenace
0xFantomMenace merged commit 4d91b05 into master Nov 14, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant