oxarchive 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

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/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/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/resources/funding.py

@@ -44,8 +44,8 @@ class FundingResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
     ) -> list[FundingRate]:
@@ -54,8 +54,8 @@ class FundingResource:
 
         Args:
             coin: The coin symbol (e.g., 'BTC', 'ETH')
-            start: Start timestamp
-            end: End timestamp
+            start: Start timestamp (required)
+            end: End timestamp (required)
             limit: Maximum number of results
             offset: Number of results to skip
 
@@ -77,12 +77,12 @@ class FundingResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
     ) -> list[FundingRate]:
-        """Async version of history()."""
+        """Async version of history(). start and end are required."""
         data = await self._http.aget(
             f"/v1/funding/{coin.upper()}",
             params={

oxarchive/resources/openinterest.py

@@ -44,8 +44,8 @@ class OpenInterestResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
     ) -> list[OpenInterest]:
@@ -54,8 +54,8 @@ class OpenInterestResource:
 
         Args:
             coin: The coin symbol (e.g., 'BTC', 'ETH')
-            start: Start timestamp
-            end: End timestamp
+            start: Start timestamp (required)
+            end: End timestamp (required)
             limit: Maximum number of results
             offset: Number of results to skip
 
@@ -77,12 +77,12 @@ class OpenInterestResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
     ) -> list[OpenInterest]:
