oxarchive 0.6.0__tar.gz → 0.6.1__tar.gz

{oxarchive-0.6.0 → oxarchive-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.6.0
+Version: 0.6.1
 Summary: Official Python SDK for 0xarchive - Hyperliquid Historical Data API
 Project-URL: Homepage, https://0xarchive.io
 Project-URL: Documentation, https://0xarchive.io/docs/sdks
@@ -639,6 +639,43 @@ async def main():
 asyncio.run(main())
 ```
 
+### Gap Detection
+
+During historical replay and bulk streaming, the server automatically detects gaps in the data and notifies the client. This helps identify periods where data may be missing.
+
+```python
+import asyncio
+from oxarchive import OxArchiveWs, WsOptions
+
+async def main():
+    ws = OxArchiveWs(WsOptions(api_key="ox_..."))
+
+    # Handle gap notifications during replay/stream
+    def handle_gap(channel, coin, gap_start, gap_end, duration_minutes):
+        print(f"Gap detected in {channel}/{coin}:")
+        print(f"  From: {gap_start}")
+        print(f"  To: {gap_end}")
+        print(f"  Duration: {duration_minutes} minutes")
+
+    ws.on_gap(handle_gap)
+
+    await ws.connect()
+
+    # Start replay - gaps will be reported via on_gap callback
+    await ws.replay(
+        "orderbook", "BTC",
+        start=int(time.time() * 1000) - 86400000,
+        end=int(time.time() * 1000),
+        speed=10
+    )
+
+asyncio.run(main())
+```
+
+Gap thresholds vary by channel:
+- **orderbook**, **candles**, **liquidations**: 2 minutes
+- **trades**: 60 minutes (trades can naturally have longer gaps during low activity periods)
+
 ### WebSocket Configuration
 
 ```python
@@ -659,6 +696,7 @@ ws = OxArchiveWs(WsOptions(
 | `orderbook` | L2 order book updates | Yes | Yes |
 | `trades` | Trade/fill updates | Yes | Yes |
 | `candles` | OHLCV candle data | Yes | Yes (replay/stream only) |
+| `liquidations` | Liquidation events (May 2025+) | Yes | Yes (replay/stream only) |
 | `ticker` | Price and 24h volume | Yes | Real-time only |
 | `all_tickers` | All market tickers | No | Real-time only |
 

{oxarchive-0.6.0 → oxarchive-0.6.1}/README.md

@@ -602,6 +602,43 @@ async def main():
 asyncio.run(main())
 ```
 
+### Gap Detection
+
+During historical replay and bulk streaming, the server automatically detects gaps in the data and notifies the client. This helps identify periods where data may be missing.
+
+```python
+import asyncio
+from oxarchive import OxArchiveWs, WsOptions
+
+async def main():
+    ws = OxArchiveWs(WsOptions(api_key="ox_..."))
+
+    # Handle gap notifications during replay/stream
+    def handle_gap(channel, coin, gap_start, gap_end, duration_minutes):
+        print(f"Gap detected in {channel}/{coin}:")
+        print(f"  From: {gap_start}")
+        print(f"  To: {gap_end}")
+        print(f"  Duration: {duration_minutes} minutes")
+
+    ws.on_gap(handle_gap)
+
+    await ws.connect()
+
+    # Start replay - gaps will be reported via on_gap callback
+    await ws.replay(
+        "orderbook", "BTC",
+        start=int(time.time() * 1000) - 86400000,
+        end=int(time.time() * 1000),
+        speed=10
+    )
+
+asyncio.run(main())
+```
+
+Gap thresholds vary by channel:
+- **orderbook**, **candles**, **liquidations**: 2 minutes
+- **trades**: 60 minutes (trades can naturally have longer gaps during low activity periods)
+
 ### WebSocket Configuration
 
 ```python
@@ -622,6 +659,7 @@ ws = OxArchiveWs(WsOptions(
 | `orderbook` | L2 order book updates | Yes | Yes |
 | `trades` | Trade/fill updates | Yes | Yes |
 | `candles` | OHLCV candle data | Yes | Yes (replay/stream only) |
+| `liquidations` | Liquidation events (May 2025+) | Yes | Yes (replay/stream only) |
 | `ticker` | Price and 24h volume | Yes | Real-time only |
 | `all_tickers` | All market tickers | No | Real-time only |
 

{oxarchive-0.6.0 → oxarchive-0.6.1}/oxarchive/__init__.py

@@ -68,7 +68,7 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"
 
 __all__ = [
     # Client

{oxarchive-0.6.0 → oxarchive-0.6.1}/oxarchive/types.py

@@ -555,6 +555,24 @@ class WsStreamStopped(BaseModel):
     snapshots_sent: int
 
 
+class WsGapDetected(BaseModel):
+    """Gap detected in historical data stream.
+
+    Sent when there's a gap exceeding the threshold between consecutive data points.
+    Thresholds: 2 minutes for orderbook/candles/liquidations, 60 minutes for trades.
+    """
+
+    type: Literal["gap_detected"]
+    channel: WsChannel
+    coin: str
+    gap_start: int
+    """Start of the gap (last data point timestamp in ms)."""
+    gap_end: int
+    """End of the gap (next data point timestamp in ms)."""
+    duration_minutes: int
+    """Gap duration in minutes."""
+
+
 # =============================================================================
 # Error Types
 # =============================================================================

{oxarchive-0.6.0 → oxarchive-0.6.1}/oxarchive/websocket.py

@@ -64,6 +64,7 @@ from .types import (
     WsHistoricalBatch,
     WsStreamCompleted,
     WsStreamStopped,
+    WsGapDetected,
     TimestampedRecord,
 )
 
@@ -122,6 +123,9 @@ StreamStartHandler = Callable[[WsChannel, str, int, int], None]  # channel, coin
 StreamProgressHandler = Callable[[int], None]  # snapshots_sent
 StreamCompleteHandler = Callable[[WsChannel, str, int], None]  # channel, coin, snapshots_sent
 
+# Gap detection handler
+GapHandler = Callable[[WsChannel, str, int, int, int], None]  # channel, coin, gap_start, gap_end, duration_minutes
+
 
 def _transform_trade(coin: str, raw: dict) -> Trade:
     """Transform raw Hyperliquid trade format to SDK Trade type.
@@ -289,6 +293,9 @@ class OxArchiveWs:
         self._on_stream_progress: Optional[StreamProgressHandler] = None
         self._on_stream_complete: Optional[StreamCompleteHandler] = None
 
+        # Gap detection handler
+        self._on_gap: Optional[GapHandler] = None
+
     @property
     def state(self) -> WsConnectionState:
         """Get current connection state."""
@@ -626,6 +633,23 @@ class OxArchiveWs:
         """
         self._on_stream_complete = handler
 
+    def on_gap(self, handler: GapHandler) -> None:
+        """Set handler for gap detected events during replay or streaming.
+
+        Called when there's a gap in the historical data exceeding the threshold.
+        Thresholds: 2 minutes for orderbook/candles/liquidations, 60 minutes for trades.
+
+        Handler receives: (channel, coin, gap_start, gap_end, duration_minutes)
+
+        Example:
+            >>> def handle_gap(channel, coin, gap_start, gap_end, duration_minutes):
+            ...     print(f"Gap detected in {channel} {coin}: {duration_minutes} minutes")
+            ...     print(f"  From: {datetime.fromtimestamp(gap_start/1000)}")
+            ...     print(f"  To:   {datetime.fromtimestamp(gap_end/1000)}")
+            >>> ws.on_gap(handle_gap)
+        """
+        self._on_gap = handler
+
     # Private methods
 
     async def _send(self, msg: dict) -> None:
@@ -778,6 +802,16 @@ class OxArchiveWs:
             elif msg_type == "stream_completed" and self._on_stream_complete:
                 self._on_stream_complete(data["channel"], data["coin"], data["snapshots_sent"])
 
+            # Gap detection
+            elif msg_type == "gap_detected" and self._on_gap:
+                self._on_gap(
+                    data["channel"],
+                    data["coin"],
+                    data["gap_start"],
+                    data["gap_end"],
+                    data["duration_minutes"],
+                )
+
         except Exception as e:
             logger.error(f"Error handling message: {e}")
 

{oxarchive-0.6.0 → oxarchive-0.6.1}/pyproject.toml

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