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

oxarchive/__init__.py

@@ -65,7 +65,7 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.4.4"
+__version__ = "0.4.6"
 
 __all__ = [
     # Client

oxarchive/types.py

@@ -382,6 +382,41 @@ class WsHistoricalData(BaseModel):
     data: dict[str, Any]
 
 
+class OrderbookDelta(BaseModel):
+    """Orderbook delta for tick-level data."""
+
+    timestamp: int
+    """Timestamp in milliseconds."""
+
+    side: Literal["bid", "ask"]
+    """Side: 'bid' or 'ask'."""
+
+    price: float
+    """Price level."""
+
+    size: float
+    """New size (0 = level removed)."""
+
+    sequence: int
+    """Sequence number for ordering."""
+
+
+class WsHistoricalTickData(BaseModel):
+    """Historical tick data (granularity='tick' mode) - checkpoint + deltas.
+
+    This message type is sent when using granularity='tick' for Lighter.xyz
+    orderbook data. It provides a full checkpoint followed by incremental deltas.
+    """
+
+    type: Literal["historical_tick_data"]
+    channel: WsChannel
+    coin: str
+    checkpoint: dict[str, Any]
+    """Initial checkpoint (full orderbook snapshot)."""
+    deltas: list[OrderbookDelta]
+    """Incremental deltas to apply after checkpoint."""
+
+
 # =============================================================================
 # WebSocket Bulk Stream Types (Bulk Download Mode)
 # =============================================================================

oxarchive/websocket.py

@@ -42,6 +42,7 @@ except ImportError:
 
 from .types import (
     OrderBook,
+    OrderbookDelta,
     PriceLevel,
     Trade,
     WsChannel,
@@ -57,6 +58,7 @@ from .types import (
     WsReplayCompleted,
     WsReplayStopped,
     WsHistoricalData,
+    WsHistoricalTickData,
     WsStreamStarted,
     WsStreamProgress,
     WsHistoricalBatch,
@@ -110,6 +112,7 @@ ErrorHandler = Callable[[Exception], None]
 
 # Replay handlers
 HistoricalDataHandler = Callable[[str, int, dict], None]
+HistoricalTickDataHandler = Callable[[str, dict, list[OrderbookDelta]], None]  # coin, checkpoint, deltas
 ReplayStartHandler = Callable[[WsChannel, str, int, int, float], None]  # channel, coin, start, end, speed
 ReplayCompleteHandler = Callable[[WsChannel, str, int], None]  # channel, coin, snapshots_sent
 
@@ -276,6 +279,7 @@ class OxArchiveWs:
 
         # Replay handlers (Option B)
         self._on_historical_data: Optional[HistoricalDataHandler] = None
+        self._on_historical_tick_data: Optional[HistoricalTickDataHandler] = None
         self._on_replay_start: Optional[ReplayStartHandler] = None
         self._on_replay_complete: Optional[ReplayCompleteHandler] = None
 
@@ -307,7 +311,9 @@ class OxArchiveWs:
         url = f"{self.options.ws_url}?apiKey={self.options.api_key}"
 
         try:
-            self._ws = await ws_connect(url)
+            # Increase max_size to 50MB for large Lighter orderbook data with high granularity
+            # Lighter tick data with full depth (~3700 levels) can exceed 14MB per message
+            self._ws = await ws_connect(url, max_size=50 * 1024 * 1024)
             self._reconnect_attempts = 0
             self._set_state("connected")
 
@@ -427,6 +433,7 @@ class OxArchiveWs:
         start: int,
         end: Optional[int] = None,
         speed: float = 1.0,
+        granularity: Optional[str] = None,
     ) -> None:
         """Start historical replay with timing preserved.
 
@@ -436,6 +443,7 @@ class OxArchiveWs:
             start: Start timestamp (Unix ms)
             end: End timestamp (Unix ms, defaults to now)
             speed: Playback speed multiplier (1 = real-time, 10 = 10x faster)
+            granularity: Data resolution for Lighter orderbook ('checkpoint', '30s', '10s', '1s', 'tick')
 
         Example:
             >>> await ws.replay("orderbook", "BTC", start=time.time()*1000 - 86400000, speed=10)
@@ -449,6 +457,8 @@ class OxArchiveWs:
         }
         if end is not None:
             msg["end"] = end
+        if granularity is not None:
+            msg["granularity"] = granularity
         await self._send(msg)
 
     async def replay_pause(self) -> None:
@@ -482,6 +492,7 @@ class OxArchiveWs:
         start: int,
         end: int,
         batch_size: int = 1000,
+        granularity: Optional[str] = None,
     ) -> None:
         """Start bulk streaming for fast data download.
 
@@ -491,18 +502,22 @@ class OxArchiveWs:
             start: Start timestamp (Unix ms)
             end: End timestamp (Unix ms)
             batch_size: Records per batch message
+            granularity: Data resolution for Lighter orderbook ('checkpoint', '30s', '10s', '1s', 'tick')
 
         Example:
             >>> await ws.stream("orderbook", "ETH", start=..., end=..., batch_size=1000)
         """
-        await self._send({
+        msg = {
             "op": "stream",
             "channel": channel,
             "coin": coin,
             "start": start,
             "end": end,
             "batch_size": batch_size,
-        })
+        }
+        if granularity is not None:
+            msg["granularity"] = granularity
+        await self._send(msg)
 
     async def stream_stop(self) -> None:
         """Stop the current bulk stream."""
@@ -547,6 +562,16 @@ class OxArchiveWs:
         """
         self._on_historical_data = handler
 
+    def on_historical_tick_data(self, handler: HistoricalTickDataHandler) -> None:
+        """Set handler for historical tick data (granularity='tick' mode).
+
+        This is for tick-level granularity on Lighter.xyz orderbook data.
+        Receives a checkpoint (full orderbook) followed by incremental deltas.
+
+        Handler receives: (coin, checkpoint, deltas)
+        """
+        self._on_historical_tick_data = handler
+
     def on_replay_start(self, handler: ReplayStartHandler) -> None:
         """Set handler for replay started event.
 
@@ -722,6 +747,10 @@ class OxArchiveWs:
             elif msg_type == "historical_data" and self._on_historical_data:
                 self._on_historical_data(data["coin"], data["timestamp"], data["data"])
 
+            elif msg_type == "historical_tick_data" and self._on_historical_tick_data:
+                msg = WsHistoricalTickData(**data)
+                self._on_historical_tick_data(msg.coin, msg.checkpoint, msg.deltas)
+
             elif msg_type == "replay_completed" and self._on_replay_complete:
                 self._on_replay_complete(data["channel"], data["coin"], data["snapshots_sent"])
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.4.4
+Version: 0.4.6
 Summary: Official Python SDK for 0xarchive - Hyperliquid Historical Data API
 Project-URL: Homepage, https://0xarchive.io
 Project-URL: Documentation, https://0xarchive.io/docs/sdks
@@ -418,6 +418,19 @@ async def main():
         speed=10                                     # Optional, defaults to 1x
     )
 
+    # Lighter.xyz replay with granularity (tier restrictions apply)
+    await ws.replay(
+        "orderbook", "BTC",
+        start=int(time.time() * 1000) - 86400000,
+        speed=10,
+        granularity="10s"  # Options: 'checkpoint', '30s', '10s', '1s', 'tick'
+    )
+
+    # Handle tick-level data (granularity='tick', Enterprise tier)
+    ws.on_historical_tick_data(lambda coin, checkpoint, deltas:
+        print(f"Checkpoint: {len(checkpoint['bids'])} bids, Deltas: {len(deltas)}")
+    )
+
     # Control playback
     await ws.replay_pause()
     await ws.replay_resume()
@@ -463,6 +476,14 @@ async def main():
         batch_size=1000                            # Optional, defaults to 1000
     )
 
+    # Lighter.xyz stream with granularity (tier restrictions apply)
+    await ws.stream(
+        "orderbook", "BTC",
+        start=int(time.time() * 1000) - 3600000,
+        end=int(time.time() * 1000),
+        granularity="10s"  # Options: 'checkpoint', '30s', '10s', '1s', 'tick'
+    )
+
     # Stop if needed
     await ws.stream_stop()
 

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

@@ -1,15 +1,15 @@
-oxarchive/__init__.py,sha256=MFsShbQ6sAPBaf_Vn9azR-CydWUSK6w8S92on1oNl7Q,2666
+oxarchive/__init__.py,sha256=z02RMa5pktqkvB4hOuzdeASD5j-qUUYebmkHL5UHSeE,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
-oxarchive/types.py,sha256=hszHQVTxh2gRKvSzRANQ3d8sosPfPerKwF7QTK8p1a4,12443
-oxarchive/websocket.py,sha256=MyffJxaabDBonECcJg9vF4hAQ_4thjP4DaS7MaR4uno,28381
+oxarchive/types.py,sha256=YHy04TYtuEmJSHDMRh_9D9MVnhnXVc2rGagc45LwPiQ,13380
+oxarchive/websocket.py,sha256=sdKMJrmGeR_ApNP_c7TPJylc4DAkmrp1JXfpnRGynao,29985
 oxarchive/resources/__init__.py,sha256=ZGS3rLOfQFD665oJYMia_MxfTWlal7MXtx874DLG5EE,448
 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=NzgKH45MBb2oAHyPmy6BSikaYyq0nM-8GFjur9LIRN8,6661
 oxarchive/resources/trades.py,sha256=t4iicyi1waaHzC7Q_cC-c7O4yVx1vqS4eMH8F8_5hxk,5503
-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,,
+oxarchive-0.4.6.dist-info/METADATA,sha256=NUz-9REdplj8blQwCyS95rTiEaiNs6qGiJW4J6HFtWU,15945
+oxarchive-0.4.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oxarchive-0.4.6.dist-info/RECORD,,