Gabay sa Polymarket API: CLOB, REST at Trading Bots (2026)

Kabanata 27 ng 33

Ang Maikling Bersyon

Naglalantad ang Polymarket ng tatlong pampublikong API: CLOB (trading), Gamma (market discovery), at Data (analytics). Ang opisyal na Python SDK ay py-clob-client 0.34.6. Gumagamit ang authentication ng API key + ECDSA signature, na may mga order na pinipirmahan sa pamamagitan ng EIP-712 sa isang Polygon proxy wallet. Ang mga rate limit ay naglilimita sa iyo sa humigit-kumulang 60 order/minuto bawat key. Ang pinakamalaking gotcha para sa mga bagong developer ay ang problemang condition_id → token_id mapping sa pagitan ng Gamma at CLOB - lutasin muna iyon, at susunod na ang lahat. Humigit-kumulang $40M/buwan sa likidez (liquidity) mga gantimpala (rewards) at spread na nakukuha ng mga bot ang kinikita sa Polymarket, halos lahat ay mula sa mga user ng API.

Tatlong magkakahiwalay na serbisyo: CLOB (9,000/10s auth) para sa trading, Gamma (4,000/10s public) para sa discovery, Data (1,000/10s public) para sa historical analytics.

Bahagi 1: Ang Tatlong API

Malinaw na hinahati ng Polymarket ang mga gawain sa tatlong magkakaibang serbisyo. Ang paggamit ng tamang API para sa bawat trabaho ay nagpapanatiling mabilis, simple, at pasok sa mga rate limit ang iyong bot.

Karaniwang gumagamit ang isang bot loop ng Gamma upang maghanap ng mga market, CLOB upang kunin ang mga talaan ng order at maglagay ng mga trade, at Data upang i-back-test ang performance ng estratehiya offline. Isipin ang Gamma bilang ang "catalog," ang CLOB bilang ang "exchange," at ang Data bilang ang "warehouse."

Ang L1 ay pumipirma sa "ClobAuthDomain" EIP-712 struct gamit ang chainId 137 upang makuha ang mga kredensyal. Ang L2 HMAC-SHA256 ay pumipirma sa bawat kasunod na request gamit ang POLY_SIGNATURE headers.

Bahagi 2: Authentication & ang Proxy Wallet Model

Hindi nilalagdaan ng Polymarket ang mga trade gamit ang private key ng iyong main wallet. Sa halip, gumagamit ito ng Gnosis Safe-style proxy wallet: pinahihintulutan ng iyong main wallet ang isang proxy, at ang proxy ang nagsasagawa ng lahat ng trade sa Polygon. Nakikipag-ugnayan ang iyong API bot sa proxy na iyon.

Ang kailangan mo

• API key - i-generate sa Polymarket Settings → Developer
• Private key - ang key ng iyong trading wallet (HINDI ang iyong main MetaMask seed phrase)
• Funder address - ang address ng iyong proxy wallet (ipinapakita sa Settings → Wallet)
• Chain ID - 137 (Polygon mainnet)
• Signature type - 1 (POLY_PROXY, standard para sa mga retail user)

Signature type 1 (POLY_PROXY) para sa mga Magic-link account, type 2 (GNOSIS_SAFE) para sa mga browser-wallet proxy, type 0 (EOA) para sa direktang mga key. Kinakailangan ang Funder para sa types 1 at 2.

Bahagi 3: Pag-install ng py-clob-client

Ang opisyal na Python SDK ang pinakamabilis na paraan mula zero hanggang unang order. Gagamitin natin ang bersyon 0.34.6, na kasalukuyan noong Abril 2026.

# Gumawa muna ng virtual environment
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# I-install ang SDK
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

Pangunahing configuration ng client

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# Isang beses lang: kunin at i-cache ang API credentials
client.set_api_creds(client.create_or_derive_api_creds())

Ang tawag na create_or_derive_api_creds() ay pumipirma ng mensahe gamit ang iyong private key at ipinagpapalit ito para sa isang API key, secret, at passphrase. I-cache ang mga ito sa iyong .env pagkatapos ng unang takbo para hindi mo ma-hit ang derive endpoint sa bawat startup.

Nagbabalik ang Gamma /markets ng outcomePrices, clobTokenIds, volume24hr, tags. Gamitin ang tag_slug + order=volume24hr bilang default na query ng bot scanner.

