oxarchive 0.5.4__tar.gz → 0.6.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.5.4
+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
@@ -406,6 +406,66 @@ candles = await client.hyperliquid.candles.ahistory("BTC", start=..., end=..., i
 | `1d` | 1 day |
 | `1w` | 1 week |
 
+### Data Quality Monitoring
+
+Monitor data coverage, incidents, latency, and SLA compliance across all exchanges.
+
+```python
+# Get overall system health status
+status = client.data_quality.status()
+print(f"System status: {status.status}")
+for exchange, info in status.exchanges.items():
+    print(f"  {exchange}: {info.status}")
+
+# Get data coverage summary for all exchanges
+coverage = client.data_quality.coverage()
+for exchange in coverage.exchanges:
+    print(f"{exchange.exchange}:")
+    for dtype, info in exchange.data_types.items():
+        print(f"  {dtype}: {info.total_records:,} records, {info.completeness}% complete")
+
+# Get symbol-specific coverage with gap detection
+btc = client.data_quality.symbol_coverage("hyperliquid", "BTC")
+oi = btc.data_types["open_interest"]
+print(f"BTC OI completeness: {oi.completeness}%")
+print(f"Gaps found: {len(oi.gaps)}")
+for gap in oi.gaps[:5]:
+    print(f"  {gap.duration_minutes} min gap: {gap.start} -> {gap.end}")
+
+# List incidents with filtering
+result = client.data_quality.list_incidents(status="open")
+for incident in result.incidents:
+    print(f"[{incident.severity}] {incident.title}")
+
+# Get latency metrics
+latency = client.data_quality.latency()
+for exchange, metrics in latency.exchanges.items():
+    print(f"{exchange}: OB lag {metrics.data_freshness.orderbook_lag_ms}ms")
+
+# Get SLA compliance metrics for a specific month
+sla = client.data_quality.sla(year=2026, month=1)
+print(f"Period: {sla.period}")
+print(f"Uptime: {sla.actual.uptime}% ({sla.actual.uptime_status})")
+print(f"API P99: {sla.actual.api_latency_p99_ms}ms ({sla.actual.latency_status})")
+
+# Async versions available for all methods
+status = await client.data_quality.astatus()
+coverage = await client.data_quality.acoverage()
+```
+
+#### Data Quality Endpoints
+
+| Method | Description |
+|--------|-------------|
+| `status()` | Overall system health and per-exchange status |
+| `coverage()` | Data coverage summary for all exchanges |
+| `exchange_coverage(exchange)` | Coverage details for a specific exchange |
+| `symbol_coverage(exchange, symbol)` | Coverage with gap detection for specific symbol |
+| `list_incidents(...)` | List incidents with filtering and pagination |
+| `get_incident(incident_id)` | Get specific incident details |
+| `latency()` | Current latency metrics (WebSocket, REST, data freshness) |
+| `sla(year, month)` | SLA compliance metrics for a specific month |
+
 ### Legacy API (Deprecated)
 
 The following legacy methods are deprecated and will be removed in v2.0. They default to Hyperliquid data:
@@ -579,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
@@ -599,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.5.4 → oxarchive-0.6.1}/README.md

