feat: add combo market catalog

src/polymarket/__init__.py

@@ -31,6 +31,9 @@
     ClobTrade,
     ClosedPosition,
     ComboConditionId,
+    ComboMarket,
+    ComboMarketOutcome,
+    ComboMarketOutcomes,
     ComboPosition,
     ComboPositionLeg,
     ComboPositionMarket,
@@ -180,6 +183,9 @@
     "CancelledSigningError",
     "ClobTrade",
     "ClosedPosition",
+    "ComboMarket",
+    "ComboMarketOutcome",
+    "ComboMarketOutcomes",
     "ComboPosition",
     "Comment",
     "ComboPositionLeg",

src/polymarket/_internal/actions/rfq.py

@@ -0,0 +1,69 @@
+from collections.abc import Sequence
+from typing import cast
+
+from polymarket._internal.request import KeysetPagePayload, KeysetPaginatedSpec, QueryParamValue
+from polymarket.errors import UnexpectedResponseError, UserInputError
+from polymarket.models.rfq import ComboMarket
+from polymarket.models.types import validate_ctf_condition_id
+
+_MAX_COMBO_MARKETS_PAGE_SIZE = 100
+
+
+def list_combo_markets_spec(
+    *,
+    exclude: str | Sequence[str] | None = None,
+) -> KeysetPaginatedSpec[ComboMarket]:
+    params: dict[str, QueryParamValue] = {}
+    excluded = _coerce_excluded_condition_ids(exclude)
+    if excluded:
+        params["exclude"] = ",".join(excluded)
+
+    return KeysetPaginatedSpec(
+        service="rfq",
+        path="/v1/rfq/combo-markets",
+        parse_page=_parse_combo_markets_page,
+        base_params=params or None,
+        cursor_param="cursor",
+    )
+
+
+def validate_combo_markets_page_size(page_size: int) -> None:
+    if type(page_size) is not int:
+        raise UserInputError("page_size must be an int.")
+    if page_size < 1 or page_size > _MAX_COMBO_MARKETS_PAGE_SIZE:
+        raise UserInputError(f"page_size must be between 1 and {_MAX_COMBO_MARKETS_PAGE_SIZE}.")
+
+
+def _parse_combo_markets_page(data: object) -> KeysetPagePayload[ComboMarket]:
+    if not isinstance(data, dict):
+        raise UnexpectedResponseError("Combo market response did not match expected shape")
+    payload = cast(dict[str, object], data)
+
+    raw_markets = payload.get("markets")
+    if not isinstance(raw_markets, list):
+        raise UnexpectedResponseError("Combo market response is missing markets array")
+    market_items = cast(list[object], raw_markets)
+    markets = tuple(ComboMarket.parse_response(item) for item in market_items)
+
+    raw_cursor = payload.get("next_cursor")
+    if raw_cursor is None:
+        next_cursor = None
+    elif isinstance(raw_cursor, str) and raw_cursor:
+        next_cursor = raw_cursor
+    else:
+        raise UnexpectedResponseError("Combo market next_cursor did not match expected shape")
+
+    return KeysetPagePayload(items=markets, server_next_cursor=next_cursor)
+
+
+def _coerce_excluded_condition_ids(exclude: str | Sequence[str] | None) -> tuple[str, ...]:
+    if exclude is None:
+        return ()
+    if isinstance(exclude, str):
+        return (validate_ctf_condition_id(exclude),)
+    if isinstance(exclude, bytes):
+        raise UserInputError("exclude does not accept bytes")
+    return tuple(validate_ctf_condition_id(value) for value in exclude)
+
+
+__all__ = ["list_combo_markets_spec", "validate_combo_markets_page_size"]

src/polymarket/_internal/context.py

@@ -19,6 +19,7 @@ class SyncClientContext:
     gamma: SyncTransport
     data: SyncTransport
     clob: SyncTransport
+    rfq: SyncTransport
 
 
 @dataclass(frozen=True, slots=True)
@@ -39,6 +40,7 @@ class AsyncClientContext:
     gamma: AsyncTransport
     data: AsyncTransport
     clob: AsyncTransport
+    rfq: AsyncTransport
 
 
 @dataclass(frozen=True, slots=True)

src/polymarket/_internal/dispatch.py

@@ -32,6 +32,8 @@ def _sync_transport_for(ctx: SyncClientContext, service: Service) -> SyncTranspo
             return ctx.gamma
         case "data":
             return ctx.data
