polymarket-apis 0.3.0__py3-none-any.whl → 0.3.9__py3-none-any.whl

polymarket_apis/clients/clob_client.py

@@ -1,7 +1,7 @@
 import json
 import logging
-from datetime import UTC, datetime
-from typing import Literal, Optional
+from datetime import UTC, datetime, timedelta
+from typing import Literal, cast
 from urllib.parse import urljoin
 
 import httpx
@@ -27,11 +27,11 @@ from ..types.clob_types import (
     PaginatedResponse,
     PartialCreateOrderOptions,
     PolygonTrade,
-    PolymarketRewardItem,
     PostOrdersArgs,
     Price,
     PriceHistory,
     RequestArgs,
+    RewardMarket,
     Spread,
     TickSize,
     TokenBidAskDict,
@@ -88,17 +88,18 @@ from ..utilities.signing.signer import Signer
 
 logger = logging.getLogger(__name__)
 
+
 class PolymarketClobClient:
     def __init__(
-            self,
-            private_key: str,
-            proxy_address: EthAddress,
-            creds: Optional[ApiCreds] = None,
-            chain_id: Literal[137, 80002] = POLYGON,
-            signature_type: Literal[0, 1, 2] = 1,
-            # 0 - EOA wallet, 1 - Proxy wallet, 2 - Gnosis Safe wallet
+        self,
+        private_key: str,
+        address: EthAddress,
+        creds: ApiCreds | None = None,
+        chain_id: Literal[137, 80002] = POLYGON,
+        signature_type: Literal[0, 1, 2] = 1,
+        # 0 - EOA wallet, 1 - Proxy wallet, 2 - Gnosis Safe wallet
     ):
-        self.proxy_address = proxy_address
+        self.address = address
         self.client = httpx.Client(http2=True, timeout=30.0)
         self.async_client = httpx.AsyncClient(http2=True, timeout=30.0)
         self.base_url: str = "https://clob.polymarket.com"
@@ -106,14 +107,14 @@ class PolymarketClobClient:
         self.builder = OrderBuilder(
             signer=self.signer,
             sig_type=signature_type,
-            funder=proxy_address,
+            funder=address,
         )
         self.creds = creds if creds else self.create_or_derive_api_creds()
 
         # local cache
-        self.__tick_sizes = {}
-        self.__neg_risk = {}
-        self.__fee_rates = {}
+        self.__tick_sizes: dict[str, TickSize] = {}
+        self.__neg_risk: dict[str, bool] = {}
+        self.__fee_rates: dict[str, int] = {}
 
     def _build_url(self, endpoint: str) -> str:
         return urljoin(self.base_url, endpoint)
@@ -123,19 +124,19 @@ class PolymarketClobClient:
         response.raise_for_status()
         return response.json()
 
-    def create_api_creds(self, nonce: Optional[int] = None) -> ApiCreds:
+    def create_api_creds(self, nonce: int | None = None) -> ApiCreds:
         headers = create_level_1_headers(self.signer, nonce)
         response = self.client.post(self._build_url(CREATE_API_KEY), headers=headers)
         response.raise_for_status()
         return ApiCreds(**response.json())
 
-    def derive_api_key(self, nonce: Optional[int] = None) -> ApiCreds:
+    def derive_api_key(self, nonce: int | None = None) -> ApiCreds:
         headers = create_level_1_headers(self.signer, nonce)
         response = self.client.get(self._build_url(DERIVE_API_KEY), headers=headers)
         response.raise_for_status()
         return ApiCreds(**response.json())
 
-    def create_or_derive_api_creds(self, nonce: Optional[int] = None) -> ApiCreds:
+    def create_or_derive_api_creds(self, nonce: int | None = None) -> ApiCreds:
         try:
             return self.create_api_creds(nonce)
         except HTTPStatusError:
@@ -171,7 +172,9 @@ class PolymarketClobClient:
         params = {"token_id": token_id}
         response = self.client.get(self._build_url(GET_TICK_SIZE), params=params)
         response.raise_for_status()
-        self.__tick_sizes[token_id] = str(response.json()["minimum_tick_size"])
+        self.__tick_sizes[token_id] = cast(
+            "TickSize", str(response.json()["minimum_tick_size"])
+        )
 
         return self.__tick_sizes[token_id]
 
@@ -199,7 +202,9 @@ class PolymarketClobClient:
         return fee_rate
 
     def __resolve_tick_size(
-            self, token_id: str, tick_size: TickSize = None,
+        self,
+        token_id: str,
+        tick_size: TickSize | None = None,
     ) -> TickSize:
         min_tick_size = self.get_tick_size(token_id)
         if tick_size is not None:
@@ -211,12 +216,19 @@ class PolymarketClobClient:
         return tick_size
 
     def __resolve_fee_rate(
-            self, token_id: str, user_fee_rate: Optional[int] = None,
+        self,
+        token_id: str,
+        user_fee_rate: int | None = None,
     ) -> int:
         market_fee_rate_bps = self.get_fee_rate_bps(token_id)
         # If both fee rate on the market and the user supplied fee rate are non-zero, validate that they match
         # else return the market fee rate
-        if market_fee_rate_bps > 0 and user_fee_rate is not None and user_fee_rate > 0 and user_fee_rate != market_fee_rate_bps:
+        if (
+            market_fee_rate_bps > 0
+            and user_fee_rate is not None
+            and user_fee_rate > 0
+            and user_fee_rate != market_fee_rate_bps
+        ):
             msg = f"invalid user provided fee rate: ({user_fee_rate}), fee rate for the market must be {market_fee_rate_bps}"
             raise InvalidFeeRateError(msg)
         return market_fee_rate_bps
@@ -291,10 +303,14 @@ class PolymarketClobClient:
         response.raise_for_status()
         return [OrderBookSummary(**obs) for obs in response.json()]
 
-    async def get_order_books_async(self, token_ids: list[str]) -> list[OrderBookSummary]:
+    async def get_order_books_async(
+        self, token_ids: list[str]
+    ) -> list[OrderBookSummary]:
         """Get the orderbook for a set of tokens asynchronously."""
         body = [{"token_id": token_id} for token_id in token_ids]
-        response = await self.async_client.post(self._build_url(GET_ORDER_BOOKS), json=body)
+        response = await self.async_client.post(
+            self._build_url(GET_ORDER_BOOKS), json=body
+        )
         response.raise_for_status()
         return [OrderBookSummary(**obs) for obs in response.json()]
 
@@ -304,7 +320,7 @@ class PolymarketClobClient:
         response.raise_for_status()
         return ClobMarket(**response.json())
 
-    def get_markets(self, next_cursor="MA==")  -> PaginatedResponse[ClobMarket]:
+    def get_markets(self, next_cursor="MA==") -> PaginatedResponse[ClobMarket]:
         """Get paginated ClobMarkets."""
         params = {"next_cursor": next_cursor}
         response = self.client.get(self._build_url(GET_MARKETS), params=params)
@@ -333,17 +349,26 @@ class PolymarketClobClient:
         return current_markets + next_page_markets
 
     def get_recent_history(
-            self,
-            token_id: str,
-            interval: Optional[Literal["1d", "6h", "1h"]] = "1d",
-            fidelity: int = 1,  # resolution in minutes
+        self,
+        token_id: str,
+        interval: Literal["1h", "6h", "1d", "1w", "1m", "max"] = "1d",
+        fidelity: int = 1,  # resolution in minutes
     ) -> PriceHistory:
-        """Get the recent price history of a token (up to now) - 1h, 6h, 1d."""
-        if fidelity < 1:
-            msg = f"invalid filters: minimum 'fidelity' for '{interval}' range is 1"
+        """Get the recent price history of a token (up to now) - 1h, 6h, 1d, 1w, 1m."""
+        min_fidelities: dict[str, int] = {
+            "1h": 1,
+            "6h": 1,
+            "1d": 1,
+            "1w": 5,
+            "1m": 10,
+            "max": 2,
+        }
+
+        if fidelity < min_fidelities[interval]:
+            msg = f"invalid filters: minimum fidelity' for '{interval}' range is {min_fidelities.get(interval)}"
             raise ValueError(msg)
 
-        params = {
+        params: dict[str, int | str] = {
             "market": token_id,
             "interval": interval,
             "fidelity": fidelity,
@@ -353,43 +378,52 @@ class PolymarketClobClient:
         return PriceHistory(**response.json(), token_id=token_id)
 
     def get_history(
-            self,
-            token_id: str,
-            start_time: Optional[datetime] = None,
-            end_time: Optional[datetime] = None,
-            interval: Optional[Literal["max", "1m", "1w"]] = "max",
-            fidelity: Optional[int] = 2,  # resolution in minutes
+        self,
+        token_id: str,
+        start_time: datetime | None = None,
+        end_time: datetime | None = None,
+        fidelity: int = 2,  # resolution in minutes
     ) -> PriceHistory:
-        """Get the price history of a token between selected dates - 1m, 1w, max."""
-        min_fidelities = {"1m": 10, "1w": 5, "max": 2}
-
-        if fidelity < min_fidelities[interval]:
-            msg = f"invalid filters: minimum 'fidelity' for '{interval}' range is {min_fidelities[interval]}"
-            raise ValueError(msg)
-
+        """Get the price history of a token between a selected date range of max 15 days or from start_time to now."""
         if start_time is None and end_time is None:
-            msg = "At least one of 'start_time' or 'end_time' must be provided."
+            msg = "At least 'start_time' or ('start_time' and 'end_time') must be provided"
             raise ValueError(msg)
 
-        # Default values for timestamps if one is not provided
-
-        if start_time is None:
-            start_time = datetime(2020, 1, 1, tzinfo=UTC)  # Default start time
-        if end_time is None:
-            end_time = datetime.now(UTC)  # Default end time
+        if (
+            start_time
+            and end_time
+            and start_time + timedelta(days=15, seconds=1) < end_time
+        ):
+            msg = "'start_time' - 'end_time' range cannot exceed 15 days. Remove 'end_time' to get prices up to now or set a shorter range."
+            raise ValueError(msg)
 
-        params = {
+        params: dict[str, int | str] = {
             "market": token_id,
-            "startTs": int(start_time.timestamp()),
-            "endTs": int(end_time.timestamp()),
-            "interval": interval,
             "fidelity": fidelity,
         }
+        if start_time:
+            params["startTs"] = int(start_time.timestamp())
+        if end_time:
+            params["endTs"] = int(end_time.timestamp())
+
         response = self.client.get(self._build_url("/prices-history"), params=params)
         response.raise_for_status()
         return PriceHistory(**response.json(), token_id=token_id)
 
-    def get_orders(self, order_id: Optional[str] = None, condition_id: Optional[Keccak256] = None, token_id: Optional[str] = None, next_cursor: str ="MA==") -> list[OpenOrder]:
+    def get_all_history(self, token_id: str) -> PriceHistory:
+        """Get the full price history of a token."""
+        return self.get_history(
+            token_id=token_id,
+            start_time=datetime(2020, 1, 1, tzinfo=UTC),
+        )
+
+    def get_orders(
+        self,
+        order_id: str | None = None,
+        condition_id: Keccak256 | None = None,
+        token_id: str | None = None,
+        next_cursor: str = "MA==",
+    ) -> list[OpenOrder]:
         """Gets your active orders, filtered by order_id, condition_id, token_id."""
         params = {}
         if order_id:
@@ -406,14 +440,18 @@ class PolymarketClobClient:
         next_cursor = next_cursor if next_cursor is not None else "MA=="
         while next_cursor != END_CURSOR:
             params["next_cursor"] = next_cursor
-            response = self.client.get(self._build_url(ORDERS), headers=headers, params=params)
+            response = self.client.get(
+                self._build_url(ORDERS), headers=headers, params=params
+            )
             response.raise_for_status()
             next_cursor = response.json()["next_cursor"]
             results += [OpenOrder(**order) for order in response.json()["data"]]
 
         return results
 
-    def create_order(self, order_args: OrderArgs, options: Optional[PartialCreateOrderOptions] = None) -> SignedOrder:
+    def create_order(
+        self, order_args: OrderArgs, options: PartialCreateOrderOptions | None = None
+    ) -> SignedOrder:
         """Creates and signs an order."""
         # add resolve_order_options, or similar
         tick_size = self.__resolve_tick_size(
@@ -425,7 +463,6 @@ class PolymarketClobClient:
             msg = f"price ({order_args.price}), min: {tick_size} - max: {1 - float(tick_size)}"
             raise InvalidPriceError(msg)
 
-
         neg_risk = (
             options.neg_risk
             if options and options.neg_risk
@@ -433,7 +470,9 @@ class PolymarketClobClient:
         )
 
         # fee rate
-        fee_rate_bps = self.__resolve_fee_rate(order_args.token_id, order_args.fee_rate_bps)
+        fee_rate_bps = self.__resolve_fee_rate(
+            order_args.token_id, order_args.fee_rate_bps
+        )
         order_args.fee_rate_bps = fee_rate_bps
 
         return self.builder.create_order(
@@ -444,7 +483,9 @@ class PolymarketClobClient:
             ),
         )
 
-    def post_order(self, order: SignedOrder, order_type: OrderType = OrderType.GTC) -> Optional[OrderPostResponse]:
+    def post_order(
+        self, order: SignedOrder, order_type: OrderType = OrderType.GTC
+    ) -> OrderPostResponse | None:
         """Posts a SignedOrder."""
         body = order_to_json(order, self.creds.key, order_type)
         headers = create_level_2_headers(
@@ -466,15 +507,23 @@ class PolymarketClobClient:
             logger.warning(msg)
             error_json = exc.response.json()
             print("Details:", error_json["error"])
-
-    def create_and_post_order(self, order_args: OrderArgs, options: Optional[PartialCreateOrderOptions] = None, order_type: OrderType = OrderType.GTC) -> OrderPostResponse:
+            return None
+
+    def create_and_post_order(
+        self,
+        order_args: OrderArgs,
+        options: PartialCreateOrderOptions | None = None,
+        order_type: OrderType = OrderType.GTC,
+    ) -> OrderPostResponse | None:
         """Utility function to create and publish an order."""
         order = self.create_order(order_args, options)
         return self.post_order(order=order, order_type=order_type)
 
-    def post_orders(self, args: list[PostOrdersArgs]):
+    def post_orders(self, args: list[PostOrdersArgs]) -> list[OrderPostResponse] | None:
         """Posts multiple SignedOrders at once."""
-        body = [order_to_json(arg.order, self.creds.key, arg.order_type) for arg in args]
+        body = [
+            order_to_json(arg.order, self.creds.key, arg.order_type) for arg in args
+        ]
         headers = create_level_2_headers(
             self.signer,
             self.creds,
@@ -493,26 +542,36 @@ class PolymarketClobClient:
                 resp = OrderPostResponse(**item)
                 order_responses.append(resp)
                 if resp.error_msg:
-                    msg = (f"Error posting order in position {index} \n"
-                           f"Details: {resp.error_msg}")
+                    msg = (
+                        f"Error posting order in position {index} \n"
+                        f"Details: {resp.error_msg}"
+                    )
                     logger.warning(msg)
         except httpx.HTTPStatusError as exc:
             msg = f"Client Error '{exc.response.status_code} {exc.response.reason_phrase}' while posting order"
             logger.warning(msg)
             error_json = exc.response.json()
             print("Details:", error_json["error"])
+            return None
         else:
             return order_responses
 
-    def create_and_post_orders(self, args: list[OrderArgs], order_types: list[OrderType]) -> list[OrderPostResponse]:
+    def create_and_post_orders(
+        self, args: list[OrderArgs], order_types: list[OrderType]
+    ) -> list[OrderPostResponse] | None:
         """Utility function to create and publish multiple orders at once."""
         return self.post_orders(
-            [PostOrdersArgs(order=self.create_order(order_args),
-                            order_type=order_type)
-             for order_args, order_type in zip(args, order_types, strict=True)],
+            [
+                PostOrdersArgs(
+                    order=self.create_order(order_args), order_type=order_type
+                )
+                for order_args, order_type in zip(args, order_types, strict=True)
+            ],
         )
 
-    def calculate_market_price(self, token_id: str, side: str, amount: float, order_type: OrderType) -> float:
+    def calculate_market_price(
+        self, token_id: str, side: str, amount: float, order_type: OrderType
+    ) -> float:
         """Calculates the matching price considering an amount and the current orderbook."""
         book = self.get_order_book(token_id)
         if book is None:
@@ -523,19 +582,27 @@ class PolymarketClobClient:
                 msg = "No ask orders available"
                 raise LiquidityError(msg)
             return self.builder.calculate_buy_market_price(
-                book.asks, amount, order_type,
+                book.asks,
+                amount,
+                order_type,
             )
         if side == "SELL":
             if book.bids is None:
                 msg = "No bid orders available"
                 raise LiquidityError(msg)
             return self.builder.calculate_sell_market_price(
-                book.bids, amount, order_type,
+                book.bids,
+                amount,
+                order_type,
             )
         msg = 'Side must be "BUY" or "SELL"'
         raise ValueError(msg)
 
-    def create_market_order(self, order_args: MarketOrderArgs, options: Optional[PartialCreateOrderOptions] = None):
+    def create_market_order(
+        self,
+        order_args: MarketOrderArgs,
+        options: PartialCreateOrderOptions | None = None,
+    ):
         """Creates and signs a market order."""
         tick_size = self.__resolve_tick_size(
             order_args.token_id,
@@ -561,7 +628,9 @@ class PolymarketClobClient:
         )
 
         # fee rate
-        fee_rate_bps = self.__resolve_fee_rate(order_args.token_id, order_args.fee_rate_bps)
+        fee_rate_bps = self.__resolve_fee_rate(
+            order_args.token_id, order_args.fee_rate_bps
+        )
         order_args.fee_rate_bps = fee_rate_bps
 
         return self.builder.create_market_order(
@@ -573,11 +642,11 @@ class PolymarketClobClient:
         )
 
     def create_and_post_market_order(
-            self,
-            order_args: MarketOrderArgs,
-            options: Optional[PartialCreateOrderOptions] = None,
-            order_type: OrderType = OrderType.FOK,
-    ) -> OrderPostResponse:
+        self,
+        order_args: MarketOrderArgs,
+        options: PartialCreateOrderOptions | None = None,
+        order_type: OrderType = OrderType.FOK,
+    ) -> OrderPostResponse | None:
         """Utility function to create and publish a market order."""
         order = self.create_market_order(order_args, options)
         return self.post_order(order=order, order_type=order_type)
@@ -589,7 +658,12 @@ class PolymarketClobClient:
         request_args = RequestArgs(method="DELETE", request_path=CANCEL, body=body)
         headers = create_level_2_headers(self.signer, self.creds, request_args)
 
-        response = self.client.request("DELETE", self._build_url(CANCEL), headers=headers, data=json.dumps(body).encode("utf-8"))
+        response = self.client.request(
+            "DELETE",
+            self._build_url(CANCEL),
+            headers=headers,
+            content=json.dumps(body).encode("utf-8"),
+        )
         response.raise_for_status()
         return OrderCancelResponse(**response.json())
 
@@ -598,11 +672,18 @@ class PolymarketClobClient:
         body = order_ids
 
         request_args = RequestArgs(
-            method="DELETE", request_path=CANCEL_ORDERS, body=body,
+            method="DELETE",
+            request_path=CANCEL_ORDERS,
+            body=body,
         )
         headers = create_level_2_headers(self.signer, self.creds, request_args)
 
-        response = self.client.request("DELETE", self._build_url(CANCEL_ORDERS), headers=headers, data=json.dumps(body).encode("utf-8"))
+        response = self.client.request(
+            "DELETE",
+            self._build_url(CANCEL_ORDERS),
+            headers=headers,
+            content=json.dumps(body).encode("utf-8"),
+        )
         response.raise_for_status()
         return OrderCancelResponse(**response.json())
 
@@ -620,7 +701,11 @@ class PolymarketClobClient:
         request_args = RequestArgs(method="GET", request_path=IS_ORDER_SCORING)
         headers = create_level_2_headers(self.signer, self.creds, request_args)
 
-        response = self.client.get(self._build_url(IS_ORDER_SCORING), headers=headers, params={"order_id": order_id})
+        response = self.client.get(
+            self._build_url(IS_ORDER_SCORING),
+            headers=headers,
+            params={"order_id": order_id},
+        )
         response.raise_for_status()
         return response.json()["scoring"]
 
@@ -628,12 +713,16 @@ class PolymarketClobClient:
         """Check if the orders are currently scoring."""
         body = order_ids
         request_args = RequestArgs(
-            method="POST", request_path=ARE_ORDERS_SCORING, body=body,
+            method="POST",
+            request_path=ARE_ORDERS_SCORING,
+            body=body,
         )
         headers = create_level_2_headers(self.signer, self.creds, request_args)
         headers["Content-Type"] = "application/json"
 
-        response = self.client.post(self._build_url(ARE_ORDERS_SCORING), headers=headers, json=body)
+        response = self.client.post(
+            self._build_url(ARE_ORDERS_SCORING), headers=headers, json=body
+        )
         response.raise_for_status()
         return response.json()
 
@@ -646,21 +735,24 @@ class PolymarketClobClient:
         request_args = RequestArgs(method="GET", request_path="/rewards/markets/")
         headers = create_level_2_headers(self.signer, self.creds, request_args)
 
-        response = self.client.get(self._build_url("/rewards/markets/" + condition_id), headers=headers)
+        response = self.client.get(
+            self._build_url("/rewards/markets/" + condition_id), headers=headers
+        )
         response.raise_for_status()
         return next(MarketRewards(**market) for market in response.json()["data"])
 
     def get_trades(
-            self,
-            condition_id: Optional[Keccak256] = None,
-            token_id: Optional[str] = None,
-            trade_id: Optional[str] = None,
-            before: Optional[datetime] = None,
-            after: Optional[datetime] = None,
-            proxy_address: Optional[int] = None,
-            next_cursor="MA==") -> list[PolygonTrade]:
+        self,
+        condition_id: Keccak256 | None = None,
+        token_id: str | None = None,
+        trade_id: str | None = None,
+        before: datetime | None = None,
+        after: datetime | None = None,
+        address: EthAddress | None = None,
+        next_cursor="MA==",
+    ) -> list[PolygonTrade]:
         """Fetches the trade history for a user."""
-        params = {}
+        params: dict[str, str | int] = {}
         if condition_id:
             params["market"] = condition_id
         if token_id:
@@ -671,8 +763,8 @@ class PolymarketClobClient:
             params["before"] = int(before.replace(microsecond=0).timestamp())
         if after:
             params["after"] = int(after.replace(microsecond=0).timestamp())
-        if proxy_address:
-            params["maker_address"] = proxy_address
+        if address:
+            params["maker_address"] = address
 
         request_args = RequestArgs(method="GET", request_path=TRADES)
         headers = create_level_2_headers(self.signer, self.creds, request_args)
@@ -681,47 +773,61 @@ class PolymarketClobClient:
         next_cursor = next_cursor if next_cursor is not None else "MA=="
         while next_cursor != END_CURSOR:
             params["next_cursor"] = next_cursor
-            response =  self.client.get(self._build_url(TRADES), headers=headers, params=params)
+            response = self.client.get(
+                self._build_url(TRADES), headers=headers, params=params
+            )
             response.raise_for_status()
             next_cursor = response.json()["next_cursor"]
             results += [PolygonTrade(**trade) for trade in response.json()["data"]]
 
         return results
 
-    def get_total_rewards(self, date: Optional[datetime] = None) -> DailyEarnedReward:
+    def get_total_rewards(self, date: datetime | None = None) -> DailyEarnedReward:
         """Get the total rewards earned on a given date (seems to only hold the 6 most recent data points)."""
         if date is None:
             date = datetime.now(UTC)
         params = {
             "authenticationType": "magic",
-            "date": f"{date.strftime("%Y-%m-%d")}",
+            "date": f"{date.strftime('%Y-%m-%d')}",
         }
 
         request_args = RequestArgs(method="GET", request_path="/rewards/user/total")
         headers = create_level_2_headers(self.signer, self.creds, request_args)
         params["l2Headers"] = json.dumps(headers)
 
-        response = self.client.get("https://polymarket.com/api/rewards/totalEarnings", params=params)
+        response = self.client.get(
+            "https://polymarket.com/api/rewards/totalEarnings", params=params
+        )
         response.raise_for_status()
         if response.json():
             return DailyEarnedReward(**response.json()[0])
         return DailyEarnedReward(
             date=date,
             asset_address="0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
-            maker_address=self.proxy_address,
+            maker_address=self.address,
             earnings=0.0,
             asset_rate=0.0,
         )
 
     def get_reward_markets(
-            self,
-            sort_by: Optional[Literal["market", "max_spread", "min_size", "rate_per_day", "spread", "price", "earnings", "earning_percentage"]] = "market",
-            sort_direction: Optional[Literal["ASC", "DESC"]] = None,
-            query: Optional[str] = None,
-            show_favorites: bool = False,
-    ) -> list[PolymarketRewardItem]:
+        self,
+        query: str | None = None,
+        sort_by: Literal[
+            "market",
+            "max_spread",
+            "min_size",
+            "rate_per_day",
+            "spread",
+            "price",
+            "earnings",
+            "earning_percentage",
+        ]
+        | None = "market",
+        sort_direction: Literal["ASC", "DESC"] | None = None,
+        show_favorites: bool = False,
+    ) -> list[RewardMarket]:
         """
-        Get all polymarket.com/rewards items, sorted by different criteria.
+        Search through markets that offer rewards (polymarket.com/rewards items) by query, sorted by different metrics. If query is empty, returns all markets with rewards.
 
          - market start date ("market") - TODO confirm this
          - max spread for rewards in usdc
@@ -734,7 +840,7 @@ class PolymarketClobClient:
         """
         results = []
         desc = {"ASC": False, "DESC": True}
-        params = {
+        params: dict[str, bool | str] = {
             "authenticationType": "magic",
             "showFavorites": show_favorites,
         }
@@ -753,11 +859,12 @@ class PolymarketClobClient:
         next_cursor = "MA=="
         while next_cursor != END_CURSOR:
             params["nextCursor"] = next_cursor
-            response = self.client.get("https://polymarket.com/api/rewards/markets", params=params)
-            # can probably use clob/rewards/user/markets here but haven't figure out auth
+            response = self.client.get(
+                "https://polymarket.com/api/rewards/markets", params=params
+            )
             response.raise_for_status()
             next_cursor = response.json()["next_cursor"]
-            results += [PolymarketRewardItem(**reward) for reward in response.json()["data"]]
+            results += [RewardMarket(**reward) for reward in response.json()["data"]]
 
         return results