oxarchive 0.1.0__tar.gz → 0.2.0__tar.gz

{oxarchive-0.1.0 → oxarchive-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.1.0
+Version: 0.2.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
@@ -345,7 +345,7 @@ asyncio.run(main())
 ```python
 ws = OxArchiveWs(WsOptions(
     api_key="ox_your_api_key",
-    ws_url="wss://ws.0xarchive.io",  # Optional
+    ws_url="wss://api.0xarchive.io/ws",  # Optional
     auto_reconnect=True,             # Auto-reconnect on disconnect
     reconnect_delay=1.0,             # Initial reconnect delay (seconds)
     max_reconnect_attempts=10,       # Max reconnect attempts

{oxarchive-0.1.0 → oxarchive-0.2.0}/README.md

@@ -309,7 +309,7 @@ asyncio.run(main())
 ```python
 ws = OxArchiveWs(WsOptions(
     api_key="ox_your_api_key",
-    ws_url="wss://ws.0xarchive.io",  # Optional
+    ws_url="wss://api.0xarchive.io/ws",  # Optional
     auto_reconnect=True,             # Auto-reconnect on disconnect
     reconnect_delay=1.0,             # Initial reconnect delay (seconds)
     max_reconnect_attempts=10,       # Max reconnect attempts

{oxarchive-0.1.0 → oxarchive-0.2.0}/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.0 → oxarchive-0.2.0}/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.1.0 → oxarchive-0.2.0}/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,25 @@ class Candle(BaseModel):
 
 
 class Instrument(BaseModel):
-    """Trading instrument metadata."""
+    """Trading instrument specification."""
 
-    coin: str
     name: str
+    """Instrument symbol (e.g., BTC)."""
+
     sz_decimals: int
-    max_leverage: int
-    only_isolated: bool
-    is_active: bool
+    """Size decimal precision."""
+
+    max_leverage: Optional[int] = None
+    """Maximum leverage allowed."""
+
+    only_isolated: Optional[bool] = None
+    """If true, only isolated margin mode is allowed."""
+
+    instrument_type: Optional[Literal["perp", "spot"]] = None
+    """Type of instrument."""
+
+    is_active: bool = True
+    """Whether the instrument is currently tradeable."""
 
 
 # =============================================================================
@@ -102,9 +167,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 +185,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 +259,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 +279,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 +306,7 @@ class WsReplayCompleted(BaseModel):
     type: Literal["replay_completed"]
     channel: WsChannel
     coin: str
-    records_sent: int
+    snapshots_sent: int
 
 
 class WsReplayStopped(BaseModel):
@@ -219,11 +322,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 +337,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 +371,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 +403,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-0.1.0 → oxarchive-0.2.0}/oxarchive/websocket.py

@@ -65,15 +65,32 @@ from .types import (
 
 logger = logging.getLogger("oxarchive.websocket")
 
-DEFAULT_WS_URL = "wss://ws.0xarchive.io"
+DEFAULT_WS_URL = "wss://api.0xarchive.io/ws"
 DEFAULT_PING_INTERVAL = 30
 DEFAULT_RECONNECT_DELAY = 1.0
 DEFAULT_MAX_RECONNECT_ATTEMPTS = 10
 
+# Server idle timeout is 60 seconds. The SDK sends pings every 30 seconds
+# to keep the connection alive. The websockets library also automatically
+# responds to WebSocket protocol-level ping frames from the server.
+
 
 @dataclass
 class WsOptions:
-    """WebSocket connection options."""
+    """WebSocket connection options.
+
+    The server sends WebSocket ping frames every 30 seconds and will disconnect
+    idle connections after 60 seconds. This SDK automatically handles keep-alive
+    by sending application-level pings at the configured interval.
+
+    Attributes:
+        api_key: Your 0xarchive API key
+        ws_url: WebSocket server URL (default: wss://api.0xarchive.io/ws)
+        auto_reconnect: Automatically reconnect on disconnect (default: True)
+        reconnect_delay: Initial reconnect delay in seconds (default: 1.0)
+        max_reconnect_attempts: Maximum reconnection attempts (default: 10)
+        ping_interval: Interval between keep-alive pings in seconds (default: 30)
+    """
 
     api_key: str
     ws_url: str = DEFAULT_WS_URL

{oxarchive-0.1.0 → oxarchive-0.2.0}/pyproject.toml

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

oxarchive-0.1.0/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"]]