oxarchive 0.3.9__py3-none-any.whl → 0.3.11__py3-none-any.whl

oxarchive/__init__.py

@@ -57,7 +57,7 @@ except ImportError:
     OxArchiveWs = None  # type: ignore
     WsOptions = None  # type: ignore
 
-__version__ = "0.3.9"
+__version__ = "0.3.11"
 
 __all__ = [
     # Client

oxarchive/resources/funding.py

@@ -6,7 +6,7 @@ from datetime import datetime
 from typing import Optional
 
 from ..http import HttpClient
-from ..types import FundingRate, Timestamp
+from ..types import CursorResponse, FundingRate, Timestamp
 
 
 class FundingResource:
@@ -46,32 +46,44 @@ class FundingResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
-    ) -> list[FundingRate]:
+    ) -> CursorResponse[list[FundingRate]]:
         """
-        Get funding rate history for a coin.
+        Get funding rate 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)
-            limit: Maximum number of results
-            offset: Number of results to skip
+            cursor: Cursor from previous response's next_cursor (timestamp)
+            limit: Maximum number of results (default: 100, max: 1000)
 
         Returns:
-            List of funding rate records
+            CursorResponse with funding rate records and next_cursor for pagination
+
+        Example:
+            >>> result = client.funding.history("BTC", start=start, end=end, limit=1000)
+            >>> rates = result.data
+            >>> while result.next_cursor:
+            ...     result = client.funding.history(
+            ...         "BTC", start=start, end=end, cursor=result.next_cursor, limit=1000
+            ...     )
+            ...     rates.extend(result.data)
         """
         data = self._http.get(
             f"/v1/funding/{coin.upper()}",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
             },
         )
-        return [FundingRate.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[FundingRate.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
 
     async def ahistory(
         self,
@@ -79,20 +91,23 @@ class FundingResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
-    ) -> list[FundingRate]:
+    ) -> CursorResponse[list[FundingRate]]:
         """Async version of history(). start and end are required."""
         data = await self._http.aget(
             f"/v1/funding/{coin.upper()}",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
             },
         )
-        return [FundingRate.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[FundingRate.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
 
     def current(self, coin: str) -> FundingRate:
         """

oxarchive/resources/openinterest.py

@@ -6,7 +6,7 @@ from datetime import datetime
 from typing import Optional
 
 from ..http import HttpClient
-from ..types import OpenInterest, Timestamp
+from ..types import CursorResponse, OpenInterest, Timestamp
 
 
 class OpenInterestResource:
@@ -46,32 +46,44 @@ class OpenInterestResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
-    ) -> list[OpenInterest]:
+    ) -> CursorResponse[list[OpenInterest]]:
         """
-        Get open interest history for a coin.
+        Get open interest 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)
-            limit: Maximum number of results
-            offset: Number of results to skip
+            cursor: Cursor from previous response's next_cursor (timestamp)
+            limit: Maximum number of results (default: 100, max: 1000)
 
         Returns:
-            List of open interest records
+            CursorResponse with open interest records and next_cursor for pagination
+
+        Example:
+            >>> result = client.open_interest.history("BTC", start=start, end=end, limit=1000)
+            >>> records = result.data
+            >>> while result.next_cursor:
+            ...     result = client.open_interest.history(
+            ...         "BTC", start=start, end=end, cursor=result.next_cursor, limit=1000
+            ...     )
+            ...     records.extend(result.data)
         """
         data = self._http.get(
             f"/v1/openinterest/{coin.upper()}",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
             },
         )
-        return [OpenInterest.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[OpenInterest.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
 
     async def ahistory(
         self,
@@ -79,20 +91,23 @@ class OpenInterestResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
-    ) -> list[OpenInterest]:
+    ) -> CursorResponse[list[OpenInterest]]:
         """Async version of history(). start and end are required."""
         data = await self._http.aget(
             f"/v1/openinterest/{coin.upper()}",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
             },
         )
-        return [OpenInterest.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[OpenInterest.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
 
     def current(self, coin: str) -> OpenInterest:
         """

oxarchive/resources/orderbook.py

@@ -6,7 +6,7 @@ from datetime import datetime
 from typing import Optional, Union
 
 from ..http import HttpClient
-from ..types import OrderBook, Timestamp
+from ..types import CursorResponse, OrderBook, Timestamp
 
 
 class OrderBookResource:
@@ -94,35 +94,47 @@ class OrderBookResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
         depth: Optional[int] = None,
-    ) -> list[OrderBook]:
+    ) -> CursorResponse[list[OrderBook]]:
         """
-        Get historical order book snapshots.
+        Get historical order book snapshots with cursor-based pagination.
 
         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
+            cursor: Cursor from previous response's next_cursor (timestamp)
+            limit: Maximum number of results (default: 100, max: 1000)
             depth: Number of price levels per side
 
         Returns:
-            List of order book snapshots
+            CursorResponse with order book snapshots and next_cursor for pagination
+
+        Example:
+            >>> result = client.orderbook.history("BTC", start=start, end=end, limit=1000)
+            >>> snapshots = result.data
+            >>> while result.next_cursor:
+            ...     result = client.orderbook.history(
+            ...         "BTC", start=start, end=end, cursor=result.next_cursor, limit=1000
+            ...     )
+            ...     snapshots.extend(result.data)
         """
         data = self._http.get(
             f"/v1/orderbook/{coin.upper()}/history",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
                 "depth": depth,
             },
         )
