oxarchive 0.3.10__py3-none-any.whl → 0.4.0__py3-none-any.whl

oxarchive/__init__.py

@@ -1,22 +1,28 @@
 """
 oxarchive - Official Python SDK for 0xarchive
 
-Hyperliquid Historical Data API.
+Historical Market Data API for multiple exchanges:
+- Hyperliquid (perpetuals data from April 2023)
+- Lighter.xyz (perpetuals data)
 
 Example:
     >>> from oxarchive import Client
     >>>
     >>> client = Client(api_key="ox_your_api_key")
     >>>
-    >>> # Get current order book
-    >>> orderbook = client.orderbook.get("BTC")
-    >>> print(f"BTC mid price: {orderbook.mid_price}")
+    >>> # Hyperliquid data
+    >>> hl_orderbook = client.hyperliquid.orderbook.get("BTC")
+    >>> print(f"BTC mid price: {hl_orderbook.mid_price}")
+    >>>
+    >>> # Lighter.xyz data
+    >>> lighter_orderbook = client.lighter.orderbook.get("BTC")
     >>>
     >>> # Get historical snapshots
-    >>> history = client.orderbook.history("ETH", start="2024-01-01", end="2024-01-02")
+    >>> history = client.hyperliquid.orderbook.history("ETH", start="2024-01-01", end="2024-01-02")
 """
 
 from .client import Client
