From 453577d15d4e691ef18a922f673185df3e2d65e8 Mon Sep 17 00:00:00 2001 From: 0xFantomMenace <93462858+0xFantomMenace@users.noreply.github.com> Date: Fri, 13 Nov 2026 23:40:22 +0000 Subject: [PATCH 1/2] Accept null data times on summaries, trigger levels and L4 snapshots (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. --- .gitignore | 1 + CHANGELOG.md | 30 +++++ README.md | 3 +- oxarchive/__init__.py | 2 +- oxarchive/resources/l2_orderbook.py | 4 +- oxarchive/resources/orders.py | 3 +- oxarchive/types.py | 23 +++- pyproject.toml | 2 +- tests/test_derived_datasets.py | 4 +- tests/test_nullable_times.py | 199 ++++++++++++++++++++++++++++ 10 files changed, 258 insertions(+), 13 deletions(-) create mode 100644 tests/test_nullable_times.py diff --git a/.gitignore b/.gitignore index 33c18a5..034d7b9 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ tests/* !tests/test_rh_lighter.py !tests/test_mempool.py !tests/test_websocket_sends.py +!tests/test_nullable_times.py !tests/_mock_api.py !tests/test_timestamps.py !tests/test_spec_fixes.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d5f56c..decc935 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,36 @@ All notable changes to the `oxarchive` Python SDK are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.14.1] - Unreleased + +Times that describe market data are the time of the data, and are `None` when +that time is unknown. Responses that carry these fields as before still parse. + +### Changed +- `CoinSummary.timestamp` (`get_summary()` on Hyperliquid, HIP-3, HIP-4, + Lighter and Lighter on Robinhood Chain) is `Optional[datetime]`. It is the + time of the market data the summary is built from, not the time of the + request, and `None` when no market data was available. +- `TriggerLevels.as_of` (`orders.trigger_levels()` on Hyperliquid and HIP-3) + is `Optional[str]`. It is the block time of the newest trigger order event + the map reflects, with millisecond precision, and no longer the server read + time. An answer served from a cache keeps the time of its data. +- `WsL4Snapshot.timestamp` is `Optional[int]`: the block time of + `last_block_number` in Unix milliseconds, or `None` while that block's time + is not known. This covers the snapshot that opens `l4_diffs`, + `hip3_l4_diffs`, `spot_l4_diffs`, `hip4_l4_diffs`, `orderbook_full` and + `hip3_orderbook_full`, live and in replay. + +### Added +- `TriggerLevels.as_of_block`: the block the trigger map reflects, or `None` + when it is unknown or not sent. + +### Fixed +- An `l4_snapshot` with a `null` `timestamp` no longer fails validation, so it + reaches `on_message` and `on_l4_snapshot` instead of being dropped. A + summary or trigger map with a `null` time no longer raises + `ValidationError`. + ## [1.14.0] - 2026-11-04 Four datasets included with the Build, Pro, Scale and Enterprise plans, on diff --git a/README.md b/README.md index e940e23..de76b8c 100644 --- a/README.md +++ b/README.md @@ -950,6 +950,7 @@ print(f"24h volume: {summary.volume_24h}") print(f"24h liquidation volume: ${summary.liquidation_volume_24h}") print(f" Long: ${summary.long_liquidation_volume_24h}") print(f" Short: ${summary.short_liquidation_volume_24h}") +print(f"Data time: {summary.timestamp}") # None when the time of the data is unknown # Lighter (price, funding, OI; no volume/liquidation data) lighter_summary = client.lighter.get_summary("BTC") @@ -2168,7 +2169,7 @@ ws.subscribe_orderbook_full("BTC") ws.subscribe_hip3_orderbook_full("xyz:TSLA") # case-sensitive ``` -Each level is `{"px", "sz", "n"}` with numeric values; a changed level also carries `side` (`"B"` or `"A"`) and `bn`, the block it was applied in. The snapshot's `data` also holds `bid_count`, `ask_count`, `total_bid_size`, `total_ask_size`, `mid_price`, `spread`, `spread_bps` and `is_crossed`, and `last_block_number` on the message is the block the snapshot reflects. +Each level is `{"px", "sz", "n"}` with numeric values; a changed level also carries `side` (`"B"` or `"A"`) and `bn`, the block it was applied in. The snapshot's `data` also holds `bid_count`, `ask_count`, `total_bid_size`, `total_ask_size`, `mid_price`, `spread`, `spread_bps` and `is_crossed`, and `last_block_number` on the message is the block the snapshot reflects. The message's `timestamp` is that block's time in Unix milliseconds, or `None` while the time of the block is not known yet. ### Live Lighter Data diff --git a/oxarchive/__init__.py b/oxarchive/__init__.py index fec7bcd..6ad3643 100644 --- a/oxarchive/__init__.py +++ b/oxarchive/__init__.py @@ -268,7 +268,7 @@ WS_CHANNELS = None # type: ignore decode_lighter_payload = None # type: ignore -__version__ = "1.14.0" +__version__ = "1.14.1" __all__ = [ # Client diff --git a/oxarchive/resources/l2_orderbook.py b/oxarchive/resources/l2_orderbook.py index 56eac4d..6f695ba 100644 --- a/oxarchive/resources/l2_orderbook.py +++ b/oxarchive/resources/l2_orderbook.py @@ -50,7 +50,9 @@ def get( depth: Number of price levels per side (omit for full depth) Returns: - L2 order book with aggregated price levels (px, sz, n per level) + L2 order book with aggregated price levels (px, sz, n per level). + Its ``timestamp`` is the block time of the book as a UTC RFC 3339 + string, or ``None`` when the time of the data is unknown. """ symbol = self._resolve_symbol(symbol, kwargs) data = self._http.get( diff --git a/oxarchive/resources/orders.py b/oxarchive/resources/orders.py index d079a9e..be36f3c 100644 --- a/oxarchive/resources/orders.py +++ b/oxarchive/resources/orders.py @@ -324,7 +324,8 @@ def trigger_levels( into price buckets near the current mid/mark price. Voluntary trigger orders, not projected forced liquidations (see ``liquidations.levels`` for those). The response's ``as_of`` is the - server read time. + block time of the newest trigger order event the map reflects, and + ``as_of_block`` is that block; either is ``None`` when unknown. Args: symbol: The symbol (e.g., 'BTC', or 'xyz:TSLA' on HIP-3) diff --git a/oxarchive/types.py b/oxarchive/types.py index 680dab5..41fb730 100644 --- a/oxarchive/types.py +++ b/oxarchive/types.py @@ -1085,8 +1085,15 @@ class TriggerLevels(_ApiRecord): mid_price: float """Current mid/mark price, center of the requested range.""" - as_of: str - """UTC RFC3339 server time the pending-trigger state was read.""" + as_of: Optional[str] = None + """Block time of the newest trigger order event the map reflects, as a + UTC RFC 3339 string with millisecond precision. An answer served from a + cache keeps the time of the data it was built from. ``None`` when the time + of the data is unknown.""" + + as_of_block: Optional[int] = None + """Hyperliquid block number the map reflects. ``None`` when it is unknown, + or when the API does not send it.""" total_bid_size: float """Total pending bid size across the returned window.""" @@ -1171,8 +1178,11 @@ class CoinSummary(_ApiRecord): coin: str """Trading pair symbol.""" - timestamp: datetime - """Summary timestamp.""" + timestamp: Optional[datetime] = None + """Time of the market data the summary is built from: the sample its + prices, open interest and funding come from. It is not the time of the + request, and the 24h volume and liquidation totals do not move it. + ``None`` when the time of the data is unknown.""" mark_price: Optional[str] = None """Current mark price.""" @@ -1400,8 +1410,9 @@ class WsL4Snapshot(BaseModel): last_block_number: int """Highest block applied to this snapshot.""" - timestamp: int - """Snapshot timestamp in Unix milliseconds.""" + timestamp: Optional[int] = None + """Block time of ``last_block_number`` in Unix milliseconds. ``None`` when + the time of that block is not known yet.""" data: dict[str, Any] """Full L4 book state.""" diff --git a/pyproject.toml b/pyproject.toml index f756de1..3e20219 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "oxarchive" -version = "1.14.0" +version = "1.14.1" description = "Python SDK for the 0xArchive market data API for Hyperliquid and Lighter" readme = "README.md" license = "MIT" diff --git a/tests/test_derived_datasets.py b/tests/test_derived_datasets.py index 5a52031..1477ace 100644 --- a/tests/test_derived_datasets.py +++ b/tests/test_derived_datasets.py @@ -828,5 +828,5 @@ def test_sdk_intervals_match_the_capability_rows() -> None: assert row["page_limit"] == USDC_FLOWS_MAX_LIMIT -def test_version_is_1_14_0() -> None: - assert oxarchive.__version__ == "1.14.0" +def test_version_is_1_14_1() -> None: + assert oxarchive.__version__ == "1.14.1" diff --git a/tests/test_nullable_times.py b/tests/test_nullable_times.py new file mode 100644 index 0000000..392b5dc --- /dev/null +++ b/tests/test_nullable_times.py @@ -0,0 +1,199 @@ +"""Times that describe market data can be null when the time of the data is unknown. + +Covers ``CoinSummary.timestamp``, ``TriggerLevels.as_of`` and ``as_of_block``, +and ``WsL4Snapshot.timestamp``. Each accepts a value, ``null`` and a missing +field, so responses with or without these fields parse. +""" + +from __future__ import annotations + +import json +from datetime import datetime, timezone +from typing import Any, Callable + +import pytest +from _mock_api import envelope, mock_client + +from oxarchive import Client +from oxarchive.types import CoinSummary, TriggerLevels, WsL4Snapshot +from oxarchive.websocket import OxArchiveWs, WsOptions + +SUMMARY: dict[str, Any] = { + "coin": "BTC", + "timestamp": "2026-11-13T22:21:00Z", + "mark_price": "98123.5", + "oracle_price": "98120.0", + "funding_rate": "0.0000125", + "open_interest": "31234.5", +} + +TRIGGER_LEVELS: dict[str, Any] = { + "mid_price": 98123.5, + "as_of": "2026-11-13T22:21:05.695Z", + "as_of_block": 1220113000, + "total_bid_size": 1.5, + "total_ask_size": 4.0, + "levels": [ + {"price_bucket": 97000.0, "bid_count": 1, "bid_size": 1.5, "ask_count": 0, "ask_size": 0.0}, + {"price_bucket": 99000.0, "bid_count": 0, "bid_size": 0.0, "ask_count": 2, "ask_size": 4.0}, + ], +} + +L4_SNAPSHOT: dict[str, Any] = { + "type": "l4_snapshot", + "channel": "l4_diffs", + "coin": "BTC", + "symbol": "BTC", + "last_block_number": 1220113000, + "timestamp": 1794608465695, + "data": {"bids": [], "asks": []}, +} + + +def _without(record: dict[str, Any], *keys: str) -> dict[str, Any]: + return {k: v for k, v in record.items() if k not in keys} + + +def _with(record: dict[str, Any], **values: Any) -> dict[str, Any]: + return {**record, **values} + + +# --------------------------------------------------------------------------- +# Market summary +# --------------------------------------------------------------------------- + +SummaryCall = Callable[[Client], CoinSummary] + +SUMMARY_ROUTES: list[tuple[str, SummaryCall, str]] = [ + ("hyperliquid", lambda c: c.hyperliquid.get_summary("BTC"), "/v1/hyperliquid/summary/BTC"), + ( + "hip3", + lambda c: c.hyperliquid.hip3.get_summary("xyz:TSLA"), + "/v1/hyperliquid/hip3/summary/xyz:TSLA", + ), + ("hip4", lambda c: c.hyperliquid.hip4.get_summary("0"), "/v1/hyperliquid/hip4/summary/0"), + ("lighter", lambda c: c.lighter.get_summary("BTC"), "/v1/lighter/summary/BTC"), + ("rh_lighter", lambda c: c.rh_lighter.get_summary("BTC"), "/v1/rh-lighter/summary/BTC"), +] + + +@pytest.mark.parametrize( + "body, expected", + [ + (SUMMARY, datetime(2026, 11, 13, 22, 21, tzinfo=timezone.utc)), + (_with(SUMMARY, timestamp=None), None), + (_without(SUMMARY, "timestamp"), None), + ], + ids=["value", "null", "missing"], +) +@pytest.mark.parametrize("venue, call, path", SUMMARY_ROUTES, ids=[r[0] for r in SUMMARY_ROUTES]) +def test_summary_timestamp_is_optional( + venue: str, call: SummaryCall, path: str, body: dict[str, Any], expected: Any +) -> None: + client, api = mock_client(lambda _path, _query: envelope(body)) + summary = call(client) + assert isinstance(summary, CoinSummary) + assert summary.timestamp == expected + assert summary.mark_price == "98123.5" + assert api.calls[0][0] == path + + +# --------------------------------------------------------------------------- +# Trigger levels +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize( + "body, as_of, as_of_block", + [ + (TRIGGER_LEVELS, "2026-11-13T22:21:05.695Z", 1220113000), + (_with(TRIGGER_LEVELS, as_of=None, as_of_block=None), None, None), + (_without(TRIGGER_LEVELS, "as_of", "as_of_block"), None, None), + # An answer that predates as_of_block: a whole-second as_of and no block. + ( + _without(_with(TRIGGER_LEVELS, as_of="2026-11-13T22:21:05Z"), "as_of_block"), + "2026-11-13T22:21:05Z", + None, + ), + ], + ids=["value", "null", "missing", "without-block"], +) +@pytest.mark.parametrize("product", ["hyperliquid", "hip3"]) +def test_trigger_levels_as_of_is_optional( + product: str, body: dict[str, Any], as_of: Any, as_of_block: Any +) -> None: + client, api = mock_client(lambda _path, _query: envelope(body)) + if product == "hyperliquid": + levels = client.hyperliquid.orders.trigger_levels("BTC") + path = "/v1/hyperliquid/orders/BTC/trigger-levels" + else: + levels = client.hyperliquid.hip3.orders.trigger_levels("xyz:TSLA") + path = "/v1/hyperliquid/hip3/orders/xyz:TSLA/trigger-levels" + assert isinstance(levels, TriggerLevels) + assert levels.as_of == as_of + assert levels.as_of_block == as_of_block + assert levels.mid_price == 98123.5 + assert [b.price_bucket for b in levels.levels] == [97000.0, 99000.0] + assert api.calls[0][0] == path + + +async def test_async_trigger_levels_accept_null_as_of() -> None: + body = _with(TRIGGER_LEVELS, as_of=None, as_of_block=None) + client, _ = mock_client(lambda _path, _query: envelope(body)) + levels = await client.hyperliquid.orders.atrigger_levels("BTC") + assert levels.as_of is None and levels.as_of_block is None + + +# --------------------------------------------------------------------------- +# WebSocket l4_snapshot +# --------------------------------------------------------------------------- + +L4_SNAPSHOT_CHANNELS = [ + "l4_diffs", + "hip3_l4_diffs", + "spot_l4_diffs", + "hip4_l4_diffs", + "orderbook_full", + "hip3_orderbook_full", +] + + +@pytest.mark.parametrize( + "timestamp, present", + [(1794608465695, True), (None, True), (None, False)], + ids=["value", "null", "missing"], +) +@pytest.mark.parametrize("channel", L4_SNAPSHOT_CHANNELS) +def test_l4_snapshot_timestamp_is_optional_and_reaches_the_handlers( + channel: str, timestamp: Any, present: bool +) -> None: + frame = _with(L4_SNAPSHOT, channel=channel, timestamp=timestamp) + if not present: + frame = _without(frame, "timestamp") + + ws = OxArchiveWs(WsOptions(api_key="test-key")) + messages: list[object] = [] + snapshots: list[tuple[str, str, dict[str, Any]]] = [] + ws.on_message(messages.append) + ws.on_l4_snapshot(lambda ch, coin, message: snapshots.append((ch, coin, message))) + + # A frame that fails validation is logged and dropped, so both handlers + # receiving it is the proof that it parsed. + ws._handle_message(json.dumps(frame)) + + assert len(messages) == 1 + snapshot = messages[0] + assert isinstance(snapshot, WsL4Snapshot) + assert snapshot.channel == channel + assert snapshot.timestamp == timestamp + assert snapshot.last_block_number == 1220113000 + assert snapshots == [(channel, "BTC", frame)] + + +def test_models_accept_null_and_missing_times_directly() -> None: + assert CoinSummary.model_validate(_with(SUMMARY, timestamp=None)).timestamp is None + assert CoinSummary.model_validate(_without(SUMMARY, "timestamp")).timestamp is None + assert TriggerLevels.model_validate(_with(TRIGGER_LEVELS, as_of=None)).as_of is None + assert TriggerLevels.model_validate(_without(TRIGGER_LEVELS, "as_of_block")).as_of_block is None + assert WsL4Snapshot.model_validate(_with(L4_SNAPSHOT, timestamp=None)).timestamp is None + assert WsL4Snapshot.model_validate(_without(L4_SNAPSHOT, "timestamp")).timestamp is None From a583caac1846d00c1e0a7112c335fcf5c50f90ea Mon Sep 17 00:00:00 2001 From: 0xFantomMenace <93462858+0xFantomMenace@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:43:13 +0000 Subject: [PATCH 2/2] Release 1.15.0 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. --- CHANGELOG.md | 2 +- oxarchive/__init__.py | 2 +- pyproject.toml | 2 +- tests/test_derived_datasets.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index decc935..fe6e5aa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,7 @@ All notable changes to the `oxarchive` Python SDK are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [1.14.1] - Unreleased +## [1.15.0] - 2026-11-14 Times that describe market data are the time of the data, and are `None` when that time is unknown. Responses that carry these fields as before still parse. diff --git a/oxarchive/__init__.py b/oxarchive/__init__.py index 6ad3643..50fce50 100644 --- a/oxarchive/__init__.py +++ b/oxarchive/__init__.py @@ -268,7 +268,7 @@ WS_CHANNELS = None # type: ignore decode_lighter_payload = None # type: ignore -__version__ = "1.14.1" +__version__ = "1.15.0" __all__ = [ # Client diff --git a/pyproject.toml b/pyproject.toml index 3e20219..141e176 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "oxarchive" -version = "1.14.1" +version = "1.15.0" description = "Python SDK for the 0xArchive market data API for Hyperliquid and Lighter" readme = "README.md" license = "MIT" diff --git a/tests/test_derived_datasets.py b/tests/test_derived_datasets.py index 1477ace..a6a46c8 100644 --- a/tests/test_derived_datasets.py +++ b/tests/test_derived_datasets.py @@ -829,4 +829,4 @@ def test_sdk_intervals_match_the_capability_rows() -> None: def test_version_is_1_14_1() -> None: - assert oxarchive.__version__ == "1.14.1" + assert oxarchive.__version__ == "1.15.0"