-        return [OrderBook.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[OrderBook.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )
 
     async def ahistory(
         self,
@@ -130,19 +142,22 @@ class OrderBookResource:
         *,
         start: Timestamp,
         end: Timestamp,
+        cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
-        offset: Optional[int] = None,
         depth: Optional[int] = None,
-    ) -> list[OrderBook]:
+    ) -> CursorResponse[list[OrderBook]]:
         """Async version of history(). start and end are required."""
         data = await self._http.aget(
             f"/v1/orderbook/{coin.upper()}/history",
             params={
                 "start": self._convert_timestamp(start),
                 "end": self._convert_timestamp(end),
+                "cursor": self._convert_timestamp(cursor),
                 "limit": limit,
-                "offset": offset,
                 "depth": depth,
             },
         )
-        return [OrderBook.model_validate(item) for item in data["data"]]
+        return CursorResponse(
+            data=[OrderBook.model_validate(item) for item in data["data"]],
+            next_cursor=data.get("meta", {}).get("next_cursor"),
+        )

oxarchive/resources/trades.py

@@ -2,20 +2,11 @@
 
 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
+from ..types import CursorResponse, Trade, Timestamp
 
 
 class TradesResource:
@@ -64,7 +55,7 @@ class TradesResource:
         cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
         side: Optional[Literal["buy", "sell"]] = None,
-    ) -> CursorResponse:
+    ) -> CursorResponse[list[Trade]]:
         """
         Get trade history for a coin using cursor-based pagination.
 
@@ -118,7 +109,7 @@ class TradesResource:
         cursor: Optional[Timestamp] = None,
         limit: Optional[int] = None,
         side: Optional[Literal["buy", "sell"]] = None,
-    ) -> CursorResponse:
+    ) -> CursorResponse[list[Trade]]:
         """
         Async version of list().
 
@@ -139,83 +130,6 @@ class TradesResource:
             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.
@@ -240,60 +154,3 @@ 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/types.py

@@ -411,6 +411,21 @@ class OxArchiveError(Exception):
         return f"[{self.code}] {self.message}"
 
 
+# =============================================================================
+# Pagination Types
+# =============================================================================
+
+
+class CursorResponse(BaseModel, Generic[T]):
+    """Response with cursor for pagination."""
+
+    data: T
+    """The paginated data."""
+
+    next_cursor: Optional[str] = None
+    """Cursor for the next page (use as cursor parameter)."""
+
+
 # Type alias for timestamp parameters
 Timestamp = Union[int, str, datetime]
 """Timestamp can be Unix ms (int), ISO string, or datetime object."""

oxarchive/websocket.py

@@ -32,6 +32,7 @@ from typing import Any, Callable, Optional, Set, Union
 
 try:
     from websockets.asyncio.client import connect as ws_connect, ClientConnection
