oxarchive 0.3.4__py3-none-any.whl → 0.4.3__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
 # =============================================================================
@@ -414,6 +458,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,12 +31,12 @@ 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]"
     )
 
@@ -124,13 +124,36 @@ def _transform_trade(coin: str, raw: dict) -> Trade:
     """Transform raw Hyperliquid trade format to SDK Trade type.
 
     Raw WebSocket format: { coin, side, px, sz, time, hash, tid, users: [maker, taker] }
+    Historical replay format: { coin, side, price, size, time, hash, tradeId, userAddress, ... }
     SDK format: { coin, side, price, size, timestamp, tx_hash, trade_id, maker_address, taker_address }
     """
     from datetime import datetime
 
     # Check if already in SDK format (from REST API or historical replay)
     if "price" in raw and "size" in raw:
-        return Trade(**raw)
+        # Map camelCase keys from WebSocket to snake_case for Pydantic
+        mapped = {
+            "coin": raw.get("coin", coin),
+            "side": raw.get("side", "B"),
+            "price": raw.get("price"),
+            "size": raw.get("size"),
+            "timestamp": raw.get("timestamp") or (datetime.utcfromtimestamp(raw.get("time", 0) / 1000).isoformat() + "Z" if raw.get("time") else None),
+            "tx_hash": raw.get("tx_hash") or raw.get("hash"),
+            "trade_id": raw.get("trade_id") or raw.get("tradeId"),
+            "order_id": raw.get("order_id") or raw.get("orderId"),
+            "crossed": raw.get("crossed"),
+            "fee": raw.get("fee"),
+            "fee_token": raw.get("fee_token") or raw.get("feeToken"),
+            "closed_pnl": raw.get("closed_pnl") or raw.get("closedPnl"),
+            "direction": raw.get("direction"),
+            "start_position": raw.get("start_position") or raw.get("startPosition"),
+            "user_address": raw.get("user_address") or raw.get("userAddress"),
+            "maker_address": raw.get("maker_address"),
+            "taker_address": raw.get("taker_address"),
+        }
+        # Remove None values to let Pydantic use defaults
+        mapped = {k: v for k, v in mapped.items() if v is not None}
+        return Trade(**mapped)
 
     # Transform from Hyperliquid raw format
     time_ms = raw.get("time")
@@ -234,7 +257,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
@@ -284,7 +307,7 @@ class OxArchiveWs:
         url = f"{self.options.ws_url}?apiKey={self.options.api_key}"
 
         try:
-            self._ws = await websockets.connect(url)
+            self._ws = await ws_connect(url)
             self._reconnect_attempts = 0
             self._set_state("connected")
 
@@ -628,7 +651,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)