+from .exchanges import HyperliquidClient, LighterClient
 from .types import (
     OrderBook,
     Trade,
@@ -57,11 +63,14 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.3.10"
+__version__ = "0.4.0"
 
 __all__ = [
     # Client
     "Client",
+    # Exchange Clients
+    "HyperliquidClient",
+    "LighterClient",
     # WebSocket Client
     "OxArchiveWs",
     "WsOptions",

oxarchive/client.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import Optional
 
 from .http import HttpClient
+from .exchanges import HyperliquidClient, LighterClient
 from .resources import (
     OrderBookResource,
     TradesResource,
@@ -21,20 +22,27 @@ class Client:
     """
     0xarchive API client.
 
+    Supports multiple exchanges:
+    - `client.hyperliquid` - Hyperliquid perpetuals (April 2023+)
+    - `client.lighter` - Lighter.xyz perpetuals
+
     Example:
         >>> from oxarchive import Client
         >>>
         >>> client = Client(api_key="ox_your_api_key")
         >>>
-        >>> # Get current order book
-        >>> orderbook = client.orderbook.get("BTC")
-        >>> print(f"BTC mid price: {orderbook.mid_price}")
+        >>> # Hyperliquid data
+        >>> hl_orderbook = client.hyperliquid.orderbook.get("BTC")
+        >>> print(f"BTC mid price: {hl_orderbook.mid_price}")
+        >>>
+        >>> # Lighter.xyz data
+        >>> lighter_orderbook = client.lighter.orderbook.get("BTC")
         >>>
         >>> # Get historical snapshots
-        >>> history = client.orderbook.history("ETH", start="2024-01-01", end="2024-01-02")
+        >>> history = client.hyperliquid.orderbook.history("ETH", start="2024-01-01", end="2024-01-02")
         >>>
         >>> # List all instruments
-        >>> instruments = client.instruments.list()
+        >>> instruments = client.hyperliquid.instruments.list()
 
     Async example:
         >>> import asyncio
@@ -42,11 +50,15 @@ class Client:
         >>>
         >>> async def main():
         ...     client = Client(api_key="ox_your_api_key")
-        ...     orderbook = await client.orderbook.aget("BTC")
+        ...     orderbook = await client.hyperliquid.orderbook.aget("BTC")
         ...     print(f"BTC mid price: {orderbook.mid_price}")
         ...     await client.aclose()
         >>>
         >>> asyncio.run(main())
+
+    Legacy usage (deprecated, will be removed in v2.0):
+        >>> # These still work but use client.hyperliquid.* instead
+        >>> orderbook = client.orderbook.get("BTC")  # deprecated
     """
 
     def __init__(
@@ -73,21 +85,31 @@ class Client:
             timeout=timeout or DEFAULT_TIMEOUT,
         )
 
-        # Initialize resource namespaces
-        self.orderbook = OrderBookResource(self._http)
-        """Order book data (L2 snapshots from April 2023)"""
+        # Exchange-specific clients (recommended)
+        self.hyperliquid = HyperliquidClient(self._http)
+        """Hyperliquid exchange data (orderbook, trades, funding, OI from April 2023)"""
+
+        self.lighter = LighterClient(self._http)
+        """Lighter.xyz exchange data (orderbook reconstructed from checkpoints + deltas)"""
+
+        # Legacy resource namespaces (deprecated - use client.hyperliquid.* instead)
+        # These will be removed in v2.0
+        # Note: Using /v1/hyperliquid base path for backward compatibility
+        legacy_base = "/v1/hyperliquid"
+        self.orderbook = OrderBookResource(self._http, legacy_base)
+        """[DEPRECATED] Use client.hyperliquid.orderbook instead"""
 
-        self.trades = TradesResource(self._http)
-        """Trade/fill history"""
+        self.trades = TradesResource(self._http, legacy_base)
+        """[DEPRECATED] Use client.hyperliquid.trades instead"""
 
-        self.instruments = InstrumentsResource(self._http)
-        """Trading instruments metadata"""
+        self.instruments = InstrumentsResource(self._http, legacy_base)
+        """[DEPRECATED] Use client.hyperliquid.instruments instead"""
 
-        self.funding = FundingResource(self._http)
-        """Funding rates"""
+        self.funding = FundingResource(self._http, legacy_base)
+        """[DEPRECATED] Use client.hyperliquid.funding instead"""
 
-        self.open_interest = OpenInterestResource(self._http)
-        """Open interest"""
+        self.open_interest = OpenInterestResource(self._http, legacy_base)
+        """[DEPRECATED] Use client.hyperliquid.open_interest instead"""
 
     def close(self) -> None:
         """Close the HTTP client and release resources."""

oxarchive/exchanges.py

@@ -0,0 +1,77 @@
+"""Exchange-specific client classes."""
+
+from __future__ import annotations
+
+from .http import HttpClient
+from .resources import (
+    OrderBookResource,
+    TradesResource,
+    InstrumentsResource,
+    FundingResource,
+    OpenInterestResource,
+)
+
+
+class HyperliquidClient:
+    """
+    Hyperliquid exchange client.
+
+    Access Hyperliquid market data through the 0xarchive API.
+
+    Example:
+        >>> client = oxarchive.Client(api_key="...")
+        >>> orderbook = client.hyperliquid.orderbook.get("BTC")
+        >>> trades = client.hyperliquid.trades.list("ETH", start=..., end=...)
+    """
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+        base_path = "/v1/hyperliquid"
+
+        self.orderbook = OrderBookResource(http, base_path)
+        """Order book data (L2 snapshots from April 2023)"""
+
+        self.trades = TradesResource(http, base_path)
+        """Trade/fill history"""
+
+        self.instruments = InstrumentsResource(http, base_path)
+        """Trading instruments metadata"""
+
+        self.funding = FundingResource(http, base_path)
+        """Funding rates"""
+
+        self.open_interest = OpenInterestResource(http, base_path)
+        """Open interest"""
+
+
+class LighterClient:
+    """
+    Lighter.xyz exchange client.
+
+    Access Lighter.xyz market data through the 0xarchive API.
+    Lighter orderbooks are reconstructed from checkpoint + delta data.
+
+    Example:
+        >>> client = oxarchive.Client(api_key="...")
+        >>> orderbook = client.lighter.orderbook.get("BTC")
+        >>> trades = client.lighter.trades.list("ETH", start=..., end=...)
+    """
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+        base_path = "/v1/lighter"
+
+        self.orderbook = OrderBookResource(http, base_path)
+        """Order book data (reconstructed from checkpoints + deltas)"""
+
+        self.trades = TradesResource(http, base_path)
+        """Trade/fill history"""
+
+        self.instruments = InstrumentsResource(http, base_path)
+        """Trading instruments metadata"""
+
+        self.funding = FundingResource(http, base_path)
+        """Funding rates"""
+
+        self.open_interest = OpenInterestResource(http, base_path)
+        """Open interest"""

oxarchive/resources/funding.py

@@ -6,7 +6,7 @@ from datetime import datetime
 from typing import Optional
 
 from ..http import HttpClient
-from ..types import FundingRate, Timestamp
+from ..types import CursorResponse, FundingRate, Timestamp
 
 
 class FundingResource:
@@ -21,8 +21,9 @@ class FundingResource:
         >>> history = client.funding.history("ETH", start="2024-01-01", end="2024-01-07")
     """
 
-    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."""
@@ -46,32 +47,44 @@ class FundingResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
-    ) -> list[FundingRate]:
+    ) -> CursorResponse[list[FundingRate]]:
         """
-        Get funding rate history for a coin.
+        Get funding rate history for a coin 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)
 
         Returns:
-            List of funding rate records
+            CursorResponse with funding rate records and next_cursor for pagination
+
+        Example:
+            >>> result = client.funding.history("BTC", start=start, end=end, limit=1000)
+            >>> rates = result.data
+            >>> while result.next_cursor:
+            ...     result = client.funding.history(
+            ...         "BTC", start=start, end=end, cursor=result.next_cursor, limit=1000
+            ...     )
+            ...     rates.extend(result.data)
         """
         data = self._http.get(
-            f"/v1/funding/{coin.upper()}",
+            f"{self._base_path}/funding/{coin.upper()}",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
             },
         )
