How to Build a Polymarket Trading Bot: Python Tutorial with the CLOB API

Polymarket's CLOB (Central Limit Order Book) API lets you build trading bots that fetch markets, monitor prices, and place orders programmatically. This guide walks you through building a Polymarket bot in Python from scratch.

Prerequisites

• Python 3.9+: Installed on your machine
• Polymarket account: Active account with USDC deposited
• Wallet: Ethereum wallet (MetaMask or similar) connected to Polymarket
• API key: Generate API credentials through Polymarket's developer settings
• Libraries: py-clob-client (Polymarket's Python SDK), web3, requests

Step 1: Environment setup

Install the required libraries using pip:

pip install py-clob-client web3 python-dotenv

Store your credentials in a .env file (never commit this to git):

• POLYMARKET_API_KEY — Your API key
• POLYMARKET_API_SECRET — Your API secret
• POLYMARKET_PASSPHRASE — Your API passphrase
• PRIVATE_KEY — Your wallet private key (handle with extreme care)

Step 2: Initialize the CLOB client

Create a client instance using py-clob-client. The client handles authentication, request signing, and API communication. Initialize it with your API credentials and wallet private key loaded from environment variables.

Key client methods:

• get_markets() — Fetch available markets
• get_order_book() — Get current bids and asks for a market
• create_order() — Place a new order
• cancel_order() — Cancel an existing order
• get_positions() — View your current positions

Step 3: Fetch and filter markets

Query available markets and filter by criteria like volume, category, or status. Each market has a condition ID (used for trading) and metadata including the question, resolution source, and current prices.

Useful filters:

• Filter by active=True to get only live markets
• Sort by volume to find the most liquid markets
• Filter by end date to focus on near-term resolutions

Step 4: Read the order book

The order book shows current bids (buy orders) and asks (sell orders). Analyzing order book depth tells you about liquidity and likely fill prices.

What to look for:

• Best bid/ask: The highest buy price and lowest sell price
• Spread: Gap between best bid and ask. Tighter = more liquid
• Depth: How many contracts are available at each price level
• Imbalance: More bids than asks (or vice versa) can signal directional pressure

Step 5: Place orders

To place an order, specify the market (condition ID and token ID), side (buy/sell), price, and size. Use limit orders to control your entry price.

Order parameters:

• token_id — The specific outcome token (Yes or No)
• side — BUY or SELL
• price — Price in USDC (0.01 to 0.99)
• size — Number of shares

Safety rules for your bot:

• Always use limit orders. Never place market orders in automated systems.
• Set maximum position size limits in code.
• Add a kill switch that cancels all orders if something goes wrong.
• Start with tiny sizes ($1-$5) until your bot is proven.

Step 6: Build a monitoring loop

A basic bot runs a loop that:

1. Fetches current market prices at a regular interval
2. Compares to your strategy's target prices or thresholds
3. Places, adjusts, or cancels orders as needed
4. Logs all activity for debugging and tax records
5. Checks for errors and handles rate limits

Rate limits: Polymarket enforces API rate limits. Implement backoff logic: if you get a 429 response, wait exponentially longer between retries. A 5-10 second polling interval is a safe starting point.

Step 7: Risk management

Every bot needs safeguards:

• Max position per market: Cap how much your bot can hold in any single market
• Max total exposure: Limit total capital deployed across all markets
• Loss limit: If daily losses exceed a threshold, stop trading and alert you
• Stale quote protection: If the bot can't update quotes for 5+ minutes (API failure), cancel all open orders
• Event calendar: Don't leave quotes up during scheduled resolutions or major news events

Power your bot with Alphascope signals

Alphascope provides the intelligence that makes your bot smarter:

• News → Feed news signals into your bot to adjust quotes around market-moving events.
• Predictions → AI probability estimates can serve as fair value anchors for your bot's quoting logic.
• Arbitrage → Detect cross-platform price gaps your bot can exploit.

FAQ

Is automated trading allowed on Polymarket?

Yes. Polymarket provides a public API specifically for programmatic trading. Many of the platform's most active traders use bots.

What is py-clob-client?

It's Polymarket's official Python library for interacting with the CLOB API. It handles authentication, order signing, and API calls. Install with pip install py-clob-client.

How do I handle my private key safely?

Never hardcode private keys. Use environment variables, a .env file (excluded from git), or a secrets manager. Consider using a dedicated trading wallet with limited funds.

What programming language is best for Polymarket bots?

Python is the most common due to py-clob-client. JavaScript/TypeScript also works well with Polymarket's API. Choose whatever you're most productive in.