Building automated trading algorithms, data pipelines, and analytics bots on Polymarket requires programmatic access via its developer API ecosystem. Polymarket operates a modular architecture that separates public market discovery from low-latency order execution.
In this guide, we explain how to connect to the Polymarket API, differentiate between the Gamma and CLOB APIs, derive Layer-2 (L2) authentication credentials, and place your first automated trade using Python.
Polymarket API Architecture Overview
Polymarket’s API ecosystem is divided into three primary services:
- Gamma API (
https://gamma-api.polymarket.com): Public REST API used for market discovery, resolution data, event metadata, search queries, and historical volume. Requires no authentication or API keys. - CLOB API (
https://clob.polymarket.com): Central Limit Order Book API for high-speed trading operations—including placing limit/market orders, canceling orders, viewing live order book depth, and checking balances. Requires L2 HMAC authentication. - Data API (
https://data-api.polymarket.com): User-specific position tracking, PnL analytics, and transaction history.
If you are building AI agents to automate your strategy, see our guide on how to connect OpenClaw to Polymarket or our specialized tutorial on how to build a Polymarket weather bot.
Step 1: Fetching Public Data with the Gamma API (No Auth)
To pull live markets, tags, and pricing data, you can send standard HTTP GET requests without generating any keys.
Example: Querying Active Markets via cURL
curl -X GET "https://gamma-api.polymarket.com/events?closed=false&limit=5" \
-H "Accept: application/json"Example: Querying Markets with Python
import requests
url = "https://gamma-api.polymarket.com/markets"
params = {"limit": 10, "active": True}
response = requests.get(url, params=params)
markets = response.json()
for market in markets:
print(f"Question: {market.get('question')}")
print(f"Tokens: {market.get('clobTokenIds')}")
print(f"Volume: ${float(market.get('volume', 0)):,.2f}\n")Step 2: Generating Layer-2 (L2) CLOB API Credentials
Trading on the CLOB API requires an API Key, API Secret, and Passphrase. These credentials are generated by signing an EIP-712 structured message with your Ethereum/Polygon private key.
Authentication Flow:
- Your client signs a cryptographic timestamp message with your wallet private key.
- The signed payload is sent to the CLOB endpoint to derive scoped L2 credentials.
- All subsequent trading requests are signed via HMAC-SHA256 using your API Secret.
Step 3: Setting Up the Official Python SDK
The fastest and most secure way to interact with the CLOB API is using the official Python client: py-clob-client.
Installation
pip install py-clob-client web3 requestsStep 4: Authenticated Trading Examples in Python
1. Initializing the Authenticated Client
from py_clob_client.client import ClobClient
from py_clob_client.clob_types import ApiCreds
HOST = "https://clob.polymarket.com"
CHAIN_ID = 137 # Polygon Mainnet
PRIVATE_KEY = "0xYOUR_BOT_PRIVATE_KEY"
# Option A: Initialize and derive credentials automatically
client = ClobClient(
host=HOST,
key=PRIVATE_KEY,
chain_id=CHAIN_ID
)
# Derive or create API credentials
creds: ApiCreds = client.create_or_derive_api_creds()
client.set_api_creds(creds)
print(f"Authenticated with API Key: {creds.api_key}")2. Fetching Live Order Book Depth
# Fetch order book for a specific token ID
token_id = "TOKEN_ID_HERE"
order_book = client.get_order_book(token_id)
print("--- ASKS ---")
for ask in order_book.asks[:3]:
print(f"Price: ${ask.price} | Size: {ask.size}")
print("--- BIDS ---")
for bid in order_book.bids[:3]:
print(f"Price: ${bid.price} | Size: {bid.size}")3. Submitting a Limit Order
from py_clob_client.clob_types import OrderArgs, BUY
# Place a Buy order for 50 shares at $0.45
order_args = OrderArgs(
price=0.45,
size=50.0,
side=BUY,
token_id=token_id
)
signed_order = client.create_order(order_args)
response = client.post_order(signed_order)
print(f"Order Status: {response}")For strategic risk management and position sizing math, see our [Polymarket strategy guide for 2026](https://tradetheoutcome.com/polymarket-strategy-2026/).
Step 5: Subscribing to Real-Time WebSocket Feeds
For low-latency execution, polling REST endpoints is too slow. Use Polymarket’s WebSocket feed for sub-second updates on market price changes and order fills:
- WebSocket URL:
wss://ws-subscriptions-clob.polymarket.com/ws/market - Channels:
book(order book changes),price_change(recent trade updates).
Developer Best Practices & Rate Limits
- Rate Limiting: Polymarket enforces rate limits across REST endpoints (typically 100 requests per 10 seconds for standard endpoints). Implement exponential backoff when encountering HTTP 429 status codes.
- Use Scoped Sub-Wallets: Never embed your primary cold wallet private key into trading bot scripts. Always use isolated sub-wallets funded with dedicated trading capital.
- Nonce Management: When submitting high-frequency orders, track client nonces carefully to prevent out-of-order execution errors.
Do I need an API key to access public market data?
No. The Gamma API (https://gamma-api.polymarket.com) provides public access to market lists, token IDs, prices, and resolution metadata without any authentication or API keys.
Which programming language is best for Polymarket bots?
Python and TypeScript/JavaScript are the two most popular languages for Polymarket bots. Polymarket provides official client libraries for both (py-clob-client for Python and @polymarket/clob-client for Node.js).
How do I authenticate with the CLOB API?
You authenticate by signing an EIP-712 structured message with your Polygon wallet private key, which generates an API Key, Secret, and Passphrase for HMAC-SHA256 signature verification.
What is the difference between the Gamma API and CLOB API?
The Gamma API is a read-only metadata service for browsing events, markets, and categories. The CLOB API is the high-performance trading engine used for live order books, order placement, and position execution.
