oxarchive 0.1.1__tar.gz → 0.2.1__tar.gz

{oxarchive-0.1.1 → oxarchive-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.1.1
+Version: 0.2.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
@@ -140,20 +140,6 @@ trades = client.trades.list(
 )
 ```
 
-### Candles (OHLCV)
-
-```python
-# Get hourly candles
-candles = client.candles.list(
-    "BTC",
-    interval="1h",
-    start="2024-01-01",
-    end="2024-01-02"
-)
-
-# Available intervals: '1m', '5m', '15m', '1h', '4h', '1d'
-```
-
 ### Instruments
 
 ```python
@@ -272,8 +258,8 @@ async def main():
         print(f"{ts}: {data['mid_price']}")
     )
 
-    ws.on_replay_start(lambda ch, coin, total, speed:
-        print(f"Starting replay of {total} records at {speed}x")
+    ws.on_replay_start(lambda ch, coin, start, end, speed:
+        print(f"Starting replay from {start} to {end} at {speed}x")
     )
 
     ws.on_replay_complete(lambda ch, coin, sent:
@@ -316,8 +302,8 @@ async def main():
         all_data.extend([r.data for r in records])
     )
 
-    ws.on_stream_progress(lambda sent, total, pct:
-        print(f"Progress: {pct:.1f}%")
+    ws.on_stream_progress(lambda snapshots_sent:
+        print(f"Sent: {snapshots_sent} snapshots")
     )
 
     ws.on_stream_complete(lambda ch, coin, sent:

{oxarchive-0.1.1 → oxarchive-0.2.1}/README.md

@@ -104,20 +104,6 @@ trades = client.trades.list(
 )
 ```
 
-### Candles (OHLCV)
-
-```python
-# Get hourly candles
-candles = client.candles.list(
-    "BTC",
-    interval="1h",
-    start="2024-01-01",
-    end="2024-01-02"
-)
-
-# Available intervals: '1m', '5m', '15m', '1h', '4h', '1d'
-```
-
 ### Instruments
 
 ```python
@@ -236,8 +222,8 @@ async def main():
         print(f"{ts}: {data['mid_price']}")
     )
 
-    ws.on_replay_start(lambda ch, coin, total, speed:
-        print(f"Starting replay of {total} records at {speed}x")
+    ws.on_replay_start(lambda ch, coin, start, end, speed:
+        print(f"Starting replay from {start} to {end} at {speed}x")
     )
 
     ws.on_replay_complete(lambda ch, coin, sent:
@@ -280,8 +266,8 @@ async def main():
         all_data.extend([r.data for r in records])
     )
 
-    ws.on_stream_progress(lambda sent, total, pct:
-        print(f"Progress: {pct:.1f}%")
+    ws.on_stream_progress(lambda snapshots_sent:
+        print(f"Sent: {snapshots_sent} snapshots")
     )
 
     ws.on_stream_complete(lambda ch, coin, sent:

{oxarchive-0.1.1 → oxarchive-0.2.1}/oxarchive/__init__.py

@@ -20,8 +20,6 @@ from .client import Client
 from .types import (
     OrderBook,
     Trade,
-    Candle,
-    CandleInterval,
     Instrument,
     FundingRate,
     OpenInterest,
@@ -70,8 +68,6 @@ __all__ = [
     # Types
     "OrderBook",
     "Trade",
-    "Candle",
-    "CandleInterval",
     "Instrument",
     "FundingRate",
     "OpenInterest",

{oxarchive-0.1.1 → oxarchive-0.2.1}/oxarchive/client.py

@@ -8,7 +8,6 @@ from .http import HttpClient
 from .resources import (
     OrderBookResource,
     TradesResource,
-    CandlesResource,
     InstrumentsResource,
     FundingResource,
     OpenInterestResource,
@@ -81,9 +80,6 @@ class Client:
         self.trades = TradesResource(self._http)
         """Trade/fill history"""
 
-        self.candles = CandlesResource(self._http)
-        """OHLCV candles"""
-
         self.instruments = InstrumentsResource(self._http)
         """Trading instruments metadata"""
 

{oxarchive-0.1.1 → oxarchive-0.2.1}/oxarchive/resources/__init__.py

@@ -2,7 +2,6 @@
 
 from .orderbook import OrderBookResource
 from .trades import TradesResource
-from .candles import CandlesResource
 from .instruments import InstrumentsResource
 from .funding import FundingResource
 from .openinterest import OpenInterestResource
@@ -10,7 +9,6 @@ from .openinterest import OpenInterestResource
 __all__ = [
     "OrderBookResource",
     "TradesResource",
-    "CandlesResource",
     "InstrumentsResource",
     "FundingResource",
     "OpenInterestResource",

oxarchive-0.2.1/oxarchive/types.py

@@ -0,0 +1,408 @@
+"""Type definitions for the 0xarchive SDK."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Generic, Literal, Optional, TypeVar, Union
+
+from pydantic import BaseModel, Field
+
+
+# =============================================================================
+# Base Types
+# =============================================================================
+
+T = TypeVar("T")
+
+
+class ApiMeta(BaseModel):
+    """Response metadata."""
+
+    count: int
+    next_cursor: Optional[str] = None
+    request_id: str
+
+
+class ApiResponse(BaseModel, Generic[T]):
+    """Standard API response wrapper."""
+
+    success: bool
+    data: T
+    meta: ApiMeta
+
+
+# =============================================================================
+# Order Book Types
+# =============================================================================
+
+
+class PriceLevel(BaseModel):
+    """Single price level in the order book."""
+
+    px: str
+    """Price at this level."""
+
+    sz: str
+    """Total size at this price level."""
+
+    n: int
+    """Number of orders at this level."""
+
+
+class OrderBook(BaseModel):
+    """L2 order book snapshot."""
+
+    coin: str
+    """Trading pair symbol (e.g., BTC, ETH)."""
+
+    timestamp: datetime
+    """Snapshot timestamp (UTC)."""
+
+    bids: list[PriceLevel]
+    """Bid price levels (best bid first)."""
+
+    asks: list[PriceLevel]
+    """Ask price levels (best ask first)."""
+
+    mid_price: Optional[str] = None
+    """Mid price (best bid + best ask) / 2."""
+
+    spread: Optional[str] = None
+    """Spread in absolute terms (best ask - best bid)."""
+
+    spread_bps: Optional[str] = None
+    """Spread in basis points."""
+
+
+# =============================================================================
+# Trade/Fill Types
+# =============================================================================
+
+
+class Trade(BaseModel):
+    """Trade/fill record with full execution details."""
+
+    coin: str
+    """Trading pair symbol."""
+
+    side: Literal["A", "B"]
+    """Trade side: 'B' (buy) or 'A' (sell/ask)."""
+
+    price: str
+    """Execution price."""
+
+    size: str
+    """Trade size."""
+
+    timestamp: datetime
+    """Execution timestamp (UTC)."""
+
+    tx_hash: Optional[str] = None
+    """Blockchain transaction hash."""
+
+    trade_id: Optional[int] = None
+    """Unique trade ID."""
+
+    order_id: Optional[int] = None
+    """Associated order ID."""
+
+    crossed: Optional[bool] = None
+    """True if taker (crossed the spread), false if maker."""
+
+    fee: Optional[str] = None
+    """Trading fee amount."""
+
+    fee_token: Optional[str] = None
+    """Fee denomination (e.g., USDC)."""
+
+    closed_pnl: Optional[str] = None
+    """Realized PnL if closing a position."""
+
+    direction: Optional[Literal["Open Long", "Open Short", "Close Long", "Close Short"]] = None
+    """Position direction."""
+
+    start_position: Optional[str] = None
+    """Position size before this trade."""
+
+    source: Optional[Literal["s3", "ws", "api"]] = None
+    """Data source."""
+
+    user_address: Optional[str] = None
+    """User's wallet address."""
+
+
+# =============================================================================
+# Instrument Types
+# =============================================================================
+
+
+class Instrument(BaseModel):
+    """Trading instrument specification."""
+
+    model_config = {"populate_by_name": True}
+
+    name: str
+    """Instrument symbol (e.g., BTC)."""
+
+    sz_decimals: int = Field(alias="szDecimals")
+    """Size decimal precision."""
+
+    max_leverage: Optional[int] = Field(default=None, alias="maxLeverage")
+    """Maximum leverage allowed."""
+
+    only_isolated: Optional[bool] = Field(default=None, alias="onlyIsolated")
+    """If true, only isolated margin mode is allowed."""
+
+    instrument_type: Optional[Literal["perp", "spot"]] = Field(default=None, alias="instrumentType")
+    """Type of instrument."""
+
+    is_active: bool = Field(default=True, alias="isActive")
+    """Whether the instrument is currently tradeable."""
+
+
+# =============================================================================
+# Funding Types
+# =============================================================================
+
+
+class FundingRate(BaseModel):
+    """Funding rate record."""
+
+    coin: str
+    """Trading pair symbol."""
+
+    timestamp: datetime
+    """Funding timestamp (UTC)."""
+
+    funding_rate: str
+    """Funding rate as decimal (e.g., 0.0001 = 0.01%)."""
+
+    premium: Optional[str] = None
+    """Premium component of funding rate."""
+
+
+# =============================================================================
+# Open Interest Types
+# =============================================================================
+
+
+class OpenInterest(BaseModel):
+    """Open interest snapshot with market context."""
+
+    coin: str
+    """Trading pair symbol."""
+
+    timestamp: datetime
+    """Snapshot timestamp (UTC)."""
+
+    open_interest: str
+    """Total open interest in contracts."""
+
+    mark_price: Optional[str] = None
+    """Mark price used for liquidations."""
+
+    oracle_price: Optional[str] = None
+    """Oracle price from external feed."""
+
+    day_ntl_volume: Optional[str] = None
+    """24-hour notional volume."""
+
+    prev_day_price: Optional[str] = None
+    """Price 24 hours ago."""
+
+    mid_price: Optional[str] = None
+    """Current mid price."""
+
+    impact_bid_price: Optional[str] = None
+    """Impact bid price for liquidations."""
+
+    impact_ask_price: Optional[str] = None
+    """Impact ask price for liquidations."""
+
+
+# =============================================================================
+# WebSocket Types
+# =============================================================================
+
+WsChannel = Literal["orderbook", "trades", "ticker", "all_tickers"]
+"""Available WebSocket channels. Note: ticker/all_tickers are real-time only."""
+
+WsConnectionState = Literal["connecting", "connected", "disconnected", "reconnecting"]
+"""WebSocket connection state."""
+
+
+class WsSubscribed(BaseModel):
+    """Subscription confirmed from server."""
+
+    type: Literal["subscribed"]
+    channel: WsChannel
+    coin: Optional[str] = None
+
+
+class WsUnsubscribed(BaseModel):
+    """Unsubscription confirmed from server."""
+
+    type: Literal["unsubscribed"]
+    channel: WsChannel
+    coin: Optional[str] = None
+
+
+class WsPong(BaseModel):
+    """Pong response from server."""
+
+    type: Literal["pong"]
+
+
+class WsError(BaseModel):
+    """Error from server."""
+
+    type: Literal["error"]
+    message: str
+
+
+class WsData(BaseModel):
+    """Real-time data message from server."""
+
+    type: Literal["data"]
+    channel: WsChannel
+    coin: str
+    data: dict[str, Any]
+
+
+# =============================================================================
+# WebSocket Replay Types (Historical Replay Mode)
+# =============================================================================
+
+
+class WsReplayStarted(BaseModel):
+    """Replay started response."""
+
+    type: Literal["replay_started"]
+    channel: WsChannel
+    coin: str
+    start: int
+    """Start timestamp in milliseconds."""
+    end: int
+    """End timestamp in milliseconds."""
+    speed: float
+    """Playback speed multiplier."""
+
+
+class WsReplayPaused(BaseModel):
+    """Replay paused response."""
+
+    type: Literal["replay_paused"]
+    current_timestamp: int
+
+
+class WsReplayResumed(BaseModel):
+    """Replay resumed response."""
+
+    type: Literal["replay_resumed"]
+    current_timestamp: int
+
+
+class WsReplayCompleted(BaseModel):
+    """Replay completed response."""
+
+    type: Literal["replay_completed"]
+    channel: WsChannel
+    coin: str
+    snapshots_sent: int
+
+
+class WsReplayStopped(BaseModel):
+    """Replay stopped response."""
+
+    type: Literal["replay_stopped"]
+
+
+class WsHistoricalData(BaseModel):
+    """Historical data point (replay mode)."""
+
+    type: Literal["historical_data"]
+    channel: WsChannel
+    coin: str
+    timestamp: int
+    data: dict[str, Any]
+
+
+# =============================================================================
+# WebSocket Bulk Stream Types (Bulk Download Mode)
+# =============================================================================
+
+
+class WsStreamStarted(BaseModel):
+    """Stream started response."""
+
+    type: Literal["stream_started"]
+    channel: WsChannel
+    coin: str
+    start: int
+    """Start timestamp in milliseconds."""
+    end: int
+    """End timestamp in milliseconds."""
+
+
+class WsStreamProgress(BaseModel):
+    """Stream progress response (sent every ~2 seconds)."""
+
+    type: Literal["stream_progress"]
+    snapshots_sent: int
+
+
+class TimestampedRecord(BaseModel):
+    """A record with timestamp for batched data."""
+
+    timestamp: int
+    data: dict[str, Any]
+
+
+class WsHistoricalBatch(BaseModel):
+    """Batch of historical data (bulk streaming)."""
+
+    type: Literal["historical_batch"]
+    channel: WsChannel
+    coin: str
+    data: list[TimestampedRecord]
+
+
+class WsStreamCompleted(BaseModel):
+    """Stream completed response."""
+
+    type: Literal["stream_completed"]
+    channel: WsChannel
+    coin: str
+    snapshots_sent: int
+
+
+class WsStreamStopped(BaseModel):
+    """Stream stopped response."""
+
+    type: Literal["stream_stopped"]
+    snapshots_sent: int
+
+
+# =============================================================================
+# Error Types
+# =============================================================================
+
+
+class OxArchiveError(Exception):
+    """SDK error class."""
+
+    def __init__(self, message: str, code: int, request_id: Optional[str] = None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        if self.request_id:
+            return f"[{self.code}] {self.message} (request_id: {self.request_id})"
+        return f"[{self.code}] {self.message}"
+
+
+# Type alias for timestamp parameters
+Timestamp = Union[int, str, datetime]
+"""Timestamp can be Unix ms (int), ISO string, or datetime object."""

{oxarchive-0.1.1 → oxarchive-0.2.1}/oxarchive/websocket.py

@@ -33,6 +33,7 @@ from typing import Any, Callable, Optional, Set, Union
 try:
     import websockets
     from websockets.client import WebSocketClientProtocol
+    from websockets.protocol import State as WsState
 except ImportError:
     raise ImportError(
         "WebSocket support requires the 'websockets' package. "
@@ -108,14 +109,14 @@ ErrorHandler = Callable[[Exception], None]
 
 # Replay handlers
 HistoricalDataHandler = Callable[[str, int, dict], None]
-ReplayStartHandler = Callable[[WsChannel, str, int, float], None]
-ReplayCompleteHandler = Callable[[WsChannel, str, int], None]
+ReplayStartHandler = Callable[[WsChannel, str, int, int, float], None]  # channel, coin, start, end, speed
+ReplayCompleteHandler = Callable[[WsChannel, str, int], None]  # channel, coin, snapshots_sent
 
 # Stream handlers
 BatchHandler = Callable[[str, list[TimestampedRecord]], None]
-StreamStartHandler = Callable[[WsChannel, str, int], None]
-StreamProgressHandler = Callable[[int, int, float], None]
-StreamCompleteHandler = Callable[[WsChannel, str, int], None]
+StreamStartHandler = Callable[[WsChannel, str, int, int], None]  # channel, coin, start, end
+StreamProgressHandler = Callable[[int], None]  # snapshots_sent
+StreamCompleteHandler = Callable[[WsChannel, str, int], None]  # channel, coin, snapshots_sent
 
 
 class OxArchiveWs:
@@ -164,7 +165,7 @@ class OxArchiveWs:
     @property
     def is_connected(self) -> bool:
         """Check if connected."""
-        return self._ws is not None and self._ws.open
+        return self._ws is not None and self._ws.state == WsState.OPEN
 
     async def connect(self) -> None:
         """Connect to the WebSocket server."""
@@ -421,14 +422,14 @@ class OxArchiveWs:
     def on_replay_start(self, handler: ReplayStartHandler) -> None:
         """Set handler for replay started event.
 
-        Handler receives: (channel, coin, total_records, speed)
+        Handler receives: (channel, coin, start, end, speed)
         """
         self._on_replay_start = handler
 
     def on_replay_complete(self, handler: ReplayCompleteHandler) -> None:
         """Set handler for replay completed event.
 
-        Handler receives: (channel, coin, records_sent)
+        Handler receives: (channel, coin, snapshots_sent)
         """
         self._on_replay_complete = handler
 
@@ -444,21 +445,21 @@ class OxArchiveWs:
     def on_stream_start(self, handler: StreamStartHandler) -> None:
         """Set handler for stream started event.
 
-        Handler receives: (channel, coin, total_records)
+        Handler receives: (channel, coin, start, end)
         """
         self._on_stream_start = handler
 
     def on_stream_progress(self, handler: StreamProgressHandler) -> None:
         """Set handler for stream progress event.
 
-        Handler receives: (records_sent, total_records, progress_pct)
+        Handler receives: (snapshots_sent)
         """
         self._on_stream_progress = handler
 
     def on_stream_complete(self, handler: StreamCompleteHandler) -> None:
         """Set handler for stream completed event.
 
-        Handler receives: (channel, coin, records_sent)
+        Handler receives: (channel, coin, snapshots_sent)
         """
         self._on_stream_complete = handler
 
@@ -585,30 +586,28 @@ class OxArchiveWs:
             # Replay messages (Option B)
             elif msg_type == "replay_started" and self._on_replay_start:
                 self._on_replay_start(
-                    data["channel"], data["coin"], data["total_records"], data["speed"]
+                    data["channel"], data["coin"], data["start"], data["end"], data["speed"]
                 )
 
             elif msg_type == "historical_data" and self._on_historical_data:
                 self._on_historical_data(data["coin"], data["timestamp"], data["data"])
 
             elif msg_type == "replay_completed" and self._on_replay_complete:
-                self._on_replay_complete(data["channel"], data["coin"], data["records_sent"])
+                self._on_replay_complete(data["channel"], data["coin"], data["snapshots_sent"])
 
             # Stream messages (Option D)
             elif msg_type == "stream_started" and self._on_stream_start:
-                self._on_stream_start(data["channel"], data["coin"], data["total_records"])
+                self._on_stream_start(data["channel"], data["coin"], data["start"], data["end"])
 
             elif msg_type == "stream_progress" and self._on_stream_progress:
-                self._on_stream_progress(
-                    data["records_sent"], data["total_records"], data["progress_pct"]
-                )
+                self._on_stream_progress(data["snapshots_sent"])
 
             elif msg_type == "historical_batch" and self._on_batch:
-                records = [TimestampedRecord(**r) for r in data["records"]]
+                records = [TimestampedRecord(**r) for r in data["data"]]
                 self._on_batch(data["coin"], records)
 
             elif msg_type == "stream_completed" and self._on_stream_complete:
-                self._on_stream_complete(data["channel"], data["coin"], data["records_sent"])
+                self._on_stream_complete(data["channel"], data["coin"], data["snapshots_sent"])
 
         except Exception as e:
             logger.error(f"Error handling message: {e}")

{oxarchive-0.1.1 → oxarchive-0.2.1}/pyproject.toml

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

oxarchive-0.1.1/oxarchive/resources/candles.py

@@ -1,100 +0,0 @@
-"""Candles API resource."""
-
-from __future__ import annotations
-
-from datetime import datetime
-from typing import Optional
-
-from ..http import HttpClient
-from ..types import Candle, CandleInterval, Timestamp
-
-
-class CandlesResource:
-    """
-    Candles (OHLCV) API resource.
-
-    Example:
-        >>> # Get hourly candles
-        >>> candles = client.candles.list("BTC", interval="1h")
-        >>>
-        >>> # Get daily candles for a date range
-        >>> daily = client.candles.list("ETH", interval="1d", start="2024-01-01", end="2024-01-31")
-    """
-
-    def __init__(self, http: HttpClient):
-        self._http = http
-
-    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
-
-    def list(
-        self,
-        coin: str,
-        *,
-        interval: Optional[CandleInterval] = None,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
-    ) -> list[Candle]:
-        """
-        Get OHLCV candles for a coin.
-
-        Args:
-            coin: The coin symbol (e.g., 'BTC', 'ETH')
-            interval: Candle interval ('1m', '5m', '15m', '1h', '4h', '1d')
-            start: Start timestamp
-            end: End timestamp
-            limit: Maximum number of results
-            offset: Number of results to skip
-
-        Returns:
-            List of candles
-        """
-        data = self._http.get(
-            f"/v1/candles/{coin.upper()}",
-            params={
-                "interval": interval,
-                "start": self._convert_timestamp(start),
-                "end": self._convert_timestamp(end),
-                "limit": limit,
-                "offset": offset,
-            },
-        )
-        return [Candle.model_validate(item) for item in data["data"]]
-
-    async def alist(
-        self,
-        coin: str,
-        *,
-        interval: Optional[CandleInterval] = None,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
-    ) -> list[Candle]:
-        """Async version of list()."""
-        data = await self._http.aget(
-            f"/v1/candles/{coin.upper()}",
-            params={
-                "interval": interval,
-                "start": self._convert_timestamp(start),
-                "end": self._convert_timestamp(end),
-                "limit": limit,
-                "offset": offset,
-            },
-        )
-        return [Candle.model_validate(item) for item in data["data"]]

oxarchive-0.1.1/oxarchive/types.py

@@ -1,304 +0,0 @@
-"""Type definitions for the 0xarchive SDK."""
-
-from __future__ import annotations
-
-from datetime import datetime
-from typing import Literal, Optional, Union
-
-from pydantic import BaseModel, Field
-
-
-# =============================================================================
-# Base Types
-# =============================================================================
-
-
-class ApiResponse(BaseModel):
-    """Standard API response wrapper."""
-
-    success: bool
-    count: int
-    request_id: str
-
-
-# =============================================================================
-# Order Book Types
-# =============================================================================
-
-
-class OrderBook(BaseModel):
-    """Order book snapshot."""
-
-    coin: str
-    timestamp: int
-    bids: list[tuple[str, str]]
-    asks: list[tuple[str, str]]
-    mid_price: str
-    spread: str
-    spread_bps: str
-
-
-# =============================================================================
-# Trade Types
-# =============================================================================
-
-
-class Trade(BaseModel):
-    """Trade/fill record."""
-
-    id: str
-    coin: str
-    side: Literal["buy", "sell"]
-    price: str
-    size: str
-    value: str
-    timestamp: int
-    trade_type: str
-
-
-# =============================================================================
-# Candle Types
-# =============================================================================
-
-CandleInterval = Literal["1m", "5m", "15m", "1h", "4h", "1d"]
-
-
-class Candle(BaseModel):
-    """OHLCV candle."""
-
-    coin: str
-    interval: str
-    timestamp: int
-    open: str
-    high: str
-    low: str
-    close: str
-    volume: str
-    trades: int
-
-
-# =============================================================================
-# Instrument Types
-# =============================================================================
-
-
-class Instrument(BaseModel):
-    """Trading instrument metadata."""
-
-    coin: str
-    name: str
-    sz_decimals: int
-    max_leverage: int
-    only_isolated: bool
-    is_active: bool
-
-
-# =============================================================================
-# Funding Types
-# =============================================================================
-
-
-class FundingRate(BaseModel):
-    """Funding rate record."""
-
-    coin: str
-    funding_rate: str
-    premium: str
-    timestamp: int
-
-
-# =============================================================================
-# Open Interest Types
-# =============================================================================
-
-
-class OpenInterest(BaseModel):
-    """Open interest record."""
-
-    coin: str
-    open_interest: str
-    timestamp: int
-
-
-# =============================================================================
-# WebSocket Types
-# =============================================================================
-
-WsChannel = Literal["orderbook", "trades", "ticker", "all_tickers", "candles", "funding", "openinterest"]
-WsConnectionState = Literal["connecting", "connected", "disconnected", "reconnecting"]
-
-
-class WsSubscribed(BaseModel):
-    """Subscription confirmed from server."""
-
-    type: Literal["subscribed"]
-    channel: WsChannel
-    coin: Optional[str] = None
-
-
-class WsUnsubscribed(BaseModel):
-    """Unsubscription confirmed from server."""
-
-    type: Literal["unsubscribed"]
-    channel: WsChannel
-    coin: Optional[str] = None
-
-
-class WsPong(BaseModel):
-    """Pong response from server."""
-
-    type: Literal["pong"]
-
-
-class WsError(BaseModel):
-    """Error from server."""
-
-    type: Literal["error"]
-    message: str
-
-
-class WsData(BaseModel):
-    """Data message from server."""
-
-    type: Literal["data"]
-    channel: WsChannel
-    coin: str
-    data: dict
-
-
-# =============================================================================
-# WebSocket Replay Types (Option B - Like Tardis.dev)
-# =============================================================================
-
-
-class WsReplayStarted(BaseModel):
-    """Replay started response."""
-
-    type: Literal["replay_started"]
-    channel: WsChannel
-    coin: str
-    start: int
-    end: int
-    speed: float
-    total_records: int
-
-
-class WsReplayPaused(BaseModel):
-    """Replay paused response."""
-
-    type: Literal["replay_paused"]
-    current_timestamp: int
-
-
-class WsReplayResumed(BaseModel):
-    """Replay resumed response."""
-
-    type: Literal["replay_resumed"]
-    current_timestamp: int
-
-
-class WsReplayCompleted(BaseModel):
-    """Replay completed response."""
-
-    type: Literal["replay_completed"]
-    channel: WsChannel
-    coin: str
-    records_sent: int
-
-
-class WsReplayStopped(BaseModel):
-    """Replay stopped response."""
-
-    type: Literal["replay_stopped"]
-
-
-class WsHistoricalData(BaseModel):
-    """Historical data point (replay mode)."""
-
-    type: Literal["historical_data"]
-    channel: WsChannel
-    coin: str
-    timestamp: int
-    data: dict
-
-
-# =============================================================================
-# WebSocket Bulk Stream Types (Option D - Like Databento)
-# =============================================================================
-
-
-class WsStreamStarted(BaseModel):
-    """Stream started response."""
-
-    type: Literal["stream_started"]
-    channel: WsChannel
-    coin: str
-    start: int
-    end: int
-    batch_size: int
-    total_records: int
-
-
-class WsStreamProgress(BaseModel):
-    """Stream progress response."""
-
-    type: Literal["stream_progress"]
-    records_sent: int
-    total_records: int
-    progress_pct: float
-
-
-class TimestampedRecord(BaseModel):
-    """A record with timestamp."""
-
-    timestamp: int
-    data: dict
-
-
-class WsHistoricalBatch(BaseModel):
-    """Stream batch (bulk data)."""
-
-    type: Literal["historical_batch"]
-    channel: WsChannel
-    coin: str
-    batch_index: int
-    records: list[TimestampedRecord]
-
-
-class WsStreamCompleted(BaseModel):
-    """Stream completed response."""
-
-    type: Literal["stream_completed"]
-    channel: WsChannel
-    coin: str
-    records_sent: int
-
-
-class WsStreamStopped(BaseModel):
-    """Stream stopped response."""
-
-    type: Literal["stream_stopped"]
-
-
-# =============================================================================
-# Error Types
-# =============================================================================
-
-
-class OxArchiveError(Exception):
-    """SDK error class."""
-
-    def __init__(self, message: str, code: int, request_id: Optional[str] = None):
-        super().__init__(message)
-        self.message = message
-        self.code = code
-        self.request_id = request_id
-
-    def __str__(self) -> str:
-        if self.request_id:
-            return f"[{self.code}] {self.message} (request_id: {self.request_id})"
-        return f"[{self.code}] {self.message}"
-
-
-# Type alias for timestamp parameters
-Timestamp = Union[int, str, datetime]