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

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.6"
+__version__ = "0.5.1"
 
 __all__ = [
     # Client
@@ -84,6 +86,8 @@ __all__ = [
     "LighterGranularity",
     "FundingRate",
     "OpenInterest",
+    "Candle",
+    "CandleInterval",
     "OxArchiveError",
     # WebSocket Types
     "WsChannel",

oxarchive/exchanges.py

@@ -10,6 +10,7 @@ from .resources import (
     LighterInstrumentsResource,
     FundingResource,
     OpenInterestResource,
+    CandlesResource,
 )
 
 
@@ -44,6 +45,9 @@ class HyperliquidClient:
         self.open_interest = OpenInterestResource(http, base_path)
         """Open interest"""
 
+        self.candles = CandlesResource(http, base_path)
+        """OHLCV candle data"""
+
 
 class LighterClient:
     """
@@ -77,3 +81,6 @@ class LighterClient:
 
         self.open_interest = OpenInterestResource(http, base_path)
         """Open interest"""
+
+        self.candles = CandlesResource(http, base_path)
+        """OHLCV candle data"""

oxarchive/resources/__init__.py

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

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/types.py

@@ -270,11 +270,48 @@ class OpenInterest(BaseModel):
     """Impact ask price for liquidations."""
 
 
+# =============================================================================
+# 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"]
+WsChannel = Literal["orderbook", "trades", "candles", "ticker", "all_tickers"]
 """Available WebSocket channels. Note: ticker/all_tickers are real-time only."""
 
 WsConnectionState = Literal["connecting", "connected", "disconnected", "reconnecting"]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.4.6
+Version: 0.5.1
 Summary: Official Python SDK for 0xarchive - Hyperliquid Historical Data API
 Project-URL: Homepage, https://0xarchive.io
 Project-URL: Documentation, https://0xarchive.io/docs/sdks
@@ -317,6 +317,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:
@@ -505,12 +556,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
 

oxarchive-0.5.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+oxarchive/__init__.py,sha256=8-68R4dD9xFfeUQ1yAuy1IadC10el1QRBNJOn3DXMfA,2738
+oxarchive/client.py,sha256=XWQ_VEBQy3UIAnmZQ-Z_FyzXnvMA3FITwtinBOf3o-Y,4453
+oxarchive/exchanges.py,sha256=ozw_eDGnzyb7D5HKMo2Hfl7-dIcVKSXJCyFlFIhiaos,2631
+oxarchive/http.py,sha256=SY_o9Ag8ADo1HI3i3uAKW1xwkYjPE75gRAjnMsddAGs,4211
+oxarchive/types.py,sha256=LX5Usgn6RgUoS6l48ufQW2zKjzH1C3xjlV5UbsEp2fY,14293
+oxarchive/websocket.py,sha256=sS-kLDKv2qS77-61hXChRePjL_hz-URcALM9UW5zxXU,30609
+oxarchive/resources/__init__.py,sha256=pFCP01qP6g9A9Dbzn-lGgF0i6x8GhGlwmwpOXGg3UWM,510
+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/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-0.4.6.dist-info/RECORD

@@ -1,15 +0,0 @@
-oxarchive/__init__.py,sha256=z02RMa5pktqkvB4hOuzdeASD5j-qUUYebmkHL5UHSeE,2666
-oxarchive/client.py,sha256=XWQ_VEBQy3UIAnmZQ-Z_FyzXnvMA3FITwtinBOf3o-Y,4453
-oxarchive/exchanges.py,sha256=kk--Uh4g1U_tPfhJhYtZD_1zR6tJS5D-iaPnOGwWa9c,2425
-oxarchive/http.py,sha256=SY_o9Ag8ADo1HI3i3uAKW1xwkYjPE75gRAjnMsddAGs,4211
-oxarchive/types.py,sha256=YHy04TYtuEmJSHDMRh_9D9MVnhnXVc2rGagc45LwPiQ,13380
-oxarchive/websocket.py,sha256=sdKMJrmGeR_ApNP_c7TPJylc4DAkmrp1JXfpnRGynao,29985
-oxarchive/resources/__init__.py,sha256=ZGS3rLOfQFD665oJYMia_MxfTWlal7MXtx874DLG5EE,448
-oxarchive/resources/funding.py,sha256=ybMWkpoccrkdwnd6W3oHgsaor7cBcA2nkYy4CbjmHUg,4485
-oxarchive/resources/instruments.py,sha256=6q7rMdIaixXgFVXgwQsVd-YuO7RIXr1oGPT5jBsqI9A,3733
-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.4.6.dist-info/METADATA,sha256=NUz-9REdplj8blQwCyS95rTiEaiNs6qGiJW4J6HFtWU,15945
-oxarchive-0.4.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-oxarchive-0.4.6.dist-info/RECORD,,