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.marketOrder()

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

Signature

agent.platforms.polymarket.marketOrder(
  request: {
    tokenId: string;
    size: number;
    side: string;
  }
): Promise<PolymarketMarketOrderResponse>

Parameters

Param	Type	Description
request	object	Market order configuration
request.tokenId	string	Market token ID for the position
request.size	number	BUY: USD amount to spend (e.g., 10 = $10) SELL: Number of shares to sell (e.g., 10 = 10 shares)
request.side	string	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

• Promise<PolymarketMarketOrderResponse>

type PolymarketMarketOrderResponse = {
  success: boolean;
  data?: {
    success: boolean;
    orderInfo: {
      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;
  errorMessage?: string;
  errorDetails?: object;
}

Examples

Buy Order

// BUY order - size is USD amount to spend
const buyResult = await agent.platforms.polymarket.marketOrder({
  tokenId: "123456",
  size: 10,  // Spend $10 to buy shares
  side: "BUY"
});

if (buyResult.success && buyResult.data) {
  await agent.log(`Order ID: ${buyResult.data.orderInfo.orderId}`);
  await agent.log(`Total Price: $${buyResult.data.orderInfo.totalPriceUsd}`);
  await agent.log(`Price per share: $${buyResult.data.orderInfo.priceUsd}`);
} else {
  await agent.log(`Error: ${buyResult.error}`, { error: true });
}

Sell Order

// SELL order - size is number of shares to sell
const sellResult = await agent.platforms.polymarket.marketOrder({
  tokenId: "123456",
  size: 5,  // Sell 5 shares
  side: "SELL"
});

if (sellResult.success && sellResult.data) {
  await agent.log(`Sold ${sellResult.data.orderInfo.size} shares`);
  await agent.log(`Received: $${sellResult.data.orderInfo.totalPriceUsd}`);
  await agent.log(`Tx: ${sellResult.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.redeemPositions()

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

Signature

agent.platforms.polymarket.redeemPositions(
  request?: {
    tokenIds?: string[];
  }
): Promise<PolymarketRedeemPositionsResponse>

Parameters

Param	Type	Description
request?	object	Optional redemption configuration
request.tokenId?	string[]	Specific token IDs to redeem. Omit or pass empty array to redeem all redeemable positions

Returns

• Promise<PolymarketRedeemPositionsResponse>

type PolymarketRedeemPositionsResponse = {
  success: boolean;
  data?: Array<{
    success: boolean;
    position: {
      contractAddress: string;
      tokenId: string | null;
      decimals: number;
      conditionId: string;
      formattedShares: string;
      shares: string;
      valueUsd: string;
      question: string;
      outcome: string;
      priceUsd: string;
      averagePriceUsd: string;
      isRedeemable: boolean;
      isNegativeRisk: boolean;
      imageUrl: string;
      initialValue: string;
      pnlUsd: string;
      pnlPercent: string;
      pnlRealizedUsd: string;
      pnlRealizedPercent: string;
      endDate: string;
    } | null;
    transactionHash: string | null;
  }>;
  error?: string;
  errorMessage?: string;
  errorDetails?: object;
}

Examples

Redeem All Positions

// Redeem all redeemable positions (no arguments)
const result = await agent.platforms.polymarket.redeemPositions();

if (result.success && result.data) {
  for (const redemption of result.data) {
    if (redemption.success && redemption.position) {
      await agent.log(
        `Redeemed: ${redemption.position.question} (${redemption.position.outcome})`
      );
      await agent.log(`Value: $${redemption.position.valueUsd}`);
      await agent.log(`PnL: $${redemption.position.pnlUsd} (${redemption.position.pnlPercent}%)`);
      await agent.log(`Tx: ${redemption.transactionHash}`);
    } else if (redemption.success) {
      await agent.log(`Unwrapped collateral: ${redemption.transactionHash}`);
    } else if (redemption.position) {
      await agent.log(
        `Failed to redeem ${redemption.position.question}`,
        { error: true }
      );
    }
  }
} else {
  await agent.log(`Error: ${result.error}`, { error: true });
}

Redeem Specific Positions

// Redeem only specific positions by token ID
const result = await agent.platforms.polymarket.redeemPositions({
  tokenIds: ["123456", "789012"]
});

if (result.success && result.data) {
  const successCount = result.data.filter(r => r.success).length;
  await agent.log(`Successfully redeemed ${successCount}/${result.data.length} 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