Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
30 changes: 30 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion oxarchive/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion oxarchive/resources/l2_orderbook.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
3 changes: 2 additions & 1 deletion oxarchive/resources/orders.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
23 changes: 17 additions & 6 deletions oxarchive/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
Expand Down Expand Up @@ -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."""
Expand Down Expand Up @@ -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."""
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions tests/test_derived_datasets.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
199 changes: 199 additions & 0 deletions tests/test_nullable_times.py
Original file line number Diff line number Diff line change
@@ -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
Loading