-        return [FundingRate.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[FundingRate.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
 
     async def ahistory(
         self,
@@ -79,20 +92,23 @@ class FundingResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
-    ) -> list[FundingRate]:
+    ) -> CursorResponse[list[FundingRate]]:
         """Async version of history(). start and end are required."""
         data = await self._http.aget(
-            f"/v1/funding/{coin.upper()}",
+            f"{self._base_path}/funding/{coin.upper()}",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
             },
         )
-        return [FundingRate.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[FundingRate.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
 
     def current(self, coin: str) -> FundingRate:
         """
@@ -104,10 +120,10 @@ class FundingResource:
         Returns:
             Current funding rate
         """
-        data = self._http.get(f"/v1/funding/{coin.upper()}/current")
+        data = self._http.get(f"{self._base_path}/funding/{coin.upper()}/current")
         return FundingRate.model_validate(data["data"])
 
     async def acurrent(self, coin: str) -> FundingRate:
         """Async version of current()."""
-        data = await self._http.aget(f"/v1/funding/{coin.upper()}/current")
+        data = await self._http.aget(f"{self._base_path}/funding/{coin.upper()}/current")
         return FundingRate.model_validate(data["data"])

oxarchive/resources/instruments.py

@@ -18,8 +18,9 @@ class InstrumentsResource:
         >>> btc = client.instruments.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 list(self) -> list[Instrument]:
         """
@@ -28,12 +29,12 @@ class InstrumentsResource:
         Returns:
             List of instruments
         """
-        data = self._http.get("/v1/instruments")
+        data = self._http.get(f"{self._base_path}/instruments")
         return [Instrument.model_validate(item) for item in data["data"]]
 
     async def alist(self) -> list[Instrument]:
         """Async version of list()."""
-        data = await self._http.aget("/v1/instruments")
+        data = await self._http.aget(f"{self._base_path}/instruments")
         return [Instrument.model_validate(item) for item in data["data"]]
 
     def get(self, coin: str) -> Instrument:
@@ -46,10 +47,10 @@ class InstrumentsResource:
         Returns:
             Instrument details
         """
-        data = self._http.get(f"/v1/instruments/{coin.upper()}")
+        data = self._http.get(f"{self._base_path}/instruments/{coin.upper()}")
         return Instrument.model_validate(data["data"])
 
     async def aget(self, coin: str) -> Instrument:
         """Async version of get()."""
-        data = await self._http.aget(f"/v1/instruments/{coin.upper()}")
+        data = await self._http.aget(f"{self._base_path}/instruments/{coin.upper()}")
         return Instrument.model_validate(data["data"])

oxarchive/resources/openinterest.py

@@ -6,7 +6,7 @@ from datetime import datetime
 from typing import Optional
 
 from ..http import HttpClient
-from ..types import OpenInterest, Timestamp
+from ..types import CursorResponse, OpenInterest, Timestamp
 
 
 class OpenInterestResource:
@@ -21,8 +21,9 @@ class OpenInterestResource:
         >>> history = client.open_interest.history("ETH", start="2024-01-01", end="2024-01-07")
     """
 
-    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."""
@@ -46,32 +47,44 @@ class OpenInterestResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
-    ) -> list[OpenInterest]:
+    ) -> CursorResponse[list[OpenInterest]]:
         """
-        Get open interest history for a coin.
+        Get open interest history for a coin 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)
 
         Returns:
-            List of open interest records
+            CursorResponse with open interest records and next_cursor for pagination
+
+        Example:
+            >>> result = client.open_interest.history("BTC", start=start, end=end, limit=1000)
+            >>> records = result.data
+            >>> while result.next_cursor:
+            ...     result = client.open_interest.history(
+            ...         "BTC", start=start, end=end, cursor=result.next_cursor, limit=1000
+            ...     )
+            ...     records.extend(result.data)
         """
         data = self._http.get(
-            f"/v1/openinterest/{coin.upper()}",
+            f"{self._base_path}/openinterest/{coin.upper()}",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
             },
         )
-        return [OpenInterest.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[OpenInterest.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
 
     async def ahistory(
         self,
@@ -79,20 +92,23 @@ class OpenInterestResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
-    ) -> list[OpenInterest]:
+    ) -> CursorResponse[list[OpenInterest]]:
         """Async version of history(). start and end are required."""
         data = await self._http.aget(
-            f"/v1/openinterest/{coin.upper()}",
+            f"{self._base_path}/openinterest/{coin.upper()}",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
             },
         )
-        return [OpenInterest.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[OpenInterest.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
 
     def current(self, coin: str) -> OpenInterest:
         """
@@ -104,10 +120,10 @@ class OpenInterestResource:
         Returns:
             Current open interest
         """
-        data = self._http.get(f"/v1/openinterest/{coin.upper()}/current")
+        data = self._http.get(f"{self._base_path}/openinterest/{coin.upper()}/current")
         return OpenInterest.model_validate(data["data"])
 
     async def acurrent(self, coin: str) -> OpenInterest:
         """Async version of current()."""
-        data = await self._http.aget(f"/v1/openinterest/{coin.upper()}/current")
+        data = await self._http.aget(f"{self._base_path}/openinterest/{coin.upper()}/current")
         return OpenInterest.model_validate(data["data"])

oxarchive/resources/orderbook.py

@@ -6,7 +6,7 @@ from datetime import datetime
 from typing import Optional, Union
 
 from ..http import HttpClient
-from ..types import OrderBook, Timestamp
+from ..types import CursorResponse, OrderBook, Timestamp
 
 
 class OrderBookResource:
@@ -14,18 +14,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 +67,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 +84,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 +98,47 @@ class OrderBookResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
         depth: Optional[int] = None,
-    ) -> list[OrderBook]:
+    ) -> 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
 
         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)
         """
         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,
             },
         )