+        case "rfq":
+            return ctx.rfq
         case _ as unreachable:
             assert_never(unreachable)
 
@@ -42,6 +44,8 @@ def _async_transport_for(ctx: AsyncClientContext, service: Service) -> AsyncTran
             return ctx.gamma
         case "data":
             return ctx.data
+        case "rfq":
+            return ctx.rfq
         case _ as unreachable:
             assert_never(unreachable)
 
@@ -175,7 +179,7 @@ def fetch(cursor: str | None) -> Page[T]:
             "limit": page_size,
         }
         if server_cursor is not None:
-            params["after_cursor"] = server_cursor
+            params[spec.cursor_param] = server_cursor
         payload = transport.get_json(spec.path, params=params)
         keyset_page = spec.parse_page(payload)
         return compute_keyset_page(
@@ -216,7 +220,7 @@ async def fetch(cursor: str | None) -> Page[T]:
             "limit": page_size,
         }
         if server_cursor is not None:
-            params["after_cursor"] = server_cursor
+            params[spec.cursor_param] = server_cursor
         payload = await transport.get_json(spec.path, params=params)
         keyset_page = spec.parse_page(payload)
         return compute_keyset_page(

src/polymarket/_internal/request.py

@@ -2,7 +2,7 @@
 from dataclasses import dataclass
 from typing import Generic, Literal, TypeVar
 
-Service = Literal["gamma", "data"]
+Service = Literal["gamma", "data", "rfq"]
 Method = Literal["GET"]
 
 QueryParamScalar = str | int | float | bool
@@ -41,6 +41,7 @@ class KeysetPaginatedSpec(Generic[T]):
     path: str
     parse_page: Callable[[object], "KeysetPagePayload[T]"]
     base_params: Mapping[str, QueryParamValue] | None = None
+    cursor_param: str = "after_cursor"
 
 
 @dataclass(frozen=True, slots=True)

src/polymarket/clients/async_public.py

@@ -12,6 +12,7 @@
 from polymarket._internal.actions import data as _data_actions
 from polymarket._internal.actions import gamma as _gamma_actions
 from polymarket._internal.actions import rewards as _rewards_actions
+from polymarket._internal.actions import rfq as _rfq_actions
 from polymarket._internal.actions.data import (
     ActivitySortBy,
     ActivityTypeFilter,
@@ -90,6 +91,7 @@
     TradedMarketCount,
     TraderLeaderboardEntry,
 )
+from polymarket.models.rfq import ComboMarket
 from polymarket.models.rtds_events import (
     CommentsEvent,
     CryptoPricesEvent,
@@ -132,6 +134,7 @@ def __init__(
             gamma=AsyncTransport(base_url=environment.gamma_url, logger=logger),
             data=AsyncTransport(base_url=environment.data_url, logger=logger),
             clob=AsyncTransport(base_url=environment.clob_url, logger=logger),
+            rfq=AsyncTransport(base_url=environment.rfq_url, logger=logger),
         )
         self._market_manager: ClobMarketStreamManager | None = None
         self._sports_manager: SportsStreamManager | None = None
@@ -289,7 +292,10 @@ async def close(self) -> None:
                         try:
                             await self._ctx.data.close()
                         finally:
-                            await self._ctx.clob.close()
+                            try:
+                                await self._ctx.clob.close()
+                            finally:
+                                await self._ctx.rfq.close()
 
     async def get_market(
         self,
@@ -895,6 +901,21 @@ def list_markets(
         )
         return async_paginate_keyset(self._ctx, spec, page_size=page_size)
 
+    def list_combo_markets(
+        self,
+        *,
+        exclude: str | Sequence[str] | None = None,
+        page_size: int = 20,
+    ) -> AsyncPaginator[ComboMarket]:
+        """List markets available for Combos.
+
+        Returns:
+            An async paginator over matching Combo markets.
+        """
+        _rfq_actions.validate_combo_markets_page_size(page_size)
+        spec = _rfq_actions.list_combo_markets_spec(exclude=exclude)
+        return async_paginate_keyset(self._ctx, spec, page_size=page_size)
+
     def list_series(
         self,
         *,

src/polymarket/clients/async_secure.py

@@ -28,6 +28,7 @@
 from polymarket._internal.actions import data as _data_actions
 from polymarket._internal.actions import gamma as _gamma_actions
 from polymarket._internal.actions import rewards as _rewards_actions
+from polymarket._internal.actions import rfq as _rfq_actions
 from polymarket._internal.actions.data import (
     ActivitySortBy,
     ActivityTypeFilter,
@@ -200,6 +201,7 @@
     TradedMarketCount,
     TraderLeaderboardEntry,
 )
+from polymarket.models.rfq import ComboMarket
 from polymarket.models.rtds_events import (
     CommentsEvent,
     CryptoPricesEvent,
@@ -413,6 +415,7 @@ def _construct_for_wallet(
         gamma = AsyncTransport(base_url=environment.gamma_url, logger=logger)
         data = AsyncTransport(base_url=environment.data_url, logger=logger)
         clob = AsyncTransport(base_url=environment.clob_url, logger=logger)
+        rfq = AsyncTransport(base_url=environment.rfq_url, logger=logger)
         relayer_resolver = make_relayer_header_resolver(api_key) if api_key is not None else None
         relayer = AsyncTransport(
             base_url=environment.relayer_url,
@@ -432,6 +435,7 @@ def _construct_for_wallet(
             gamma=gamma,
             data=data,
             clob=clob,
+            rfq=rfq,
             signer=signer,
             credentials=credentials,
             secure_clob=secure_clob,
@@ -685,6 +689,7 @@ async def close(self) -> None:
             ctx.gamma,
             ctx.data,
             ctx.clob,
+            ctx.rfq,
             ctx.secure_clob,
             ctx.relayer,
             ctx.rpc,
@@ -1324,6 +1329,21 @@ def list_markets(
         )
         return async_paginate_keyset(self._ctx, spec, page_size=page_size)
 
+    def list_combo_markets(
+        self,
+        *,
+        exclude: str | Sequence[str] | None = None,
+        page_size: int = 20,
+    ) -> AsyncPaginator[ComboMarket]:
+        """List markets available for Combos.
+
+        Returns:
+            An async paginator over matching Combo markets.
+        """
+        _rfq_actions.validate_combo_markets_page_size(page_size)
+        spec = _rfq_actions.list_combo_markets_spec(exclude=exclude)
+        return async_paginate_keyset(self._ctx, spec, page_size=page_size)
+
     def list_series(
         self,
         *,

src/polymarket/clients/public.py

@@ -11,6 +11,7 @@
 from polymarket._internal.actions import data as _data_actions
 from polymarket._internal.actions import gamma as _gamma_actions
 from polymarket._internal.actions import rewards as _rewards_actions
+from polymarket._internal.actions import rfq as _rfq_actions
 from polymarket._internal.actions.data import (
     ActivitySortBy,
     ActivityTypeFilter,
@@ -87,6 +88,7 @@
     TradedMarketCount,
     TraderLeaderboardEntry,
 )
+from polymarket.models.rfq import ComboMarket
 from polymarket.models.types import CtfConditionId
 from polymarket.pagination import Page, Paginator
 
@@ -108,6 +110,7 @@ def __init__(
             gamma=SyncTransport(base_url=environment.gamma_url, logger=logger),
             data=SyncTransport(base_url=environment.data_url, logger=logger),
             clob=SyncTransport(base_url=environment.clob_url, logger=logger),
+            rfq=SyncTransport(base_url=environment.rfq_url, logger=logger),
         )
 
     @property
@@ -134,7 +137,10 @@ def close(self) -> None:
             try:
                 self._ctx.data.close()
             finally:
-                self._ctx.clob.close()
+                try:
+                    self._ctx.clob.close()
+                finally:
+                    self._ctx.rfq.close()
 
     def get_market(
         self,
@@ -749,6 +755,21 @@ def list_markets(
         )
         return sync_paginate_keyset(self._ctx, spec, page_size=page_size)
 
+    def list_combo_markets(
+        self,
+        *,
+        exclude: str | Sequence[str] | None = None,
+        page_size: int = 20,
+    ) -> Paginator[ComboMarket]:
+        """List markets available for Combos.
+
+        Returns:
+            A paginator over matching Combo markets.
+        """
+        _rfq_actions.validate_combo_markets_page_size(page_size)
+        spec = _rfq_actions.list_combo_markets_spec(exclude=exclude)
+        return sync_paginate_keyset(self._ctx, spec, page_size=page_size)
+
     def list_series(
         self,
         *,