oxarchive 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

oxarchive/resources/trades.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import warnings
+from dataclasses import dataclass
 from datetime import datetime
 from typing import Literal, Optional
 
@@ -9,6 +11,13 @@ 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.
@@ -17,8 +26,14 @@ class TradesResource:
         >>> # Get recent trades
         >>> trades = client.trades.recent("BTC")
         >>>
-        >>> # Get trade history with time range
-        >>> history = client.trades.list("ETH", start="2024-01-01", end="2024-01-02")
+        >>> # 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):
@@ -41,6 +56,90 @@ class TradesResource:
         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,
         *,
@@ -51,7 +150,10 @@ class TradesResource:
         side: Optional[Literal["buy", "sell"]] = None,
     ) -> list[Trade]:
         """
-        Get trade history for a coin.
+        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')
@@ -64,6 +166,11 @@ class TradesResource:
         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={
@@ -76,7 +183,7 @@ class TradesResource:
         )
         return [Trade.model_validate(item) for item in data["data"]]
 
-    async def alist(
+    async def alist_with_offset(
         self,
         coin: str,
         *,
@@ -86,7 +193,17 @@ class TradesResource:
         offset: Optional[int] = None,
         side: Optional[Literal["buy", "sell"]] = None,
     ) -> list[Trade]:
-        """Async version of list(). start and end are required."""
+        """
+        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={
@@ -123,3 +240,60 @@ class TradesResource:
             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)

{oxarchive-0.2.2.dist-info → oxarchive-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.2.2
+Version: 0.3.0
 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.2.2.dist-info → oxarchive-0.3.0.dist-info}/RECORD

@@ -8,7 +8,7 @@ oxarchive/resources/funding.py,sha256=TXkZxodVQTVcVbzNG6SpMQAzf8AkLm2NYZJxnP4MNX
 oxarchive/resources/instruments.py,sha256=flD1sH6x3P3CTqV1ZwkfwbranVacmhsHn5Dhr7lGQhM,1606
 oxarchive/resources/openinterest.py,sha256=h13yLA72LpfryUf8IqF6W7uE4ObYY2Qbc-auv4LtPqc,3552
 oxarchive/resources/orderbook.py,sha256=o_DTdpzKrZvHL9YXm8cGGUugPM8uUa6r9O_72r1ByV0,4557
-oxarchive/resources/trades.py,sha256=rAXfQ-Qq57FQphXBsdYUn03wr3_C4uEKa1wUB7uUse0,3905
-oxarchive-0.2.2.dist-info/METADATA,sha256=wkuwm2X2mJYYkrcJ4Kw_EjJwk9Sb7et6kM2V4tfypFU,8749
-oxarchive-0.2.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-oxarchive-0.2.2.dist-info/RECORD,,
+oxarchive/resources/trades.py,sha256=XCi2rXA2hxaTt0KNlWw8f7W0hzAvNWyT7DaivMz_rHw,10012
+oxarchive-0.3.0.dist-info/METADATA,sha256=yq_BurBDJwE1f1Nv6IANatT2KPE0uJ-7OUaY1N-omPk,8749
+oxarchive-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oxarchive-0.3.0.dist-info/RECORD,,