oxarchive 0.4.4__tar.gz → 0.5.3__tar.gz

{oxarchive-0.4.4 → oxarchive-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.4.4
+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=...)
 ```
 
@@ -317,6 +313,57 @@ current = await client.hyperliquid.open_interest.acurrent("BTC")
 history = await client.hyperliquid.open_interest.ahistory("ETH", start=..., end=...)
 ```
 
+### Candles (OHLCV)
+
+Get historical OHLCV candle data aggregated from trades.
+
+```python
+# Get candle history (start is required)
+candles = client.hyperliquid.candles.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    interval="1h",  # 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w
+    limit=100
+)
+
+# Iterate through candles
+for candle in candles.data:
+    print(f"{candle.timestamp}: O={candle.open} H={candle.high} L={candle.low} C={candle.close} V={candle.volume}")
+
+# Cursor-based pagination for large datasets
+result = client.hyperliquid.candles.history("BTC", start=..., end=..., interval="1m", limit=1000)
+while result.next_cursor:
+    result = client.hyperliquid.candles.history(
+        "BTC", start=..., end=..., interval="1m",
+        cursor=result.next_cursor, limit=1000
+    )
+
+# Lighter.xyz candles
+lighter_candles = client.lighter.candles.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    interval="15m"
+)
+
+# Async versions
+candles = await client.hyperliquid.candles.ahistory("BTC", start=..., end=..., interval="1h")
+```
+
+#### Available Intervals
+
+| Interval | Description |
+|----------|-------------|
+| `1m` | 1 minute |
+| `5m` | 5 minutes |
+| `15m` | 15 minutes |
+| `30m` | 30 minutes |
+| `1h` | 1 hour (default) |
+| `4h` | 4 hours |
+| `1d` | 1 day |
+| `1w` | 1 week |
+
 ### Legacy API (Deprecated)
 
 The following legacy methods are deprecated and will be removed in v2.0. They default to Hyperliquid data:
@@ -418,6 +465,19 @@ async def main():
         speed=10                                     # Optional, defaults to 1x
     )
 
+    # Lighter.xyz replay with granularity (tier restrictions apply)
+    await ws.replay(
+        "orderbook", "BTC",
+        start=int(time.time() * 1000) - 86400000,
+        speed=10,
+        granularity="10s"  # Options: 'checkpoint', '30s', '10s', '1s', 'tick'
+    )
+
+    # Handle tick-level data (granularity='tick', Enterprise tier)
+    ws.on_historical_tick_data(lambda coin, checkpoint, deltas:
+        print(f"Checkpoint: {len(checkpoint['bids'])} bids, Deltas: {len(deltas)}")
+    )
+
     # Control playback
     await ws.replay_pause()
     await ws.replay_resume()
@@ -463,6 +523,14 @@ async def main():
         batch_size=1000                            # Optional, defaults to 1000
     )
 
+    # Lighter.xyz stream with granularity (tier restrictions apply)
+    await ws.stream(
+        "orderbook", "BTC",
+        start=int(time.time() * 1000) - 3600000,
+        end=int(time.time() * 1000),
+        granularity="10s"  # Options: 'checkpoint', '30s', '10s', '1s', 'tick'
+    )
+
     # Stop if needed
     await ws.stream_stop()
 
