Mwongozo wa Polymarket API: CLOB, REST na Trading Bots (2026)

Sura ya 27 kati ya 33

Muhtasari Mfupi

Polymarket hutoa API za umma tatu: CLOB (biashara), Gamma (ugunduzi wa soko), na Data (uchambuzi). SDK rasmi ya Python ni py-clob-client 0.34.6. Uthibitishaji unatumia ufunguo wa API + sahihi ya ECDSA, huku oda zikisainiwa kupitia EIP-712 kupitia pochi wakala ya Polygon. Vikomo vya kasi vinakuwekea takriban oda 60/dakika kwa kila ufunguo. Tatizo kubwa zaidi kwa wasanidi wapya ni tatizo la uhusiano wa condition_id → token_id kati ya Gamma na CLOB - livumue kwanza, kisha kila kitu kingine kitaingia sawa. Takriban $40M/mwezi katika zawadi za ukwasi na mwanya wa bei unaonasa na bot hupatikana kwenye Polymarket, karibu yote na watumiaji wa API.

Huduma tatu tofauti: CLOB (9,000/10s auth) kwa biashara, Gamma (4,000/10s public) kwa ugunduzi, Data (1,000/10s public) kwa uchambuzi wa kihistoria.

Sehemu ya 1: API Tatu

Polymarket hutenganisha majukumu kwa usafi katika huduma tatu tofauti. Kutumia API sahihi kwa kila kazi huifanya bot yako iwe ya haraka, rahisi, na ibaki ndani ya mipaka ya idadi ya maombi.

Mzunguko wa kawaida wa bot hutumia Gamma kupata masoko, CLOB kupata daftari la oda na kuweka biashara, na Data kufanya back-test ya utendaji wa mkakati nje ya mtandao. Fikiria Gamma kama "katalogi," CLOB kama "soko," na Data kama "ghala."

L1 husaini muundo wa EIP-712 wa "ClobAuthDomain" na chainId 137 ili kupata kitambulisho. L2 HMAC-SHA256 husaini kila ombi linalofuata kwa vichwa vya POLY_SIGNATURE.

Sehemu ya 2: Uthibitishaji & Mfano wa Pochi Wakala

Polymarket haisaini biashara kwa kutumia private key ya pochi yako kuu. Badala yake, hutumia pochi wakala ya mtindo wa Gnosis Safe: pochi yako kuu huipa idhini wakala, na wakala hutekeleza biashara zote kwenye Polygon. Bot yako ya API huzungumza na wakala huyo.

Unachohitaji

• API key - tengeneza katika Polymarket Settings → Developer
• Private key - key ya trading wallet yako (SI seed phrase ya MetaMask yako kuu)
• Funder address - anwani ya pochi yako wakala (inaonyeshwa katika Settings → Wallet)
• Chain ID - 137 (Polygon mainnet)
• Signature type - 1 (POLY_PROXY, ya kawaida kwa watumiaji wa rejareja)

Aina ya saini 1 (POLY_PROXY) kwa akaunti za Magic-link, aina ya 2 (GNOSIS_SAFE) kwa proxy za pochi za kivinjari, aina ya 0 (EOA) kwa keys za moja kwa moja. Funder inahitajika kwa aina 1 na 2.

Sehemu ya 3: Kusakinisha py-clob-client

SDK rasmi ya Python ndiyo njia ya haraka zaidi kutoka sifuri hadi oda ya kwanza. Tutatumia toleo 0.34.6, ambalo ni la sasa kufikia Aprili 2026.

# Tengeneza kwanza mazingira ya mtandao ya kuendesha programu
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

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

Mipangilio ya msingi ya mteja

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"],
)

# Mara moja tu: toa na hifadhi stakabadhi za API
client.set_api_creds(client.create_or_derive_api_creds())

Wito wa create_or_derive_api_creds() husaini ujumbe kwa kutumia ufunguo wako wa faragha na kuubadilisha kwa ufunguo wa API, siri, na nenosiri la siri. Hifadhi hivi kwenye .env yako baada ya mara ya kwanza ili usiende kwenye endpoint ya derive kila programu inapoanza.

Gamma /markets hurejesha outcomePrices, clobTokenIds, volume24hr, tags. Tumia tag_slug + order=volume24hr kama hoja-msingi ya kichunguzi cha bot.

Sehemu ya 4: Kugundua Masoko kupitia Gamma

