Polymarket API Guide - Build Your First Trading Bot in 2026

Câu hỏi thường gặp

• Does Polymarket have a public API?
  Yes - three of them. CLOB (clob.polymarket.com) handles trading, Gamma (gamma-api.polymarket.com) serves market discovery and metadata, and Data (data-api.polymarket.com) provides historical analytics. Gamma and Data are unauthenticated. CLOB requires an API key derived from your Polygon proxy wallet.
• What Python SDK should I use?
  Use the official py-clob-client, version 0.40 or newer. The April 28, 2026 pUSD / CLOB v2 upgrade changed the collateral address inside every order signature from USDC.e to pUSD, and only py-clob-client 0.40+ signs against pUSD correctly; older 0.3x releases fail with 'signature verification failed'. Install it with `pip install "py-clob-client>=0.40.0"`. Configure it with your private key, chain_id=137, signature_type=1 (POLY_PROXY), and your funder address (your Polymarket proxy wallet). It handles EIP-712 order signing and API credential derivation for you.
• What are the Polymarket API rate limits?
  Order placement is capped at roughly 60 per minute per API key with a burst of about 10 per second. Cancellations get a higher ceiling (~120/min). Market data reads via CLOB are ~300/min. Gamma is more generous but still enforces 429s. Always implement exponential backoff with jitter when you hit a 429.
• What is the condition_id vs token_id problem?
  Gamma API returns a market's condition_id, but CLOB trading endpoints need a token_id. Each market has one condition_id and two or more token_ids (one per outcome). The Gamma response includes a clobTokenIds field. Parse that JSON string array and use the matching token_id for each outcome. Mixing them up is the #1 new-developer bug.
• Do I need a testnet to prototype?
  Polymarket does not run a public testnet. The standard workaround is paper trading with tiny real amounts. Place $1-$5 orders on low-liquidity markets to check your code, then scale up. Budget a few dollars for your first week of debugging. It is faster and cheaper than building a mock exchange.
• How do I handle the WebSocket disconnecting?
  Expect disconnects every few hours. Build auto-reconnect with exponential backoff. On every reconnect, re-fetch the order book via REST before you resubscribe. Otherwise your local book will drift from the real one. Send a ping every 20 seconds and treat two missed pongs as a dead connection.
• Can my bot earn liquidity rewards?
  Yes - this is where most API users earn. Polymarket hands out roughly $5M/month in general liquidity rewards, plus $5M+/month in sports-specific rewards. The formula favors orders near the midpoint, with real size and time-on-book. A simple two-sided quoter that reprices on every book update can earn solid rebates, even without directional alpha.
• Is my private key safe if I use py-clob-client?
  Yes, as long as you handle the key correctly. py-clob-client signs orders locally with EIP-712 and only sends signed messages. Your key never leaves your machine. The real risks are environmental: committing the key to git, pasting it into chat, or running your bot on a compromised host. Use a dedicated trading wallet (separate from your main MetaMask), store the key in environment variables, and rotate it if in doubt.
• How do I buy and sell on the Polymarket CLOB API?
  Build an OrderArgs with the outcome token_id, a price aligned to the market tick size, a size in shares, and side="BUY" or "SELL". Sign it with create_order() (EIP-712) and submit with post_order(order, OrderType.GTC). BUY needs USDC; SELL needs shares you already hold. There is no separate market order - send a FAK order at an aggressive price to take liquidity immediately.
• What are the main Polymarket CLOB v2 REST endpoints?
  Base URL https://clob.polymarket.com. Public reads: GET /markets and /sampling-markets (tradeable books only), /book?token_id=, /price?token_id=&side=buy, /midpoint?token_id=, /spread?token_id=, /tick-size?token_id=, /prices-history. Authenticated: POST /order, DELETE /order, GET /orders, GET /balance-allowance. /book, /price and /midpoint return 404 for closed markets.
• Why is my Polymarket order rejected as off-tick or invalid price?
  Every price must be an exact multiple of the market minimum_tick_size (usually 0.01, sometimes 0.001). Fetch it from /tick-size?token_id= and round your price to it before signing. Passing a condition_id where a token_id is expected, or an unaligned price, are the two most common rejection causes.
• Is py-clob-client still the right tool in 2026?
  Yes, but pin 0.40 or newer. The 0.40 line is the minimum that signs orders against pUSD after the April 28, 2026 CLOB v2 collateral switch - 0.3x releases sign against the retired USDC.e address and fail. Pin it as `py-clob-client>=0.40,<0.50` so you get pUSD support without a surprise breaking change, and verify endpoints against the live API since some features may move to a future unified SDK.