@@ -484,12 +552,43 @@ ws = OxArchiveWs(WsOptions(
 
 ### Available Channels
 
-| Channel | Description | Requires Coin |
-|---------|-------------|---------------|
-| `orderbook` | L2 order book updates | Yes |
-| `trades` | Trade/fill updates | Yes |
-| `ticker` | Price and 24h volume | Yes |
-| `all_tickers` | All market tickers | No |
+| Channel | Description | Requires Coin | Historical Support |
+|---------|-------------|---------------|-------------------|
+| `orderbook` | L2 order book updates | Yes | Yes |
+| `trades` | Trade/fill updates | Yes | Yes |
+| `candles` | OHLCV candle data | Yes | Yes (replay/stream only) |
+| `ticker` | Price and 24h volume | Yes | Real-time only |
+| `all_tickers` | All market tickers | No | Real-time only |
+
+#### Candle Replay/Stream
+
+```python
+# Replay candles at 10x speed
+await ws.replay(
+    "candles", "BTC",
+    start=int(time.time() * 1000) - 86400000,
+    end=int(time.time() * 1000),
+    speed=10,
+    interval="15m"  # 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w
+)
+
+# Bulk stream candles
+await ws.stream(
+    "candles", "ETH",
+    start=int(time.time() * 1000) - 3600000,
+    end=int(time.time() * 1000),
+    batch_size=1000,
+    interval="1h"
+)
+
+# Lighter.xyz candles
+await ws.replay(
+    "lighter_candles", "BTC",
+    start=...,
+    speed=10,
+    interval="5m"
+)
+```
 
 ## Timestamp Formats
 
@@ -538,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.4.4 → oxarchive-0.5.3}/README.md

@@ -174,9 +174,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
@@ -195,8 +192,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=...)
 ```
 
@@ -280,6 +276,57 @@ current = await client.hyperliquid.open_interest.acurrent("BTC")
 history = await client.hyperliquid.open_interest.ahistory("ETH", start=..., end=...)
 ```
 
+### Candles (OHLCV)
+
+Get historical OHLCV candle data aggregated from trades.
+
+```python
+# Get candle history (start is required)
+candles = client.hyperliquid.candles.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    interval="1h",  # 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w
+    limit=100
+)
+
+# Iterate through candles
+for candle in candles.data:
+    print(f"{candle.timestamp}: O={candle.open} H={candle.high} L={candle.low} C={candle.close} V={candle.volume}")
+
+# Cursor-based pagination for large datasets
+result = client.hyperliquid.candles.history("BTC", start=..., end=..., interval="1m", limit=1000)
+while result.next_cursor:
+    result = client.hyperliquid.candles.history(
+        "BTC", start=..., end=..., interval="1m",
+        cursor=result.next_cursor, limit=1000
+    )
+
+# Lighter.xyz candles
+lighter_candles = client.lighter.candles.history(
+    "BTC",
+    start="2024-01-01",
+    end="2024-01-02",
+    interval="15m"
+)
+
+# Async versions
+candles = await client.hyperliquid.candles.ahistory("BTC", start=..., end=..., interval="1h")
+```
+
+#### Available Intervals
+
+| Interval | Description |
+|----------|-------------|
+| `1m` | 1 minute |
+| `5m` | 5 minutes |
+| `15m` | 15 minutes |
+| `30m` | 30 minutes |
+| `1h` | 1 hour (default) |
+| `4h` | 4 hours |
+| `1d` | 1 day |
+| `1w` | 1 week |
+
 ### Legacy API (Deprecated)
 
 The following legacy methods are deprecated and will be removed in v2.0. They default to Hyperliquid data:
@@ -381,6 +428,19 @@ async def main():
         speed=10                                     # Optional, defaults to 1x
     )
 
+    # Lighter.xyz replay with granularity (tier restrictions apply)
+    await ws.replay(
+        "orderbook", "BTC",
+        start=int(time.time() * 1000) - 86400000,
+        speed=10,
+        granularity="10s"  # Options: 'checkpoint', '30s', '10s', '1s', 'tick'
+    )
+
+    # Handle tick-level data (granularity='tick', Enterprise tier)
+    ws.on_historical_tick_data(lambda coin, checkpoint, deltas:
+        print(f"Checkpoint: {len(checkpoint['bids'])} bids, Deltas: {len(deltas)}")
+    )
+
     # Control playback
     await ws.replay_pause()
     await ws.replay_resume()
@@ -426,6 +486,14 @@ async def main():
         batch_size=1000                            # Optional, defaults to 1000
     )
 
+    # Lighter.xyz stream with granularity (tier restrictions apply)
+    await ws.stream(
+        "orderbook", "BTC",
+        start=int(time.time() * 1000) - 3600000,
+        end=int(time.time() * 1000),
+        granularity="10s"  # Options: 'checkpoint', '30s', '10s', '1s', 'tick'
+    )
+
     # Stop if needed
     await ws.stream_stop()
 