@@ -369,6 +369,66 @@ candles = await client.hyperliquid.candles.ahistory("BTC", start=..., end=..., i
 | `1d` | 1 day |
 | `1w` | 1 week |
 
+### Data Quality Monitoring
+
+Monitor data coverage, incidents, latency, and SLA compliance across all exchanges.
+
+```python
+# Get overall system health status
+status = client.data_quality.status()
+print(f"System status: {status.status}")
+for exchange, info in status.exchanges.items():
+    print(f"  {exchange}: {info.status}")
+
+# Get data coverage summary for all exchanges
+coverage = client.data_quality.coverage()
+for exchange in coverage.exchanges:
+    print(f"{exchange.exchange}:")
+    for dtype, info in exchange.data_types.items():
+        print(f"  {dtype}: {info.total_records:,} records, {info.completeness}% complete")
+
+# Get symbol-specific coverage with gap detection
+btc = client.data_quality.symbol_coverage("hyperliquid", "BTC")
+oi = btc.data_types["open_interest"]
+print(f"BTC OI completeness: {oi.completeness}%")
+print(f"Gaps found: {len(oi.gaps)}")
+for gap in oi.gaps[:5]:
+    print(f"  {gap.duration_minutes} min gap: {gap.start} -> {gap.end}")
+
+# List incidents with filtering
+result = client.data_quality.list_incidents(status="open")
+for incident in result.incidents:
+    print(f"[{incident.severity}] {incident.title}")
+
+# Get latency metrics
+latency = client.data_quality.latency()
+for exchange, metrics in latency.exchanges.items():
+    print(f"{exchange}: OB lag {metrics.data_freshness.orderbook_lag_ms}ms")
+
+# Get SLA compliance metrics for a specific month
+sla = client.data_quality.sla(year=2026, month=1)
+print(f"Period: {sla.period}")
+print(f"Uptime: {sla.actual.uptime}% ({sla.actual.uptime_status})")
+print(f"API P99: {sla.actual.api_latency_p99_ms}ms ({sla.actual.latency_status})")
+
+# Async versions available for all methods
+status = await client.data_quality.astatus()
+coverage = await client.data_quality.acoverage()
+```
+
+#### Data Quality Endpoints
+
+| Method | Description |
+|--------|-------------|
+| `status()` | Overall system health and per-exchange status |
+| `coverage()` | Data coverage summary for all exchanges |
+| `exchange_coverage(exchange)` | Coverage details for a specific exchange |
+| `symbol_coverage(exchange, symbol)` | Coverage with gap detection for specific symbol |
+| `list_incidents(...)` | List incidents with filtering and pagination |
+| `get_incident(incident_id)` | Get specific incident details |
+| `latency()` | Current latency metrics (WebSocket, REST, data freshness) |
+| `sla(year, month)` | SLA compliance metrics for a specific month |
+
 ### Legacy API (Deprecated)
 
 The following legacy methods are deprecated and will be removed in v2.0. They default to Hyperliquid data:
@@ -542,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
@@ -562,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.5.4 → oxarchive-0.6.1}/oxarchive/__init__.py

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

{oxarchive-0.5.4 → oxarchive-0.6.1}/oxarchive/client.py

@@ -12,6 +12,7 @@ from .resources import (
     InstrumentsResource,
     FundingResource,
     OpenInterestResource,
+    DataQualityResource,
 )
 
 DEFAULT_BASE_URL = "https://api.0xarchive.io"
@@ -92,6 +93,10 @@ class Client:
         self.lighter = LighterClient(self._http)
         """Lighter.xyz exchange data (August 2025+)"""
 
+        # Data quality monitoring (cross-exchange)
+        self.data_quality = DataQualityResource(self._http)
+        """Data quality metrics: status, coverage, incidents, latency, SLA"""
+
         # Legacy resource namespaces (deprecated - use client.hyperliquid.* instead)
         # These will be removed in v2.0
         # Note: Using /v1/hyperliquid base path for backward compatibility

{oxarchive-0.5.4 → oxarchive-0.6.1}/oxarchive/resources/__init__.py

@@ -7,6 +7,7 @@ from .funding import FundingResource
 from .openinterest import OpenInterestResource
 from .candles import CandlesResource
 from .liquidations import LiquidationsResource
