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..fe6e5aa 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.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. + +### 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..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.0" +__version__ = "1.15.0" __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..141e176 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "oxarchive" -version = "1.14.0" +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 5a52031..a6a46c8 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.15.0" 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