oxarchive 0.1.0__py3-none-any.whl

oxarchive/resources/openinterest.py

@@ -0,0 +1,113 @@
+"""Open interest API resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from ..http import HttpClient
+from ..types import OpenInterest, Timestamp
+
+
+class OpenInterestResource:
+    """
+    Open interest API resource.
+
+    Example:
+        >>> # Get current open interest
+        >>> current = client.open_interest.current("BTC")
+        >>>
+        >>> # Get open interest history
+        >>> history = client.open_interest.history("ETH", start="2024-01-01", end="2024-01-07")
+    """
+
+    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 history(
+        self,
+        coin: str,
+        *,
+        start: Optional[Timestamp] = None,
+        end: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> list[OpenInterest]:
+        """
+        Get open interest history for a coin.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+            start: Start timestamp
+            end: End timestamp
+            limit: Maximum number of results
+            offset: Number of results to skip
+
+        Returns:
+            List of open interest records
+        """
+        data = self._http.get(
+            f"/v1/openinterest/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+        return [OpenInterest.model_validate(item) for item in data["data"]]
+
+    async def ahistory(
+        self,
+        coin: str,
+        *,
+        start: Optional[Timestamp] = None,
+        end: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> list[OpenInterest]:
+        """Async version of history()."""
+        data = await self._http.aget(
+            f"/v1/openinterest/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+        return [OpenInterest.model_validate(item) for item in data["data"]]
+
+    def current(self, coin: str) -> OpenInterest:
+        """
+        Get current open interest for a coin.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+
+        Returns:
+            Current open interest
+        """
+        data = self._http.get(f"/v1/openinterest/{coin.upper()}/current")
+        return OpenInterest.model_validate(data["data"])
+
+    async def acurrent(self, coin: str) -> OpenInterest:
+        """Async version of current()."""
+        data = await self._http.aget(f"/v1/openinterest/{coin.upper()}/current")
+        return OpenInterest.model_validate(data["data"])

oxarchive/resources/orderbook.py

@@ -0,0 +1,148 @@
+"""Order book API resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional, Union
+
+from ..http import HttpClient
+from ..types import OrderBook, Timestamp
+
+
+class OrderBookResource:
+    """
+    Order book API resource.
+
+    Example:
+        >>> # Get current order book
+        >>> orderbook = client.orderbook.get("BTC")
+        >>>
+        >>> # Get order book at specific timestamp
+        >>> historical = client.orderbook.get("ETH", timestamp=1704067200000)
+        >>>
+        >>> # Get order book history
+        >>> history = client.orderbook.history("BTC", start="2024-01-01", end="2024-01-02")
+    """
+
+    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 parsing ISO format
+            try:
+                dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+                return int(dt.timestamp() * 1000)
+            except ValueError:
+                return int(ts)
+        return None
+
+    def get(
+        self,
+        coin: str,
+        *,
+        timestamp: Optional[Timestamp] = None,
+        depth: Optional[int] = None,
+    ) -> OrderBook:
+        """
+        Get order book snapshot for a coin.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+            timestamp: Optional timestamp to get historical snapshot
+            depth: Number of price levels to return per side
+
+        Returns:
+            Order book snapshot
+        """
+        data = self._http.get(
+            f"/v1/orderbook/{coin.upper()}",
+            params={
+                "timestamp": self._convert_timestamp(timestamp),
+                "depth": depth,
+            },
+        )
+        return OrderBook.model_validate(data["data"])
+
+    async def aget(
+        self,
+        coin: str,
+        *,
+        timestamp: Optional[Timestamp] = None,
+        depth: Optional[int] = None,
+    ) -> OrderBook:
+        """Async version of get()."""
+        data = await self._http.aget(
+            f"/v1/orderbook/{coin.upper()}",
+            params={
+                "timestamp": self._convert_timestamp(timestamp),
+                "depth": depth,
+            },
+        )
+        return OrderBook.model_validate(data["data"])
+
+    def history(
+        self,
+        coin: str,
+        *,
+        start: Optional[Timestamp] = None,
+        end: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        depth: Optional[int] = None,
+    ) -> list[OrderBook]:
+        """
+        Get historical order book snapshots.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+            start: Start timestamp
+            end: End timestamp
+            limit: Maximum number of results
+            offset: Number of results to skip
+            depth: Number of price levels per side
+
+        Returns:
+            List of order book snapshots
+        """
+        data = self._http.get(
+            f"/v1/orderbook/{coin.upper()}/history",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "limit": limit,
+                "offset": offset,
+                "depth": depth,
+            },
+        )
+        return [OrderBook.model_validate(item) for item in data["data"]]
+
+    async def ahistory(
+        self,
+        coin: str,
+        *,
+        start: Optional[Timestamp] = None,
+        end: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        depth: Optional[int] = None,
+    ) -> list[OrderBook]:
+        """Async version of history()."""
+        data = await self._http.aget(
+            f"/v1/orderbook/{coin.upper()}/history",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "limit": limit,
+                "offset": offset,
+                "depth": depth,
+            },
+        )
+        return [OrderBook.model_validate(item) for item in data["data"]]

oxarchive/resources/trades.py

@@ -0,0 +1,125 @@
+"""Trades API resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from ..http import HttpClient
+from ..types import Trade, Timestamp
+
+
+class TradesResource:
+    """
+    Trades API resource.
+
+    Example:
+        >>> # 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")
+    """
+
+    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,
+        *,
+        start: Optional[Timestamp] = None,
+        end: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> list[Trade]:
+        """
+        Get trade history for a coin.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+            start: Start timestamp
+            end: End timestamp
+            limit: Maximum number of results
+            offset: Number of results to skip
+            side: Filter by trade side
+
+        Returns:
+            List of trades
+        """
+        data = self._http.get(
+            f"/v1/trades/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "limit": limit,
+                "offset": offset,
+                "side": side,
+            },
+        )
+        return [Trade.model_validate(item) for item in data["data"]]
+
+    async def alist(
+        self,
+        coin: str,
+        *,
+        start: Optional[Timestamp] = None,
+        end: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> list[Trade]:
+        """Async version of list()."""
+        data = await self._http.aget(
+            f"/v1/trades/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "limit": limit,
+                "offset": offset,
+                "side": side,
+            },
+        )
+        return [Trade.model_validate(item) for item in data["data"]]
+
+    def recent(self, coin: str, limit: Optional[int] = None) -> list[Trade]:
+        """
+        Get most recent trades for a coin.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+            limit: Number of trades to return (default: 100)
+
+        Returns:
+            List of recent trades
+        """
+        data = self._http.get(
+            f"/v1/trades/{coin.upper()}/recent",
+            params={"limit": limit},
+        )
+        return [Trade.model_validate(item) for item in data["data"]]
+
+    async def arecent(self, coin: str, limit: Optional[int] = None) -> list[Trade]:
+        """Async version of recent()."""
+        data = await self._http.aget(
+            f"/v1/trades/{coin.upper()}/recent",
+            params={"limit": limit},
+        )
+        return [Trade.model_validate(item) for item in data["data"]]

oxarchive/types.py

@@ -0,0 +1,304 @@
+"""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]