HELD until the API returns next_cursor on order flow: document order-flow paging

CHANGELOG.md

@@ -8,12 +8,12 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ## [Unreleased]
 
 ### Added
-- `orders.flow()` and `aflow()` take `cursor` (Hyperliquid, HIP-3 and HIP-4)
-  and send it; the API starts the response at the first bucket that opens
-  after it. Before this, a `cursor` keyword was accepted and silently dropped.
-  The API does not return `next_cursor` on order flow yet: it arrives with an
-  API switch, and until then `next_cursor` on an order-flow response is
-  `None`.
+- `orders.flow()` and `aflow()` take `cursor` (Hyperliquid, HIP-3 and HIP-4).
+  The API now pages order flow: a page holds the oldest `limit` buckets of
+  the window, and `next_cursor` is set while more may follow. Pass it back as
+  `cursor` with the same `start`, `end` and `interval` until it is `None`.
+  Before this, a `cursor` keyword was accepted and silently dropped, so every
+  call returned the first page.
 
 ### Changed
 - `client.hyperliquid.hip3.breadth.history()` and `ahistory()` accept

README.md

@@ -1009,14 +1009,25 @@ result = client.hyperliquid.orders.history(
     order_type="limit"
 )
 
-# Get order flow aggregation: time buckets, oldest first
+# Get order flow aggregation: one page of time buckets
 flow = client.hyperliquid.orders.flow(
     "BTC",
     start="2026-07-13T00:00:00Z",
     end="2026-07-14T00:00:00Z",
-    interval="15m",  # 1m (default), 5m, 15m, 1h
-    limit=1000,  # buckets (default 1000, max 10000)
+    interval="1m",  # 1m (default), 5m, 15m, 1h
 )
+buckets = list(flow.data)
+# A page holds up to `limit` buckets (default 1000, max 10000); follow the
+# cursor with the same start, end and interval until it is None
+while flow.next_cursor:
+    flow = client.hyperliquid.orders.flow(
+        "BTC",
+        start="2026-07-13T00:00:00Z",
+        end="2026-07-14T00:00:00Z",
+        interval="1m",
+        cursor=flow.next_cursor,
+    )
+    buckets.extend(flow.data)
 
 # Get TP/SL history
 tpsl = client.hyperliquid.orders.tpsl(

oxarchive/resources/orders.py

@@ -142,23 +142,24 @@ def flow(
         **kwargs,
     ) -> CursorResponse:
         """
-        Get order flow aggregation in time buckets.
+        Get order flow aggregation, one page of time buckets.
 
         Buckets are labelled by their open time in UTC, and buckets with no
-        events are omitted. A response holds the oldest ``limit`` buckets of
-        the window.
+        events are omitted. A page holds the oldest ``limit`` buckets of the
+        window. While ``next_cursor`` is set, pass it back as ``cursor`` with
+        the same ``start``, ``end`` and ``interval``; stop when it is None.
 
         Args:
             symbol: The symbol (e.g., 'BTC', 'ETH')
             start: Start timestamp, inclusive (required)
             end: End timestamp, exclusive (required)
             interval: Bucket width: '1m' (default), '5m', '15m' or '1h'
-            cursor: Optional resume point, a Unix millisecond timestamp; the
-                response starts at the first bucket that opens after it
-            limit: Maximum number of buckets (default: 1000, max: 10000)
+            cursor: The previous response's next_cursor (a numeric
+                millisecond timestamp string); pass it back unchanged
+            limit: Buckets per page (default: 1000, max: 10000)
 
         Returns:
-            CursorResponse with order flow buckets
+            CursorResponse with order flow buckets and next_cursor for pagination
         """
         symbol = self._resolve_symbol(symbol, kwargs)
         data = self._http.get(