Polymarket

​

Market Order

def market_order(request: PolymarketMarketOrderRequest | PolymarketMarketOrderRequestInput) -> PolymarketMarketOrderResponse

• tokenId (string): Market token ID for the position
• size (number): Order size (meaning differs by side)
• side (string): “BUY” or “SELL”
• idempotencyKey (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 each run start).

• BUY: size is the USD amount to spend (e.g., 10 = $10 worth of shares)
• SELL: size is the number of shares to sell (e.g., 10 = 10 shares)

• success (boolean): Whether the operation succeeded
• data.orderInfo (object): Order information (on success)
  • orderId (string): Unique order identifier
  • side (string): “BUY” or “SELL”
  • size (string): Order size
  • priceUsd (string): Price per share in USD
  • totalPriceUsd (string): Total order value in USD
  • txHashes (string[]): Transaction hashes
• error (string | null): Error message (on failure)

# BUY order - size is USD amount to spend
# tokenId comes from Polymarket's API for the specific outcome you want to trade
token_id = "71321045679252212594626385532706912750332728571942532289631379312455583992563"

buy_result = agent.platforms.polymarket.market_order({
    "tokenId": token_id,
    "size": 10,  # Spend $10 to buy shares
    "side": "BUY"
})

if buy_result.success and buy_result.data:
    agent.log(f"Order ID: {buy_result.data.order_info.order_id}")
    agent.log(f"Total Price: ${buy_result.data.order_info.total_price_usd}")
    agent.log(f"Price per share: ${buy_result.data.order_info.price_usd}")

# SELL order - size is number of shares to sell
sell_result = agent.platforms.polymarket.market_order({
    "tokenId": token_id,
    "size": 5,  # Sell 5 shares
    "side": "SELL"
})

if sell_result.success and sell_result.data:
    agent.log(f"Sold {sell_result.data.order_info.size} shares")
    agent.log(f"Received: ${sell_result.data.order_info.total_price_usd}")

​

Redeem Positions

def redeem_positions(request: PolymarketRedeemPositionsRequest | PolymarketRedeemPositionsRequestInput) -> PolymarketRedeemPositionsResponse

• 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 per redeemPositions() / redeem_positions() call when omitted.

• success (boolean): Whether the operation succeeded
• data (array): Array of redemption results
  • success (boolean): Whether this redemption succeeded
  • position (object | null): Position details (on success)
    • question (string): Market question text
    • outcome (string): Outcome name (e.g., “Yes”, “No”)
    • valueUsd (string): Position value in USD
    • pnlUsd (string): Profit/loss in USD
    • pnlPercent (string): Profit/loss percentage
    • isRedeemable (boolean): Whether position can be redeemed
    • contractAddress (string): Token contract address
    • tokenId (string | null): Token ID
    • decimals (number): Token decimals
    • conditionId (string): Market condition ID
    • formattedShares (string): Human-readable share count
    • shares (string): Raw share count
    • averagePriceUsd (string): Average entry price
    • initialValue (string): Original position value
    • pnlRealizedUsd (string): Realized PnL in USD
    • pnlRealizedPercent (string): Realized PnL percentage
    • isNegativeRisk (boolean): Whether this is a negative risk market
    • imageUrl (string): Market image URL
    • endDate (string): Market end date
  • transactionHash (string | null): Transaction hash. null with success: false means 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 when success is false.
• error (string | null): Error message (on failure)

# Redeem this agent's settled positions
portfolio = agent.platforms.polymarket.positions()
redeemable = [
    p.token_id
    for p in (portfolio.data.positions if portfolio.success and portfolio.data else [])
    if p.is_redeemable and p.token_id
]

if redeemable:
    redemption = agent.platforms.polymarket.redeem_positions({"tokenIds": redeemable})

    if redemption.success and redemption.data:
        successful = [r for r in redemption.data if r.success]
        agent.log(f"Redeemed {len(successful)} positions")

        for tx in redemption.data:
            if tx.success and tx.position:
                agent.log(f"Redeemed: {tx.position.question} ({tx.position.outcome})")
                agent.log(f"Value: ${tx.position.value_usd}")
                agent.log(f"PnL: ${tx.position.pnl_usd} ({tx.position.pnl_percent}%)")
                agent.log(f"Tx: {tx.transaction_hash}")

​

Get Positions

def positions() -> PolymarketPositionsResponse

• success (boolean): Whether the operation succeeded
• data.totalValue (number): Total USD value of the session’s Polymarket positions
• data.positions (array): Enriched positions — each with tokenId, question, outcome, priceUsd, valueUsd, shares, isRedeemable, pnlUsd, pnlPercent, endDate, …
• error (string): Error message (only present on failure)

result = agent.platforms.polymarket.positions()
if result.success and result.data:
    for pos in result.data.positions:
        agent.log(f"{pos.question} [{pos.outcome}]: ${pos.value_usd} (PnL ${pos.pnl_usd})")
        if pos.is_redeemable:
            agent.log(f"  redeemable — tokenId {pos.token_id}")

​

Common Errors

​

Getting Token IDs

• Polymarket’s CLOB API: GET https://clob.polymarket.com/markets returns all markets with their tokens array, each containing a token_id and outcome.
• From your holdings: If you already hold shares, agent.portfolio.positions includes Polymarket positions with token IDs in position.polymarketMetadata.tokenId.

​

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.
• Open positions are available via agent.portfolio.positions (pUSD cash stays in agent.portfolio.balances).
• Polymarket positions always include enriched metadata (question, outcome, PNL) on position.polymarketMetadata.
• SDKs generate idempotencyKey automatically for marketOrder and redeemPositions; pass a stable key only when you need to resume the same logical action after a process restart.

​

See Also

• Polymarket Agent Example — Full working prediction market agent
• Positions — Polymarket positions include enriched metadata on polymarketMetadata
• Error Handling — Polymarket-specific error codes