Trading with Polymarket API

The Polymarket API enables developers and algorithmic traders to interact with prediction markets programmatically. Whether you're building trading bots, analyzing market data, or automating your trading strategy, the API provides powerful tools to execute trades and access real-time market information.

What is the Polymarket API?

The Polymarket API is a Central Limit Order Book (CLOB) API that allows you to:

• Place trades programmatically - Buy and sell shares without using the web interface
• Access real-time market data - Fetch prices, liquidity, and order book information
• Manage orders - Create, cancel, and monitor your open orders
• Retrieve trade history - Download your trading activity and performance data
• Build trading algorithms - Automate strategies like arbitrage, market making, or trend following

Since Polymarket transitioned to an order book model, the API has become essential for serious traders who need speed, precision, and automation.

Where to Find the API Documentation

The official Polymarket API documentation is available at:

📚 docs.polymarket.com/developers/CLOB

The documentation includes:

• Quick Start Guide - Get up and running in minutes
• Authentication - How to obtain and use API credentials
• API Reference - Complete endpoint documentation
• Code Examples - Sample implementations in multiple languages
• SDK Documentation - Client library guides

Official SDKs

Polymarket provides official SDKs to simplify API integration:

• TypeScript SDK: github.com/Polymarket/clob-client
• Python SDK: github.com/Polymarket/py-clob-client

These SDKs handle authentication, request formatting, and error handling, making it easier to build trading applications.

Getting Started: Authentication

Before you can trade via API, you need to authenticate your requests. Here's how:

Step 1: Create a Polymarket Account

First, you need a Polymarket account. If you don't have one yet:

1. Visit polymarket.com
2. Sign up using email or connect a wallet
3. Complete any required verification steps

Step 2: Generate API Credentials

1. Log into your Polymarket account
2. Navigate to Settings → API (or Developer Settings)
3. Generate a new API key
4. Save your credentials securely - You'll need:
   • API Key
   • API Secret (only shown once)

Step 3: Authenticate Requests

The API uses signature-based authentication. Each request must include:

• Your API key
• A cryptographic signature generated using your API secret
• A timestamp to prevent replay attacks

The official SDKs handle this automatically, but you can also implement it manually using the documentation.

How to Trade Using the API

1. Fetch Market Data

Before placing trades, you'll want to retrieve market information:

Example: Get Market Details

// Using TypeScript SDK
import { ClobClient } from '@polymarket/clob-client';

const client = new ClobClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
});

// Get market information
const market = await client.getMarket('0x1234...'); // Market ID
console.log(market);

What you can retrieve:

• Current prices for Yes/No outcomes
• Order book depth (bids and asks)
• Recent trades
• Market liquidity
• Resolution criteria

2. Place a Buy Order

To buy shares programmatically:

Example: Buy Shares

// Place a market buy order
const order = await client.createOrder({
  market: '0x1234...', // Market ID
  side: 'BUY', // or 'SELL'
  type: 'MARKET', // or 'LIMIT'
  size: '100', // Number of shares
  price: '0.60', // Price per share (required for LIMIT orders)
});

console.log('Order placed:', order);

Order Types:

• MARKET: Execute immediately at the best available price
• LIMIT: Only execute if the price reaches your target

3. Place a Limit Order

Limit orders allow you to set a specific price:

// Place a limit buy order
const limitOrder = await client.createOrder({
  market: '0x1234...',
  side: 'BUY',
  type: 'LIMIT',
  size: '500', // 500 shares
  price: '0.55', // Only buy if price is 55¢ or lower
});

4. Cancel an Order

To cancel an open order:

// Cancel an order by ID
await client.cancelOrder('order-id-123');

5. Check Order Status

Monitor your open orders:

// Get all open orders
const openOrders = await client.getOpenOrders();

// Get a specific order
const order = await client.getOrder('order-id-123');

6. Retrieve Trade History

Download your trading activity:

// Get your trade history
const trades = await client.getTrades({
  market: '0x1234...', // Optional: filter by market
  limit: 100, // Number of trades to retrieve
});

Common Trading Strategies with API

Strategy 1: Arbitrage Bot

Monitor multiple markets for price discrepancies:

// Pseudo-code example
async function arbitrageBot() {
  const markets = await client.getMarkets();
  
  for (const market of markets) {
    const price = market.currentPrice;
    // Check for arbitrage opportunities
    if (price < 0.50) {
      // Buy if undervalued
      await client.createOrder({
        market: market.id,
        side: 'BUY',
        type: 'MARKET',
        size: '100',
      });
    }
  }
}

Strategy 2: Market Making

Provide liquidity by placing orders on both sides:

// Place buy and sell orders around current price
const currentPrice = 0.60;

// Buy order at 0.59
await client.createOrder({
  market: '0x1234...',
  side: 'BUY',
  type: 'LIMIT',
  size: '100',
  price: '0.59',
});

// Sell order at 0.61
await client.createOrder({
  market: '0x1234...',
  side: 'SELL',
  type: 'LIMIT',
  size: '100',
  price: '0.61',
});

Strategy 3: Automated Position Management

Set up stop-losses and take-profits:

// Monitor positions and execute trades based on conditions
async function managePositions() {
  const positions = await client.getPositions();
  
  for (const position of positions) {
    if (position.pnl < -0.10) {
      // Stop loss: exit if down 10%
      await client.createOrder({
        market: position.market,
        side: 'SELL',
        type: 'MARKET',
        size: position.size,
      });
    }
  }
}

API Rate Limits and Best Practices

Rate Limits

The Polymarket API has rate limits to prevent abuse:

• Public endpoints: Typically 60 requests per minute
• Trading endpoints: Varies based on your account tier
• WebSocket connections: Unlimited (for real-time data)

Tips:

• Use WebSocket connections for real-time data instead of polling
• Implement exponential backoff for retries
• Cache market data when possible
• Batch requests when applicable

Best Practices

1. Error Handling: Always implement proper error handling for network issues, invalid orders, and API errors
2. Testing: Use testnet or small amounts when developing
3. Security: Never expose your API secret in client-side code or public repositories
4. Monitoring: Log all API calls and responses for debugging
5. Risk Management: Implement position limits and stop-losses in your code

Common Use Cases

• Algorithmic Trading: Execute complex strategies automatically
• Arbitrage: Find and exploit price differences across markets
• Market Analysis: Build tools to analyze market trends and sentiment
• Portfolio Management: Automate rebalancing and risk management
• Data Collection: Gather historical data for research and backtesting

Troubleshooting

Authentication Errors

• Verify your API key and secret are correct
• Check that your system clock is synchronized (timestamps matter)
• Ensure you're using the correct API endpoint

Order Rejection

• Verify you have sufficient balance
• Check that the market is still active
• Ensure your order parameters are valid (size, price, etc.)

Rate Limit Errors

• Implement request throttling
• Use WebSocket for real-time updates
• Consider upgrading your API tier if available

Next Steps

1. Read the Documentation: Visit docs.polymarket.com/developers/CLOB for complete API reference
2. Download an SDK: Choose TypeScript or Python SDK from the GitHub repositories
3. Start Small: Begin with simple market data queries before placing trades
4. Test Thoroughly: Use small amounts to test your strategies
5. Join the Community: Connect with other API users in Polymarket's Discord or forums

The Polymarket API opens up powerful possibilities for automated trading and market analysis. With proper authentication, error handling, and risk management, you can build sophisticated trading systems that operate 24/7.

---