oxarchive 0.3.6__py3-none-any.whl → 0.4.5__py3-none-any.whl

oxarchive/resources/orderbook.py

@@ -6,7 +6,12 @@ from datetime import datetime
 from typing import Optional, Union
 
 from ..http import HttpClient
-from ..types import OrderBook, Timestamp
+from typing import Literal
+
+from ..types import CursorResponse, OrderBook, Timestamp
+
+# Lighter orderbook granularity levels (Lighter.xyz only)
+LighterGranularity = Literal["checkpoint", "30s", "10s", "1s", "tick"]
 
 
 class OrderBookResource:
@@ -14,18 +19,22 @@ class OrderBookResource:
     Order book API resource.
 
     Example:
-        >>> # Get current order book
-        >>> orderbook = client.orderbook.get("BTC")
+        >>> # Get current order book (Hyperliquid)
+        >>> orderbook = client.hyperliquid.orderbook.get("BTC")
         >>>
         >>> # Get order book at specific timestamp
-        >>> historical = client.orderbook.get("ETH", timestamp=1704067200000)
+        >>> historical = client.hyperliquid.orderbook.get("ETH", timestamp=1704067200000)
         >>>
         >>> # Get order book history
-        >>> history = client.orderbook.history("BTC", start="2024-01-01", end="2024-01-02")
+        >>> history = client.hyperliquid.orderbook.history("BTC", start="2024-01-01", end="2024-01-02")
+        >>>
+        >>> # Lighter.xyz order book
+        >>> lighter_ob = client.lighter.orderbook.get("BTC")
     """
 
-    def __init__(self, http: HttpClient):
+    def __init__(self, http: HttpClient, base_path: str = "/v1"):
         self._http = http
+        self._base_path = base_path
 
     def _convert_timestamp(self, ts: Optional[Timestamp]) -> Optional[int]:
         """Convert timestamp to Unix milliseconds."""
@@ -63,7 +72,7 @@ class OrderBookResource:
             Order book snapshot
         """
         data = self._http.get(
-            f"/v1/orderbook/{coin.upper()}",
+            f"{self._base_path}/orderbook/{coin.upper()}",
             params={
                 "timestamp": self._convert_timestamp(timestamp),
                 "depth": depth,
@@ -80,7 +89,7 @@ class OrderBookResource:
     ) -> OrderBook:
         """Async version of get()."""
         data = await self._http.aget(
-            f"/v1/orderbook/{coin.upper()}",
+            f"{self._base_path}/orderbook/{coin.upper()}",
             params={
                 "timestamp": self._convert_timestamp(timestamp),
                 "depth": depth,
@@ -94,35 +103,57 @@ class OrderBookResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
         depth: Optional[int] = None,
-    ) -> list[OrderBook]:
+        granularity: Optional[LighterGranularity] = None,
+    ) -> CursorResponse[list[OrderBook]]:
         """
-        Get historical order book snapshots.
+        Get historical order book snapshots with cursor-based pagination.
 
         Args:
             coin: The coin symbol (e.g., 'BTC', 'ETH')
             start: Start timestamp (required)
             end: End timestamp (required)
-            limit: Maximum number of results
-            offset: Number of results to skip
+            cursor: Cursor from previous response's next_cursor (timestamp)
+            limit: Maximum number of results (default: 100, max: 1000)
             depth: Number of price levels per side
+            granularity: Data resolution for Lighter orderbook (Lighter.xyz only, ignored for Hyperliquid).
+                Options: 'checkpoint' (1min, default), '30s', '10s', '1s', 'tick'.
+                Tier restrictions apply. Credit multipliers: checkpoint=1x, 30s=2x, 10s=3x, 1s=10x, tick=20x.
 
         Returns:
-            List of order book snapshots
+            CursorResponse with order book snapshots and next_cursor for pagination
+
+        Example:
+            >>> result = client.orderbook.history("BTC", start=start, end=end, limit=1000)
+            >>> snapshots = result.data
+            >>> while result.next_cursor:
+            ...     result = client.orderbook.history(
+            ...         "BTC", start=start, end=end, cursor=result.next_cursor, limit=1000
+            ...     )
+            ...     snapshots.extend(result.data)
+            >>>
+            >>> # Lighter.xyz with 10s granularity (Build+ tier)
+            >>> result = client.lighter.orderbook.history(
+            ...     "BTC", start=start, end=end, granularity="10s"
+            ... )
         """
         data = self._http.get(
-            f"/v1/orderbook/{coin.upper()}/history",
+            f"{self._base_path}/orderbook/{coin.upper()}/history",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
                 "depth": depth,
+                "granularity": granularity,
             },
         )