+from .data_quality import DataQualityResource
 
 __all__ = [
     "OrderBookResource",
@@ -17,4 +18,5 @@ __all__ = [
     "OpenInterestResource",
     "CandlesResource",
     "LiquidationsResource",
+    "DataQualityResource",
 ]

oxarchive-0.6.1/oxarchive/resources/data_quality.py

@@ -0,0 +1,336 @@
+"""Data quality API resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from ..http import HttpClient
+from ..types import (
+    CoverageResponse,
+    ExchangeCoverage,
+    Incident,
+    IncidentsResponse,
+    LatencyResponse,
+    SlaResponse,
+    StatusResponse,
+    SymbolCoverageResponse,
+    Timestamp,
+)
+
+
+class DataQualityResource:
+    """
+    Data quality API resource.
+
+    Provides endpoints for monitoring data quality, coverage, incidents, and SLA metrics.
+
+    Example:
+        >>> # Get system status
+        >>> status = client.data_quality.status()
+        >>> print(f"System status: {status.status}")
+        >>>
+        >>> # Get coverage for all exchanges
+        >>> coverage = client.data_quality.coverage()
+        >>>
+        >>> # Get symbol-specific coverage with gap detection
+        >>> btc = client.data_quality.symbol_coverage("hyperliquid", "BTC")
+        >>> print(f"BTC completeness: {btc.data_types['orderbook'].completeness}%")
+        >>> for gap in btc.data_types['orderbook'].gaps[:5]:
+        ...     print(f"Gap: {gap.start} - {gap.end} ({gap.duration_minutes} min)")
+    """
+
+    def __init__(self, http: HttpClient, base_path: str = "/v1/data-quality"):
+        self._http = http
+        self._base_path = base_path
+
+    def _convert_timestamp(self, ts: Optional[Timestamp]) -> Optional[int]:
+        """Convert timestamp to Unix milliseconds."""
+        if ts is None:
+            return None
+        if isinstance(ts, int):
+            return ts
+        if isinstance(ts, datetime):
+            return int(ts.timestamp() * 1000)
+        if isinstance(ts, str):
+            try:
+                dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+                return int(dt.timestamp() * 1000)
+            except ValueError:
+                return int(ts)
+        return None
+
+    # =========================================================================
+    # Status Endpoints
+    # =========================================================================
+
+    def status(self) -> StatusResponse:
+        """
+        Get overall system health status.
+
+        Returns:
+            StatusResponse with overall status, per-exchange status,
+            per-data-type status, and active incident count.
+
+        Example:
+            >>> status = client.data_quality.status()
+            >>> print(f"Overall: {status.status}")
+            >>> for exchange, info in status.exchanges.items():
+            ...     print(f"{exchange}: {info.status}")
+        """
+        data = self._http.get(f"{self._base_path}/status")
+        return StatusResponse.model_validate(data)
+
+    async def astatus(self) -> StatusResponse:
+        """Async version of status()."""
+        data = await self._http.aget(f"{self._base_path}/status")
+        return StatusResponse.model_validate(data)
+
+    # =========================================================================
+    # Coverage Endpoints
+    # =========================================================================
+
+    def coverage(self) -> CoverageResponse:
+        """
+        Get data coverage summary for all exchanges.
+
+        Returns:
+            CoverageResponse with coverage info for all exchanges and data types.
+
+        Example:
+            >>> coverage = client.data_quality.coverage()
+            >>> for exchange in coverage.exchanges:
+            ...     print(f"{exchange.exchange}:")
+            ...     for dtype, info in exchange.data_types.items():
+            ...         print(f"  {dtype}: {info.total_records} records")
+        """
+        data = self._http.get(f"{self._base_path}/coverage")
+        return CoverageResponse.model_validate(data)
+
+    async def acoverage(self) -> CoverageResponse:
+        """Async version of coverage()."""
+        data = await self._http.aget(f"{self._base_path}/coverage")
+        return CoverageResponse.model_validate(data)
+
+    def exchange_coverage(self, exchange: str) -> ExchangeCoverage:
+        """
+        Get data coverage for a specific exchange.
+
+        Args:
+            exchange: Exchange name ('hyperliquid' or 'lighter')
+
+        Returns:
+            ExchangeCoverage with coverage info for all data types on this exchange.
+
+        Example:
+            >>> hl = client.data_quality.exchange_coverage("hyperliquid")
+            >>> print(f"Orderbook earliest: {hl.data_types['orderbook'].earliest}")
+        """
+        data = self._http.get(f"{self._base_path}/coverage/{exchange.lower()}")
+        return ExchangeCoverage.model_validate(data)
+
+    async def aexchange_coverage(self, exchange: str) -> ExchangeCoverage:
+        """Async version of exchange_coverage()."""
+        data = await self._http.aget(f"{self._base_path}/coverage/{exchange.lower()}")
+        return ExchangeCoverage.model_validate(data)
+
+    def symbol_coverage(self, exchange: str, symbol: str) -> SymbolCoverageResponse:
+        """
+        Get data coverage for a specific symbol on an exchange.
+
+        Includes gap detection showing periods where data may be missing.
+
+        Args:
+            exchange: Exchange name ('hyperliquid' or 'lighter')
+            symbol: Symbol name (e.g., 'BTC', 'ETH')
+
+        Returns:
+            SymbolCoverageResponse with per-data-type coverage including gaps.
+
+        Example:
+            >>> btc = client.data_quality.symbol_coverage("hyperliquid", "BTC")
+            >>> oi = btc.data_types["open_interest"]
+            >>> print(f"OI completeness: {oi.completeness}%")
+            >>> print(f"Gaps found: {len(oi.gaps)}")
+            >>> for gap in oi.gaps[:3]:
+            ...     print(f"  {gap.duration_minutes} min gap at {gap.start}")
+        """
+        data = self._http.get(
+            f"{self._base_path}/coverage/{exchange.lower()}/{symbol.upper()}"
+        )
+        return SymbolCoverageResponse.model_validate(data)
+
+    async def asymbol_coverage(self, exchange: str, symbol: str) -> SymbolCoverageResponse:
+        """Async version of symbol_coverage()."""
+        data = await self._http.aget(
+            f"{self._base_path}/coverage/{exchange.lower()}/{symbol.upper()}"
+        )
+        return SymbolCoverageResponse.model_validate(data)
+
+    # =========================================================================
+    # Incidents Endpoints
+    # =========================================================================
+
+    def list_incidents(
+        self,
+        *,
+        status: Optional[Literal["open", "investigating", "identified", "monitoring", "resolved"]] = None,
+        exchange: Optional[str] = None,
+        since: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> IncidentsResponse:
+        """
+        List incidents with filtering and pagination.
+
+        Args:
+            status: Filter by incident status
+            exchange: Filter by exchange
+            since: Only show incidents starting after this timestamp
+            limit: Maximum results per page (default: 20, max: 100)
+            offset: Pagination offset
+
+        Returns:
+            IncidentsResponse with list of incidents and pagination info.
+
+        Example:
+            >>> # Get all open incidents
+            >>> result = client.data_quality.list_incidents(status="open")
+            >>> for incident in result.incidents:
+            ...     print(f"{incident.severity}: {incident.title}")
+        """
+        data = self._http.get(
+            f"{self._base_path}/incidents",
+            params={
+                "status": status,
+                "exchange": exchange,
+                "since": self._convert_timestamp(since),
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+        return IncidentsResponse.model_validate(data)
+
+    async def alist_incidents(
+        self,
+        *,
+        status: Optional[Literal["open", "investigating", "identified", "monitoring", "resolved"]] = None,
+        exchange: Optional[str] = None,
+        since: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> IncidentsResponse:
+        """Async version of list_incidents()."""
+        data = await self._http.aget(
+            f"{self._base_path}/incidents",
+            params={
+                "status": status,
+                "exchange": exchange,
+                "since": self._convert_timestamp(since),
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+        return IncidentsResponse.model_validate(data)
+
+    def get_incident(self, incident_id: str) -> Incident:
+        """
+        Get a specific incident by ID.
+
+        Args:
+            incident_id: The incident ID
+
+        Returns:
+            Incident details.
+
+        Example:
+            >>> incident = client.data_quality.get_incident("inc_123")
+            >>> print(f"Status: {incident.status}")
+            >>> print(f"Root cause: {incident.root_cause}")
+        """
+        data = self._http.get(f"{self._base_path}/incidents/{incident_id}")
+        return Incident.model_validate(data)
+
+    async def aget_incident(self, incident_id: str) -> Incident:
+        """Async version of get_incident()."""
+        data = await self._http.aget(f"{self._base_path}/incidents/{incident_id}")
+        return Incident.model_validate(data)
+
+    # =========================================================================
+    # Latency Endpoints
+    # =========================================================================
+
+    def latency(self) -> LatencyResponse:
+        """
+        Get current latency metrics for all exchanges.
+
+        Returns:
+            LatencyResponse with WebSocket, REST API, and data freshness metrics.
+
+        Example:
+            >>> latency = client.data_quality.latency()
+            >>> for exchange, metrics in latency.exchanges.items():
+            ...     print(f"{exchange}:")
+            ...     if metrics.websocket:
+            ...         print(f"  WS current: {metrics.websocket.current_ms}ms")
+            ...     print(f"  OB lag: {metrics.data_freshness.orderbook_lag_ms}ms")
+        """
+        data = self._http.get(f"{self._base_path}/latency")
+        return LatencyResponse.model_validate(data)
+
+    async def alatency(self) -> LatencyResponse:
+        """Async version of latency()."""
+        data = await self._http.aget(f"{self._base_path}/latency")
+        return LatencyResponse.model_validate(data)
+
+    # =========================================================================
+    # SLA Endpoints
+    # =========================================================================
+
+    def sla(
+        self,
+        *,
+        year: Optional[int] = None,
+        month: Optional[int] = None,
+    ) -> SlaResponse:
+        """
+        Get SLA compliance metrics for a specific month.
+
+        Args:
+            year: Year (defaults to current year)
+            month: Month 1-12 (defaults to current month)
+
+        Returns:
+            SlaResponse with SLA targets, actual metrics, and compliance status.
+
+        Example:
+            >>> sla = client.data_quality.sla(year=2026, month=1)
+            >>> print(f"Period: {sla.period}")
+            >>> print(f"Uptime: {sla.actual.uptime}% ({sla.actual.uptime_status})")
+            >>> print(f"Completeness: {sla.actual.data_completeness.overall}%")
+            >>> print(f"API P99: {sla.actual.api_latency_p99_ms}ms")
+        """
+        data = self._http.get(
+            f"{self._base_path}/sla",
+            params={
+                "year": year,
+                "month": month,
+            },
+        )
+        return SlaResponse.model_validate(data)
+
+    async def asla(
+        self,
+        *,
+        year: Optional[int] = None,
+        month: Optional[int] = None,
+    ) -> SlaResponse:
+        """Async version of sla()."""
+        data = await self._http.aget(
+            f"{self._base_path}/sla",
+            params={
+                "year": year,
+                "month": month,
+            },
+        )
+        return SlaResponse.model_validate(data)

{oxarchive-0.5.4 → 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
 # =============================================================================
@@ -593,3 +611,353 @@ class CursorResponse(BaseModel, Generic[T]):
 # Type alias for timestamp parameters
 Timestamp = Union[int, str, datetime]
 """Timestamp can be Unix ms (int), ISO string, or datetime object."""
+
+
+# =============================================================================
+# Data Quality Types
+# =============================================================================
+
+
+class SystemStatus(BaseModel):
+    """System status values: operational, degraded, outage, maintenance."""
+
+    status: Literal["operational", "degraded", "outage", "maintenance"]
+
+
+class ExchangeStatus(BaseModel):
+    """Status of a single exchange."""
+
+    status: Literal["operational", "degraded", "outage", "maintenance"]
+    """Current status."""
+
+    last_data_at: Optional[datetime] = None
+    """Timestamp of last received data."""
+
+    latency_ms: Optional[int] = None
+    """Current latency in milliseconds."""
+
+
+class DataTypeStatus(BaseModel):
+    """Status of a data type (orderbook, fills, etc.)."""
+
+    status: Literal["operational", "degraded", "outage", "maintenance"]
+    """Current status."""
+
+    completeness_24h: float
+    """Data completeness over last 24 hours (0-100)."""
+
+
+class StatusResponse(BaseModel):
+    """Overall system status response."""
+
+    status: Literal["operational", "degraded", "outage", "maintenance"]
+    """Overall system status."""
+
+    updated_at: datetime
+    """When this status was computed."""
+
+    exchanges: dict[str, ExchangeStatus]
+    """Per-exchange status."""
+
+    data_types: dict[str, DataTypeStatus]
+    """Per-data-type status."""
+
+    active_incidents: int
+    """Number of active incidents."""
+
+
+class DataTypeCoverage(BaseModel):
+    """Coverage information for a specific data type."""
+
+    earliest: datetime
+    """Earliest available data timestamp."""
+
+    latest: datetime
+    """Latest available data timestamp."""
+
+    total_records: int
+    """Total number of records."""
+
+    symbols: int
+    """Number of symbols with data."""
+
+    resolution: Optional[str] = None
+    """Data resolution (e.g., '1.2s', '1m')."""
+
+    lag: Optional[str] = None
+    """Current data lag."""
+
+    completeness: float
+    """Completeness percentage (0-100)."""
+
+
+class ExchangeCoverage(BaseModel):
+    """Coverage for a single exchange."""
+
+    exchange: str
+    """Exchange name."""
+
+    data_types: dict[str, DataTypeCoverage]
+    """Coverage per data type."""
+
+
+class CoverageResponse(BaseModel):
+    """Overall coverage response."""
+
+    exchanges: list[ExchangeCoverage]
+    """Coverage for all exchanges."""
+
+
+class CoverageGap(BaseModel):
+    """Gap information for per-symbol coverage."""
+
+    start: datetime
+    """Start of the gap (last data before gap)."""
+
+    end: datetime
+    """End of the gap (first data after gap)."""
+
+    duration_minutes: int
+    """Duration of the gap in minutes."""
+
+
+class SymbolDataTypeCoverage(BaseModel):
+    """Coverage for a specific symbol and data type."""
+
+    earliest: datetime
+    """Earliest available data timestamp."""
+
+    latest: datetime
+    """Latest available data timestamp."""
+
+    total_records: int
+    """Total number of records."""
+
+    completeness: float
+    """Completeness percentage (0-100)."""
+
+    gaps: list[CoverageGap]
+    """Detected data gaps."""
+
+
+class SymbolCoverageResponse(BaseModel):
+    """Per-symbol coverage response."""
+
+    exchange: str
+    """Exchange name."""
+
+    symbol: str
+    """Symbol name."""
+
+    data_types: dict[str, SymbolDataTypeCoverage]
+    """Coverage per data type."""
+
+
+class Incident(BaseModel):
+    """Data quality incident."""
+
+    id: str
+    """Unique incident ID."""
+
+    status: str
+    """Status: open, investigating, identified, monitoring, resolved."""
+
+    severity: str
+    """Severity: minor, major, critical."""
+
+    exchange: Optional[str] = None
+    """Affected exchange (if specific to one)."""
+
+    data_types: list[str]
+    """Affected data types."""
+
+    symbols_affected: list[str]
+    """Affected symbols."""
+
+    started_at: datetime
+    """When the incident started."""
+
+    resolved_at: Optional[datetime] = None
+    """When the incident was resolved."""
+
+    duration_minutes: Optional[int] = None
+    """Total duration in minutes."""
+
+    title: str
+    """Incident title."""
+
+    description: Optional[str] = None
+    """Detailed description."""
+
+    root_cause: Optional[str] = None
+    """Root cause analysis."""
+
+    resolution: Optional[str] = None
+    """Resolution details."""
+
+    records_affected: Optional[int] = None
+    """Number of records affected."""
+
+    records_recovered: Optional[int] = None
+    """Number of records recovered."""
+
+
+class Pagination(BaseModel):
+    """Pagination info for incident list."""
+
+    total: int
+    """Total number of incidents."""
+
+    limit: int
+    """Page size limit."""
+
+    offset: int
+    """Current offset."""
+
+
+class IncidentsResponse(BaseModel):
+    """Incidents list response."""
+
+    incidents: list[Incident]
+    """List of incidents."""
+
+    pagination: Pagination
+    """Pagination info."""
+
+
+class WebSocketLatency(BaseModel):
+    """WebSocket latency metrics."""
+
+    current_ms: int
+    """Current latency."""
+
+    avg_1h_ms: int
+    """1-hour average latency."""
+
+    avg_24h_ms: int
+    """24-hour average latency."""
+
+    p99_24h_ms: Optional[int] = None
+    """24-hour P99 latency."""
+
+
+class ApiLatency(BaseModel):
+    """REST API latency metrics."""
+
+    current_ms: int
+    """Current latency."""
+
+    avg_1h_ms: int
+    """1-hour average latency."""
+
+    avg_24h_ms: int
+    """24-hour average latency."""
+
+
+class DataFreshness(BaseModel):
+    """Data freshness metrics (lag from source)."""
+
+    orderbook_lag_ms: Optional[int] = None
+    """Orderbook data lag."""
+
+    fills_lag_ms: Optional[int] = None
+    """Fills/trades data lag."""
+
+    funding_lag_ms: Optional[int] = None
+    """Funding rate data lag."""
+
+    oi_lag_ms: Optional[int] = None
+    """Open interest data lag."""
+
+
+class ExchangeLatency(BaseModel):
+    """Latency metrics for a single exchange."""
+
+    websocket: Optional[WebSocketLatency] = None
+    """WebSocket latency metrics."""
+
+    rest_api: Optional[ApiLatency] = None
+    """REST API latency metrics."""
+
+    data_freshness: DataFreshness
+    """Data freshness metrics."""
+
+
+class LatencyResponse(BaseModel):
+    """Overall latency response."""
+
+    measured_at: datetime
+    """When these metrics were measured."""
+
+    exchanges: dict[str, ExchangeLatency]
+    """Per-exchange latency metrics."""
+
+
+class SlaTargets(BaseModel):
+    """SLA targets."""
+
+    uptime: float
+    """Uptime target percentage."""
+
+    data_completeness: float
+    """Data completeness target percentage."""
+
+    api_latency_p99_ms: int
+    """API P99 latency target in milliseconds."""
+
+
+class CompletenessMetrics(BaseModel):
+    """Completeness metrics per data type."""
+
+    orderbook: float
+    """Orderbook completeness percentage."""
+
+    fills: float
+    """Fills completeness percentage."""
+
+    funding: float
+    """Funding rate completeness percentage."""
+
+    overall: float
+    """Overall completeness percentage."""
+
+
+class SlaActual(BaseModel):
+    """Actual SLA metrics."""
+
+    uptime: float
+    """Actual uptime percentage."""
+
+    uptime_status: str
+    """'met' or 'missed'."""
+
+    data_completeness: CompletenessMetrics
+    """Actual completeness metrics."""
+
+    completeness_status: str
+    """'met' or 'missed'."""
+
+    api_latency_p99_ms: int
+    """Actual API P99 latency."""
+
+    latency_status: str
+    """'met' or 'missed'."""
+
+
+class SlaResponse(BaseModel):
+    """SLA compliance response."""
+
+    period: str
+    """Period covered (e.g., '2026-01')."""
+
+    sla_targets: SlaTargets
+    """Target SLA metrics."""
+
+    actual: SlaActual
+    """Actual SLA metrics."""
+
+    incidents_this_period: int
+    """Number of incidents in this period."""
+
+    total_downtime_minutes: int
+    """Total downtime in minutes."""

{oxarchive-0.5.4 → 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.5.4 → oxarchive-0.6.1}/pyproject.toml

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