+    from websockets.exceptions import ConnectionClosed
     from websockets.protocol import State as WsState
 except ImportError:
     raise ImportError(
@@ -650,7 +651,7 @@ class OxArchiveWs:
                 try:
                     message = await self._ws.recv()
                     self._handle_message(message)
-                except websockets.ConnectionClosed as e:
+                except ConnectionClosed as e:
                     logger.info(f"Connection closed: {e.code} {e.reason}")
                     if self._on_close:
                         self._on_close(e.code, e.reason)

{oxarchive-0.3.9.dist-info → oxarchive-0.3.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oxarchive
-Version: 0.3.9
+Version: 0.3.11
 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.3.11.dist-info/RECORD

@@ -0,0 +1,14 @@
+oxarchive/__init__.py,sha256=Gjh2Ygt74OHNVSp-NLYumXBM8WGR62QJf95oBDBlFJ4,2182
+oxarchive/client.py,sha256=3P0fvOcyM5BWppkVV4054NduDHKvRg-cWeluoGymmRk,3163
+oxarchive/http.py,sha256=SY_o9Ag8ADo1HI3i3uAKW1xwkYjPE75gRAjnMsddAGs,4211
+oxarchive/types.py,sha256=RUnni6RMGHxK3-tTajcDVtT3Rk_sJqlOJLiG5SMc3Do,11278
+oxarchive/websocket.py,sha256=MyffJxaabDBonECcJg9vF4hAQ_4thjP4DaS7MaR4uno,28381
+oxarchive/resources/__init__.py,sha256=WQ4GYQ8p3L0D2Isk4IV4h1DRpvyZlt6tOF1t_CJr6ls,385
+oxarchive/resources/funding.py,sha256=g-c_zeCxFoPKEYymeDVswsIvfZIAKz4wd_2pTYpe8zQ,4368
+oxarchive/resources/instruments.py,sha256=flD1sH6x3P3CTqV1ZwkfwbranVacmhsHn5Dhr7lGQhM,1606
+oxarchive/resources/openinterest.py,sha256=Il9OzvnYM0-UCuspPUGqXy6dHMfxBvbLojPDKfS4kzU,4436
+oxarchive/resources/orderbook.py,sha256=2aq9v2gK5ZJ2C_i6vY2plvtMdI0n50Gx8GsJLUIAEJA,5437
+oxarchive/resources/trades.py,sha256=6Gm0ryUk1XBg2Tv7g69D5QQFuN6ZKLCAD1-TJ_J0jjU,5386
+oxarchive-0.3.11.dist-info/METADATA,sha256=N_uQ-prJ3oKnXcpyjhumUvlmOAAIQP0VI5da4n4jMOA,11071
+oxarchive-0.3.11.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oxarchive-0.3.11.dist-info/RECORD,,

oxarchive-0.3.9.dist-info/RECORD

@@ -1,14 +0,0 @@
-oxarchive/__init__.py,sha256=c1JP0iZrqbnOrcTSfbMHDoojzHoDmDobFv7Mvv7qk5A,2181
-oxarchive/client.py,sha256=3P0fvOcyM5BWppkVV4054NduDHKvRg-cWeluoGymmRk,3163
-oxarchive/http.py,sha256=SY_o9Ag8ADo1HI3i3uAKW1xwkYjPE75gRAjnMsddAGs,4211
-oxarchive/types.py,sha256=lM3WrATnHcxGs0fLq54Lka-FTvXqiwWe2He2Qn9SrSA,10844
-oxarchive/websocket.py,sha256=0w7OebFUo_4c3AnjG-9vfX9IBHKyTbvgAWUXhxFO53I,28336
-oxarchive/resources/__init__.py,sha256=WQ4GYQ8p3L0D2Isk4IV4h1DRpvyZlt6tOF1t_CJr6ls,385
-oxarchive/resources/funding.py,sha256=TXkZxodVQTVcVbzNG6SpMQAzf8AkLm2NYZJxnP4MNXw,3500
-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=XCi2rXA2hxaTt0KNlWw8f7W0hzAvNWyT7DaivMz_rHw,10012
-oxarchive-0.3.9.dist-info/METADATA,sha256=O7olK5nYQ8HeHaxQwgvRUtayOudvTcgAYnhv1eTv-ro,11070
-oxarchive-0.3.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-oxarchive-0.3.9.dist-info/RECORD,,