Bahagi 4: Pagdiskubre ng mga Market sa pamamagitan ng Gamma

Bago ka makapag-trade, kailangan mong maghanap ng mga market na sulit i-trade. Nagbabalik ang Gamma ng JSON na may lahat ng ipinapakita ng Polymarket UI: tanong, mga resulta, presyo, dami sa loob ng 24h, petsa ng pag-expire, mga tag, at mga larawan.

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

Mga kapaki-pakinabang na parameter ng query sa Gamma

Ipinapakita ng Gamma ang conditionId (isa bawat market); ang CLOB ay nagte-trade sa token_id (isa bawat resulta). Ang clobTokenIds ay isang JSON-encoded na string array na naka-index para tumugma sa mga resulta.

Bahagi 5: ang Mapping ng condition_id → token_id

Ito ang #1 na pain point sa pag-develop ng Polymarket bot. Nagbabalik ang Gamma ng isang condition_id (isa bawat market). Gumagamit ang mga trade sa CLOB ng isang token_id (isa bawat outcome). Palagi mong kailangan ang pareho.

# Bawat Gamma market object ay naglalaman ng 'clobTokenIds' - isang JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # Unang outcome
no_token = token_ids[1] # Ikalawang outcome

# Alternatibo: direktang magtanong sa CLOB gamit ang condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

Kahinaan sa pagkakasunod ng outcome

Ang array ng outcomes ng Gamma at ang array ng clobTokenIds ay naka-index nang magkatugma. Palagi na basahin ang label ng outcome sa halip na ipalagay na ang index 0 ay "Yes." Sa mga multi-outcome market (NegRisk, Oscars, elections), ang index 0 ay maaaring "Kamala Harris" o "Taylor Swift" - deterministic ang pagkakasunod pero partikular sa market.

Ang talaan ay ibinabalik bilang bids na pababang nakaayos, asks na pataas. Lakaran ang mga antas upang matantiya ang fill price para sa anumang target na notional bago magpadala ng market-like FAK.

Bahagi 6: Pagbasa ng mga Talaan ng Order

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

Ang mga talaan ng order ay ibinabalik bilang mga nakaayos na array (mga bid na pababang nakaayos, mga ask na pataas na nakaayos). Bawat antas ay may price at size. Para matantiya ang pagdulas ng presyo (slippage) para sa mas malaking order, sundan ang talaan at ipunin ang notional hanggang maubos mo ang iyong target na laki.

Ang GTC ay nananatili sa talaan, ang GTD ay awtomatikong kinakansela sa timestamp, ang FOK ay nangangailangan ng buong laki na fill o kanselahin, at ang FAK ay kinukuha ang kaya nito sa limit at kinakansela ang natitira.

Bahagi 7: Paglalagay ng mga Order

Limit na order (GTC - ang default)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Mga share, hindi dolyar. 100 share @ $0.45 = $45 na pinakamataas na gastos.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

Ang tawag na create_order ay pumipirma ng EIP-712 na structured message gamit ang iyong private key. Ang post_order ay nagsusumite nito sa CLOB. Hindi ka kailanman nagpapadala ng raw private keys sa wire - mga signed order lang.

Mga uri ng order

Pagkansela

# Isang order
client.cancel(order_id="0xabc...")

# Kanselahin ang lahat ng order sa isang partikular na market
client.cancel_market_orders(market=market['conditionId'])

# Nuklear na opsyon: kanselahin ang lahat
client.cancel_all()

Bahagi 8: WebSocket Streaming

Ang pag-poll sa Gamma bawat segundo ay sayang lang, at mabilis mong maaabot ang mga rate limit. Ang WebSocket feed ay nag-stream ng real-time na mga update sa talaan ng order at mga trade, na may latency na mas mababa sa isang segundo.

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

May dalawang feed: ang /market feed (pampublikong talaan ng order + mga trade) at ang /user feed (ang sarili mong mga event ng order at fill, na may authentication). Karaniwang kumokonekta ang mga production bot sa pareho, awtomatikong muling kumokonekta kapag naputol ang koneksyon, at itinuturing ang WebSocket bilang pinagkukunan ng katotohanan para sa kasalukuyang estado ng book.

Bahagi 9: Mga Rate Limit at Backoff

