oxarchive 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

oxarchive/__init__.py

@@ -67,7 +67,7 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.5.0"
+__version__ = "0.5.2"
 
 __all__ = [
     # Client

oxarchive/exchanges.py

@@ -11,6 +11,7 @@ from .resources import (
     FundingResource,
     OpenInterestResource,
     CandlesResource,
+    LiquidationsResource,
 )
 
 
@@ -48,6 +49,9 @@ class HyperliquidClient:
         self.candles = CandlesResource(http, base_path)
         """OHLCV candle data"""
 
+        self.liquidations = LiquidationsResource(http, base_path)
+        """Liquidation events (May 2025+)"""
+
 
 class LighterClient:
     """

oxarchive/resources/__init__.py

@@ -6,6 +6,7 @@ from .instruments import InstrumentsResource, LighterInstrumentsResource
 from .funding import FundingResource
 from .openinterest import OpenInterestResource
 from .candles import CandlesResource
+from .liquidations import LiquidationsResource
 
 __all__ = [
     "OrderBookResource",
@@ -15,4 +16,5 @@ __all__ = [
     "FundingResource",
     "OpenInterestResource",
     "CandlesResource",
+    "LiquidationsResource",
 ]

oxarchive/resources/liquidations.py

@@ -0,0 +1,198 @@
+"""Liquidations API resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from ..http import HttpClient
+from ..types import CursorResponse, Liquidation, Timestamp
+
+
+class LiquidationsResource:
+    """
+    Liquidations API resource.
+
+    Retrieve historical liquidation events from Hyperliquid.
+
+    Note: Liquidation data is available from May 25, 2025 onwards.
+
+    Example:
+        >>> # Get recent liquidations
+        >>> liquidations = client.hyperliquid.liquidations.history(
+        ...     "BTC",
+        ...     start="2025-06-01",
+        ...     end="2025-06-02"
+        ... )
+        >>>
+        >>> # Get liquidations for a specific user
+        >>> user_liquidations = client.hyperliquid.liquidations.by_user(
+        ...     "0x1234...",
+        ...     start="2025-06-01",
+        ...     end="2025-06-02"
+        ... )
+    """
+
+    def __init__(self, http: HttpClient, base_path: str = "/v1"):
+        self._http = http
+        self._base_path = base_path
+
+    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: Timestamp,
+        end: Timestamp,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> CursorResponse[list[Liquidation]]:
+        """
+        Get liquidation history for a coin with cursor-based pagination.
+
+        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
+            limit: Maximum number of results (default: 100, max: 1000)
+
+        Returns:
+            CursorResponse with liquidation records and next_cursor for pagination
+
+        Example:
+            >>> result = client.hyperliquid.liquidations.history("BTC", start=start, end=end, limit=1000)
+            >>> liquidations = result.data
+            >>> while result.next_cursor:
+            ...     result = client.hyperliquid.liquidations.history(
+            ...         "BTC", start=start, end=end, cursor=result.next_cursor, limit=1000
+            ...     )
+            ...     liquidations.extend(result.data)
+        """
+        data = self._http.get(
+            f"{self._base_path}/liquidations/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "cursor": cursor,
+                "limit": limit,
+            },
+        )
+        return CursorResponse(
+            data=[Liquidation.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
+
+    async def ahistory(
+        self,
+        coin: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> CursorResponse[list[Liquidation]]:
+        """Async version of history(). start and end are required."""
+        data = await self._http.aget(
+            f"{self._base_path}/liquidations/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "cursor": cursor,
+                "limit": limit,
+            },
+        )
+        return CursorResponse(
+            data=[Liquidation.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
+
+    def by_user(
+        self,
+        user_address: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        coin: Optional[str] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> CursorResponse[list[Liquidation]]:
+        """
+        Get liquidation history for a specific user.
+
+        This returns liquidations where the user was either:
+        - The liquidated party (their position was liquidated)
+        - The liquidator (they executed the liquidation)
+
+        Args:
+            user_address: User's wallet address (e.g., '0x1234...')
+            start: Start timestamp (required)
+            end: End timestamp (required)
+            coin: Optional coin filter (e.g., 'BTC', 'ETH')
+            cursor: Cursor from previous response's next_cursor
+            limit: Maximum number of results (default: 100, max: 1000)
+
+        Returns:
+            CursorResponse with liquidation records and next_cursor for pagination
+        """
+        params = {
+            "start": self._convert_timestamp(start),
+            "end": self._convert_timestamp(end),
+            "cursor": cursor,
+            "limit": limit,
+        }
+        if coin:
+            params["coin"] = coin.upper()
+
+        data = self._http.get(
+            f"{self._base_path}/liquidations/user/{user_address}",
+            params=params,
+        )
+        return CursorResponse(
+            data=[Liquidation.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
+
+    async def aby_user(
+        self,
+        user_address: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        coin: Optional[str] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> CursorResponse[list[Liquidation]]:
+        """Async version of by_user()."""
+        params = {
+            "start": self._convert_timestamp(start),
+            "end": self._convert_timestamp(end),
+            "cursor": cursor,
+            "limit": limit,
+        }
+        if coin:
+            params["coin"] = coin.upper()
+
+        data = await self._http.aget(
+            f"{self._base_path}/liquidations/user/{user_address}",
+            params=params,
+        )
+        return CursorResponse(
+            data=[Liquidation.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )

oxarchive/types.py

@@ -270,6 +270,51 @@ class OpenInterest(BaseModel):
     """Impact ask price for liquidations."""
 
 
+# =============================================================================
+# Liquidation Types
+# =============================================================================
+
+
+class Liquidation(BaseModel):
+    """Liquidation event record."""
+
+    coin: str
+    """Trading pair symbol."""
+
+    timestamp: datetime
+    """Liquidation timestamp (UTC)."""
+
+    liquidated_user: str
+    """Address of the liquidated user."""
+
+    liquidator_user: str
+    """Address of the liquidator."""
+
+    price: str
+    """Liquidation execution price."""
+
+    size: str
+    """Liquidation size."""
+
+    side: Literal["B", "S"]
+    """Side: 'B' (buy) or 'S' (sell)."""
+
+    mark_price: Optional[str] = None
+    """Mark price at time of liquidation."""
+
+    closed_pnl: Optional[str] = None
+    """Realized PnL from the liquidation."""
+
+    direction: Optional[str] = None
+    """Position direction (e.g., 'Open Long', 'Close Short')."""
+
+    trade_id: Optional[int] = None
+    """Unique trade ID."""
+
+    tx_hash: Optional[str] = None
+    """Blockchain transaction hash."""
+
+
 # =============================================================================
 # Candle Types
 # =============================================================================
@@ -311,8 +356,8 @@ class Candle(BaseModel):
 # WebSocket Types
 # =============================================================================
 
-WsChannel = Literal["orderbook", "trades", "candles", "ticker", "all_tickers"]
-"""Available WebSocket channels. Note: ticker/all_tickers are real-time only."""
+WsChannel = Literal["orderbook", "trades", "candles", "liquidations", "ticker", "all_tickers"]
+"""Available WebSocket channels. Note: ticker/all_tickers are real-time only. Liquidations is historical only (May 2025+)."""
 
 WsConnectionState = Literal["connecting", "connected", "disconnected", "reconnecting"]
 """WebSocket connection state."""

oxarchive/websocket.py

@@ -434,6 +434,7 @@ class OxArchiveWs:
         end: Optional[int] = None,
         speed: float = 1.0,
         granularity: Optional[str] = None,
+        interval: Optional[str] = None,
     ) -> None:
         """Start historical replay with timing preserved.
 
@@ -444,9 +445,11 @@ class OxArchiveWs:
             end: End timestamp (Unix ms, defaults to now)
             speed: Playback speed multiplier (1 = real-time, 10 = 10x faster)
             granularity: Data resolution for Lighter orderbook ('checkpoint', '30s', '10s', '1s', 'tick')
+            interval: Candle interval for candles channel ('1m', '5m', '15m', '30m', '1h', '4h', '1d', '1w')
 
         Example:
             >>> await ws.replay("orderbook", "BTC", start=time.time()*1000 - 86400000, speed=10)
+            >>> await ws.replay("candles", "BTC", start=..., speed=10, interval="15m")
         """
         msg = {
             "op": "replay",
@@ -459,6 +462,8 @@ class OxArchiveWs:
             msg["end"] = end
         if granularity is not None:
             msg["granularity"] = granularity
+        if interval is not None:
+            msg["interval"] = interval
         await self._send(msg)
 
     async def replay_pause(self) -> None:
@@ -493,6 +498,7 @@ class OxArchiveWs:
         end: int,
         batch_size: int = 1000,
         granularity: Optional[str] = None,
+        interval: Optional[str] = None,
     ) -> None:
         """Start bulk streaming for fast data download.
 
@@ -503,9 +509,11 @@ class OxArchiveWs:
             end: End timestamp (Unix ms)
             batch_size: Records per batch message
             granularity: Data resolution for Lighter orderbook ('checkpoint', '30s', '10s', '1s', 'tick')
+            interval: Candle interval for candles channel ('1m', '5m', '15m', '30m', '1h', '4h', '1d', '1w')
 
         Example:
             >>> await ws.stream("orderbook", "ETH", start=..., end=..., batch_size=1000)
+            >>> await ws.stream("candles", "BTC", start=..., end=..., interval="1h")
         """
         msg = {
             "op": "stream",
@@ -517,6 +525,8 @@ class OxArchiveWs:
         }
         if granularity is not None:
             msg["granularity"] = granularity
+        if interval is not None:
+            msg["interval"] = interval
         await self._send(msg)
 
     async def stream_stop(self) -> None:

{oxarchive-0.5.0.dist-info → oxarchive-0.5.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.5.0
+Version: 0.5.2
 Summary: Official Python SDK for 0xarchive - Hyperliquid Historical Data API
 Project-URL: Homepage, https://0xarchive.io
 Project-URL: Documentation, https://0xarchive.io/docs/sdks

{oxarchive-0.5.0.dist-info → oxarchive-0.5.2.dist-info}/RECORD

@@ -1,16 +1,17 @@
-oxarchive/__init__.py,sha256=aBWv7E8wXOkAzpkf110EKknGLqTcUFToTzaOwoJn7fc,2738
+oxarchive/__init__.py,sha256=Y9i6Ev_nR_cA1CUMTd2JXQPOBSd00LFQ41-BlR3-NsM,2738
 oxarchive/client.py,sha256=XWQ_VEBQy3UIAnmZQ-Z_FyzXnvMA3FITwtinBOf3o-Y,4453
-oxarchive/exchanges.py,sha256=ozw_eDGnzyb7D5HKMo2Hfl7-dIcVKSXJCyFlFIhiaos,2631
+oxarchive/exchanges.py,sha256=nTd0gRrgV2wDoptWWxwh38HXkCcunVNuNdNEwzNDsBM,2773
 oxarchive/http.py,sha256=SY_o9Ag8ADo1HI3i3uAKW1xwkYjPE75gRAjnMsddAGs,4211
-oxarchive/types.py,sha256=LX5Usgn6RgUoS6l48ufQW2zKjzH1C3xjlV5UbsEp2fY,14293
-oxarchive/websocket.py,sha256=sdKMJrmGeR_ApNP_c7TPJylc4DAkmrp1JXfpnRGynao,29985
-oxarchive/resources/__init__.py,sha256=pFCP01qP6g9A9Dbzn-lGgF0i6x8GhGlwmwpOXGg3UWM,510
+oxarchive/types.py,sha256=tfL6QG2WTBe4cdgk5TAbgpTRGAQALvhPTADH9umqd4g,15463
+oxarchive/websocket.py,sha256=sS-kLDKv2qS77-61hXChRePjL_hz-URcALM9UW5zxXU,30609
+oxarchive/resources/__init__.py,sha256=JyNkR6dKBOGPQpYAuG6Qy1lDMCxJ68dXNLUAOua1Vs8,587
 oxarchive/resources/candles.py,sha256=GI7-YSNFckEd1i49W9mlrLn1cl955sY8ki0u12TuLgw,4449
 oxarchive/resources/funding.py,sha256=ybMWkpoccrkdwnd6W3oHgsaor7cBcA2nkYy4CbjmHUg,4485
 oxarchive/resources/instruments.py,sha256=6q7rMdIaixXgFVXgwQsVd-YuO7RIXr1oGPT5jBsqI9A,3733
+oxarchive/resources/liquidations.py,sha256=kX3mEX2u6uEvgk1aKfL4U0JE9gOjJOwsLVpkIj84arE,6741
 oxarchive/resources/openinterest.py,sha256=whwo60KFNLGwvVrDmDYYc-rMZr35Fcizb5Iil-DSvD8,4553
 oxarchive/resources/orderbook.py,sha256=NzgKH45MBb2oAHyPmy6BSikaYyq0nM-8GFjur9LIRN8,6661
 oxarchive/resources/trades.py,sha256=t4iicyi1waaHzC7Q_cC-c7O4yVx1vqS4eMH8F8_5hxk,5503
-oxarchive-0.5.0.dist-info/METADATA,sha256=9-HN2MR1BRnmavdrtsFgC9FH_PawOysBey3YzneIzwo,17974
-oxarchive-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-oxarchive-0.5.0.dist-info/RECORD,,
+oxarchive-0.5.2.dist-info/METADATA,sha256=y29y_zkpyTPlMNSbXQsOpIuK4v1Zp8k5cYHewJlSTcg,17974
+oxarchive-0.5.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oxarchive-0.5.2.dist-info/RECORD,,