oxarchive 0.1.0__py3-none-any.whl

oxarchive/__init__.py

@@ -0,0 +1,101 @@
+"""
+oxarchive - Official Python SDK for 0xarchive
+
+Hyperliquid Historical Data API.
+
+Example:
+    >>> from oxarchive import Client
+    >>>
+    >>> client = Client(api_key="ox_your_api_key")
+    >>>
+    >>> # Get current order book
+    >>> orderbook = client.orderbook.get("BTC")
+    >>> print(f"BTC mid price: {orderbook.mid_price}")
+    >>>
+    >>> # Get historical snapshots
+    >>> history = client.orderbook.history("ETH", start="2024-01-01", end="2024-01-02")
+"""
+
+from .client import Client
+from .types import (
+    OrderBook,
+    Trade,
+    Candle,
+    CandleInterval,
+    Instrument,
+    FundingRate,
+    OpenInterest,
+    OxArchiveError,
+    # WebSocket types
+    WsChannel,
+    WsConnectionState,
+    WsSubscribed,
+    WsUnsubscribed,
+    WsPong,
+    WsError,
+    WsData,
+    # Replay types (Option B)
+    WsReplayStarted,
+    WsReplayPaused,
+    WsReplayResumed,
+    WsReplayCompleted,
+    WsReplayStopped,
+    WsHistoricalData,
+    # Stream types (Option D)
+    WsStreamStarted,
+    WsStreamProgress,
+    WsHistoricalBatch,
+    WsStreamCompleted,
+    WsStreamStopped,
+    TimestampedRecord,
+)
+
+# WebSocket client (optional import - requires websockets package)
+try:
+    from .websocket import OxArchiveWs, WsOptions
+    _HAS_WEBSOCKET = True
+except ImportError:
+    _HAS_WEBSOCKET = False
+    OxArchiveWs = None  # type: ignore
+    WsOptions = None  # type: ignore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Client
+    "Client",
+    # WebSocket Client
+    "OxArchiveWs",
+    "WsOptions",
+    # Types
+    "OrderBook",
+    "Trade",
+    "Candle",
+    "CandleInterval",
+    "Instrument",
+    "FundingRate",
+    "OpenInterest",
+    "OxArchiveError",
+    # WebSocket Types
+    "WsChannel",
+    "WsConnectionState",
+    "WsSubscribed",
+    "WsUnsubscribed",
+    "WsPong",
+    "WsError",
+    "WsData",
+    # Replay Types (Option B)
+    "WsReplayStarted",
+    "WsReplayPaused",
+    "WsReplayResumed",
+    "WsReplayCompleted",
+    "WsReplayStopped",
+    "WsHistoricalData",
+    # Stream Types (Option D)
+    "WsStreamStarted",
+    "WsStreamProgress",
+    "WsHistoricalBatch",
+    "WsStreamCompleted",
+    "WsStreamStopped",
+    "TimestampedRecord",
+]

oxarchive/client.py

@@ -0,0 +1,114 @@
+"""0xarchive API client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .http import HttpClient
+from .resources import (
+    OrderBookResource,
+    TradesResource,
+    CandlesResource,
+    InstrumentsResource,
+    FundingResource,
+    OpenInterestResource,
+)
+
+DEFAULT_BASE_URL = "https://api.0xarchive.io"
+DEFAULT_TIMEOUT = 30.0
+
+
+class Client:
+    """
+    0xarchive API client.
+
+    Example:
+        >>> from oxarchive import Client
+        >>>
+        >>> client = Client(api_key="ox_your_api_key")
+        >>>
+        >>> # Get current order book
+        >>> orderbook = client.orderbook.get("BTC")
+        >>> print(f"BTC mid price: {orderbook.mid_price}")
+        >>>
+        >>> # Get historical snapshots
+        >>> history = client.orderbook.history("ETH", start="2024-01-01", end="2024-01-02")
+        >>>
+        >>> # List all instruments
+        >>> instruments = client.instruments.list()
+
+    Async example:
+        >>> import asyncio
+        >>> from oxarchive import Client
+        >>>
+        >>> async def main():
+        ...     client = Client(api_key="ox_your_api_key")
+        ...     orderbook = await client.orderbook.aget("BTC")
+        ...     print(f"BTC mid price: {orderbook.mid_price}")
+        ...     await client.aclose()
+        >>>
+        >>> asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ):
+        """
+        Create a new 0xarchive client.
+
+        Args:
+            api_key: Your 0xarchive API key
+            base_url: Base URL for the API (defaults to https://api.0xarchive.io)
+            timeout: Request timeout in seconds (defaults to 30.0)
+        """
+        if not api_key:
+            raise ValueError("API key is required. Get one at https://0xarchive.io/signup")
+
+        self._http = HttpClient(
+            base_url=base_url or DEFAULT_BASE_URL,
+            api_key=api_key,
+            timeout=timeout or DEFAULT_TIMEOUT,
+        )
+
+        # Initialize resource namespaces
+        self.orderbook = OrderBookResource(self._http)
+        """Order book data (L2 snapshots from April 2023)"""
+
+        self.trades = TradesResource(self._http)
+        """Trade/fill history"""
+
+        self.candles = CandlesResource(self._http)
+        """OHLCV candles"""
+
+        self.instruments = InstrumentsResource(self._http)
+        """Trading instruments metadata"""
+
+        self.funding = FundingResource(self._http)
+        """Funding rates"""
+
+        self.open_interest = OpenInterestResource(self._http)
+        """Open interest"""
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        self._http.close()
+
+    async def aclose(self) -> None:
+        """Close the async HTTP client and release resources."""
+        await self._http.aclose()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    async def __aenter__(self) -> "Client":
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.aclose()

