Polymarket API Tutorial: Getting Started with the CLOB
A hands-on guide to the Polymarket CLOB API — from authentication to placing your first automated trade.
What Is the Polymarket CLOB API?
Polymarket operates a Central Limit Order Book (CLOB) that matches buy and sell orders for prediction market outcomes. The CLOB API is the programmatic gateway to this order book. It exposes two communication channels:
- REST API — Request-response endpoints for placing orders, canceling orders, fetching positions, and retrieving market metadata. Ideal for operations that don't require real-time updates.
- WebSocket API — Persistent streaming connections for real-time order book updates, trade feeds, and price changes. Essential for bots that need to react to market movements instantly.
Unlike centralized exchanges that use proprietary protocols, Polymarket's CLOB settles trades on the Polygon blockchain. Every filled order results in an on-chain transaction, which means your bot interacts with both the off-chain order book (via the API) and the on-chain settlement layer (via your wallet).
Prerequisites
What You Need Before Starting
- A funded Polymarket account with USDC on Polygon
- Python 3.9+ or Node.js 18+ installed locally
- Your Polygon wallet private key (for signing orders)
- Basic familiarity with REST APIs and JSON
- A code editor and terminal
Step 1: Install the Client Library
Polymarket provides official client libraries that handle authentication, request signing, and order construction. Choose your language:
Python
Install the Python CLOB client:
pip install py-clob-client
The py-clob-client library wraps all REST and WebSocket endpoints with Pythonic interfaces. It handles EIP-712 signature generation, nonce management, and request serialization automatically.
TypeScript / JavaScript
Install the TypeScript CLOB client:
npm install @polymarket/clob-client
The TypeScript client provides typed interfaces for all API responses, making it easier to build type-safe bots with compile-time error checking.
Step 2: Authentication and Configuration
The CLOB API uses wallet-based authentication. You sign requests with your Polygon private key, proving ownership of your trading account without transmitting the key itself.
Create a configuration object with your credentials:
Configuration Parameters
- host — The CLOB API base URL (e.g.,
https://clob.polymarket.com) - key — Your API key from the Polymarket dashboard
- secret — Your API secret (keep this secure, never commit to version control)
- passphrase — Additional authentication passphrase
- chain_id — Polygon chain ID (137 for mainnet)
- funder — Your wallet address that holds USDC for trading
Security tip: Store credentials in environment variables or a secrets manager. Never hardcode them in source files. See our bot safety guide for detailed security practices.
Step 3: Fetching Market Data
Before placing any trades, your bot needs to understand what markets are available and their current state. The API provides several market data endpoints:
List Markets
Retrieve all active markets with metadata including the question text, category, resolution source, and current prices. Markets are paginated — use the next_cursor parameter to iterate through all results.
Get Order Book
Fetch the current order book for a specific market outcome. The response includes all open bids (buy orders) and asks (sell orders) with their prices and sizes. This tells your bot the current best available prices and the depth of liquidity at each price level.
Get Market Price
Retrieve the last traded price and mid-market price for an outcome. The mid-market price is the average of the best bid and best ask — it represents the market's current consensus probability.
Step 4: Understanding Order Types
The CLOB supports two primary order types that your bot can use:
Limit Orders
Specify the exact price and size you want. The order sits on the book until it's filled by a matching counter-order or you cancel it. Limit orders give you price certainty but no fill guarantee — the market might never reach your price.
Use when: You have a specific price target and can wait for the market to come to you.
Market Orders
Execute immediately at the best available price. Market orders guarantee execution but not price — in thin markets, you may experience significant slippage (paying more or receiving less than the displayed price).
Use when: Speed matters more than price, such as reacting to breaking news or copying a trade immediately.
Step 5: Placing Your First Order
With authentication configured and market data available, you can place an order. The process involves three stages:
Build the Order
Construct an order object specifying the market token ID, side (BUY or SELL), price, and size. The client library provides builder functions that validate parameters before submission.
Sign the Order
The client library signs the order with your private key using EIP-712 typed data. This cryptographic signature proves you authorized the trade without exposing your key to the API server.
Submit to the CLOB
Send the signed order to the POST /order endpoint. The API validates the signature, checks your balance, and places the order on the book. You receive an order ID for tracking.
Step 6: WebSocket Streaming
For real-time data, connect to the WebSocket API. This is essential for bots that need to react to market changes instantly rather than polling REST endpoints.
Available Channels
- market channel — Real-time order book updates (new orders, cancellations, fills)
- trade channel — Stream of executed trades across all markets
- user channel — Your own order updates (fills, cancellations, expirations)
Subscribe to specific markets or receive updates for all markets. WebSocket connections require the same authentication as REST requests.
Step 7: Managing Positions
After placing trades, your bot needs to track open positions and handle their lifecycle:
- Monitor P&L — Track unrealized profit/loss based on current market prices versus your entry price
- Handle resolution — When a market resolves, your position converts to a payout (or zero). The API provides resolution events you can subscribe to.
- Implement exits — Define conditions under which your bot should close positions (price targets, time-based exits, stop-losses)
Common API Errors and Solutions
Error Reference
- 401 Unauthorized — Invalid API key or signature. Verify credentials and ensure your system clock is synchronized.
- 429 Too Many Requests — Rate limit exceeded. Implement exponential backoff: wait 1s, then 2s, then 4s before retrying.
- 400 Insufficient Balance — Not enough USDC to cover the order. Check available balance before placing orders.
- 400 Invalid Price — Price outside valid range (0.01 to 0.99 for binary markets). Validate prices in your order construction logic.
- 503 Service Unavailable — API temporarily down. Queue orders and retry when service recovers.
Next Steps
Now that you understand the API fundamentals, you're ready to build a complete bot. Check out our Python bot tutorial for a full implementation walkthrough, or explore bot safety best practices before deploying to production.
Want to Copy Top Polymarket Traders Automatically?
Polycool lets you follow the best wallets and copy their trades in one tap. No manual tracking needed.
Try Polycool Free →