@@ -447,12 +515,43 @@ ws = OxArchiveWs(WsOptions(
 
 ### Available Channels
 
-| Channel | Description | Requires Coin |
-|---------|-------------|---------------|
-| `orderbook` | L2 order book updates | Yes |
-| `trades` | Trade/fill updates | Yes |
-| `ticker` | Price and 24h volume | Yes |
-| `all_tickers` | All market tickers | No |
+| Channel | Description | Requires Coin | Historical Support |
+|---------|-------------|---------------|-------------------|
+| `orderbook` | L2 order book updates | Yes | Yes |
+| `trades` | Trade/fill updates | Yes | Yes |
+| `candles` | OHLCV candle data | Yes | Yes (replay/stream only) |
+| `ticker` | Price and 24h volume | Yes | Real-time only |
+| `all_tickers` | All market tickers | No | Real-time only |
+
+#### Candle Replay/Stream
+
+```python
+# Replay candles at 10x speed
+await ws.replay(
+    "candles", "BTC",
+    start=int(time.time() * 1000) - 86400000,
+    end=int(time.time() * 1000),
+    speed=10,
+    interval="15m"  # 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w
+)
+
+# Bulk stream candles
+await ws.stream(
+    "candles", "ETH",
+    start=int(time.time() * 1000) - 3600000,
+    end=int(time.time() * 1000),
+    batch_size=1000,
+    interval="1h"
+)
+
+# Lighter.xyz candles
+await ws.replay(
+    "lighter_candles", "BTC",
+    start=...,
+    speed=10,
+    interval="5m"
+)
+```
 
 ## Timestamp Formats
 
@@ -501,9 +600,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.4.4 → oxarchive-0.5.3}/oxarchive/__init__.py

@@ -31,6 +31,8 @@ from .types import (
     LighterInstrument,
     FundingRate,
     OpenInterest,
+    Candle,
+    CandleInterval,
     OxArchiveError,
     # WebSocket types
     WsChannel,
@@ -65,7 +67,7 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.4.4"
+__version__ = "0.5.3"
 
 __all__ = [
     # Client
@@ -84,6 +86,8 @@ __all__ = [
     "LighterGranularity",
     "FundingRate",
     "OpenInterest",
+    "Candle",
+    "CandleInterval",
     "OxArchiveError",
     # WebSocket Types
     "WsChannel",

{oxarchive-0.4.4 → oxarchive-0.5.3}/oxarchive/exchanges.py

@@ -10,6 +10,8 @@ from .resources import (
     LighterInstrumentsResource,
     FundingResource,
     OpenInterestResource,
+    CandlesResource,
+    LiquidationsResource,
 )
 
 
@@ -44,6 +46,12 @@ class HyperliquidClient:
         self.open_interest = OpenInterestResource(http, base_path)
         """Open interest"""
 
+        self.candles = CandlesResource(http, base_path)
+        """OHLCV candle data"""
+
+        self.liquidations = LiquidationsResource(http, base_path)
+        """Liquidation events (May 2025+)"""
+
 
 class LighterClient:
     """
@@ -77,3 +85,6 @@ class LighterClient:
 
         self.open_interest = OpenInterestResource(http, base_path)
         """Open interest"""
+
+        self.candles = CandlesResource(http, base_path)
+        """OHLCV candle data"""

{oxarchive-0.4.4 → oxarchive-0.5.3}/oxarchive/resources/__init__.py

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

oxarchive-0.5.3/oxarchive/resources/candles.py

@@ -0,0 +1,121 @@
+"""Candles (OHLCV) API resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from ..http import HttpClient
+from ..types import Candle, CandleInterval, CursorResponse, Timestamp
+
+
+class CandlesResource:
+    """
+    Candles (OHLCV) API resource.
+
+    Example:
+        >>> # Get candle history
+        >>> result = client.candles.history("BTC", start=start, end=end, interval="1h")
+        >>> for candle in result.data:
+        ...     print(f"{candle.timestamp}: O={candle.open} H={candle.high} L={candle.low} C={candle.close}")
+        >>>
+        >>> # Paginate through large datasets
+        >>> all_candles = result.data
+        >>> while result.next_cursor:
+        ...     result = client.candles.history("BTC", start=start, end=end, cursor=result.next_cursor)
+        ...     all_candles.extend(result.data)
+    """
+
+    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,
+        interval: Optional[CandleInterval] = None,
+        cursor: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+    ) -> CursorResponse[list[Candle]]:
+        """
+        Get historical OHLCV candle data with cursor-based pagination.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+            start: Start timestamp (required)
+            end: End timestamp (required)
+            interval: Candle interval (1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w). Default: 1h
+            cursor: Cursor from previous response's next_cursor
+            limit: Maximum number of results (default: 100, max: 1000)
+
+        Returns:
+            CursorResponse with candle records and next_cursor for pagination
+
+        Example:
+            >>> result = client.candles.history("BTC", start=start, end=end, interval="1h", limit=1000)
+            >>> candles = result.data
+            >>> while result.next_cursor:
+            ...     result = client.candles.history(
+            ...         "BTC", start=start, end=end, interval="1h", cursor=result.next_cursor, limit=1000
+            ...     )
+            ...     candles.extend(result.data)
+        """
+        data = self._http.get(
+            f"{self._base_path}/candles/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "interval": interval,
+                "cursor": self._convert_timestamp(cursor),
+                "limit": limit,
+            },
+        )
+        return CursorResponse(
+            data=[Candle.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,
+        interval: Optional[CandleInterval] = None,
+        cursor: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+    ) -> CursorResponse[list[Candle]]:
+        """Async version of history(). start and end are required."""
+        data = await self._http.aget(
+            f"{self._base_path}/candles/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "interval": interval,
+                "cursor": self._convert_timestamp(cursor),
+                "limit": limit,
+            },
+        )
+        return CursorResponse(
+            data=[Candle.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )

oxarchive-0.5.3/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-0.4.4 → oxarchive-0.5.3}/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-0.4.4 → oxarchive-0.5.3}/oxarchive/types.py

@@ -270,12 +270,94 @@ 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
+# =============================================================================
+
+
+CandleInterval = Literal["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"]
+"""Candle interval for OHLCV data."""
+
+
+class Candle(BaseModel):
+    """OHLCV candle data."""
+
+    timestamp: datetime
+    """Candle open timestamp (UTC)."""
+
+    open: float
+    """Opening price."""
+
+    high: float
+    """Highest price during the interval."""
+
+    low: float
+    """Lowest price during the interval."""
+
+    close: float
+    """Closing price."""
+
+    volume: float
+    """Total volume traded during the interval."""
+
+    quote_volume: Optional[float] = None
+    """Total quote volume (volume * price)."""
+
+    trade_count: Optional[int] = None
+    """Number of trades during the interval."""
+
+
 # =============================================================================
 # WebSocket Types
 # =============================================================================
 
-WsChannel = Literal["orderbook", "trades", "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."""
@@ -382,6 +464,41 @@ class WsHistoricalData(BaseModel):
     data: dict[str, Any]
 
 
+class OrderbookDelta(BaseModel):
+    """Orderbook delta for tick-level data."""
+
+    timestamp: int
+    """Timestamp in milliseconds."""
+
+    side: Literal["bid", "ask"]
+    """Side: 'bid' or 'ask'."""
+
+    price: float
+    """Price level."""
+
+    size: float
+    """New size (0 = level removed)."""
+
+    sequence: int
+    """Sequence number for ordering."""
+
+
+class WsHistoricalTickData(BaseModel):
+    """Historical tick data (granularity='tick' mode) - checkpoint + deltas.
+
+    This message type is sent when using granularity='tick' for Lighter.xyz
+    orderbook data. It provides a full checkpoint followed by incremental deltas.
+    """
+
+    type: Literal["historical_tick_data"]
+    channel: WsChannel
+    coin: str
+    checkpoint: dict[str, Any]
+    """Initial checkpoint (full orderbook snapshot)."""
+    deltas: list[OrderbookDelta]
+    """Incremental deltas to apply after checkpoint."""
+
+
 # =============================================================================
 # WebSocket Bulk Stream Types (Bulk Download Mode)
 # =============================================================================

{oxarchive-0.4.4 → oxarchive-0.5.3}/oxarchive/websocket.py

@@ -42,6 +42,7 @@ except ImportError:
 
 from .types import (
     OrderBook,
+    OrderbookDelta,
     PriceLevel,
     Trade,
     WsChannel,
@@ -57,6 +58,7 @@ from .types import (
     WsReplayCompleted,
     WsReplayStopped,
     WsHistoricalData,
+    WsHistoricalTickData,
     WsStreamStarted,
     WsStreamProgress,
     WsHistoricalBatch,
@@ -110,6 +112,7 @@ ErrorHandler = Callable[[Exception], None]
 
 # Replay handlers
 HistoricalDataHandler = Callable[[str, int, dict], None]
+HistoricalTickDataHandler = Callable[[str, dict, list[OrderbookDelta]], None]  # coin, checkpoint, deltas
 ReplayStartHandler = Callable[[WsChannel, str, int, int, float], None]  # channel, coin, start, end, speed
 ReplayCompleteHandler = Callable[[WsChannel, str, int], None]  # channel, coin, snapshots_sent
 
@@ -276,6 +279,7 @@ class OxArchiveWs:
 
         # Replay handlers (Option B)
         self._on_historical_data: Optional[HistoricalDataHandler] = None
+        self._on_historical_tick_data: Optional[HistoricalTickDataHandler] = None
         self._on_replay_start: Optional[ReplayStartHandler] = None
         self._on_replay_complete: Optional[ReplayCompleteHandler] = None
 
@@ -307,7 +311,9 @@ class OxArchiveWs:
         url = f"{self.options.ws_url}?apiKey={self.options.api_key}"
 
         try:
-            self._ws = await ws_connect(url)
+            # Increase max_size to 50MB for large Lighter orderbook data with high granularity
+            # Lighter tick data with full depth (~3700 levels) can exceed 14MB per message
+            self._ws = await ws_connect(url, max_size=50 * 1024 * 1024)
             self._reconnect_attempts = 0
             self._set_state("connected")
 
@@ -427,6 +433,8 @@ class OxArchiveWs:
         start: int,
         end: Optional[int] = None,
         speed: float = 1.0,
+        granularity: Optional[str] = None,
+        interval: Optional[str] = None,
     ) -> None:
         """Start historical replay with timing preserved.
 
@@ -436,9 +444,12 @@ class OxArchiveWs:
             start: Start timestamp (Unix ms)
             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",
@@ -449,6 +460,10 @@ class OxArchiveWs:
         }
         if end is not None:
             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:
@@ -482,6 +497,8 @@ class OxArchiveWs:
         start: int,
         end: int,
         batch_size: int = 1000,
+        granularity: Optional[str] = None,
+        interval: Optional[str] = None,
     ) -> None:
         """Start bulk streaming for fast data download.
 
@@ -491,18 +508,26 @@ class OxArchiveWs:
             start: Start timestamp (Unix ms)
             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")
         """
-        await self._send({
+        msg = {
             "op": "stream",
             "channel": channel,
             "coin": coin,
             "start": start,
             "end": end,
             "batch_size": batch_size,
-        })
+        }
+        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:
         """Stop the current bulk stream."""
@@ -547,6 +572,16 @@ class OxArchiveWs:
         """
         self._on_historical_data = handler
 
+    def on_historical_tick_data(self, handler: HistoricalTickDataHandler) -> None:
+        """Set handler for historical tick data (granularity='tick' mode).
+
+        This is for tick-level granularity on Lighter.xyz orderbook data.
+        Receives a checkpoint (full orderbook) followed by incremental deltas.
+
+        Handler receives: (coin, checkpoint, deltas)
+        """
+        self._on_historical_tick_data = handler
+
     def on_replay_start(self, handler: ReplayStartHandler) -> None:
         """Set handler for replay started event.
 
@@ -722,6 +757,10 @@ class OxArchiveWs:
             elif msg_type == "historical_data" and self._on_historical_data:
                 self._on_historical_data(data["coin"], data["timestamp"], data["data"])
 
+            elif msg_type == "historical_tick_data" and self._on_historical_tick_data:
+                msg = WsHistoricalTickData(**data)
+                self._on_historical_tick_data(msg.coin, msg.checkpoint, msg.deltas)
+
             elif msg_type == "replay_completed" and self._on_replay_complete:
                 self._on_replay_complete(data["channel"], data["coin"], data["snapshots_sent"])
 

{oxarchive-0.4.4 → oxarchive-0.5.3}/pyproject.toml

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