fix(gamma): type search sort fields

src/polymarket/_internal/actions/gamma.py

@@ -43,6 +43,15 @@
 CommentParentEntityType = Literal["Event", "Series"]
 TagMatch = Literal["any", "all"]
 Recurrence = Literal["daily", "weekly", "monthly"]
+SearchSort = Literal[
+    "volume",
+    "volume_24hr",
+    "liquidity",
+    "competitive",
+    "closed_time",
+    "start_date",
+    "end_date",
+]
 
 _T = TypeVar("_T")
 
@@ -174,6 +183,22 @@ def _check_recurrence(value: Recurrence | None) -> None:
         raise UserInputError("recurrence must be one of: daily, weekly, monthly")
 
 
+def _check_search_sort(value: SearchSort | None) -> None:
+    if value is not None and value not in {
+        "volume",
+        "volume_24hr",
+        "liquidity",
+        "competitive",
+        "closed_time",
+        "start_date",
+        "end_date",
+    }:
+        raise UserInputError(
+            "sort must be one of: volume, volume_24hr, liquidity, competitive, "
+            "closed_time, start_date, end_date"
+        )
+
+
 def _check_tag_match(value: TagMatch | None) -> None:
     if value is not None and value not in {"any", "all"}:
         raise UserInputError("tag_match must be one of: any, all")
@@ -689,10 +714,11 @@ def search_spec(
     recurrence: Recurrence | None = None,
     search_profiles: bool | None = None,
     search_tags: bool | None = None,
-    sort: str | None = None,
+    sort: SearchSort | None = None,
 ) -> PageBasedSpec[SearchResults]:
     require_nonempty("q", q)
     _check_recurrence(recurrence)
+    _check_search_sort(sort)
 
     params: dict[str, QueryParamValue] = {"q": q}
     _add_optional(params, "ascending", ascending)

src/polymarket/clients/async_public.py

@@ -29,6 +29,7 @@
     CommentParentEntityType,
     DateFilter,
     Recurrence,
+    SearchSort,
     TagMatch,
     TimestampFilter,
 )
@@ -1061,11 +1062,18 @@ def search(
         recurrence: Recurrence | None = None,
         search_profiles: bool | None = None,
         search_tags: bool | None = None,
-        sort: str | None = None,
+        sort: SearchSort | None = None,
         page_size: int = 10,
     ) -> AsyncPaginator[SearchResults]:
         """Search Polymarket content.
 
+        Args:
+            keep_closed_markets: Include markets closed within this many hours when
+                searching active events.
+            sort: Event sort field. Supported values are ``volume``, ``volume_24hr``,
+                ``liquidity``, ``competitive``, ``closed_time``, ``start_date``, and
+                ``end_date``.
+
         Returns:
             An async paginator over search result pages.
         """

src/polymarket/clients/async_secure.py

@@ -45,6 +45,7 @@
     CommentParentEntityType,
     DateFilter,
     Recurrence,
+    SearchSort,
     TagMatch,
     TimestampFilter,
 )
@@ -1489,11 +1490,18 @@ def search(
         recurrence: Recurrence | None = None,
         search_profiles: bool | None = None,
         search_tags: bool | None = None,
-        sort: str | None = None,
+        sort: SearchSort | None = None,
         page_size: int = 10,
     ) -> AsyncPaginator[SearchResults]:
         """Search Polymarket content.
 
+        Args:
+            keep_closed_markets: Include markets closed within this many hours when
+                searching active events.
+            sort: Event sort field. Supported values are ``volume``, ``volume_24hr``,
+                ``liquidity``, ``competitive``, ``closed_time``, ``start_date``, and
+                ``end_date``.
+
         Returns:
             An async paginator over search result pages.
         """

src/polymarket/clients/public.py

@@ -28,6 +28,7 @@
     CommentParentEntityType,
     DateFilter,
     Recurrence,
+    SearchSort,
     TagMatch,
     TimestampFilter,
 )
@@ -915,11 +916,18 @@ def search(
         recurrence: Recurrence | None = None,
         search_profiles: bool | None = None,
         search_tags: bool | None = None,
-        sort: str | None = None,
+        sort: SearchSort | None = None,
         page_size: int = 10,
     ) -> Paginator[SearchResults]:
         """Search Polymarket content.
 
+        Args:
+            keep_closed_markets: Include markets closed within this many hours when
+                searching active events.
+            sort: Event sort field. Supported values are ``volume``, ``volume_24hr``,
+                ``liquidity``, ``competitive``, ``closed_time``, ``start_date``, and
+                ``end_date``.
+
         Returns:
             A paginator over search result pages.
 

src/polymarket/clients/secure.py

@@ -35,6 +35,7 @@
     CommentParentEntityType,
     DateFilter,
     Recurrence,
+    SearchSort,
     TagMatch,
     TimestampFilter,
 )
@@ -1222,11 +1223,18 @@ def search(
         recurrence: Recurrence | None = None,
         search_profiles: bool | None = None,
         search_tags: bool | None = None,
-        sort: str | None = None,
+        sort: SearchSort | None = None,
         page_size: int = 10,
     ) -> Paginator[SearchResults]:
         """Search Polymarket content.
 
+        Args:
+            keep_closed_markets: Include markets closed within this many hours when
+                searching active events.
+            sort: Event sort field. Supported values are ``volume``, ``volume_24hr``,
+                ``liquidity``, ``competitive``, ``closed_time``, ``start_date``, and
+                ``end_date``.
+
         Returns:
             A paginator over search result pages.
         """

tests/unit/test_gamma_paginated_specs.py

@@ -221,7 +221,7 @@ def test_search_spec_builds_request_with_filters() -> None:
         ascending=True,
         events_tag=["politics"],
         exclude_tag_ids=[5, 6],
-        sort="recent",
+        sort="volume",
     )
 
     assert isinstance(spec, PageBasedSpec)
@@ -232,7 +232,7 @@ def test_search_spec_builds_request_with_filters() -> None:
         "ascending": True,
         "events_tag": ("politics",),
         "exclude_tag_id": (5, 6),
-        "sort": "recent",
+        "sort": "volume",
     }
 
 
@@ -241,6 +241,11 @@ def test_search_spec_rejects_invalid_recurrence() -> None:
         gamma_actions.search_spec(q="x", recurrence="yearly")  # type: ignore[arg-type]
 
 
+def test_search_spec_rejects_invalid_sort() -> None:
+    with pytest.raises(UserInputError, match="sort must be one of"):
+        gamma_actions.search_spec(q="x", sort="recent")  # type: ignore[arg-type]
+
+
 def test_list_markets_spec_treats_bare_slug_string_as_single_item() -> None:
     spec = gamma_actions.list_markets_spec(slug="foo")