oxarchive/http.py

@@ -0,0 +1,108 @@
+"""HTTP client for the 0xarchive API."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, TypeVar, Type
+import httpx
+from pydantic import BaseModel
+
+from .types import OxArchiveError
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class HttpClient:
+    """Internal HTTP client for making API requests."""
+
+    def __init__(self, base_url: str, api_key: str, timeout: float):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._client: Optional[httpx.Client] = None
+        self._async_client: Optional[httpx.AsyncClient] = None
+
+    def _get_headers(self) -> dict[str, str]:
+        return {
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json",
+        }
+
+    @property
+    def client(self) -> httpx.Client:
+        """Get or create the sync HTTP client."""
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                headers=self._get_headers(),
+                timeout=self.timeout,
+            )
+        return self._client
+
+    @property
+    def async_client(self) -> httpx.AsyncClient:
+        """Get or create the async HTTP client."""
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=self._get_headers(),
+                timeout=self.timeout,
+            )
+        return self._async_client
+
+    def close(self) -> None:
+        """Close the HTTP clients."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+        if self._async_client is not None:
+            # Note: async client should be closed with await
+            pass
+
+    async def aclose(self) -> None:
+        """Close the async HTTP client."""
+        if self._async_client is not None:
+            await self._async_client.aclose()
+            self._async_client = None
+
+    def _handle_response(self, response: httpx.Response) -> dict[str, Any]:
+        """Handle the API response and raise errors if needed."""
+        try:
+            data = response.json()
+        except Exception:
+            raise OxArchiveError(
+                f"Invalid JSON response: {response.text[:200]}",
+                response.status_code,
+            )
+
+        if not response.is_success:
+            error_msg = data.get("error", f"Request failed with status {response.status_code}")
+            request_id = data.get("request_id")
+            raise OxArchiveError(error_msg, response.status_code, request_id)
+
+        return data
+
+    def get(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Make a synchronous GET request."""
+        # Filter out None values from params
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        response = self.client.get(path, params=params)
+        return self._handle_response(response)
+
+    async def aget(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Make an asynchronous GET request."""
+        # Filter out None values from params
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        response = await self.async_client.get(path, params=params)
+        return self._handle_response(response)

oxarchive/resources/__init__.py

@@ -0,0 +1,17 @@
+"""Resource modules."""
+
+from .orderbook import OrderBookResource
+from .trades import TradesResource
+from .candles import CandlesResource
+from .instruments import InstrumentsResource
+from .funding import FundingResource
+from .openinterest import OpenInterestResource
+
+__all__ = [
+    "OrderBookResource",
+    "TradesResource",
+    "CandlesResource",
+    "InstrumentsResource",
+    "FundingResource",
+    "OpenInterestResource",
+]

oxarchive/resources/candles.py

@@ -0,0 +1,100 @@
+"""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/resources/funding.py

@@ -0,0 +1,113 @@
+"""Funding rates API resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from ..http import HttpClient
+from ..types import FundingRate, Timestamp
+
+
+class FundingResource:
+    """
+    Funding rates API resource.
+
+    Example:
+        >>> # Get current funding rate
+        >>> current = client.funding.current("BTC")
+        >>>
+        >>> # Get funding rate history
+        >>> history = client.funding.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[FundingRate]:
+        """
+        Get funding rate 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 funding rate records
+        """
+        data = self._http.get(
+            f"/v1/funding/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+        return [FundingRate.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[FundingRate]:
+        """Async version of history()."""
+        data = await self._http.aget(
+            f"/v1/funding/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+        return [FundingRate.model_validate(item) for item in data["data"]]
+
+    def current(self, coin: str) -> FundingRate:
+        """
+        Get current funding rate for a coin.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+
+        Returns:
+            Current funding rate
+        """
+        data = self._http.get(f"/v1/funding/{coin.upper()}/current")
+        return FundingRate.model_validate(data["data"])
+
+    async def acurrent(self, coin: str) -> FundingRate:
+        """Async version of current()."""
+        data = await self._http.aget(f"/v1/funding/{coin.upper()}/current")
+        return FundingRate.model_validate(data["data"])

oxarchive/resources/instruments.py

@@ -0,0 +1,55 @@
+"""Instruments API resource."""
+
+from __future__ import annotations
+
+from ..http import HttpClient
+from ..types import Instrument
+
+
+class InstrumentsResource:
+    """
+    Instruments API resource.
+
+    Example:
+        >>> # List all instruments
+        >>> instruments = client.instruments.list()
+        >>>
+        >>> # Get specific instrument
+        >>> btc = client.instruments.get("BTC")
+    """
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def list(self) -> list[Instrument]:
+        """
+        List all available trading instruments.
+
+        Returns:
+            List of instruments
+        """
+        data = self._http.get("/v1/instruments")
+        return [Instrument.model_validate(item) for item in data["data"]]
+
+    async def alist(self) -> list[Instrument]:
+        """Async version of list()."""
+        data = await self._http.aget("/v1/instruments")
+        return [Instrument.model_validate(item) for item in data["data"]]
+
+    def get(self, coin: str) -> Instrument:
+        """
+        Get a specific instrument by coin symbol.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+
+        Returns:
+            Instrument details
+        """
+        data = self._http.get(f"/v1/instruments/{coin.upper()}")
+        return Instrument.model_validate(data["data"])
+
+    async def aget(self, coin: str) -> Instrument:
+        """Async version of get()."""
+        data = await self._http.aget(f"/v1/instruments/{coin.upper()}")
+        return Instrument.model_validate(data["data"])