Polymarket

Trade prediction markets on Polygon.

Market Order

Execute a buy or sell market order.

TypeScript

async marketOrder(request: PolymarketMarketOrderRequest): Promise<PolymarketMarketOrderResponse>

Python

Request Parameters:

• tokenId (string): Market token ID for the position

• size (number): Order size (meaning differs by side)

• side (string): "BUY" or "SELL"

Size Parameter:

• 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)

Response:

• 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 / error_message (string | null): Error message (on failure)

Example:

TypeScript

// 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}`);
}

// 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}`);
}

Python

Redeem Positions

Redeem settled positions and claim winnings.

TypeScript

async redeemPositions(request?: PolymarketRedeemPositionsRequest): Promise<PolymarketRedeemPositionsResponse>

Python

Request Parameters (optional):

• tokenIds (string[], optional): Specific token IDs to redeem. Omit or pass empty array to redeem all redeemable positions.

Response:

• 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

    • Plus additional fields

  • transactionHash (string | null): Transaction hash (on success)

• error / error_message (string | null): Error message (on failure)

Example:

TypeScript

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

if (redemption.success && redemption.data) {
  const successful = redemption.data.filter(r => r.success);
  await agent.log(`Redeemed ${successful.length} positions`);
  
  for (const tx of redemption.data) {
    if (tx.success && tx.position) {
      await agent.log(`Redeemed: ${tx.position.question} (${tx.position.outcome})`);
      await agent.log(`Value: $${tx.position.valueUsd}`);
      await agent.log(`PnL: $${tx.position.pnlUsd} (${tx.position.pnlPercent}%)`);
      await agent.log(`Tx: ${tx.transactionHash}`);
    }
  }
}

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

Python

Common Errors

Errors are returned from Polymarket's API in the error / error_message field. Common errors include:

Error	Cause	Solution
"Insufficient balance"	Not enough USDC for BUY order	Check currentPositions for USDC balance
"No orderbook exists for the requested token id"	Invalid tokenId or market doesn't exist	Verify tokenId from Polymarket API

Note: Additional error messages may be returned by Polymarket's API. Check the error / error_message field in the response for specific details.

Notes

• Polymarket's API accepts different decimal precision for buys and sells. This can result in dust positions if selling a position before expiry. This can be cleaned up with the redeemPositions() method after expiry.

• Position data is available via agent.currentPositions and agent.getCurrentPositions().

• Polymarket positions include enriched metadata (question, outcome, PNL) when retrieved via getCurrentPositions().