oxarchive 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

oxarchive/__init__.py

@@ -23,6 +23,7 @@ Example:
 
 from .client import Client
 from .exchanges import HyperliquidClient, LighterClient
+from .resources.orderbook import LighterGranularity
 from .types import (
     OrderBook,
     Trade,
@@ -64,7 +65,7 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.4.2"
+__version__ = "0.4.4"
 
 __all__ = [
     # Client
@@ -80,6 +81,7 @@ __all__ = [
     "Trade",
     "Instrument",
     "LighterInstrument",
+    "LighterGranularity",
     "FundingRate",
     "OpenInterest",
     "OxArchiveError",

oxarchive/resources/orderbook.py

@@ -6,8 +6,13 @@ from datetime import datetime
 from typing import Optional, Union
 
 from ..http import HttpClient
+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:
     """
@@ -101,6 +106,7 @@ class OrderBookResource:
         cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
         depth: Optional[int] = None,
+        granularity: Optional[LighterGranularity] = None,
     ) -> CursorResponse[list[OrderBook]]:
         """
         Get historical order book snapshots with cursor-based pagination.
@@ -112,6 +118,9 @@ class OrderBookResource:
             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:
             CursorResponse with order book snapshots and next_cursor for pagination
@@ -124,6 +133,11 @@ class OrderBookResource:
             ...         "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"{self._base_path}/orderbook/{coin.upper()}/history",
@@ -133,6 +147,7 @@ class OrderBookResource:
                 "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
                 "depth": depth,
+                "granularity": granularity,
             },
         )
         return CursorResponse(
@@ -149,8 +164,9 @@ class OrderBookResource:
         cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
         depth: Optional[int] = None,
+        granularity: Optional[LighterGranularity] = None,
     ) -> CursorResponse[list[OrderBook]]:
-        """Async version of history(). start and end are required."""
+        """Async version of history(). start and end are required. See history() for granularity details."""
         data = await self._http.aget(
             f"{self._base_path}/orderbook/{coin.upper()}/history",
             params={
@@ -159,6 +175,7 @@ class OrderBookResource:
                 "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
                 "depth": depth,
+                "granularity": granularity,
             },
         )
         return CursorResponse(

{oxarchive-0.4.2.dist-info → oxarchive-0.4.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.4.2
+Version: 0.4.4
 Summary: Official Python SDK for 0xarchive - Hyperliquid Historical Data API
 Project-URL: Homepage, https://0xarchive.io
 Project-URL: Documentation, https://0xarchive.io/docs/sdks
@@ -153,6 +153,59 @@ orderbook = await client.hyperliquid.orderbook.aget("BTC")
 history = await client.hyperliquid.orderbook.ahistory("BTC", start=..., end=...)
 ```
 
+#### Orderbook Depth Limits
+
+The `depth` parameter controls how many price levels are returned per side. Tier-based limits apply:
+
+| Tier | Max Depth |
+|------|-----------|
+| Free | 20 |
+| Build | 50 |
+| Pro | 100 |
+| Enterprise | Full Depth |
+
+**Note:** Hyperliquid source data only contains 20 levels. Higher limits apply to Lighter.xyz data.
+
+#### Lighter Orderbook Granularity
+
+Lighter.xyz orderbook history supports a `granularity` parameter for different data resolutions. Tier restrictions apply.
+
+| Granularity | Interval | Tier Required | Credit Multiplier |
+|-------------|----------|---------------|-------------------|
+| `checkpoint` | ~60s | Free+ | 1x |
+| `30s` | 30s | Build+ | 2x |
+| `10s` | 10s | Build+ | 3x |
+| `1s` | 1s | Pro+ | 10x |
+| `tick` | tick-level | Enterprise | 20x |
+
+```python
+# Get Lighter orderbook history with 10s resolution (Build+ tier)
+history = client.lighter.orderbook.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    granularity="10s"
+)
+
+# Get 1-second resolution (Pro+ tier)
+history = client.lighter.orderbook.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    granularity="1s"
+)
+
+# Tick-level data (Enterprise tier) - returns checkpoint + raw deltas
+history = client.lighter.orderbook.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    granularity="tick"
+)
+```
+
+**Note:** The `granularity` parameter is ignored for Hyperliquid orderbook history.
+
 ### Trades
 
 The trades API uses cursor-based pagination for efficient retrieval of large datasets.
@@ -479,7 +532,7 @@ except OxArchiveError as e:
 Full type hint support with Pydantic models:
 
 ```python
-from oxarchive import Client
+from oxarchive import Client, LighterGranularity
 from oxarchive.types import OrderBook, Trade, Instrument, LighterInstrument, FundingRate, OpenInterest
 from oxarchive.resources.trades import CursorResponse
 
@@ -488,6 +541,9 @@ client = Client(api_key="ox_your_api_key")
 orderbook: OrderBook = client.orderbook.get("BTC")
 trades: list[Trade] = client.trades.recent("BTC")
 result: CursorResponse = client.trades.list("BTC", start=..., end=...)
+
+# Lighter granularity type hint
+granularity: LighterGranularity = "10s"
 ```
 
 ## Requirements

{oxarchive-0.4.2.dist-info → oxarchive-0.4.4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-oxarchive/__init__.py,sha256=6yC9nqGCEj0sxWPUpZaf1XR4ux7Iry3K2rZ0Z1jw3qg,2586
+oxarchive/__init__.py,sha256=MFsShbQ6sAPBaf_Vn9azR-CydWUSK6w8S92on1oNl7Q,2666
 oxarchive/client.py,sha256=XWQ_VEBQy3UIAnmZQ-Z_FyzXnvMA3FITwtinBOf3o-Y,4453
 oxarchive/exchanges.py,sha256=kk--Uh4g1U_tPfhJhYtZD_1zR6tJS5D-iaPnOGwWa9c,2425
 oxarchive/http.py,sha256=SY_o9Ag8ADo1HI3i3uAKW1xwkYjPE75gRAjnMsddAGs,4211
@@ -8,8 +8,8 @@ oxarchive/resources/__init__.py,sha256=ZGS3rLOfQFD665oJYMia_MxfTWlal7MXtx874DLG5
 oxarchive/resources/funding.py,sha256=ybMWkpoccrkdwnd6W3oHgsaor7cBcA2nkYy4CbjmHUg,4485
 oxarchive/resources/instruments.py,sha256=6q7rMdIaixXgFVXgwQsVd-YuO7RIXr1oGPT5jBsqI9A,3733
 oxarchive/resources/openinterest.py,sha256=whwo60KFNLGwvVrDmDYYc-rMZr35Fcizb5Iil-DSvD8,4553
-oxarchive/resources/orderbook.py,sha256=-paXBdGYBCMX-LK-MeXIKlcFz97iW2UWn9Am2XCgg2U,5717
+oxarchive/resources/orderbook.py,sha256=NzgKH45MBb2oAHyPmy6BSikaYyq0nM-8GFjur9LIRN8,6661
 oxarchive/resources/trades.py,sha256=t4iicyi1waaHzC7Q_cC-c7O4yVx1vqS4eMH8F8_5hxk,5503
-oxarchive-0.4.2.dist-info/METADATA,sha256=7WMhogTWSSHLw5wleZTw1ZCpM04Qe0OfXUIxcAJAJXg,13620
-oxarchive-0.4.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-oxarchive-0.4.2.dist-info/RECORD,,
+oxarchive-0.4.4.dist-info/METADATA,sha256=wcgN_17HlgSwtcayWuMLoDTfzU_ofwbgr0uWivhfDEo,15163
+oxarchive-0.4.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oxarchive-0.4.4.dist-info/RECORD,,