Add futures beta support

README.md

@@ -62,6 +62,41 @@ for quote in quotes:
     print(quote)
 ```
 
+### Pagination Behavior
+
+By default, the client paginates results for endpoints like `list_trades` and `list_quotes` behind the scenes for you. Understanding how pagination interacts with the `limit` parameter is key.
+
+#### Default (Pagination Enabled)
+
+Pagination is enabled by default (`pagination=True`):
+
+* `limit` controls the page size, not the total number of results.
+* The client automatically fetches all pages, yielding results until none remain.
+
+Here's an example:
+
+```python
+client = RESTClient(api_key="<API_KEY>")
+trades = [t for t in client.list_trades(ticker="TSLA", limit=100)]
+```
+
+This fetches all TSLA trades, 100 per page.
+
+#### Disabling Pagination
+
+To return a fixed number of results and stop, disable pagination:
+
+```python
+client = RESTClient(api_key="<API_KEY>", pagination=False)
+trades = [t for t in client.list_trades(ticker="TSLA", limit=100)]
+```
+
+This returns at most 100 total trades, no additional pages.
+
+### Performance Tip
+
+If you're fetching large datasets, always use the maximum supported limit for the API endpoint. This reduces the number of API calls and improves overall performance.
+
 ### Additional Filter Parameters
 
 Many of the APIs in this client library support the use of additional filter parameters to refine your queries. Please refer to the specific API documentation for details on which filter parameters are supported for each endpoint. These filters can be applied using the following operators:

polygon/rest/__init__.py

@@ -1,4 +1,5 @@
 from .aggs import AggsClient
+from .futures import FuturesClient
 from .trades import TradesClient
 from .quotes import QuotesClient
 from .snapshot import SnapshotClient
@@ -23,6 +24,7 @@
 
 class RESTClient(
     AggsClient,
+    FuturesClient,
     TradesClient,
     QuotesClient,
     SnapshotClient,
@@ -44,6 +46,7 @@ def __init__(
         num_pools: int = 10,
         retries: int = 3,
         base: str = BASE,
+        pagination: bool = True,
         verbose: bool = False,
         trace: bool = False,
         custom_json: Optional[Any] = None,
@@ -55,6 +58,7 @@ def __init__(
             num_pools=num_pools,
             retries=retries,
             base=base,
+            pagination=pagination,
             verbose=verbose,
             trace=trace,
             custom_json=custom_json,
@@ -66,6 +70,7 @@ def __init__(
             num_pools=num_pools,
             retries=retries,
             base=base,
+            pagination=pagination,
             verbose=verbose,
             trace=trace,
             custom_json=custom_json,

polygon/rest/base.py

@@ -10,7 +10,7 @@
 from .models.request import RequestOptionBuilder
 from ..logging import get_logger
 import logging
-from urllib.parse import urlencode
+from urllib.parse import urlencode, urlparse
 from ..exceptions import AuthError, BadResponse
 
 logger = get_logger("RESTClient")
@@ -30,6 +30,7 @@ def __init__(
         num_pools: int,
         retries: int,
         base: str,
+        pagination: bool,
         verbose: bool,
         trace: bool,
         custom_json: Optional[Any] = None,
@@ -41,6 +42,7 @@ def __init__(
 
         self.API_KEY = api_key
         self.BASE = base
+        self.pagination = pagination
 
         self.headers = {
             "Authorization": "Bearer " + self.API_KEY,
@@ -227,11 +229,14 @@ def _paginate_iter(
                 return []
             for t in decoded[result_key]:
                 yield deserializer(t)
-            if "next_url" in decoded:
-                path = decoded["next_url"].replace(self.BASE, "")
-                params = {}
-            else:
+            if not self.pagination or "next_url" not in decoded:
                 return
+            next_url = decoded["next_url"]
+            parsed = urlparse(next_url)
+            path = parsed.path
+            if parsed.query:
+                path += "?" + parsed.query
+            params = {}
 
     def _paginate(
         self,