-        """Async version of history()."""
+        """Async version of history(). start and end are required."""
         data = await self._http.aget(
             f"/v1/openinterest/{coin.upper()}",
             params={

oxarchive/resources/orderbook.py

@@ -92,8 +92,8 @@ class OrderBookResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
         depth: Optional[int] = None,
@@ -103,8 +103,8 @@ class OrderBookResource:
 
         Args:
             coin: The coin symbol (e.g., 'BTC', 'ETH')
-            start: Start timestamp
-            end: End timestamp
+            start: Start timestamp (required)
+            end: End timestamp (required)
             limit: Maximum number of results
             offset: Number of results to skip
             depth: Number of price levels per side
@@ -128,13 +128,13 @@ class OrderBookResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
         depth: Optional[int] = None,
     ) -> list[OrderBook]:
-        """Async version of history()."""
+        """Async version of history(). start and end are required."""
         data = await self._http.aget(
             f"/v1/orderbook/{coin.upper()}/history",
             params={

oxarchive/resources/trades.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import warnings
+from dataclasses import dataclass
 from datetime import datetime
 from typing import Literal, Optional
 
@@ -9,6 +11,13 @@ from ..http import HttpClient
 from ..types import Trade, Timestamp
 
 
+@dataclass
+class CursorResponse:
+    """Response with cursor for pagination."""
+    data: list[Trade]
+    next_cursor: Optional[str] = None
+
+
 class TradesResource:
     """
     Trades API resource.
@@ -17,8 +26,14 @@ class TradesResource:
         >>> # Get recent trades
         >>> trades = client.trades.recent("BTC")
         >>>
-        >>> # Get trade history with time range
-        >>> history = client.trades.list("ETH", start="2024-01-01", end="2024-01-02")
+        >>> # Get trade history with cursor-based pagination (recommended)
+        >>> result = client.trades.list("BTC", start="2024-01-01", end="2024-01-02")
+        >>> trades = result.data
+        >>>
+        >>> # Get all pages
+        >>> while result.next_cursor:
+        ...     result = client.trades.list("BTC", start="2024-01-01", end="2024-01-02", cursor=result.next_cursor)
+        ...     trades.extend(result.data)
     """
 
     def __init__(self, http: HttpClient):
@@ -44,19 +59,106 @@ class TradesResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
+        cursor: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> CursorResponse:
+        """
+        Get trade history for a coin using cursor-based pagination.
+
+        Uses cursor-based pagination by default, which is more efficient for large datasets.
+        Use the next_cursor from the response as the cursor parameter to get the next page.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+            start: Start timestamp (required)
+            end: End timestamp (required)
+            cursor: Cursor from previous response's next_cursor (timestamp)
+            limit: Maximum number of results (default: 100, max: 1000)
+            side: Filter by trade side
+
+        Returns:
+            CursorResponse with trades and next_cursor for pagination
+
+        Example:
+            >>> # First page
+            >>> result = client.trades.list("BTC", start=start, end=end, limit=1000)
+            >>> trades = result.data
+            >>>
+            >>> # Subsequent pages
+            >>> while result.next_cursor:
+            ...     result = client.trades.list(
+            ...         "BTC", start=start, end=end, cursor=result.next_cursor, limit=1000
+            ...     )
+            ...     trades.extend(result.data)
+        """
+        data = self._http.get(
+            f"/v1/trades/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
+                "limit": limit,
+                "side": side,
+            },
+        )
+        return CursorResponse(
+            data=[Trade.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
+
+    async def alist(
+        self,
+        coin: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        cursor: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> CursorResponse:
+        """
+        Async version of list().
+
+        Uses cursor-based pagination by default.
+        """
+        data = await self._http.aget(
+            f"/v1/trades/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
+                "limit": limit,
+                "side": side,
+            },
+        )
+        return CursorResponse(
+            data=[Trade.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
+
+    def list_with_offset(
+        self,
+        coin: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
         side: Optional[Literal["buy", "sell"]] = None,
     ) -> list[Trade]:
         """
-        Get trade history for a coin.
+        Get trade history using offset-based pagination.
+
+        .. deprecated::
+            Use list() with cursor-based pagination instead for better performance.
 
         Args:
             coin: The coin symbol (e.g., 'BTC', 'ETH')
-            start: Start timestamp
-            end: End timestamp
+            start: Start timestamp (required)
+            end: End timestamp (required)
             limit: Maximum number of results
             offset: Number of results to skip
             side: Filter by trade side
@@ -64,6 +166,11 @@ class TradesResource:
         Returns:
             List of trades
         """
+        warnings.warn(
+            "list_with_offset() is deprecated. Use list() with cursor-based pagination instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         data = self._http.get(
             f"/v1/trades/{coin.upper()}",
             params={
@@ -76,17 +183,27 @@ class TradesResource:
         )
         return [Trade.model_validate(item) for item in data["data"]]
 
-    async def alist(
+    async def alist_with_offset(
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
         side: Optional[Literal["buy", "sell"]] = None,
     ) -> list[Trade]:
-        """Async version of list()."""
+        """
+        Async version of list_with_offset().
+
+        .. deprecated::
+            Use alist() with cursor-based pagination instead.
+        """
+        warnings.warn(
+            "alist_with_offset() is deprecated. Use alist() with cursor-based pagination instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         data = await self._http.aget(
             f"/v1/trades/{coin.upper()}",
             params={
@@ -123,3 +240,60 @@ class TradesResource:
             params={"limit": limit},
         )
         return [Trade.model_validate(item) for item in data["data"]]
+
+    def list_cursor(
+        self,
+        coin: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        cursor: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> CursorResponse:
+        """
+        Get trade history using cursor-based pagination.
+
+        .. deprecated::
+            Use list() instead - it now uses cursor-based pagination by default.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+            start: Start timestamp (required)
+            end: End timestamp (required)
+            cursor: Cursor from previous response's next_cursor (timestamp)
+            limit: Maximum number of results
+            side: Filter by trade side
+
+        Returns:
+            CursorResponse with trades and next_cursor for pagination
+        """
+        warnings.warn(
+            "list_cursor() is deprecated. Use list() instead - it now uses cursor-based pagination by default.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.list(coin, start=start, end=end, cursor=cursor, limit=limit, side=side)
+
+    async def alist_cursor(
+        self,
+        coin: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        cursor: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> CursorResponse:
+        """
+        Async version of list_cursor().
+
+        .. deprecated::
+            Use alist() instead - it now uses cursor-based pagination by default.
+        """
+        warnings.warn(
+            "alist_cursor() is deprecated. Use alist() instead - it now uses cursor-based pagination by default.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self.alist(coin, start=start, end=end, cursor=cursor, limit=limit, side=side)

oxarchive/types.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Literal, Optional, Union
+from typing import Any, Generic, Literal, Optional, TypeVar, Union
 
 from pydantic import BaseModel, Field
 
@@ -12,69 +12,123 @@ from pydantic import BaseModel, Field
 # Base Types
 # =============================================================================
 
+T = TypeVar("T")
 
-class ApiResponse(BaseModel):
-    """Standard API response wrapper."""
 
-    success: bool
+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):
-    """Order book snapshot."""
+    """L2 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
+    """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 Types
+# Trade/Fill Types
 # =============================================================================
 
 
 class Trade(BaseModel):
-    """Trade/fill record."""
+    """Trade/fill record with full execution details."""
 
-    id: str
     coin: str
-    side: Literal["buy", "sell"]
+    """Trading pair symbol."""
+
+    side: Literal["A", "B"]
+    """Trade side: 'B' (buy) or 'A' (sell/ask)."""
+
     price: str
+    """Execution price."""
+
     size: str
-    value: str
-    timestamp: int
-    trade_type: str
+    """Trade size."""
 
+    timestamp: datetime
+    """Execution timestamp (UTC)."""
 
-# =============================================================================
-# Candle Types
-# =============================================================================
+    tx_hash: Optional[str] = None
+    """Blockchain transaction hash."""
 
-CandleInterval = Literal["1m", "5m", "15m", "1h", "4h", "1d"]
+    trade_id: Optional[int] = None
+    """Unique trade ID."""
 
+    order_id: Optional[int] = None
+    """Associated order ID."""
 
-class Candle(BaseModel):
-    """OHLCV candle."""
+    crossed: Optional[bool] = None
+    """True if taker (crossed the spread), false if maker."""
 
-    coin: str
-    interval: str
-    timestamp: int
-    open: str
-    high: str
-    low: str
-    close: str
-    volume: str
-    trades: int
+    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."""
 
 
 # =============================================================================
@@ -83,14 +137,27 @@ class Candle(BaseModel):
 
 
 class Instrument(BaseModel):
-    """Trading instrument metadata."""
+    """Trading instrument specification."""
+
+    model_config = {"populate_by_name": True}
 
-    coin: str
     name: str
-    sz_decimals: int
-    max_leverage: int
-    only_isolated: bool
-    is_active: bool
+    """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."""
 
 
 # =============================================================================
@@ -102,9 +169,16 @@ class FundingRate(BaseModel):
     """Funding rate record."""
 
     coin: str
+    """Trading pair symbol."""
+
+    timestamp: datetime
+    """Funding timestamp (UTC)."""
+
     funding_rate: str
-    premium: str
-    timestamp: int
+    """Funding rate as decimal (e.g., 0.0001 = 0.01%)."""
+
+    premium: Optional[str] = None
+    """Premium component of funding rate."""
 
 
 # =============================================================================
@@ -113,19 +187,48 @@ class FundingRate(BaseModel):
 
 
 class OpenInterest(BaseModel):
-    """Open interest record."""
+    """Open interest snapshot with market context."""
 
     coin: str
+    """Trading pair symbol."""
+
+    timestamp: datetime
+    """Snapshot timestamp (UTC)."""
+
     open_interest: str
-    timestamp: int
+    """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", "candles", "funding", "openinterest"]
+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):
@@ -158,16 +261,16 @@ class WsError(BaseModel):
 
 
 class WsData(BaseModel):
-    """Data message from server."""
+    """Real-time data message from server."""
 
     type: Literal["data"]
     channel: WsChannel
     coin: str
-    data: dict
+    data: dict[str, Any]
 
 
 # =============================================================================
-# WebSocket Replay Types (Option B - Like Tardis.dev)
+# WebSocket Replay Types (Historical Replay Mode)
 # =============================================================================
 
 
@@ -178,9 +281,11 @@ class WsReplayStarted(BaseModel):
     channel: WsChannel
     coin: str
     start: int
+    """Start timestamp in milliseconds."""
     end: int
+    """End timestamp in milliseconds."""
     speed: float
-    total_records: int
+    """Playback speed multiplier."""
 
 
 class WsReplayPaused(BaseModel):
@@ -203,7 +308,7 @@ class WsReplayCompleted(BaseModel):
     type: Literal["replay_completed"]
     channel: WsChannel
     coin: str
-    records_sent: int
+    snapshots_sent: int
 
 
 class WsReplayStopped(BaseModel):
@@ -219,11 +324,11 @@ class WsHistoricalData(BaseModel):
     channel: WsChannel
     coin: str
     timestamp: int
-    data: dict
+    data: dict[str, Any]
 
 
 # =============================================================================
-# WebSocket Bulk Stream Types (Option D - Like Databento)
+# WebSocket Bulk Stream Types (Bulk Download Mode)
 # =============================================================================
 
 
@@ -234,35 +339,32 @@ class WsStreamStarted(BaseModel):
     channel: WsChannel
     coin: str
     start: int
+    """Start timestamp in milliseconds."""
     end: int
-    batch_size: int
-    total_records: int
+    """End timestamp in milliseconds."""
 
 
 class WsStreamProgress(BaseModel):
-    """Stream progress response."""
+    """Stream progress response (sent every ~2 seconds)."""
 
     type: Literal["stream_progress"]
-    records_sent: int
-    total_records: int
-    progress_pct: float
+    snapshots_sent: int
 
 
 class TimestampedRecord(BaseModel):
-    """A record with timestamp."""
+    """A record with timestamp for batched data."""
 
     timestamp: int
-    data: dict
+    data: dict[str, Any]
 
 
 class WsHistoricalBatch(BaseModel):
-    """Stream batch (bulk data)."""
+    """Batch of historical data (bulk streaming)."""
 
     type: Literal["historical_batch"]
     channel: WsChannel
     coin: str
-    batch_index: int
-    records: list[TimestampedRecord]
+    data: list[TimestampedRecord]
 
 
 class WsStreamCompleted(BaseModel):
@@ -271,13 +373,14 @@ class WsStreamCompleted(BaseModel):
     type: Literal["stream_completed"]
     channel: WsChannel
     coin: str
-    records_sent: int
+    snapshots_sent: int
 
 
 class WsStreamStopped(BaseModel):
     """Stream stopped response."""
 
     type: Literal["stream_stopped"]
+    snapshots_sent: int
 
 
 # =============================================================================
@@ -302,3 +405,4 @@ class OxArchiveError(Exception):
 
 # Type alias for timestamp parameters
 Timestamp = Union[int, str, datetime]
+"""Timestamp can be Unix ms (int), ISO string, or datetime object."""

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. "
@@ -41,6 +42,7 @@ except ImportError:
 
 from .types import (
     OrderBook,
+    PriceLevel,
     Trade,
     WsChannel,
     WsConnectionState,
@@ -108,14 +110,74 @@ 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
+
+
+def _transform_orderbook(coin: str, raw: dict) -> OrderBook:
+    """Transform raw Hyperliquid orderbook format to SDK OrderBook type.
+
+    Raw format: { coin, levels: [[{px, sz, n}, ...], [{px, sz, n}, ...]], time }
+    SDK format: { coin, timestamp, bids: [{px, sz, n}], asks: [{px, sz, n}], mid_price, spread, spread_bps }
+    """
+    from datetime import datetime
+
+    # Check if already in SDK format (from REST API or historical replay)
+    if "bids" in raw and "asks" in raw:
+        return OrderBook(**raw)
+
+    # Transform from Hyperliquid raw format
+    # levels is [[{px, sz, n}, ...], [{px, sz, n}, ...]] where [0]=bids, [1]=asks
+    levels = raw.get("levels", [[], []])
+    time_ms = raw.get("time")
+
+    bids = []
+    asks = []
+
+    if len(levels) >= 2:
+        # levels[0] = bids, levels[1] = asks
+        # Each level is already {px, sz, n} object
+        for level in levels[0] or []:
+            if isinstance(level, dict):
+                bids.append(PriceLevel(px=str(level.get("px", "0")), sz=str(level.get("sz", "0")), n=int(level.get("n", 0))))
+        for level in levels[1] or []:
+            if isinstance(level, dict):
+                asks.append(PriceLevel(px=str(level.get("px", "0")), sz=str(level.get("sz", "0")), n=int(level.get("n", 0))))
+
+    # Calculate mid price and spread
+    mid_price = None
+    spread = None
+    spread_bps = None
+
+    if bids and asks:
+        best_bid = float(bids[0].px)
+        best_ask = float(asks[0].px)
+        mid = (best_bid + best_ask) / 2
+        mid_price = str(mid)
+        spread = str(best_ask - best_bid)
+        spread_bps = f"{((best_ask - best_bid) / mid * 10000):.2f}"
+
+    # Convert timestamp
+    if time_ms:
+        timestamp = datetime.utcfromtimestamp(time_ms / 1000).isoformat() + "Z"
+    else:
+        timestamp = datetime.utcnow().isoformat() + "Z"
+
+    return OrderBook(
+        coin=coin,
+        timestamp=timestamp,
+        bids=bids,
+        asks=asks,
+        mid_price=mid_price,
+        spread=spread,
+        spread_bps=spread_bps,
+    )
 
 
 class OxArchiveWs:
@@ -164,7 +226,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 +483,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 +506,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
 
@@ -575,7 +637,8 @@ class OxArchiveWs:
                 raw_data = data.get("data", {})
 
                 if channel == "orderbook" and self._on_orderbook:
-                    orderbook = OrderBook(**raw_data)
+                    # Transform raw Hyperliquid format to SDK OrderBook type
+                    orderbook = _transform_orderbook(coin, raw_data)
                     self._on_orderbook(coin, orderbook)
 
                 elif channel == "trades" and self._on_trades:
@@ -585,30 +648,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.dist-info → oxarchive-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.1.1
+Version: 0.3.0
 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.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+oxarchive/__init__.py,sha256=QqBnxRIGEBXE2wHdmynznUEBoJsePN_xObo_v79lPZI,2181
+oxarchive/client.py,sha256=3P0fvOcyM5BWppkVV4054NduDHKvRg-cWeluoGymmRk,3163
+oxarchive/http.py,sha256=LJgw488_nNb14ixRoDv5ChuhUvyzTGtQ4aTSdEEwXww,3577
+oxarchive/types.py,sha256=8n_R41IjdNnshPscY5zAfrHa855EbvSTSdbi-GZExKo,10434
+oxarchive/websocket.py,sha256=BM6CmUbRdYptNnlicmAVPKBdqlyZBSI1l5iUt_OzWwo,25126
+oxarchive/resources/__init__.py,sha256=WQ4GYQ8p3L0D2Isk4IV4h1DRpvyZlt6tOF1t_CJr6ls,385
+oxarchive/resources/funding.py,sha256=TXkZxodVQTVcVbzNG6SpMQAzf8AkLm2NYZJxnP4MNXw,3500
+oxarchive/resources/instruments.py,sha256=flD1sH6x3P3CTqV1ZwkfwbranVacmhsHn5Dhr7lGQhM,1606
+oxarchive/resources/openinterest.py,sha256=h13yLA72LpfryUf8IqF6W7uE4ObYY2Qbc-auv4LtPqc,3552
+oxarchive/resources/orderbook.py,sha256=o_DTdpzKrZvHL9YXm8cGGUugPM8uUa6r9O_72r1ByV0,4557
+oxarchive/resources/trades.py,sha256=XCi2rXA2hxaTt0KNlWw8f7W0hzAvNWyT7DaivMz_rHw,10012
+oxarchive-0.3.0.dist-info/METADATA,sha256=yq_BurBDJwE1f1Nv6IANatT2KPE0uJ-7OUaY1N-omPk,8749
+oxarchive-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oxarchive-0.3.0.dist-info/RECORD,,

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.dist-info/RECORD

@@ -1,15 +0,0 @@
-oxarchive/__init__.py,sha256=hRUWIJhKmm8d4XBt2gWCSQ6j-9VNaC52y89rXpAKvH0,2253
-oxarchive/client.py,sha256=tIvsxR9qE92xIeGwazJdwqY7bawFe_ZlzEWG0NsNxsw,3268
-oxarchive/http.py,sha256=LJgw488_nNb14ixRoDv5ChuhUvyzTGtQ4aTSdEEwXww,3577
-oxarchive/types.py,sha256=9eCETwCVE_cewap8El2GNSJcYN3BXaeImpyqLneyPUM,7135
-oxarchive/websocket.py,sha256=yByFOfeU6yrHhmd5Eo8FFs4hNBHuL1O65ZH-wsmG1vE,22806
-oxarchive/resources/__init__.py,sha256=4gt5xVlnPhLUjk2n03ldJ9VCnodgdR75U9d1H88a7BE,447
-oxarchive/resources/candles.py,sha256=IhyBCm65CZz4Nsm6IPqfMZHQl_3K4H3jHgChfigc3QU,3147
-oxarchive/resources/funding.py,sha256=JrJ1LqXy8GX6U70zOI89lLIX_d5vM_Rq0qFJy0YRof0,3518
-oxarchive/resources/instruments.py,sha256=flD1sH6x3P3CTqV1ZwkfwbranVacmhsHn5Dhr7lGQhM,1606
-oxarchive/resources/openinterest.py,sha256=trMFr6TEEV88WQkpptQCUEJTy0aaoAy3QnBx9opNZH8,3570
-oxarchive/resources/orderbook.py,sha256=ZfK3HhYrpVpELz6GDb9qpGcWzQ3p4-uxUyEY2Emhr0o,4575
-oxarchive/resources/trades.py,sha256=4sXgyBVaq6RHFJe0jeOvFBIX-bDCe8FwgoeeeM_He3Q,3923
-oxarchive-0.1.1.dist-info/METADATA,sha256=MLL3mweHZ7l9MA0TsdTRvY3qj0V4-_64b5vRGyd0txU,8956
-oxarchive-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-oxarchive-0.1.1.dist-info/RECORD,,