Request and execute Combo quotes for users through the Builder Gateway
Approved builders can request executable Combo quotes and accept them for their
users. The Builder Gateway runs a quote competition, returns the best available
quote, and tracks the accepted trade through onchain execution.You need the builder credentials provided during onboarding, plus authenticated
access to the trading account. If you are not registered, register as a
builder before continuing.This guide starts with the custodial model, where the builder controls and signs
for one omnibus trading account. If each user signs for their own wallet, follow
the non-custodial guide at the end of this page.
Keep the Builder API secret on trusted infrastructure. Never expose it in a
browser or other untrusted client.
In the custodial model, the builder holds Combo positions for users in one
omnibus Deposit Wallet and controls the account signer. The same account and
builder identity must request and accept each quote.
Choose 2–50 unique, mutually compatible underlying market position IDs as the
legs. These are outcome position IDs from
Combo-enabled markets, not
CLOB token IDs or the derived Combo position IDs. Contradictory legs cannot form
a Combo. A BUY request sets the maximum collateral budget, including fees. A
SELL request specifies the number of Combo shares to sell.
TypeScript
Python
API
Use requestComboQuote() on a TypeScript SecureClient to request, accept, and
track a Combo quote.Don’t have the TypeScript SDK installed? Start with the
TypeScript SDK guide’s wallet integrations,
then come back.
1
Create a Custodial Client
Configure a SecureClient with the wallet signer, Deposit Wallet address, and
Builder API Key. This server-side example keeps the account key and builder
secret on trusted infrastructure.
Call requestComboQuote() with the leg position IDs and a human-readable
collateral amount. Amounts and sizes must be positive and have at most six
decimal places. Combo quote requests currently target the YES side, which the
SDK supplies by default. The method resolves when the quote competition closes.
import { OrderSide } from "@polymarket/client";const result = await client.requestComboQuote({ legPositionIds: ["<yes-position-id-1>", "<yes-position-id-2>"], direction: OrderSide.BUY, amount: "10",});// result: RequestComboQuoteResult
If no usable quote is available, result.quote is null and result.reason
explains the outcome. A winning quote includes its acceptance deadline in
result.quote.expiresAt, as a Unix timestamp in milliseconds. Use that value
rather than assuming a fixed acceptance window.For a SELL quote, pass direction: OrderSide.SELL with a human-readable size
instead of amount. The returned quote.netReceive is the exact collateral
proceeds after fees.
3
Accept and Track the Quote
Pass the returned quote to acceptComboQuote() immediately. After it enters
execution, call waitForComboFill() to wait for a terminal result.
import { RfqStatus } from "@polymarket/client";async function acceptAndTrackQuote() { if (result.quote === null) { console.log(`No quote available: ${result.reason}`); return; } const acceptance = await client.acceptComboQuote(result.quote); if (acceptance.status === "failed") { console.log(`Quote not accepted: ${acceptance.reason}`); return; } const fill = await client.waitForComboFill({ rfqId: acceptance.rfqId, timeoutMs: 120_000, }); if (fill.status === RfqStatus.Filled) { console.log(`Filled: ${fill.txHash}`); return; } console.log(`Execution ended with ${fill.status}`);}await acceptAndTrackQuote();
An acceptance with status: "executing" is not yet a confirmed fill. A maker
decline, expired window, or execution failure is returned as a business outcome.
A local timeout does not mean the trade failed.
Use request_combo_quote() on AsyncSecureClient to request, accept, and track
a Combo quote. The synchronous SecureClient exposes the same methods.Don’t have the Python SDK installed? Start with the
Python SDK guide, then come back.
1
Configure Custodial Credentials
Load the Builder API Key on trusted infrastructure. The workflow below uses a
server-side account key and Deposit Wallet address.
Call request_combo_quote() with the leg position IDs and a human-readable
collateral amount. Amounts and sizes must be positive and have at most six
decimal places. Combo quote requests currently target the YES side, which the
SDK supplies by default. The method resolves when the quote competition closes.
from decimal import Decimalfrom polymarket import AsyncSecureClient, RfqStatus, TimeoutErrorasync with await AsyncSecureClient.create( private_key=os.environ["POLYMARKET_PRIVATE_KEY"], wallet=os.environ["POLYMARKET_DEPOSIT_WALLET"], api_key=builder_api_key,) as client: result = await client.request_combo_quote( leg_position_ids=["<yes-position-id-1>", "<yes-position-id-2>"], direction="BUY", amount=Decimal("10"), ) if result.quote is None: print(f"No quote available: {result.reason}") else: try: acceptance = await client.accept_combo_quote(result.quote) if acceptance.status == "failed": print(f"Quote not accepted: {acceptance.reason}") else: fill = await client.wait_for_combo_fill( rfq_id=acceptance.rfq_id, timeout=120.0, ) if fill.status is RfqStatus.FILLED: print(f"Filled: {fill.tx_hash}") else: print(f"Execution ended with {fill.status}") except TimeoutError: status = await client.fetch_rfq_status(rfq_id=result.rfq_id) print(f"Current status: {status.status}")
If no usable quote is available, result.quote is None and result.reason
explains the outcome. A winning quote includes its acceptance deadline in
result.quote.expires_at, as a Unix timestamp in milliseconds. Use that value
rather than assuming a fixed acceptance window.For a SELL quote, pass direction="SELL" with a human-readable size instead
of amount. The returned quote.net_receive is the exact collateral proceeds
after fees.An acceptance with status == "executing" is not yet a confirmed fill. A maker
decline, expired window, or execution failure is returned as a business outcome.
A local timeout does not mean the trade failed. The context manager closes the
client after the workflow, including after an exception.
The Direct API gives custodial server-side integrations lower-level control over
request signing and order construction. The gateway host is provided during
builder onboarding, and its base path is /v1/builder/rfq.
1
Sign Request Headers
Create and accept requests require both account and builder authentication.
Status requests require account authentication only.
Request
Account headers
Builder headers
POST /requests
Required
Required
POST /requests/{rfq_id}/accept
Required
Required
GET /requests/{rfq_id} after acceptance
Required
Do not send
The account header set is POLY_ADDRESS, POLY_API_KEY, POLY_PASSPHRASE,
POLY_TIMESTAMP, and POLY_SIGNATURE. The builder header set is
POLY_BUILDER_API_KEY, POLY_BUILDER_PASSPHRASE,
POLY_BUILDER_TIMESTAMP, and POLY_BUILDER_SIGNATURE.POLY_ADDRESS is the EOA that owns the omnibus account credentials. Both
signer_address and maker_address are the builder-controlled Deposit Wallet
address.Compute each signature with HMAC-SHA256, using the base64-decoded secret as the
key. Sign an uppercase method, a Unix timestamp in seconds, the full request path
such as /v1/builder/rfq/requests without the host or query string, and the exact
serialized body sent on the wire. Omit the body for GET requests. Encode the
digest as base64url with padding preserved.
Use unit: "notional" for BUY requests and unit: "shares" for SELL
requests. The value_e6 value is a string in 6-decimal base units. side must
currently be "YES".An executable response includes the RFQ, the winning quote, and an acceptance
deadline:
A terminal result such as no quotes returns HTTP 200 with status: "FAILED"
and an error object. expires_at and request.created_at are Unix timestamps
in milliseconds. Construct and submit the signed order before expires_at; do
not assume a fixed acceptance window. total_required_e6 is the exact requester
balance required: collateral including fees for BUY, or Combo shares for SELL.
For BUY quotes, net_receive_e6 is the number of Combo shares received. For SELL
quotes, it is the exact collateral proceeds after fees; use it instead of
deriving proceeds from the blended price.
3
Accept the Quote
Build an Exchange v3 requester order from the returned RFQ and quote, sign it
for the authenticated wallet type, then submit it with both authentication
sets. Use Polygon chain ID 137 and Exchange v3 contract
0xe3333700cA9d93003F00f0F71f8515005F6c00Aa for the EIP-712 domain.Deposit Wallets use signatureType: 3 and an ERC-7739-wrapped signature. See
Authorize the Quote for the
Exchange v3 order types and wallet-specific signing paths.
For both directions, copy maker_amount_e6 to makerAmount and
taker_amount_e6 to takerAmount, and use the returned Combo YES position ID
as tokenId. Set side to 0 for BUY or 1 for SELL. The order’s builder
must equal the returned builder_code.The response contains the latest known state. If last look is still pending,
the gateway waits for an update for up to one second before returning. If the
response still has status: "AWAITING_MAKER_CONFIRMATION", fetch status until
the maker responds.
The taker_order_hash is the EIP-712 hash of the requester order. A maker
decline or execution failure still returns HTTP 200, with status: "FAILED"
and a nested error object. Retrying the same authenticated acceptance does not
execute twice; its response may omit taker_order_hash. Use rfq_id as the
stable recovery identifier.
4
Fetch Status
After acceptance, fetch durable status with account headers only.
GET /v1/builder/rfq/requests/<rfq-id>Accept: application/jsonPOLY_ADDRESS: <account-signer-address>POLY_API_KEY: <account-api-key>POLY_PASSPHRASE: <account-passphrase>POLY_TIMESTAMP: <account-timestamp>POLY_SIGNATURE: <account-signature>
Status reads before acceptance return HTTP 409. The status response contains
one top-level status plus an optional tx_hash or error; it does not repeat
the request or quote. Status can progress through
AWAITING_MAKER_CONFIRMATION, EXECUTING, MINED, and RETRYING before
reaching a successful CONFIRMED or FILLED state. FAILED, EXPIRED, and
CANCELED are terminal states without a fill.
In the non-custodial model, each user controls the account signer for their own
Deposit Wallet, while the builder provides integration authorization from
trusted infrastructure.
TypeScript
Use remoteBuilderSigning() with a TypeScript SecureClient so the connected
wallet authorizes account actions while your server keeps the Builder API secret.Start with a connected Viem WalletClient and the user’s Deposit Wallet
address. See the TypeScript wallet integrations
if you have not configured the account signer yet.
Combo quote requests require authenticated account access. Create a
SecureClient with remoteBuilderSigning() so the user’s signer and the
builder’s signing service authorize their parts of the request separately.
Here, walletClient is the connected Viem WalletClient and
depositWalletAddress is that user’s Deposit Wallet. Authenticate calls to
/api/builder/sign with your application session. For cookie authentication,
pass credentials: "include" when the signing API is cross-origin. For bearer
authentication, pass the token through the headers option on
remoteBuilderSigning().Use a Deposit Wallet already associated with the user. To provision a new
account first, follow Create New Accounts.The signing response gives the browser the Builder key identifier, passphrase,
timestamp, and a signature scoped to that request. The Builder secret never
leaves the signing server.
Do not sign arbitrary request details from the browser. Bind the application
session to the expected user and Deposit Wallet, allow only the required
method and path combinations, and validate account identities in request
bodies. Protect cookie-backed endpoints from CSRF and rate-limit signing
requests. Client setup can request signatures for CLOB authentication and
Deposit Wallet checks before the Combo create and accept requests, so include
those setup operations in your allowlist. If you parse a body to validate it,
still sign the original raw body string without reserializing it.
Use the same Combo requester methods as the custodial TypeScript flow. The
account identity now comes from the user’s signer and Deposit Wallet, while
Builder authentication comes from your signing API.
import { OrderSide, RfqStatus } from "@polymarket/client";async function requestAndTrackQuote() { const result = await client.requestComboQuote({ legPositionIds: ["<yes-position-id-1>", "<yes-position-id-2>"], direction: OrderSide.BUY, amount: "10", }); if (result.quote === null) { console.log(`No quote available: ${result.reason}`); return; } const acceptance = await client.acceptComboQuote(result.quote); if (acceptance.status === "failed") { console.log(`Quote not accepted: ${acceptance.reason}`); return; } const fill = await client.waitForComboFill({ rfqId: acceptance.rfqId, timeoutMs: 120_000, }); if (fill.status === RfqStatus.Filled) { console.log(`Filled: ${fill.txHash}`); return; } console.log(`Execution ended with ${fill.status}`);}await requestAndTrackQuote();
The user must approve the requester order before the quote expires. Preserve the
returned quote and retry acceptance before result.quote.expiresAt if wallet or
remote signing fails. Keep the RFQ ID to recover status after an interrupted
Gateway response or local timeout.
Custodial and non-custodial accounts share the same quote and execution
outcomes. The account model changes who authorizes the trade, not how the RFQ
progresses. Keep the RFQ ID until the request reaches a terminal state.
Case
What happened
What to do
No executable quote
The competition ended without a usable quote.
Treat it as a normal market outcome. Retry later or adjust the requested size.
Acceptance failed
The maker declined, the deadline passed, or execution could not start.
Request a fresh quote. Do not reuse an expired quote.
Local wait timed out
Your client stopped waiting before a durable outcome was available.
Fetch the RFQ status and continue until it reaches a terminal state.
Execution ended without a fill
The RFQ failed, expired, or was canceled.
Inspect the returned error before deciding whether to request another quote.
Filled
The trade was confirmed onchain.
Record the transaction hash and reconcile the trade and resulting positions.
Request failed
Authentication, validation, rate limiting, transport, or a dependency failed.
Correct the reported cause; retry only when the request is safe to repeat.
No executable quote, failed acceptance, and terminal execution failure are
business outcomes. They can be returned successfully by the service and should
not be treated as transport failures.
Catch TimeoutError, then use the standalone fetchRfqStatus() action with result.rfqId.
Execution ended without a fill
fill.status is RfqStatus.Failed, RfqStatus.Expired, or RfqStatus.Canceled.
Filled
fill.status === RfqStatus.Filled; the transaction hash is fill.txHash.
Request failed
The SDK throws a typed request, input, authentication, rate-limit, transport, or response error.
Remote signing failed
SigningError is thrown. This applies only when the non-custodial flow uses remoteBuilderSigning().
If remote signing fails while accepting a quote, preserve result.quote and
retry acceptance before result.quote.expiresAt. The acceptance may not have
reached the Builder Gateway, so do not assume that a status read can recover it.
Use request_combo_quote() and its follow-up methods on AsyncSecureClient or
SecureClient to detect each case. Use the original RFQ ID when a local wait
times out.
Catch TimeoutError, then call await client.fetch_rfq_status(rfq_id=result.rfq_id).
Execution ended without a fill
fill.status is RfqStatus.FAILED, RfqStatus.EXPIRED, or RfqStatus.CANCELED.
Filled
fill.status is RfqStatus.FILLED; the transaction hash is fill.tx_hash.
Request failed
The SDK raises a typed request, input, authentication, rate-limit, transport, or response error.
Inspect the response status and error fields after each Direct API request.
Do not use the HTTP status alone to decide whether the trade filled.
Case
How to detect or recover
No executable quote
HTTP 200 with status: "FAILED" and a nested error.
Acceptance failed
HTTP 200 with status: "FAILED", or HTTP 409 if the acceptance window expired. Request a fresh quote.
Status polling was interrupted
Repeat GET /v1/builder/rfq/requests/{rfq_id} with account authentication after acceptance is recorded.
Execution ended without a fill
status is FAILED, EXPIRED, or CANCELED.
Filled
status is CONFIRMED or FILLED; the transaction hash is tx_hash.
Request failed
A non-2xx response contains a stable code and a human-readable top-level error; a transport failure has no response.
If a create request is interrupted, do not assume that an RFQ was created. If
an acceptance request is interrupted, safely retry the same authenticated
acceptance before the quote expires. Once acceptance is recorded, use the RFQ
ID for status polling.For requests rejected before an RFQ outcome, use the HTTP status to identify
the failure category:
HTTP status
Meaning
400
Invalid JSON, RFQ body, acceptance, or signed order
401
Missing or invalid account or builder authentication
403
Account authorization failed, or the builder key has no enabled builder code
404
Unknown RFQ
409
RFQ state conflict, expired acceptance window, quote mismatch, or status read before acceptance
