platforms.polymarket

Trade prediction markets on Polymarket directly from your agent. Execute market orders and redeem settled positions using your session wallet. All operations handle approvals, signing, and submission automatically.

Note: Position data is available via agent.currentPositions.

Note: Right now, Polymarket's API accepts different decimal precision for buys and sells, this will result in dust positions if you are selling out of a position before expiry. Once expired, dust can be cleaned up during the redeem step.

platforms.polymarket.market_order()

Place a buy or sell market order on Polymarket for a specific outcome token.

Signature

agent.platforms.polymarket.market_order(
    request: {
        tokenId: str,
        size: float,
        side: str
    }
) -> PolymarketMarketOrderResponse

Parameters

Param	Type	Description
request	dict	Market order configuration
request.tokenId	str	Market token ID for the position
request.size	float	BUY: USD amount to spend (e.g., 10 = $10) SELL: Number of shares to sell (e.g., 10 = 10 shares)
request.side	str	Order side; "BUY" | "SELL"

Important: The size parameter meaning differs by the order side

• BUY: size is the USD amount to spend

• SELL: size is the number of shares/tokens to sell

Returns

• PolymarketMarketOrderResponse

class PolymarketMarketOrderResponse:
    success: bool
    data: {
        success: bool,
        orderInfo: {
            orderId: str,          # Unique order identifier
            side: str,             # "BUY" or "SELL"
            size: str,             # Order size
            priceUsd: str,         # Price per share in USD
            totalPriceUsd: str,    # Total order value in USD
            txHashes: list[str]    # Transaction hashes
        }
    } | None
    error: str | None
    error_details: dict | None

Examples

Buy Order

# BUY order - size is USD amount to spend
buy_result = agent.platforms.polymarket.market_order({
    "tokenId": "123456",
    "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.orderInfo.orderId}")
    agent.log(f"Total Price: ${buy_result.data.orderInfo.totalPriceUsd}")
    agent.log(f"Price per share: ${buy_result.data.orderInfo.priceUsd}")
else:
    agent.log(f"Error: {buy_result.error}", error=True)

Sell Order

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

if sell_result.success and sell_result.data:
    agent.log(f"Sold {sell_result.data.orderInfo.size} shares")
    agent.log(f"Received: ${sell_result.data.orderInfo.totalPriceUsd}")
    agent.log(f"Tx: {sell_result.data.orderInfo.txHashes[0]}")

Common Errors

Error	Cause	Solution
"Could not get order"	Invalid tokenId or market doesn't exist	Verify tokenId from Polymarket API
"Insufficient balance"	Not enough USDC for BUY order	Check currentPositions for USDC balance
"Insufficient shares"	Not enough shares for SELL order	Check currentPositions for position
"Order too small"	Size below minimum	Use at least $1-2 for orders
"Market closed"	Market already resolved/ended	Check market status before trading

platforms.polymarket.redeem_positions()

Redeem settled positions on Polymarket and claim winnings. Can redeem all redeemable positions or specific ones by token ID.

Signature

agent.platforms.polymarket.redeem_positions(
    request: {
        tokenIds: list[str]
    } | None = None
) -> PolymarketRedeemPositionsResponse

Parameters

Param	Type	Description
request	dict | None	Optional redemption configuration
request.tokenId	list[str]	Specific token IDs to redeem. Omit or pass empty array to redeem all redeemable positions

Returns

• PolymarketRedeemPositionsResponse

class PolymarketRedeemPositionsResponse:
    success: bool
    data: list[{
        success: bool,
        position: {
            contractAddress: str,
            tokenId: str | None,
            decimals: int,
            conditionId: str,
            formattedShares: str,
            shares: str,
            valueUsd: str,
            question: str,
            outcome: str,
            priceUsd: str,
            averagePriceUsd: str,
            isRedeemable: bool,
            isNegativeRisk: bool,
            imageUrl: str,
            initialValue: str,
            pnlUsd: str,
            pnlPercent: str,
            pnlRealizedUsd: str,
            pnlRealizedPercent: str,
            endDate: str
        } | None,
        transactionHash: str | None
    }] | None
    error: str | None
    error_details: dict | None

Examples

Redeem All Positions

# Redeem all redeemable positions (no arguments)
result = agent.platforms.polymarket.redeem_positions()

if result.success and result.data:
    for redemption in result.data:
        if redemption.success and redemption.position:
            agent.log(
                f"Redeemed: {redemption.position.question} ({redemption.position.outcome})"
            )
            agent.log(f"Value: ${redemption.position.valueUsd}")
            agent.log(f"PnL: ${redemption.position.pnlUsd} ({redemption.position.pnlPercent}%)")
            agent.log(f"Tx: {redemption.transactionHash}")
        elif redemption.success:
            agent.log(f"Unwrapped collateral: {redemption.transactionHash}")
        elif redemption.position:
            agent.log(
                f"Failed to redeem {redemption.position.question}",
                error=True
            )
else:
    agent.log(f"Error: {result.error}", error=True)

Redeem Specific Positions

# Redeem only specific positions by token ID
result = agent.platforms.polymarket.redeem_positions({
    "tokenIds": ["123456", "789012"]
})

if result.success and result.data:
    success_count = sum(1 for r in result.data if r.success)
    agent.log(f"Successfully redeemed {success_count}/{len(result.data)} positions")

Common Errors

Error	Cause	Solution
"No redeemable positions"	No winning positions to redeem	Check isRedeemable on positions first
"Invalid tokenId"	tokenId doesn't exist	Verify tokenId from currentPositions