oxarchive 0.5.1__py3-none-any.whl → 0.5.3__py3-none-any.whl

oxarchive/__init__.py

@@ -67,7 +67,7 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.5.1"
+__version__ = "0.5.3"
 
 __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/resources/trades.py

@@ -14,17 +14,17 @@ class TradesResource:
     Trades API resource.
 
     Example:
-        >>> # Get recent trades
-        >>> trades = client.trades.recent("BTC")
-        >>>
         >>> # Get trade history with cursor-based pagination (recommended)
-        >>> result = client.trades.list("BTC", start="2024-01-01", end="2024-01-02")
+        >>> result = client.hyperliquid.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)
+        ...     result = client.hyperliquid.trades.list("BTC", start="2024-01-01", end="2024-01-02", cursor=result.next_cursor)
         ...     trades.extend(result.data)
+        >>>
+        >>> # Get recent trades (Lighter only - has real-time data)
+        >>> recent = client.lighter.trades.recent("BTC")
     """
 
     def __init__(self, http: HttpClient, base_path: str = "/v1"):
@@ -135,6 +135,10 @@ class TradesResource:
         """
         Get most recent trades for a coin.
 
+        Note: This method is only available for Lighter (client.lighter.trades.recent())
+        which has real-time data ingestion. Hyperliquid uses hourly backfill so this
+        endpoint is not available for Hyperliquid.
+
         Args:
             coin: The coin symbol (e.g., 'BTC', 'ETH')
             limit: Number of trades to return (default: 100)

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-0.5.1.dist-info → oxarchive-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.5.1
+Version: 0.5.3
 Summary: Official Python SDK for 0xarchive - Hyperliquid Historical Data API
 Project-URL: Homepage, https://0xarchive.io
 Project-URL: Documentation, https://0xarchive.io/docs/sdks
@@ -211,9 +211,6 @@ history = client.lighter.orderbook.history(
 The trades API uses cursor-based pagination for efficient retrieval of large datasets.
 
 ```python
-# Get recent trades
-recent = client.hyperliquid.trades.recent("BTC", limit=100)
-
 # Get trade history with cursor-based pagination
 result = client.hyperliquid.trades.list("ETH", start="2024-01-01", end="2024-01-02", limit=1000)
 trades = result.data
@@ -232,8 +229,7 @@ while result.next_cursor:
 # Filter by side
 buys = client.hyperliquid.trades.list("BTC", start=..., end=..., side="buy")
 
-# Async versions
-recent = await client.hyperliquid.trades.arecent("BTC")
+# Async version
 result = await client.hyperliquid.trades.alist("ETH", start=..., end=...)
 ```
 
@@ -641,9 +637,11 @@ from oxarchive.resources.trades import CursorResponse
 
 client = Client(api_key="ox_your_api_key")
 
-orderbook: OrderBook = client.orderbook.get("BTC")
-trades: list[Trade] = client.trades.recent("BTC")
-result: CursorResponse = client.trades.list("BTC", start=..., end=...)
+orderbook: OrderBook = client.hyperliquid.orderbook.get("BTC")
+result: CursorResponse = client.hyperliquid.trades.list("BTC", start=..., end=...)
+
+# Lighter has real-time data, so recent() is available
+recent: list[Trade] = client.lighter.trades.recent("BTC")
 
 # Lighter granularity type hint
 granularity: LighterGranularity = "10s"

{oxarchive-0.5.1.dist-info → oxarchive-0.5.3.dist-info}/RECORD

@@ -1,16 +1,17 @@
-oxarchive/__init__.py,sha256=8-68R4dD9xFfeUQ1yAuy1IadC10el1QRBNJOn3DXMfA,2738
+oxarchive/__init__.py,sha256=-TIv-IqajJ0h3W4QyZsnBKb-PLc3hrRcsz54ynKA_hw,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/types.py,sha256=tfL6QG2WTBe4cdgk5TAbgpTRGAQALvhPTADH9umqd4g,15463
 oxarchive/websocket.py,sha256=sS-kLDKv2qS77-61hXChRePjL_hz-URcALM9UW5zxXU,30609
-oxarchive/resources/__init__.py,sha256=pFCP01qP6g9A9Dbzn-lGgF0i6x8GhGlwmwpOXGg3UWM,510
+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.1.dist-info/METADATA,sha256=iR7PKuDuF89N-I5b1QqcNyZNKr-OI2tJXBirT1-tYTU,17974
-oxarchive-0.5.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-oxarchive-0.5.1.dist-info/RECORD,,
+oxarchive/resources/trades.py,sha256=RhOTbhqSSBAaekden6rLY8qJL-NDArGTqCempvUbX08,5801
+oxarchive-0.5.3.dist-info/METADATA,sha256=a134ZFK2iEmo5UPDAI2sw3ZcqpqjzVphjSKGUS2-4LA,17924
+oxarchive-0.5.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oxarchive-0.5.3.dist-info/RECORD,,