Kapag nakatama ka ng HTTP 429, magbabalik ang server ng header na Retry-After. Ipatupad ang exponential backoff na may jitter:

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Sobrang daming retry")

Bahagi 10: Isang Reference na Arkitektura ng Bot

Bawat matibay na Polymarket bot ay may parehong anim na bahagi. Buuin ang bawat isa bilang sarili nitong module; panatilihing maluwag ang pagkakadugtong ng mga ito.

Bahagi 11: Mga Karaniwang Mode ng Pagkabigo

• Lumang WebSocket data - Subaybayan ang oras ng huling mensahe per asset; kung walang mga update sa loob ng >30s sa isang aktibong market, piliting mag-refresh sa REST.
• Nonce collisions - Hinahawakan ng py-clob-client ang mga order nonce para sa iyo, pero kung sarili mong signer ang ginagamit mo, i-increment ang nonce sa bawat order.
• Kulang na balanse - Laging i-check ang balanse ng USDC bago maglagay; maaaring ipakita ng book ang order mo pero tatanggihan ito ng matching.
• Paused o nagre-resolve na market - I-check ang market.active && !market.closed bago mag-trade. Ang mga update ng Gamma ay nahuhuli sa CLOB nang ilang segundo sa paligid ng pagresolba (resolution).
• Hindi tugmang NegRisk adapter - Ang mga multi-outcome market ay dumadaan sa hiwalay na NegRisk adapter. Hinahawakan ito ng SDK, pero kumpirmahin na ang order mo ay napunta sa tamang venue.

Bahagi 12: Mga Reward sa Liquidity sa Pamamagitan ng API

Nagpapatakbo ang Polymarket ng ~$5M/buwan sa pangkalahatang liquidity mga gantimpala (rewards) at $5M+/buwan sa mga reward na partikular sa sports (tingnan ang Liquidity Rewards). Ang napakalaking bahagi ay napupunta sa mga API-driven na market maker (maker) na kayang magpanatili ng mahigpit na two-sided quotes sa libo-libong market.

Gumagantimpala ang formula ng reward sa mga order na malapit sa midpoint, laki, at oras sa book. Isang minimal na market-making loop:

1. Basahin ang aklat ng mga order (order book) para sa target na market
2. Kuwentahin ang isang patas na midpoint (hal., VWAP ng top 3 levels sa bawat panig)
3. Mag-post ng bid sa mid − spread_target/2 at ask sa mid + spread_target/2
4. Sa bawat WebSocket update, i-reprice kung ang iyong quote ay lumihis nang higit sa isang tick mula sa target
5. Kanselahin at lumabas kung numipis ang book o may pumutok na balita

Bahagi 13: Paglipat sa Production

• Hosting: sapat na ang $6/buwan na VPS (Hetzner, DigitalOcean) sa Europe o US-East para sa karamihan ng mga bot. I-co-locate sa Polygon RPC kung kailangan mo ng sub-10ms na latency.
• RPC: gumamit ng Alchemy, Infura, o QuickNode para sa maaasahang Polygon RPC. Ayos lang ang mga free tier hanggang makapaglagay ka ng daan-daang order kada minuto.
• Monitoring: Prometheus + Grafana para sa metrics; Telegram bot para sa mga alerto. I-log ang bawat order ID na ipinapadala mo at bawat fill na natatanggap mo.
• Backups: i-persist ang state kada minuto. Kung mamatay ang VPS sa gitna ng fill, gusto mong makapagpatuloy sa loob ng ilang segundo, hindi mano-manong mag-reconcile.
• Tax: ang logger mo rin ang iyong audit trail - tingnan ang Tax Guide.

Bahagi 14 - Mga Validated na Pro Tip Para sa Polymarket API

Situation → Action Cheat Sheet

Ano ang Susunod?

• Mga Tool at Resource - mga third-party dashboard, analytics, at data feed na umaakma sa API
• Mga Advanced na Estratehiya - multi-leg arbitrage at mga konstruksyong parang options na angkop para sa bots
• Liquidity Rewards - eksaktong mga formula para kumita ng market-making rebates
• Gabay sa Order Book - mas malalim na pag-unawa sa pagbabasa ng book bago mo ito koda-an
• Talahuluganan - mga depinisyon sa simpleng Ingles ng bawat termino sa gabay na ito