Kabla hujanza kufanya biashara, unahitaji kupata masoko yanayostahili kufanyiwa biashara. Gamma hurejesha JSON yenye kila kitu ambacho UI ya Polymarket inaonyesha: swali, matokeo, bei, kiasi cha saa 24, muda wa kuisha, lebo, na picha.

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}")

Vigezo muhimu vya hoja ya Gamma

Gamma hufichua conditionId (moja kwa kila soko); CLOB hufanya biashara kwenye token_id (moja kwa kila matokeo). clobTokenIds ni safu ya mfuatano iliyosimbwa kwa JSON iliyo na ulinganifu wa faharasa na matokeo.

Sehemu ya 5: Ulinganisho wa condition_id - token_id

Hili ndilo tuduma kuu #1 katika uundaji wa bot za Polymarket. Gamma hurejesha condition_id (moja kwa kila soko). Miamala ya CLOB hutumia token_id (moja kwa kila matokeo). Daima unahitaji vyote viwili.

# Kila kitu cha soko cha Gamma kina 'clobTokenIds' - safu ya JSON ya string
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # Matokeo ya kwanza
no_token = token_ids[1] # Matokeo ya pili

# Chaguo mbadala: uliza CLOB moja kwa moja kwa kutumia condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

Kituko cha mpangilio wa matokeo

Safu ya outcomes ya Gamma na safu ya clobTokenIds zina ulinganifu wa faharasa. Daima soma lebo ya matokeo badala ya kudhani kuwa faharasa 0 ni "Yes." Katika masoko ya matokeo mengi (NegRisk, Oscars, uchaguzi), faharasa 0 inaweza kuwa "Kamala Harris" au "Taylor Swift" - mpangilio ni wa kudumu lakini hutegemea soko husika.

Daftari linarudishwa kama bids kushuka, asks kupanda. Pitia viwango ili kukadiria bei ya kujazwa kwa notional yoyote lengwa kabla ya kutuma FAK inayofanana na soko.

Sehemu ya 6: Kusoma Daftari la Oda

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}")

Daftari za oda hurudishwa kama safu zilizopangwa (bids kushuka, asks kupanda). Kila kiwango kina price na size. Ili kukadiria mtelezo wa bei kwa oda kubwa zaidi, pita kwenye daftari na ujikusanyie thamani ya notional hadi utakapokuwa umetumia ukubwa wako lengwa.

GTC husalia kwenye daftari, GTD hughairiwa kiotomatiki kwenye muhuri wa muda, FOK huhitaji ujazo kamili au kughairiwa, FAK huchukua kile inachoweza kwa kiwango-kikomo na kughairi kilichobaki.

Sehemu ya 7: Kuweka Oda

Oda ya bei-kikomo (GTC - chaguo-msingi)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Hisa, si dola. Hisa 100 @ $0.45 = gharama ya juu $45.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

Wito wa create_order hutia sahihi ujumbe uliopangiliwa wa EIP-712 kwa kutumia ufunguo wako binafsi. post_order huwasilisha kwa CLOB. Hutumi kamwe funguo binafsi ghafi kupitia mtandao - ni oda zilizotiwa sahihi tu.

Aina za oda

Kufuta

# Oda moja
client.cancel(order_id="0xabc...")

# Futa oda zote katika soko mahususi
client.cancel_market_orders(market=market['conditionId'])

# Chaguo la nyuklia: futa kila kitu
client.cancel_all()

Sehemu ya 8: Utiririshaji wa WebSocket

Kupiga polling Gamma kila sekunde ni kupoteza rasilimali na utafikisha viwango vya kikomo haraka. Mlisho wa WebSocket hutiririsha masasisho ya wakati halisi ya daftari la oda na biashara, kwa ucheleweshaji wa chini ya sekunde.

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)

Kuna milisho miwili: mlisho wa /market (daftari la oda la umma + biashara) na mlisho wa /user (oda zako mwenyewe na matukio ya kujazwa, ukiwa umethibitishwa). Roboti za uzalishaji kwa kawaida huunganika kwenye yote mawili, huunganishwa upya kiotomatiki wakikatika, na hutumia WebSocket kama chanzo cha ukweli kwa hali ya sasa ya daftari.

Sehemu ya 9: Vikomo vya Kiwango na Backoff

