oxarchive 0.4.2__tar.gz → 0.4.3__tar.gz

{oxarchive-0.4.2 → oxarchive-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.4.2
+Version: 0.4.3
 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,46 @@ orderbook = await client.hyperliquid.orderbook.aget("BTC")
 history = await client.hyperliquid.orderbook.ahistory("BTC", start=..., end=...)
 ```
 
+#### 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 +519,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 +528,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 → oxarchive-0.4.3}/README.md

@@ -116,6 +116,46 @@ orderbook = await client.hyperliquid.orderbook.aget("BTC")
 history = await client.hyperliquid.orderbook.ahistory("BTC", start=..., end=...)
 ```
 
+#### 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.
@@ -442,7 +482,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
 
@@ -451,6 +491,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 → oxarchive-0.4.3}/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.3"
 
 __all__ = [
     # Client
@@ -80,6 +81,7 @@ __all__ = [
     "Trade",
     "Instrument",
     "LighterInstrument",
+    "LighterGranularity",
     "FundingRate",
     "OpenInterest",
     "OxArchiveError",

{oxarchive-0.4.2 → oxarchive-0.4.3}/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 → oxarchive-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oxarchive"
-version = "0.4.2"
+version = "0.4.3"
 description = "Official Python SDK for 0xarchive - Hyperliquid Historical Data API"
 readme = "README.md"
 license = "MIT"