-        return [OrderBook.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[OrderBook.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
 
     async def ahistory(
         self,
@@ -130,19 +161,24 @@ class OrderBookResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
         depth: Optional[int] = None,
-    ) -> list[OrderBook]:
-        """Async version of history(). start and end are required."""
+        granularity: Optional[LighterGranularity] = None,
+    ) -> CursorResponse[list[OrderBook]]:
+        """Async version of history(). start and end are required. See history() for granularity details."""
         data = await self._http.aget(
-            f"/v1/orderbook/{coin.upper()}/history",
+            f"{self._base_path}/orderbook/{coin.upper()}/history",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
                 "depth": depth,
+                "granularity": granularity,
             },
         )
-        return [OrderBook.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[OrderBook.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )

oxarchive/resources/trades.py

@@ -2,20 +2,11 @@
 
 from __future__ import annotations
 
-import warnings
-from dataclasses import dataclass
 from datetime import datetime
 from typing import Literal, Optional
 
 from ..http import HttpClient
-from ..types import Trade, Timestamp
-
-
-@dataclass
-class CursorResponse:
-    """Response with cursor for pagination."""
-    data: list[Trade]
-    next_cursor: Optional[str] = None
+from ..types import CursorResponse, Trade, Timestamp
 
 
 class TradesResource:
@@ -36,8 +27,9 @@ class TradesResource:
         ...     trades.extend(result.data)
     """
 
-    def __init__(self, http: HttpClient):
+    def __init__(self, http: HttpClient, base_path: str = "/v1"):
         self._http = http
+        self._base_path = base_path
 
     def _convert_timestamp(self, ts: Optional[Timestamp]) -> Optional[int]:
         """Convert timestamp to Unix milliseconds."""
@@ -64,7 +56,7 @@ class TradesResource:
         cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
         side: Optional[Literal["buy", "sell"]] = None,
-    ) -> CursorResponse:
+    ) -> CursorResponse[list[Trade]]:
         """
         Get trade history for a coin using cursor-based pagination.
 
@@ -95,7 +87,7 @@ class TradesResource:
             ...     trades.extend(result.data)
         """
         data = self._http.get(
-            f"/v1/trades/{coin.upper()}",
+            f"{self._base_path}/trades/{coin.upper()}",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
@@ -118,14 +110,14 @@ class TradesResource:
         cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
         side: Optional[Literal["buy", "sell"]] = None,
-    ) -> CursorResponse:
+    ) -> CursorResponse[list[Trade]]:
         """
         Async version of list().
 
         Uses cursor-based pagination by default.
         """
         data = await self._http.aget(
-            f"/v1/trades/{coin.upper()}",
+            f"{self._base_path}/trades/{coin.upper()}",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
@@ -139,83 +131,6 @@ class TradesResource:
             next_cursor=data.get("meta", {}).get("next_cursor"),
         )
 
-    def list_with_offset(
-        self,
-        coin: str,
-        *,
-        start: Timestamp,
-        end: Timestamp,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
-        side: Optional[Literal["buy", "sell"]] = None,
-    ) -> list[Trade]:
-        """
-        Get trade history using offset-based pagination.
-
-        .. deprecated::
-            Use list() with cursor-based pagination instead for better performance.
-
-        Args:
-            coin: The coin symbol (e.g., 'BTC', 'ETH')
-            start: Start timestamp (required)
-            end: End timestamp (required)
-            limit: Maximum number of results
-            offset: Number of results to skip
-            side: Filter by trade side
-
-        Returns:
-            List of trades
-        """
-        warnings.warn(
-            "list_with_offset() is deprecated. Use list() with cursor-based pagination instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        data = self._http.get(
-            f"/v1/trades/{coin.upper()}",
-            params={
-                "start": self._convert_timestamp(start),
-                "end": self._convert_timestamp(end),
-                "limit": limit,
-                "offset": offset,
-                "side": side,
-            },
-        )
-        return [Trade.model_validate(item) for item in data["data"]]
-
-    async def alist_with_offset(
-        self,
-        coin: str,
-        *,
-        start: Timestamp,
-        end: Timestamp,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
-        side: Optional[Literal["buy", "sell"]] = None,
-    ) -> list[Trade]:
-        """
-        Async version of list_with_offset().
-
-        .. deprecated::
-            Use alist() with cursor-based pagination instead.
-        """
-        warnings.warn(
-            "alist_with_offset() is deprecated. Use alist() with cursor-based pagination instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        data = await self._http.aget(
-            f"/v1/trades/{coin.upper()}",
-            params={
-                "start": self._convert_timestamp(start),
-                "end": self._convert_timestamp(end),
-                "limit": limit,
-                "offset": offset,
-                "side": side,
-            },
-        )
-        return [Trade.model_validate(item) for item in data["data"]]
-
     def recent(self, coin: str, limit: Optional[int] = None) -> list[Trade]:
         """
         Get most recent trades for a coin.
@@ -228,7 +143,7 @@ class TradesResource:
             List of recent trades
         """
         data = self._http.get(
-            f"/v1/trades/{coin.upper()}/recent",
+            f"{self._base_path}/trades/{coin.upper()}/recent",
             params={"limit": limit},
         )
         return [Trade.model_validate(item) for item in data["data"]]
@@ -236,64 +151,7 @@ class TradesResource:
     async def arecent(self, coin: str, limit: Optional[int] = None) -> list[Trade]:
         """Async version of recent()."""
         data = await self._http.aget(
-            f"/v1/trades/{coin.upper()}/recent",
+            f"{self._base_path}/trades/{coin.upper()}/recent",
             params={"limit": limit},
         )
         return [Trade.model_validate(item) for item in data["data"]]
-
-    def list_cursor(
-        self,
-        coin: str,
-        *,
-        start: Timestamp,
-        end: Timestamp,
-        cursor: Optional[Timestamp] = None,
-        limit: Optional[int] = None,
-        side: Optional[Literal["buy", "sell"]] = None,
-    ) -> CursorResponse:
-        """
-        Get trade history using cursor-based pagination.
-
-        .. deprecated::
-            Use list() instead - it now uses cursor-based pagination by default.
-
-        Args:
-            coin: The coin symbol (e.g., 'BTC', 'ETH')
-            start: Start timestamp (required)
-            end: End timestamp (required)
-            cursor: Cursor from previous response's next_cursor (timestamp)
-            limit: Maximum number of results
-            side: Filter by trade side
-
-        Returns:
-            CursorResponse with trades and next_cursor for pagination
-        """
-        warnings.warn(
-            "list_cursor() is deprecated. Use list() instead - it now uses cursor-based pagination by default.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.list(coin, start=start, end=end, cursor=cursor, limit=limit, side=side)
-
-    async def alist_cursor(
-        self,
-        coin: str,
-        *,
-        start: Timestamp,
-        end: Timestamp,
-        cursor: Optional[Timestamp] = None,
-        limit: Optional[int] = None,
-        side: Optional[Literal["buy", "sell"]] = None,
-    ) -> CursorResponse:
-        """
-        Async version of list_cursor().
-
-        .. deprecated::
-            Use alist() instead - it now uses cursor-based pagination by default.
-        """
-        warnings.warn(
-            "alist_cursor() is deprecated. Use alist() instead - it now uses cursor-based pagination by default.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return await self.alist(coin, start=start, end=end, cursor=cursor, limit=limit, side=side)

oxarchive/types.py

@@ -124,9 +124,6 @@ class Trade(BaseModel):
     start_position: Optional[str] = None
     """Position size before this trade."""
 
-    source: Optional[Literal["s3", "ws", "api", "live"]] = None
-    """Data source: 's3' (historical), 'api' (REST backfill), 'ws' (websocket), 'live' (real-time ingestion)."""
-
     user_address: Optional[str] = None
     """User's wallet address (for fill-level data)."""
 
@@ -143,7 +140,7 @@ class Trade(BaseModel):
 
 
 class Instrument(BaseModel):
-    """Trading instrument specification."""
+    """Trading instrument specification (Hyperliquid)."""
 
     model_config = {"populate_by_name": True}
 
@@ -166,6 +163,53 @@ class Instrument(BaseModel):
     """Whether the instrument is currently tradeable."""
 
 
+class LighterInstrument(BaseModel):
+    """Trading instrument specification (Lighter.xyz).
+
+    Lighter instruments have a different schema than Hyperliquid with more
+    detailed market configuration including fees and minimum amounts.
+    """
+
+    symbol: str
+    """Instrument symbol (e.g., BTC, ETH)."""
+
+    market_id: int
+    """Unique market identifier."""
+
+    market_type: str
+    """Market type (e.g., 'perp')."""
+
+    status: str
+    """Market status (e.g., 'active')."""
+
+    taker_fee: float
+    """Taker fee rate (e.g., 0.0005 = 0.05%)."""
+
+    maker_fee: float
+    """Maker fee rate (e.g., 0.0002 = 0.02%)."""
+
+    liquidation_fee: float
+    """Liquidation fee rate."""
+
+    min_base_amount: float
+    """Minimum order size in base currency."""
+
+    min_quote_amount: float
+    """Minimum order size in quote currency."""
+
+    size_decimals: int
+    """Size decimal precision."""
+
+    price_decimals: int
+    """Price decimal precision."""
+
+    quote_decimals: int
+    """Quote currency decimal precision."""
+
+    is_active: bool
+    """Whether the instrument is currently tradeable."""
+
+
 # =============================================================================
 # Funding Types
 # =============================================================================
@@ -338,6 +382,41 @@ class WsHistoricalData(BaseModel):
     data: dict[str, Any]
 
 
+class OrderbookDelta(BaseModel):
+    """Orderbook delta for tick-level data."""
+
+    timestamp: int
+    """Timestamp in milliseconds."""
+
+    side: Literal["bid", "ask"]
+    """Side: 'bid' or 'ask'."""
+
+    price: float
+    """Price level."""
+
+    size: float
+    """New size (0 = level removed)."""
+
+    sequence: int
+    """Sequence number for ordering."""
+
+
+class WsHistoricalTickData(BaseModel):
+    """Historical tick data (granularity='tick' mode) - checkpoint + deltas.
+
+    This message type is sent when using granularity='tick' for Lighter.xyz
+    orderbook data. It provides a full checkpoint followed by incremental deltas.
+    """
+
+    type: Literal["historical_tick_data"]
+    channel: WsChannel
+    coin: str
+    checkpoint: dict[str, Any]
+    """Initial checkpoint (full orderbook snapshot)."""
+    deltas: list[OrderbookDelta]
+    """Incremental deltas to apply after checkpoint."""
+
+
 # =============================================================================
 # WebSocket Bulk Stream Types (Bulk Download Mode)
 # =============================================================================
@@ -414,6 +493,21 @@ class OxArchiveError(Exception):
         return f"[{self.code}] {self.message}"
 
 
+# =============================================================================
+# Pagination Types
+# =============================================================================
+
+
+class CursorResponse(BaseModel, Generic[T]):
+    """Response with cursor for pagination."""
+
+    data: T
+    """The paginated data."""
+
+    next_cursor: Optional[str] = None
+    """Cursor for the next page (use as cursor parameter)."""
+
+
 # Type alias for timestamp parameters
 Timestamp = Union[int, str, datetime]
 """Timestamp can be Unix ms (int), ISO string, or datetime object."""

oxarchive/websocket.py

@@ -31,17 +31,18 @@ from dataclasses import dataclass, field
 from typing import Any, Callable, Optional, Set, Union
 
 try:
-    import websockets
-    from websockets.client import WebSocketClientProtocol
+    from websockets.asyncio.client import connect as ws_connect, ClientConnection
+    from websockets.exceptions import ConnectionClosed
     from websockets.protocol import State as WsState
 except ImportError:
     raise ImportError(
-        "WebSocket support requires the 'websockets' package. "
+        "WebSocket support requires the 'websockets' package (>=14.0). "
         "Install with: pip install oxarchive[websocket]"
     )
 
 from .types import (
     OrderBook,
+    OrderbookDelta,
     PriceLevel,
     Trade,
     WsChannel,
@@ -57,6 +58,7 @@ from .types import (
     WsReplayCompleted,
     WsReplayStopped,
     WsHistoricalData,
+    WsHistoricalTickData,
     WsStreamStarted,
     WsStreamProgress,
     WsHistoricalBatch,
@@ -110,6 +112,7 @@ ErrorHandler = Callable[[Exception], None]
 
 # Replay handlers
 HistoricalDataHandler = Callable[[str, int, dict], None]
+HistoricalTickDataHandler = Callable[[str, dict, list[OrderbookDelta]], None]  # coin, checkpoint, deltas
 ReplayStartHandler = Callable[[WsChannel, str, int, int, float], None]  # channel, coin, start, end, speed
 ReplayCompleteHandler = Callable[[WsChannel, str, int], None]  # channel, coin, snapshots_sent
 
@@ -147,7 +150,6 @@ def _transform_trade(coin: str, raw: dict) -> Trade:
             "closed_pnl": raw.get("closed_pnl") or raw.get("closedPnl"),
             "direction": raw.get("direction"),
             "start_position": raw.get("start_position") or raw.get("startPosition"),
-            "source": raw.get("source"),
             "user_address": raw.get("user_address") or raw.get("userAddress"),
             "maker_address": raw.get("maker_address"),
             "taker_address": raw.get("taker_address"),
@@ -258,7 +260,7 @@ class OxArchiveWs:
             options: WebSocket connection options
         """
         self.options = options
-        self._ws: Optional[WebSocketClientProtocol] = None
+        self._ws: Optional[ClientConnection] = None
         self._state: WsConnectionState = "disconnected"
         self._subscriptions: Set[str] = set()
         self._reconnect_attempts = 0
@@ -277,6 +279,7 @@ class OxArchiveWs:
 
         # Replay handlers (Option B)
         self._on_historical_data: Optional[HistoricalDataHandler] = None
+        self._on_historical_tick_data: Optional[HistoricalTickDataHandler] = None
         self._on_replay_start: Optional[ReplayStartHandler] = None
         self._on_replay_complete: Optional[ReplayCompleteHandler] = None
 
@@ -308,7 +311,8 @@ class OxArchiveWs:
         url = f"{self.options.ws_url}?apiKey={self.options.api_key}"
 
         try:
-            self._ws = await websockets.connect(url)
+            # Increase max_size from default 1MB to 10MB for large Lighter orderbook data
+            self._ws = await ws_connect(url, max_size=10 * 1024 * 1024)
             self._reconnect_attempts = 0
             self._set_state("connected")
 
@@ -428,6 +432,7 @@ class OxArchiveWs:
         start: int,
         end: Optional[int] = None,
         speed: float = 1.0,
+        granularity: Optional[str] = None,
     ) -> None:
         """Start historical replay with timing preserved.
 
@@ -437,6 +442,7 @@ class OxArchiveWs:
             start: Start timestamp (Unix ms)
             end: End timestamp (Unix ms, defaults to now)
             speed: Playback speed multiplier (1 = real-time, 10 = 10x faster)
+            granularity: Data resolution for Lighter orderbook ('checkpoint', '30s', '10s', '1s', 'tick')
 
         Example:
             >>> await ws.replay("orderbook", "BTC", start=time.time()*1000 - 86400000, speed=10)
@@ -450,6 +456,8 @@ class OxArchiveWs:
         }
         if end is not None:
             msg["end"] = end
+        if granularity is not None:
+            msg["granularity"] = granularity
         await self._send(msg)
 
     async def replay_pause(self) -> None:
@@ -483,6 +491,7 @@ class OxArchiveWs:
         start: int,
         end: int,
         batch_size: int = 1000,
+        granularity: Optional[str] = None,
     ) -> None:
         """Start bulk streaming for fast data download.
 
@@ -492,18 +501,22 @@ class OxArchiveWs:
             start: Start timestamp (Unix ms)
             end: End timestamp (Unix ms)
             batch_size: Records per batch message
+            granularity: Data resolution for Lighter orderbook ('checkpoint', '30s', '10s', '1s', 'tick')
 
         Example:
             >>> await ws.stream("orderbook", "ETH", start=..., end=..., batch_size=1000)
         """
-        await self._send({
+        msg = {
             "op": "stream",
             "channel": channel,
             "coin": coin,
             "start": start,
             "end": end,
             "batch_size": batch_size,
-        })
+        }
+        if granularity is not None:
+            msg["granularity"] = granularity
+        await self._send(msg)
 
     async def stream_stop(self) -> None:
         """Stop the current bulk stream."""
@@ -548,6 +561,16 @@ class OxArchiveWs:
         """
         self._on_historical_data = handler
 
+    def on_historical_tick_data(self, handler: HistoricalTickDataHandler) -> None:
+        """Set handler for historical tick data (granularity='tick' mode).
+
+        This is for tick-level granularity on Lighter.xyz orderbook data.
+        Receives a checkpoint (full orderbook) followed by incremental deltas.
+
+        Handler receives: (coin, checkpoint, deltas)
+        """
+        self._on_historical_tick_data = handler
+
     def on_replay_start(self, handler: ReplayStartHandler) -> None:
         """Set handler for replay started event.
 
@@ -652,7 +675,7 @@ class OxArchiveWs:
                 try:
                     message = await self._ws.recv()
                     self._handle_message(message)
-                except websockets.ConnectionClosed as e:
+                except ConnectionClosed as e:
                     logger.info(f"Connection closed: {e.code} {e.reason}")
                     if self._on_close:
                         self._on_close(e.code, e.reason)
@@ -723,6 +746,10 @@ class OxArchiveWs:
             elif msg_type == "historical_data" and self._on_historical_data:
                 self._on_historical_data(data["coin"], data["timestamp"], data["data"])
 
+            elif msg_type == "historical_tick_data" and self._on_historical_tick_data:
+                msg = WsHistoricalTickData(**data)
+                self._on_historical_tick_data(msg.coin, msg.checkpoint, msg.deltas)
+
             elif msg_type == "replay_completed" and self._on_replay_complete:
                 self._on_replay_complete(data["channel"], data["coin"], data["snapshots_sent"])