Ukikumbana na HTTP 429, seva hurudisha kichwa cha Retry-After. Tekeleza backoff ya kielelezo yenye 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("Too many retries")

Sehemu ya 10: Usanifu wa Bot ya Rejea

Kila bot imara ya Polymarket ina sehemu sita zilezile. Jenga kila moja kama moduli yake yenyewe; ziweke zikiwa zimeunganishwa kwa kulegea.

Sehemu ya 11: Njia za Kawaida za Kushindwa

• Taarifa za WebSocket zilizochakaa - Fuatilia muda wa ujumbe wa mwisho kwa kila asset; kama hakuna masasisho kwa zaidi ya 30s kwenye soko linalofanya kazi, lazimisha uboreshaji wa REST.
• Mgongano wa nonce - py-clob-client hushughulikia nonces za oda kwa ajili yako, lakini kama unajenga yako mwenyewe signer, ongeza nonce kwenye kila oda.
• Salio lisilotosha - Daima angalia salio la USDC kabla ya kuweka; daftari linaweza kuonyesha oda yako lakini matching itakataa.
• Soko limesitishwa au linafikiwa suluhisho - Angalia market.active && !market.closed kabla ya kufanya biashara. Masasisho ya Gamma huchelewa CLOB kwa sekunde chache wakati wa kufikia suluhisho.
• Ulinganifu wa adapter wa NegRisk haupo sawa - Masoko ya matokeo mengi hupitia adapter tofauti ya NegRisk. SDK hulishughulikia, lakini thibitisha oda yako ilienda kwenye venue sahihi.

Sehemu ya 12: Zawadi za Ukwasi kupitia API

Polymarket huendesha takriban $5M/mwezi katika zawadi za jumla za ukwasi pamoja na zaidi ya $5M/mwezi katika zawadi mahsusi za michezo (ona Liquidity Rewards). Sehemu kubwa sana huenda kwa mweka ukwasi wanaoendeshwa na API ambao wanaweza kudumisha nukuu nyembamba za pande mbili katika maelfu ya masoko.

Fomula ya zawadi huwazawadia oda zilizo karibu na midpoint, ukubwa, na muda kwenye daftari. Mzunguko wa kimsingi wa kutengeneza ukwasi:

1. Soma daftari la oda kwa soko lengwa
2. Hesabu midpoint ya haki (kwa mfano, VWAP ya viwango 3 vya juu kila upande)
3. Weka bid kwa mid - spread_target/2 na ask kwa mid + spread_target/2
4. Katika kila uboreshaji wa WebSocket, badilisha bei upya kama nukuu yako inapotoka zaidi ya tick moja kutoka lengwa
5. Futa na toka kama daftari linakuwa nyembamba au habari mpya zinatokea

Sehemu ya 13: Kuelekea Production

• Hosting: VPS ya $6/mwezi (Hetzner, DigitalOcean) barani Ulaya au US-East inatosha kwa bots wengi. Weka karibu na Polygon RPC kama unahitaji latency chini ya 10ms.
• RPC: tumia Alchemy, Infura, au QuickNode kwa Polygon RPC ya kuaminika. Viwango vya bure vinatosha hadi uweke mamia ya oda kwa dakika.
• Ufuatiliaji: Prometheus + Grafana kwa metrics; bot ya Telegram kwa arifa. Rekodi kila order ID unayotuma na kila fill unayopokea.
• Hifadhi nakala: dhibiti state kila dakika. Kama VPS ikifa katikati ya fill, unataka kuendelea ndani ya sekunde, si kufanya reconciliation kwa mkono.
• Kodi: logger yako pia ni rekodi yako ya ukaguzi - ona Tax Guide.

Sehemu ya 14 - Vidokezo Vilivyothibitishwa vya Pro kwa Polymarket API

Muhtasari wa Hali - Hatua

Kinachofuata?

• Vifaa na Rasilimali - dashibodi za wahusika wengine, uchanganuzi, na mlisho wa data unaokamilisha API
• Mikakati ya Juu - arbitrage ya vipengele vingi na miundo kama ya options inayofaa kwa bot
• Zawadi za Ukwasi - fomula sahihi za kupata punguzo za kutengeneza soko
• Mwongozo wa Daftari la Oda - ufahamu wa kina zaidi wa kusoma daftari kabla hujaandika msimbo dhidi yake
• Kamusi - fasili kwa lugha rahisi za kila istilahi katika mwongozo huu