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

oxarchive/__init__.py

@@ -1,26 +1,34 @@
 """
 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 .resources.orderbook import LighterGranularity
 from .types import (
     OrderBook,
     Trade,
     Instrument,
+    LighterInstrument,
     FundingRate,
     OpenInterest,
     OxArchiveError,
@@ -57,11 +65,14 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.3.6"
+__version__ = "0.4.5"
 
 __all__ = [
     # Client
     "Client",
+    # Exchange Clients
+    "HyperliquidClient",
+    "LighterClient",
     # WebSocket Client
     "OxArchiveWs",
     "WsOptions",
@@ -69,6 +80,8 @@ __all__ = [
     "OrderBook",
     "Trade",
     "Instrument",
+    "LighterInstrument",
+    "LighterGranularity",
     "FundingRate",
     "OpenInterest",
     "OxArchiveError",

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 (August 2025+)"""
+
+        # 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,79 @@
+"""Exchange-specific client classes."""
+
+from __future__ import annotations
+
+from .http import HttpClient
+from .resources import (
+    OrderBookResource,
+    TradesResource,
+    InstrumentsResource,
+    LighterInstrumentsResource,
+    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.
+
+    Example:
+        >>> client = oxarchive.Client(api_key="...")
+        >>> orderbook = client.lighter.orderbook.get("BTC")
+        >>> trades = client.lighter.trades.list("ETH", start=..., end=...)
+        >>> instruments = client.lighter.instruments.list()
+        >>> print(f"ETH taker fee: {instruments[0].taker_fee}")
+    """
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+        base_path = "/v1/lighter"
+
+        self.orderbook = OrderBookResource(http, base_path)
+        """Order book data (L2 snapshots)"""
+
+        self.trades = TradesResource(http, base_path)
+        """Trade/fill history"""
+
+        self.instruments = LighterInstrumentsResource(http, base_path)
+        """Trading instruments metadata (returns LighterInstrument with fees, min amounts, etc.)"""
+
+        self.funding = FundingResource(http, base_path)
+        """Funding rates"""
+
+        self.open_interest = OpenInterestResource(http, base_path)
+        """Open interest"""

oxarchive/resources/__init__.py

@@ -2,7 +2,7 @@
 
 from .orderbook import OrderBookResource
 from .trades import TradesResource
-from .instruments import InstrumentsResource
+from .instruments import InstrumentsResource, LighterInstrumentsResource
 from .funding import FundingResource
 from .openinterest import OpenInterestResource
 
@@ -10,6 +10,7 @@ __all__ = [
     "OrderBookResource",
     "TradesResource",
     "InstrumentsResource",
+    "LighterInstrumentsResource",
     "FundingResource",
     "OpenInterestResource",
 ]

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

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from ..http import HttpClient
-from ..types import Instrument
+from ..types import Instrument, LighterInstrument
 
 
 class InstrumentsResource:
@@ -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,64 @@ 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"])
+
+
+class LighterInstrumentsResource:
+    """
+    Lighter.xyz Instruments API resource.
+
+    Lighter instruments have a different schema than Hyperliquid with more
+    detailed market configuration including fees and minimum amounts.
+
+    Example:
+        >>> # List all Lighter instruments
+        >>> instruments = client.lighter.instruments.list()
+        >>>
+        >>> # Get specific instrument
+        >>> btc = client.lighter.instruments.get("BTC")
+        >>> print(f"Taker fee: {btc.taker_fee}")
+    """
+
+    def __init__(self, http: HttpClient, base_path: str = "/v1/lighter"):
+        self._http = http
+        self._base_path = base_path
+
+    def list(self) -> list[LighterInstrument]:
+        """
+        List all available Lighter trading instruments.
+
+        Returns:
+            List of Lighter instruments with full market configuration
+        """
+        data = self._http.get(f"{self._base_path}/instruments")
+        return [LighterInstrument.model_validate(item) for item in data["data"]]
+
+    async def alist(self) -> list[LighterInstrument]:
+        """Async version of list()."""
+        data = await self._http.aget(f"{self._base_path}/instruments")
+        return [LighterInstrument.model_validate(item) for item in data["data"]]
+
+    def get(self, coin: str) -> LighterInstrument:
+        """
+        Get a specific Lighter instrument by coin symbol.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+
+        Returns:
+            Lighter instrument details with full market configuration
+        """
+        data = self._http.get(f"{self._base_path}/instruments/{coin.upper()}")
+        return LighterInstrument.model_validate(data["data"])
+
+    async def aget(self, coin: str) -> LighterInstrument:
+        """Async version of get()."""
+        data = await self._http.aget(f"{self._base_path}/instruments/{coin.upper()}")
+        return LighterInstrument.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"])