Market Order
Execute a buy or sell market order.tokenId(string): Market token ID for the positionside(string): “BUY” or “SELL”spendUsd(number, BUY only): The USD (pUSD) amount to spend -20buys $20 of sharesshares(number, SELL only): The number of outcome shares to sellidempotencyKey(string, optional): Durable retry key for auto-mode market orders. SDKs generate one automatically; provide a stable key only when retrying the same logical order after a process restart.expiresAt(string | null, optional): ISO 8601 timestamp. In manual mode, the suggestion expires at this time. If omitted, no time-based expiry is set (suggestions are auto-cleared at eachrunstart).
idempotencyKey within the current agent run. Duplicate active or already-submitted attempts are rejected; only failures before any external side effect can retry under the same key.
Response:
success(boolean): Whether the operation succeededdata.orderInfo(object): Order information (on success)orderId(string): Unique order identifierside(string): “BUY” or “SELL”size(string): Order sizepriceUsd(string): Price per share in USDtotalPriceUsd(string): Total order value in USDtxHashes(string[]): Mined settlement transaction hashes (the order succeeds only once its settlement lands onchain)
error(string | null): Error message (on failure)
PolymarketMarketOrderResponse is returned and data is a suggestion envelope ({ suggested: true, suggestionId }) instead of order information. See Manual vs Auto Mode.
Example:
Redeem Positions
Redeem settled positions and claim winnings. Pass the token IDs of the positions to redeem - fetch your positions first and filter forisRedeemable. Agents only redeem positions their own session holds; there is no “redeem everything in the wallet” mode.
tokenIds(string[], required, non-empty): Token IDs of the positions to redeem. Requesting a token the session doesn’t hold fails with a 404.idempotencyKey(string, optional): Durable retry key for auto-mode redeem attempts. SDKs generate one perredeemPositions()/redeem_positions()call when omitted.
idempotencyKey only when retrying the same logical redeem after a process restart. Active attempts and attempts that already reached an onchain side effect return a conflict for the same key; only failures before any broadcast can retry under the same key.
Response:
success(boolean): Whether the operation succeededdata(array): Array of redemption resultssuccess(boolean): Whether this redemption succeededposition(object | null): Position details (on success)question(string): Market question textoutcome(string): Outcome name (e.g., “Yes”, “No”)marketValueUsd(string): Position value in USDpnlUsd(string): Profit/loss in USDpnlPercent(string): Profit/loss percentageisRedeemable(boolean): Whether position can be redeemedcontractAddress(string): Token contract addresstokenId(string | null): Token IDdecimals(number): Token decimalsconditionId(string): Market condition IDformattedShares(string): Human-readable share countshares(string): Raw share countaveragePriceUsd(string): Average entry priceinitialValue(string): Original position valuepnlRealizedUsd(string): Realized PnL in USDpnlRealizedPercent(string): Realized PnL percentageisNegativeRisk(boolean): Whether this is a negative risk marketimageUrl(string): Market image URLendDate(string): Market end date
transactionHash(string | null): Transaction hash.nullwithsuccess: falsemeans the position was skipped (not settled yet) and no transaction was broadcast.skippedReason(string, optional): Why the position was skipped without broadcasting (e.g. not settled yet). Present only whensuccessis false.
error(string | null): Error message (on failure)
POSITIONS_NOT_REDEEMABLE - the error message lists every skip reason. It never reports success for a redeem that executed nothing.
In manual mode the redeem is captured as a suggestion for the user to approve; data is then a suggestion envelope ({ suggested: true, suggestionId }) instead of the redemption array. See Manual vs Auto Mode.
Example:
Reading positions
Polymarket positions at invocation start are inagent.allocation.positions, with each position enriched under polymarketMetadata (question, outcome, price, value, redeemability, PnL). Filter the allocation to Polymarket positions by the presence of polymarketMetadata.
Common Errors
Errors are returned from Polymarket’s API in theerror field. Common errors include:
Note: Additional error messages may be returned by Polymarket’s API. Check the
error field in the response for specific details.
Search Events
Discover Polymarket events by name - market resolution step 1 of 2.query(string): Specific names to search for - teams, people, tickers ("egypt","australia egypt"). Never category words: “world cup” ranks generic futures above today’s match.
data):
events(array): Top-ranked matching events, each withslug,title, and themarketssearch exposes (liquidity-sorted; same market shape as Event Markets)moreEvents(array): Lower-ranked matches as{ slug, title, startDate }refs - check here when the wanted event isn’t inevents; a match is often outranked by unrelated popular markets. Enumerate a ref’s full catalog witheventMarkets(slug).
title actually names what you’re looking for before trading, and report “no matching market” rather than trading the closest miss.
Event Markets
Enumerate one event’s COMPLETE market catalog by slug - market resolution step 2 of 2, and the only authority on which markets an event has. (Polymarket splits sports matches across a main event and a companion “more markets” event that search never returns; this merges them.)slug(string): Event slug exactly as returned bysearchEvents
data):
slug,title(string): The eventmarkets(array): Every tradeable market, in descending-liquidity order:question(string): e.g. “Australia vs. Egypt: O/U 0.5”sportsMarketType(string | null):"moneyline"|"totals"|"spreads"| … (null for non-sports)groupItemTitle(string | null): the side/option this market represents within the event, e.g."Egypt"line(number | null): spread/total line, e.g.0.5gameStartTime(string | null):"2026-07-03 18:00:00+00"(space-separated, not ISOT) - use it to pick “today’s” matchliquidityUsd,volume24hUsd(number)outcomes(array): each outcome’sname(e.g."Yes"/"Over"),priceUsd, and thetokenIdorders take
Getting Token IDs
ThetokenId identifies a specific outcome (e.g., “Yes” or “No”) in a Polymarket market - a ~77-digit decimal string you must resolve, never invent. Two sources:
- From your holdings:
agent.allocation.positionsincludes invocation-start Polymarket positions with token IDs inposition.polymarketMetadata.tokenId. - From market resolution:
searchEvents(discover) →eventMarkets(enumerate) → pick the market matching the intent → the outcome’stokenId.
- Trade only the most liquid market matching the intent - markets come back liquidity-sorted; skip thin books. For a generic sports bet that’s the match’s moneyline.
- Sports model: one match = one event; a soccer moneyline is one Yes/No market per side (
groupItemTitlenames the side - “bet on Egypt” =groupItemTitle: "Egypt", outcome"Yes"). Totals are one market per line with Over/Under outcomes - “over 0.5 goals” = thetotalsmarket withline: 0.5, outcome"Over". - Never conclude a market doesn’t exist from search results - enumerate the event’s full catalog first.
Notes
- Polymarket’s API accepts different decimal precision for buys and sells. This can result in dust positions if selling a position before expiry. Clean up dust with
redeemPositions({ tokenIds })after market expiry. - Negative risk markets: Some markets use an inverted pricing model. The SDK handles this transparently, but be aware that position values may display differently.
- Invocation-start open positions are available in
agent.allocation.positions(pUSD cash stays inbalances). - Polymarket positions always include enriched metadata (question, outcome, PNL) on
position.polymarketMetadata. - SDKs generate
idempotencyKeyautomatically formarketOrderandredeemPositions; pass a stable key only when you need to resume the same logical action after a process restart.
See Also
- Positions - Polymarket positions include enriched metadata on
polymarketMetadata - Error Handling - Polymarket-specific error codes