-        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 +146,22 @@ class OrderBookResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
         depth: Optional[int] = None,
-    ) -> list[OrderBook]:
+    ) -> CursorResponse[list[OrderBook]]:
         """Async version of history(). start and end are required."""
         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,
             },
         )
-        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

@@ -411,6 +411,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-0.3.10.dist-info → oxarchive-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.3.10
+Version: 0.4.0
 Summary: Official Python SDK for 0xarchive - Hyperliquid Historical Data API
 Project-URL: Homepage, https://0xarchive.io
 Project-URL: Documentation, https://0xarchive.io/docs/sdks
@@ -37,7 +37,11 @@ Description-Content-Type: text/markdown
 
 # oxarchive
 
-Official Python SDK for [0xarchive](https://0xarchive.io) - Hyperliquid Historical Data API.
+Official Python SDK for [0xarchive](https://0xarchive.io) - Historical Market Data API.
+
+Supports multiple exchanges:
+- **Hyperliquid** - Perpetuals data from April 2023
+- **Lighter.xyz** - Perpetuals data with orderbook reconstruction
 
 ## Installation
 
@@ -58,12 +62,16 @@ from oxarchive import Client
 
 client = Client(api_key="ox_your_api_key")
 
-# Get current order book
-orderbook = client.orderbook.get("BTC")
-print(f"BTC mid price: {orderbook.mid_price}")
+# Hyperliquid data
+hl_orderbook = client.hyperliquid.orderbook.get("BTC")
+print(f"Hyperliquid BTC mid price: {hl_orderbook.mid_price}")
+
+# Lighter.xyz data
+lighter_orderbook = client.lighter.orderbook.get("BTC")
+print(f"Lighter BTC mid price: {lighter_orderbook.mid_price}")
 
 # Get historical order book snapshots
-history = client.orderbook.history(
+history = client.hyperliquid.orderbook.history(
     "ETH",
     start="2024-01-01",
     end="2024-01-02",
@@ -82,10 +90,13 @@ from oxarchive import Client
 async def main():
     client = Client(api_key="ox_your_api_key")
 
-    # Async get
-    orderbook = await client.orderbook.aget("BTC")
+    # Async get (Hyperliquid)
+    orderbook = await client.hyperliquid.orderbook.aget("BTC")
     print(f"BTC mid price: {orderbook.mid_price}")
 
+    # Async get (Lighter.xyz)
+    lighter_ob = await client.lighter.orderbook.aget("BTC")
+
     # Don't forget to close the client
     await client.aclose()
 
@@ -96,7 +107,7 @@ Or use as async context manager:
 
 ```python
 async with Client(api_key="ox_your_api_key") as client:
-    orderbook = await client.orderbook.aget("BTC")
+    orderbook = await client.hyperliquid.orderbook.aget("BTC")
 ```
 
 ## Configuration
@@ -111,20 +122,25 @@ client = Client(
 
 ## REST API Reference
 
+All examples use `client.hyperliquid.*` but the same methods are available on `client.lighter.*` for Lighter.xyz data.
+
 ### Order Book
 
 ```python
-# Get current order book
-orderbook = client.orderbook.get("BTC")
+# Get current order book (Hyperliquid)
+orderbook = client.hyperliquid.orderbook.get("BTC")
+
+# Get current order book (Lighter.xyz)
+orderbook = client.lighter.orderbook.get("BTC")
 
 # Get order book at specific timestamp
-historical = client.orderbook.get("BTC", timestamp=1704067200000)
+historical = client.hyperliquid.orderbook.get("BTC", timestamp=1704067200000)
 
 # Get with limited depth
-shallow = client.orderbook.get("BTC", depth=10)
+shallow = client.hyperliquid.orderbook.get("BTC", depth=10)
 
 # Get historical snapshots (start and end are required)
-history = client.orderbook.history(
+history = client.hyperliquid.orderbook.history(
     "BTC",
     start="2024-01-01",
     end="2024-01-02",
@@ -133,8 +149,8 @@ history = client.orderbook.history(
 )
 
 # Async versions
-orderbook = await client.orderbook.aget("BTC")
-history = await client.orderbook.ahistory("BTC", start=..., end=...)
+orderbook = await client.hyperliquid.orderbook.aget("BTC")
+history = await client.hyperliquid.orderbook.ahistory("BTC", start=..., end=...)
 ```
 
 ### Trades
@@ -143,15 +159,15 @@ The trades API uses cursor-based pagination for efficient retrieval of large dat
 
 ```python
 # Get recent trades
-recent = client.trades.recent("BTC", limit=100)
+recent = client.hyperliquid.trades.recent("BTC", limit=100)
 
 # Get trade history with cursor-based pagination
-result = client.trades.list("ETH", start="2024-01-01", end="2024-01-02", limit=1000)
+result = client.hyperliquid.trades.list("ETH", start="2024-01-01", end="2024-01-02", limit=1000)
 trades = result.data
 
 # Paginate through all results
 while result.next_cursor:
-    result = client.trades.list(
+    result = client.hyperliquid.trades.list(
         "ETH",
         start="2024-01-01",
         end="2024-01-02",
@@ -161,61 +177,73 @@ while result.next_cursor:
     trades.extend(result.data)
 
 # Filter by side
-buys = client.trades.list("BTC", start=..., end=..., side="buy")
+buys = client.hyperliquid.trades.list("BTC", start=..., end=..., side="buy")
 
 # Async versions
-recent = await client.trades.arecent("BTC")
-result = await client.trades.alist("ETH", start=..., end=...)
+recent = await client.hyperliquid.trades.arecent("BTC")
+result = await client.hyperliquid.trades.alist("ETH", start=..., end=...)
 ```
 
 ### Instruments
 
 ```python
 # List all trading instruments
-instruments = client.instruments.list()
+instruments = client.hyperliquid.instruments.list()
 
 # Get specific instrument details
-btc = client.instruments.get("BTC")
+btc = client.hyperliquid.instruments.get("BTC")
 
 # Async versions
-instruments = await client.instruments.alist()
-btc = await client.instruments.aget("BTC")
+instruments = await client.hyperliquid.instruments.alist()
+btc = await client.hyperliquid.instruments.aget("BTC")
 ```
 
 ### Funding Rates
 
 ```python
 # Get current funding rate
-current = client.funding.current("BTC")
+current = client.hyperliquid.funding.current("BTC")
 
 # Get funding rate history (start is required)
-history = client.funding.history(
+history = client.hyperliquid.funding.history(
     "ETH",
     start="2024-01-01",
     end="2024-01-07"
 )
 
 # Async versions
-current = await client.funding.acurrent("BTC")
-history = await client.funding.ahistory("ETH", start=..., end=...)
+current = await client.hyperliquid.funding.acurrent("BTC")
+history = await client.hyperliquid.funding.ahistory("ETH", start=..., end=...)
 ```
 
 ### Open Interest
 
 ```python
 # Get current open interest
-current = client.open_interest.current("BTC")
+current = client.hyperliquid.open_interest.current("BTC")
 
 # Get open interest history (start is required)
-history = client.open_interest.history(
+history = client.hyperliquid.open_interest.history(
     "ETH",
     start="2024-01-01",
     end="2024-01-07"
 )
 
 # Async versions
-current = await client.open_interest.acurrent("BTC")
-history = await client.open_interest.ahistory("ETH", start=..., end=...)
+current = await client.hyperliquid.open_interest.acurrent("BTC")
+history = await client.hyperliquid.open_interest.ahistory("ETH", start=..., end=...)
+```
+
+### Legacy API (Deprecated)
+
+The following legacy methods are deprecated and will be removed in v2.0. They default to Hyperliquid data:
+
+```python
+# Deprecated - use client.hyperliquid.orderbook.get() instead
+orderbook = client.orderbook.get("BTC")
+
+# Deprecated - use client.hyperliquid.trades.list() instead
+trades = client.trades.list("BTC", start=..., end=...)
 ```
 
 ## WebSocket Client

oxarchive-0.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+oxarchive/__init__.py,sha256=lBRtHH7NMlNqEN783KdsvFgmd3mT1B8UDcfFo2TW-_w,2536
+oxarchive/client.py,sha256=uoZ_1oxL13M-TvysQdd4qiyRM5MkrMhdSXTCzr5rtw4,4490
+oxarchive/exchanges.py,sha256=fujxX--IKVgJbuJpxrmYZhgMyjkOIPY3TiX1oX9RhZE,2301
+oxarchive/http.py,sha256=SY_o9Ag8ADo1HI3i3uAKW1xwkYjPE75gRAjnMsddAGs,4211
+oxarchive/types.py,sha256=RUnni6RMGHxK3-tTajcDVtT3Rk_sJqlOJLiG5SMc3Do,11278
+oxarchive/websocket.py,sha256=MyffJxaabDBonECcJg9vF4hAQ_4thjP4DaS7MaR4uno,28381
+oxarchive/resources/__init__.py,sha256=WQ4GYQ8p3L0D2Isk4IV4h1DRpvyZlt6tOF1t_CJr6ls,385
+oxarchive/resources/funding.py,sha256=ybMWkpoccrkdwnd6W3oHgsaor7cBcA2nkYy4CbjmHUg,4485
+oxarchive/resources/instruments.py,sha256=9XAqYcwiJ1UXh17AgfKHYC-ExOLjn4hkmxmOTQdhcY4,1725
+oxarchive/resources/openinterest.py,sha256=whwo60KFNLGwvVrDmDYYc-rMZr35Fcizb5Iil-DSvD8,4553
+oxarchive/resources/orderbook.py,sha256=-paXBdGYBCMX-LK-MeXIKlcFz97iW2UWn9Am2XCgg2U,5717
+oxarchive/resources/trades.py,sha256=t4iicyi1waaHzC7Q_cC-c7O4yVx1vqS4eMH8F8_5hxk,5503
+oxarchive-0.4.0.dist-info/METADATA,sha256=yNo8AmElD6sG8Fb2c3qKf8Tg01CS041-9wnFxWb9CFQ,12397
+oxarchive-0.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oxarchive-0.4.0.dist-info/RECORD,,

oxarchive-0.3.10.dist-info/RECORD

@@ -1,14 +0,0 @@
-oxarchive/__init__.py,sha256=AQVwSQ6yMPb6Dm5mqRyLuM0gk4XvaqffLMTdUaSFhdg,2182
-oxarchive/client.py,sha256=3P0fvOcyM5BWppkVV4054NduDHKvRg-cWeluoGymmRk,3163
-oxarchive/http.py,sha256=SY_o9Ag8ADo1HI3i3uAKW1xwkYjPE75gRAjnMsddAGs,4211
-oxarchive/types.py,sha256=lM3WrATnHcxGs0fLq54Lka-FTvXqiwWe2He2Qn9SrSA,10844
-oxarchive/websocket.py,sha256=MyffJxaabDBonECcJg9vF4hAQ_4thjP4DaS7MaR4uno,28381
-oxarchive/resources/__init__.py,sha256=WQ4GYQ8p3L0D2Isk4IV4h1DRpvyZlt6tOF1t_CJr6ls,385
-oxarchive/resources/funding.py,sha256=TXkZxodVQTVcVbzNG6SpMQAzf8AkLm2NYZJxnP4MNXw,3500
-oxarchive/resources/instruments.py,sha256=flD1sH6x3P3CTqV1ZwkfwbranVacmhsHn5Dhr7lGQhM,1606
-oxarchive/resources/openinterest.py,sha256=h13yLA72LpfryUf8IqF6W7uE4ObYY2Qbc-auv4LtPqc,3552
-oxarchive/resources/orderbook.py,sha256=o_DTdpzKrZvHL9YXm8cGGUugPM8uUa6r9O_72r1ByV0,4557
-oxarchive/resources/trades.py,sha256=XCi2rXA2hxaTt0KNlWw8f7W0hzAvNWyT7DaivMz_rHw,10012
-oxarchive-0.3.10.dist-info/METADATA,sha256=rPdO6lBAEQfApyJFllhU6vcuBEYpj7i3iLyR2-NaP9c,11071
-oxarchive-0.3.10.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-oxarchive-0.3.10.dist-info/RECORD,,