oxarchive 0.1.1__tar.gz → 0.3.1__tar.gz

{oxarchive-0.1.1 → oxarchive-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.1.1
+Version: 0.3.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
@@ -140,20 +140,6 @@ trades = client.trades.list(
 )
 ```
 
-### Candles (OHLCV)
-
-```python
-# Get hourly candles
-candles = client.candles.list(
-    "BTC",
-    interval="1h",
-    start="2024-01-01",
-    end="2024-01-02"
-)
-
-# Available intervals: '1m', '5m', '15m', '1h', '4h', '1d'
-```
-
 ### Instruments
 
 ```python
@@ -272,8 +258,8 @@ async def main():
         print(f"{ts}: {data['mid_price']}")
     )
 
-    ws.on_replay_start(lambda ch, coin, total, speed:
-        print(f"Starting replay of {total} records at {speed}x")
+    ws.on_replay_start(lambda ch, coin, start, end, speed:
+        print(f"Starting replay from {start} to {end} at {speed}x")
     )
 
     ws.on_replay_complete(lambda ch, coin, sent:
@@ -316,8 +302,8 @@ async def main():
         all_data.extend([r.data for r in records])
     )
 
-    ws.on_stream_progress(lambda sent, total, pct:
-        print(f"Progress: {pct:.1f}%")
+    ws.on_stream_progress(lambda snapshots_sent:
+        print(f"Sent: {snapshots_sent} snapshots")
     )
 
     ws.on_stream_complete(lambda ch, coin, sent:

{oxarchive-0.1.1 → oxarchive-0.3.1}/README.md

@@ -104,20 +104,6 @@ trades = client.trades.list(
 )
 ```
 
-### Candles (OHLCV)
-
-```python
-# Get hourly candles
-candles = client.candles.list(
-    "BTC",
-    interval="1h",
-    start="2024-01-01",
-    end="2024-01-02"
-)
-
-# Available intervals: '1m', '5m', '15m', '1h', '4h', '1d'
-```
-
 ### Instruments
 
 ```python
@@ -236,8 +222,8 @@ async def main():
         print(f"{ts}: {data['mid_price']}")
     )
 
-    ws.on_replay_start(lambda ch, coin, total, speed:
-        print(f"Starting replay of {total} records at {speed}x")
+    ws.on_replay_start(lambda ch, coin, start, end, speed:
+        print(f"Starting replay from {start} to {end} at {speed}x")
     )
 
     ws.on_replay_complete(lambda ch, coin, sent:
@@ -280,8 +266,8 @@ async def main():
         all_data.extend([r.data for r in records])
     )
 
-    ws.on_stream_progress(lambda sent, total, pct:
-        print(f"Progress: {pct:.1f}%")
+    ws.on_stream_progress(lambda snapshots_sent:
+        print(f"Sent: {snapshots_sent} snapshots")
     )
 
     ws.on_stream_complete(lambda ch, coin, sent:

{oxarchive-0.1.1 → oxarchive-0.3.1}/oxarchive/__init__.py

@@ -20,8 +20,6 @@ from .client import Client
 from .types import (
     OrderBook,
     Trade,
-    Candle,
-    CandleInterval,
     Instrument,
     FundingRate,
     OpenInterest,
@@ -70,8 +68,6 @@ __all__ = [
     # Types
     "OrderBook",
     "Trade",
-    "Candle",
-    "CandleInterval",
     "Instrument",
     "FundingRate",
     "OpenInterest",

{oxarchive-0.1.1 → oxarchive-0.3.1}/oxarchive/client.py

@@ -8,7 +8,6 @@ from .http import HttpClient
 from .resources import (
     OrderBookResource,
     TradesResource,
-    CandlesResource,
     InstrumentsResource,
     FundingResource,
     OpenInterestResource,
@@ -81,9 +80,6 @@ class Client:
         self.trades = TradesResource(self._http)
         """Trade/fill history"""
 
-        self.candles = CandlesResource(self._http)
-        """OHLCV candles"""
-
         self.instruments = InstrumentsResource(self._http)
         """Trading instruments metadata"""
 

{oxarchive-0.1.1 → oxarchive-0.3.1}/oxarchive/resources/__init__.py

@@ -2,7 +2,6 @@
 
 from .orderbook import OrderBookResource
 from .trades import TradesResource
-from .candles import CandlesResource
 from .instruments import InstrumentsResource
 from .funding import FundingResource
 from .openinterest import OpenInterestResource
@@ -10,7 +9,6 @@ from .openinterest import OpenInterestResource
 __all__ = [
     "OrderBookResource",
     "TradesResource",
-    "CandlesResource",
     "InstrumentsResource",
     "FundingResource",
     "OpenInterestResource",

{oxarchive-0.1.1 → oxarchive-0.3.1}/oxarchive/resources/funding.py

@@ -44,8 +44,8 @@ class FundingResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
     ) -> list[FundingRate]:
@@ -54,8 +54,8 @@ class FundingResource:
 
         Args:
             coin: The coin symbol (e.g., 'BTC', 'ETH')
-            start: Start timestamp
-            end: End timestamp
+            start: Start timestamp (required)
+            end: End timestamp (required)
             limit: Maximum number of results
             offset: Number of results to skip
 
@@ -77,12 +77,12 @@ class FundingResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
     ) -> list[FundingRate]:
-        """Async version of history()."""
+        """Async version of history(). start and end are required."""
         data = await self._http.aget(
             f"/v1/funding/{coin.upper()}",
             params={

{oxarchive-0.1.1 → oxarchive-0.3.1}/oxarchive/resources/openinterest.py

@@ -44,8 +44,8 @@ class OpenInterestResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
     ) -> list[OpenInterest]:
@@ -54,8 +54,8 @@ class OpenInterestResource:
 
         Args:
             coin: The coin symbol (e.g., 'BTC', 'ETH')
-            start: Start timestamp
-            end: End timestamp
+            start: Start timestamp (required)
+            end: End timestamp (required)
             limit: Maximum number of results
             offset: Number of results to skip
 
@@ -77,12 +77,12 @@ class OpenInterestResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
     ) -> list[OpenInterest]:
-        """Async version of history()."""
+        """Async version of history(). start and end are required."""
         data = await self._http.aget(
             f"/v1/openinterest/{coin.upper()}",
             params={

{oxarchive-0.1.1 → oxarchive-0.3.1}/oxarchive/resources/orderbook.py

@@ -92,8 +92,8 @@ class OrderBookResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
         depth: Optional[int] = None,
@@ -103,8 +103,8 @@ class OrderBookResource:
 
         Args:
             coin: The coin symbol (e.g., 'BTC', 'ETH')
-            start: Start timestamp
-            end: End timestamp
+            start: Start timestamp (required)
+            end: End timestamp (required)
             limit: Maximum number of results
             offset: Number of results to skip
             depth: Number of price levels per side
@@ -128,13 +128,13 @@ class OrderBookResource:
         self,
         coin: str,
         *,
-        start: Optional[Timestamp] = None,
-        end: Optional[Timestamp] = None,
+        start: Timestamp,
+        end: Timestamp,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
         depth: Optional[int] = None,
     ) -> list[OrderBook]:
-        """Async version of history()."""
+        """Async version of history(). start and end are required."""
         data = await self._http.aget(
             f"/v1/orderbook/{coin.upper()}/history",
             params={

oxarchive-0.3.1/oxarchive/resources/trades.py

@@ -0,0 +1,299 @@
+"""Trades API resource."""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal, Optional
+
+from ..http import HttpClient
+from ..types import Trade, Timestamp
+
+
+@dataclass
+class CursorResponse:
+    """Response with cursor for pagination."""
+    data: list[Trade]
+    next_cursor: Optional[str] = None
+
+
+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")
+        >>> 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)
+        ...     trades.extend(result.data)
+    """
+
+    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,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        cursor: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> CursorResponse:
+        """
+        Get trade history for a coin using cursor-based pagination.
+
+        Uses cursor-based pagination by default, which is more efficient for large datasets.
+        Use the next_cursor from the response as the cursor parameter to get the next page.
+
+        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 (timestamp)
+            limit: Maximum number of results (default: 100, max: 1000)
+            side: Filter by trade side
+
+        Returns:
+            CursorResponse with trades and next_cursor for pagination
+
+        Example:
+            >>> # First page
+            >>> result = client.trades.list("BTC", start=start, end=end, limit=1000)
+            >>> trades = result.data
+            >>>
+            >>> # Subsequent pages
+            >>> while result.next_cursor:
+            ...     result = client.trades.list(
+            ...         "BTC", start=start, end=end, cursor=result.next_cursor, limit=1000
+            ...     )
+            ...     trades.extend(result.data)
+        """
+        data = self._http.get(
+            f"/v1/trades/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
+                "limit": limit,
+                "side": side,
+            },
+        )
+        return CursorResponse(
+            data=[Trade.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
+
+    async def alist(
+        self,
+        coin: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        cursor: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> CursorResponse:
+        """
+        Async version of list().
+
+        Uses cursor-based pagination by default.
+        """
+        data = await self._http.aget(
+            f"/v1/trades/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
+                "limit": limit,
+                "side": side,
+            },
+        )
+        return CursorResponse(
+            data=[Trade.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
+
+    def list_with_offset(
+        self,
+        coin: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> list[Trade]:
+        """
+        Get trade history using offset-based pagination.
+
+        .. deprecated::
+            Use list() with cursor-based pagination instead for better performance.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+            start: Start timestamp (required)
+            end: End timestamp (required)
+            limit: Maximum number of results
+            offset: Number of results to skip
+            side: Filter by trade side
+
+        Returns:
+            List of trades
+        """
+        warnings.warn(
+            "list_with_offset() is deprecated. Use list() with cursor-based pagination instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        data = self._http.get(
+            f"/v1/trades/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "limit": limit,
+                "offset": offset,
+                "side": side,
+            },
+        )
+        return [Trade.model_validate(item) for item in data["data"]]
+
+    async def alist_with_offset(
+        self,
+        coin: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> list[Trade]:
+        """
+        Async version of list_with_offset().
+
+        .. deprecated::
+            Use alist() with cursor-based pagination instead.
+        """
+        warnings.warn(
+            "alist_with_offset() is deprecated. Use alist() with cursor-based pagination instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        data = await self._http.aget(
+            f"/v1/trades/{coin.upper()}",
+            params={
+                "start": self._convert_timestamp(start),
+                "end": self._convert_timestamp(end),
+                "limit": limit,
+                "offset": offset,
+                "side": side,
+            },
+        )
+        return [Trade.model_validate(item) for item in data["data"]]
+
+    def recent(self, coin: str, limit: Optional[int] = None) -> list[Trade]:
+        """
+        Get most recent trades for a coin.
+
+        Args:
+            coin: The coin symbol (e.g., 'BTC', 'ETH')
+            limit: Number of trades to return (default: 100)
+
+        Returns:
+            List of recent trades
+        """
+        data = self._http.get(
+            f"/v1/trades/{coin.upper()}/recent",
+            params={"limit": limit},
+        )
+        return [Trade.model_validate(item) for item in data["data"]]
+
+    async def arecent(self, coin: str, limit: Optional[int] = None) -> list[Trade]:
+        """Async version of recent()."""
+        data = await self._http.aget(
+            f"/v1/trades/{coin.upper()}/recent",
+            params={"limit": limit},
+        )
+        return [Trade.model_validate(item) for item in data["data"]]
+
+    def list_cursor(
+        self,
+        coin: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        cursor: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> CursorResponse:
+        """
+        Get trade history using cursor-based pagination.
+
+        .. deprecated::
+            Use list() instead - it now uses cursor-based pagination by default.
+
+        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 (timestamp)
+            limit: Maximum number of results
+            side: Filter by trade side
+
+        Returns:
+            CursorResponse with trades and next_cursor for pagination
+        """
+        warnings.warn(
+            "list_cursor() is deprecated. Use list() instead - it now uses cursor-based pagination by default.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.list(coin, start=start, end=end, cursor=cursor, limit=limit, side=side)
+
+    async def alist_cursor(
+        self,
+        coin: str,
+        *,
+        start: Timestamp,
+        end: Timestamp,
+        cursor: Optional[Timestamp] = None,
+        limit: Optional[int] = None,
+        side: Optional[Literal["buy", "sell"]] = None,
+    ) -> CursorResponse:
+        """
+        Async version of list_cursor().
+
+        .. deprecated::
+            Use alist() instead - it now uses cursor-based pagination by default.
+        """
+        warnings.warn(
+            "alist_cursor() is deprecated. Use alist() instead - it now uses cursor-based pagination by default.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self.alist(coin, start=start, end=end, cursor=cursor, limit=limit, side=side)