Article
Polymarket CLOB API in Python: Orders, Fills and Timeouts
Understand Polymarket order execution in Python: outcome tokens, limit prices, partial fills, cancellations and what to check when an API request times out.

The Polymarket CLOB API lets a Python bot submit signed orders for a specific outcome token. Reliable execution also means controlling price and size, tracking partial fills and settlement, confirming cancellations, and reconciling unknown results before sending another order.
Suppose the bot has done its homework. The news checks out, the right market is available, the price makes sense and the proposed position fits its limits. Now it needs to buy.
In a demonstration, this is where one function call produces a satisfying green message. Once the bot starts trading, several new questions arise. Did the order reach the server? How much filled? Is the rest still open? And did that second attempt accidentally buy the same thing twice?
This is the execution layer: the part of a trading bot responsible for carrying out a decision and keeping an accurate record of what actually happened.
Start with one consistent Python SDK
Polymarket’s unified Python SDK is distributed as polymarket-client. The examples here use version 0.11.0, checked on September 24, 2026:
pip install polymarket-client==0.11.0
The synchronous trading client is SecureClient. There is also an AsyncSecureClient, whose operations use await. Both belong to the current SDK; copying half an example from each does not create a useful third option.
Older tutorials may use different clients, signing details or methods. Keep the package, documentation and code from the same generation. Pin a tested version and review upgrades deliberately instead of installing whatever happens to be newest every time the bot starts.
The short fragments below explain the interface. They assume an appropriately configured account and checked market data; they are not a complete trading program. Order-placement and cancellation calls perform real operations when connected to an authorized account.
The order needs an outcome token, not just a market
Imagine a fictional contract asking whether a game will launch this month. YES and NO belong to the same market, but they are separate tradable outcome tokens. Each has its own token ID.
The market ID identifies the market, and the condition ID identifies its underlying condition. Neither is a substitute for the token ID required by an order. Even an event URL can be insufficient on its own: one event may contain several contracts with different deadlines or conditions.
Once market refers to the exact binary contract you have checked, selecting its YES token looks like this:
token_id = market.outcomes.yes.token_id
if token_id is None:
raise ValueError("The selected YES token has no ID")
That check catches a missing identifier. It cannot tell whether you chose the right contract in the first place. Verify the question, deadline, resolution rules and intended outcome before reaching this line.
This is an especially unhelpful class of bug because everything can appear to work. The request is valid, the signature is correct and the server accepts it. The software has simply executed the opposite of your idea with admirable efficiency.
Trading access is different from reading market data
A public data reader does not need the secrets that authorize trading. A trading client does. In the synchronous SDK, SecureClient.create() accepts signing credentials and the account wallet to connect authenticated operations.
The signing address and the wallet holding the account’s funds may differ. Use the account’s actual wallet configuration rather than assuming that every address involved is interchangeable. The SDK handles much of the signing machinery, but it cannot choose the correct account on your behalf.
Keep private keys out of source code, public repositories, logs, screenshots and language-model prompts. A dedicated wallet with limited funds can constrain exposure. It cannot make a broken strategy safe, and it does not remove the need to understand which account a request will affect.
What a limit order actually promises
Assume an authenticated synchronous client is ready and the selected market permits the proposed price and size. A purchase instruction for ten shares at a limit of 52 cents is short:
response = client.place_limit_order(
token_id=token_id,
side="BUY",
price="0.52",
size="10",
)
if response.ok:
print(response.order_id, response.status)
else:
print(response.code, response.message)
Size means shares here. Ten shares at 52 cents would cost at most $5.20 before fees if fully filled at prices within the limit. Better available prices can reduce that cost.
The limit controls the purchase price; it does not promise a fill. The order might execute immediately, partly execute or wait in the book. With the usual good-till-canceled behavior and no expiration specified, an unfilled remainder can stay active until filled or canceled.
The market’s current price increment, or tick size, and minimum order size still apply. A neatly formatted request is not automatically a valid one.
Also, the response.ok branch only handles a response that was returned. The SDK can raise exceptions during validation, signing or a request. A complete execution system needs to handle those paths as well, particularly when it cannot establish whether submission succeeded.
Accepted, matched and settled are different stages
Polymarket uses a central limit order book: buyers and sellers submit instructions that can be matched when their prices are compatible. Order signing and matching happen off-chain; settlement takes place through Polygon.
An accepted order response can include these statuses:
| Status | What it tells you |
|---|---|
live | The order is resting in the book. |
matched | It matched immediately against available liquidity. |
delayed | A marketable order is subject to a matching delay. |
These are not interchangeable with “the full intended position is settled.” Matching can happen before final settlement, and an intended purchase may only fill partly. Record the quantity that filled and follow the trade’s subsequent state.
Suppose a resting order aims to buy 100 shares, but only 30 have filled. The remaining 70 may still be open. The bot now has acquired exposure and outstanding exposure to consider. Recording “bought 100” would be wrong; recording “nothing happened” would be wrong too.
Reconciliation means comparing the bot’s records with orders, fills, positions and balances until the account state makes sense. A reassuring line in a log is useful evidence about the program, not a substitute for that comparison.
A market order still needs a price boundary
The best offer is only the first level of the book. Consider a hypothetical set of offers: 20 shares at 51 cents, 100 at 53 cents and another 380 at 56 cents.
Buying all 500 would cost $276, or an average of 55.2 cents per share before fees, assuming those offers remained available and filled as shown. The attractive 51-cent quote would account for just 20 shares.
If your maximum purchase price were 53 cents, only 120 shares would be available within that limit in this example. Choosing an immediate execution type does not create the missing quantity:
- FAK — Fill and Kill: execute the available amount immediately and cancel the unfilled remainder.
- FOK — Fill or Kill: execute the requested order in full immediately or fill none of it.
For a 500-share request bounded at 53 cents, those rules produce very different results: a possible partial fill under FAK, or no fill under FOK. In a changing market, even the quantity visible a moment earlier may disappear before submission.
Check units when switching methods too. The market-buy method’s amount refers to money to spend before applicable fees; the limit-order size above refers to shares. A parameter named “10” is not much of a specification until you know ten of what.
Canceling an order does not sell the shares already bought
A signal can expire while an order is waiting. New information arrives, the price changes or the strategy no longer wants the remaining quantity. The bot can request cancellation using the saved order ID:
result = client.cancel_order(order_id=order_id)
if order_id in result.canceled:
print("Cancellation confirmed; reconcile any fills")
else:
print(result.not_canceled.get(order_id, "Check order state"))
The response distinguishes canceled orders from those that could not be canceled. A successful HTTP request alone does not prove the requested cancellation happened.
If 40 shares of a 100-share purchase have already filled, canceling the remaining 60 leaves a 40-share position, assuming no additional fills or other transactions. Cancellation does not reverse the purchase.
There is a timing complication: more shares can fill while the cancellation request is traveling. Check the final recorded fills and remaining order state instead of treating the quantity seen before cancellation as the final answer.
After a timeout, establish what happened before trying again
The bot sends an order. The CLOB receives it. The connection drops before the response reaches the bot.
Locally, this looks like failure. Remotely, a valid order may already exist—or may already have filled. Creating and submitting a fresh order at this point can increase exposure beyond the intended size.
An identical signed retransmission and a newly created order are not necessarily handled the same way. Do not reduce the problem to “every retry duplicates the trade,” but do not treat a timeout as proof of rejection either.
Record the intended action and available identifiers before submission, then save the returned order ID when it arrives. After an uncertain result, use those records to check orders, recent fills, positions and balances.
Looking only at open orders is insufficient. An order missing from that list could have filled already. It could also have been canceled or rejected; the absence alone cannot choose among those explanations.
If the result remains unknown, pause the affected new orders and investigate. “Try again” is a reasonable convenience for loading a photograph. For an instruction that spends money, it needs a little more context.
Handle the error you have, not a generic failure
Invalid token selection, an unsupported price increment, a quantity below the minimum, insufficient funds, unsuitable authorization and a market that no longer accepts orders are different problems. So is an immediate order that cannot find enough liquidity within its constraints.
Retrying an invalid price ten times gives the server ten opportunities to explain the same issue. It does not repair the price. Correct the input or account condition, then reconsider whether the trade is still appropriate.
A temporary service problem may justify a later, limited retry. First distinguish a known refusal from an unknown submission result and reconcile any uncertain exposure. A retry policy should not quietly become an order generator.
A funded wallet is only part of account readiness
An account can hold assets while lacking the permissions needed for a particular operation. An allowance or token approval authorizes a relevant contract to use an asset. It is separate from merely seeing funds in the wallet.
The required setup depends on the wallet and asset involved. Follow the current account workflow, verify the relevant permissions and avoid copying approval instructions for arbitrary addresses. A successful authentication step does not establish that every trading prerequisite is satisfied.
Then check the economics. Applicable fees depend on the market, while spread and order-book depth affect the obtainable execution price. A permanent setting such as “fee equals 1%” can obscure that distinction.
If an average fill estimate already includes buying across several price levels, do not subtract the same difference again as another slippage charge. Account for each cost once, using the current market rather than a convenient default.
Execution includes eligibility and ongoing observation
Before enabling live submissions, check the platform’s current geographic restrictions and the account’s eligibility to trade. The fact that a public endpoint responds does not establish permission to place orders. Use current platform guidance and applicable location checks; a country list copied into a bot can become stale.
Once trading is authorized, refresh the market and account state before submission. Confirm the outcome token, acceptable price, quantity, existing positions and pending exposure. After submission, keep following the order through fills, cancellation or completion.
WebSocket can help with timely updates, but distinguish the streams. Public market data describes the book; authenticated user updates concern your orders and trades. Neither changes the meaning of a missing response. If updates are interrupted, reconcile state rather than assuming nothing happened during the gap.
The first accepted order confirms that one request worked in those conditions. It does not establish that the bot can handle partial fills, cancellations, restarts and lost responses consistently—or that the strategy makes money.
A useful execution layer can answer three plain questions: what is still open, what actually filled, and what position does the account now hold? That is the work surrounding the one-line API call.
Frequently asked questions
Can a Python bot place orders on Polymarket?
Yes. The authenticated Python SDK can submit orders through the CLOB API. The programming language does not determine whether a strategy has an advantage, and a successful submission does not establish final settlement.
How is a token ID different from a market ID?
A market ID refers to the market. A token ID identifies a particular tradable outcome, such as YES or NO in a binary contract. An order needs the token ID for the intended outcome.
Does matched mean the trade is fully settled?
No. It indicates matching against available liquidity; subsequent settlement can still be pending. Check the trade’s final state and filled quantity rather than inferring the whole position from that one status.
What should a bot do after an order-submission timeout?
Check orders, recent fills, positions and balances using the available identifiers. The first order may already have been accepted or filled. Reconcile the result before considering a fresh submission.
Can a partially filled order be canceled?
Only the remaining cancellable quantity can be removed. Already acquired shares stay in the position, and further fills may occur before cancellation completes. Verify the result and final quantities.
Is WebSocket required to submit an order?
No. An API client can submit it. Streams are useful for observing market and account changes, but they do not replace checking the result of an uncertain operation.
Which Python SDK is used in these examples?
The official unified package, polymarket-client, version 0.11.0. Match code to the version you have tested and check current documentation before upgrading or using an older tutorial.