מדריך API של פולימרקט: CLOB, REST ובוטי מסחר (2026)

פרק 27 מתוך 33

הגרסה הקצרה

פולימרקט חושפת שלושה APIs ציבוריים: CLOB (מסחר), Gamma (גילוי שווקים), ו-Data (אנליטיקה). ה-SDK הרשמי של Python הוא py-clob-client 0.34.6. האימות משתמש ב-מפתח API + חתימת ECDSA, כאשר פקודות נחתמות באמצעות EIP-712 דרך ארנק פרוקסי של Polygon. מגבלות הקצב מציבות אתכם בערך על 60 פקודות/דקה לכל מפתח. המלכוד הגדול ביותר למפתחים חדשים הוא בעיית המיפוי condition_id → token_id בין Gamma ל-CLOB - פותרים אותה קודם, וכל השאר מסתדר. בערך 40M$ לחודש בתגמולי נזילות וב-מרווח (spread) שנלכד בידי בוטים נצברים בפולימרקט, כמעט כולו בידי משתמשי API.

שלושה שירותים נפרדים: CLOB ‏(9,000/10s auth) למסחר, Gamma ‏(4,000/10s public) לגילוי, Data ‏(1,000/10s public) לניתוח היסטורי.

חלק 1: שלושת ה-APIs

פולימרקט מפרידה בצורה נקייה בין תחומי האחריות דרך שלושה שירותים נפרדים. שימוש ב-API הנכון לכל משימה שומר על הבוט מהיר, פשוט, ובתוך מגבלות הקצב.

לולאת בוט טיפוסית משתמשת ב-Gamma (Gamma) כדי למצוא שווקים, ב-CLOB (CLOB) כדי למשוך ספרי פקודות ולהניח עסקאות, וב-Data (Data) כדי לבצע back-test לביצועי האסטרטגיה באופן לא מקוון. חשבו על Gamma כעל ה"קטלוג", על CLOB כעל ה"בורסה", ועל Data כעל ה"מחסן".

L1 חותם על מבנה EIP-712 בשם "ClobAuthDomain" עם chainId 137 כדי לגזור אישורים. L2 HMAC-SHA256 חותם על כל בקשה עוקבת עם כותרות POLY_SIGNATURE.

חלק 2: אימות ומודל ארנק הפרוקסי

פולימרקט לא חותמת על עסקאות עם המפתח הפרטי של הארנק הראשי שלכם. במקום זאת, היא משתמשת ב-ארנק פרוקסי בסגנון Gnosis Safe: הארנק הראשי שלכם מאשר פרוקסי, והפרוקסי מבצע את כל העסקאות ב-Polygon. הבוט שלכם מתקשר מול אותו פרוקסי.

מה צריך

• מפתח API - יצירה ב-Polymarket Settings → Developer
• מפתח פרטי - המפתח של ארנק המסחר שלכם (לא seed phrase של ה-MetaMask הראשי)
• כתובת מממן - כתובת ארנק הפרוקסי שלכם (מוצגת ב-Settings → Wallet)
• Chain ID - 137 (Polygon mainnet)
• סוג חתימה - 1 (POLY_PROXY, תקן למשתמשי ריטייל)

סוג חתימה 1 (POLY_PROXY) לחשבונות Magic-link, סוג 2 (GNOSIS_SAFE) לפרוקסי של ארנקי דפדפן, סוג 0 (EOA) למפתחות ישירים. נדרש funder עבור סוגים 1 ו-2.

חלק 3: התקנת py-clob-client

ה-SDK הרשמי של Python הוא הדרך המהירה ביותר לעבור מאפס לפקודה ראשונה. נשתמש בגרסה 0.34.6, שהיא העדכנית נכון לאפריל 2026.

# Create a virtual environment first
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

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

תצורת לקוח בסיסית

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

# One-time: derive and cache API credentials
client.set_api_creds(client.create_or_derive_api_creds())

הקריאה create_or_derive_api_creds() חותמת על הודעה עם המפתח הפרטי שלכם ומחליפה אותה במפתח API, secret ו-passphrase. שמרו אותם ב-.env אחרי ההרצה הראשונה כדי שלא תצטרכו לפגוע בנקודת ה-derive בכל עלייה.

Gamma /markets מחזיר outcomePrices, clobTokenIds, volume24hr, tags. השתמשו ב-tag_slug + order=volume24hr כשאילתת ברירת המחדל לסורק הבוט.

חלק 4: גילוי שווקים דרך Gamma

לפני שאפשר לסחור, צריך למצוא שווקים ששווה לסחור בהם. Gamma מחזירה JSON עם כל מה שממשק המשתמש של Polymarket מציג: שאלה, תוצאות, מחירים, נפח 24 שעות, תפוגה, תגיות ותמונות.

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

פרמטרי שאילתת Gamma שימושיים

Gamma חושפת conditionId (אחד לכל שוק); CLOB סוחר ב-token_id (אחד לכל תוצאה). clobTokenIds הוא מערך מחרוזות בקידוד JSON שממופה לפי אינדקס לתוצאות.

חלק 5: מיפוי condition_id ל-token_id

זוהי נקודת הכאב מספר 1 בפיתוח בוטים ל-Polymarket. Gamma מחזירה condition_id (אחד לכל שוק). פקודות ב-CLOB משתמשות ב-token_id (אחד לכל תוצאה). תמיד צריך את שניהם.

# Each Gamma market object contains 'clobTokenIds' - a JSON string array
import json

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

# Alternative: ask CLOB directly using condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

מלכודת סדר התוצאות

מערך outcomes של Gamma ומערך clobTokenIds ממופים לפי אינדקס. תמיד קראו את תווית התוצאה ולא הניחו שאינדקס 0 הוא "Yes." בשווקים רב-תוצאה (NegRisk, אוסקרים, בחירות), אינדקס 0 יכול להיות "Kamala Harris" או "Taylor Swift" - הסדר דטרמיניסטי אך תלוי-שוק.

הספר מוחזר כ-bids בסדר יורד, asks בסדר עולה. יש לעבור על הרמות כדי להעריך מחיר מילוי עבור notional יעד לפני שליחת FAK דמוי-שוק.

חלק 6: קריאת ספרי פקודות

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

ספרי פקודות מוחזרים כמערכים ממוינים (bids בסדר יורד, asks בסדר עולה). לכל רמה יש price ו-size. כדי להעריך החלקה עבור פקודה גדולה יותר, עוברים על הספר ומצברים notional עד שמצרכים את גודל היעד.

GTC נשארת על הספר, GTD מתבטלת אוטומטית בזמן מסוים, FOK דורשת מילוי מלא או ביטול מלא, FAK לוקחת מה שאפשר במחיר לימיט ומבטלת את השאר.

חלק 7: הנחת פקודות

פקודת לימיט (GTC - ברירת המחדל)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Shares, not dollars. 100 shares @ $0.45 = $45 max cost.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

הקריאה create_order חותמת על הודעה מובנית מסוג EIP-712 עם המפתח הפרטי שלכם. post_order שולחת אותה ל-CLOB. לעולם אינכם שולחים מפתחות פרטיים גולמיים ברשת - רק פקודות חתומות.

סוגי פקודות

ביטול

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

# Cancel all orders on a specific market
client.cancel_market_orders(market=market['conditionId'])

# Nuclear option: cancel everything
client.cancel_all()

חלק 8: הזרמת WebSocket

Polling של Gamma כל שנייה הוא בזבזני, ותגיעו מהר למגבלות הקצב. פיד ה-WebSocket מזרים עדכוני ספר פקודות ועסקאות בזמן אמת, עם השהיית תת-שנייה.

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)

קיימים שני פידים: פיד /market ‏(ספר פקודות ציבורי + עסקאות) ופיד /user ‏(אירועי הפקודות והמילוי שלכם, מאומת). בוטי ייצור בדרך כלל מתחברים לשניהם, מתחברים מחדש אוטומטית בעת ניתוק, ומתייחסים ל-WebSocket כמקור האמת למצב הספר הנוכחי.

חלק 9: מגבלות קצב ו-backoff

כשמקבלים HTTP 429, השרת מחזיר כותרת Retry-After. יש להטמיע exponential backoff with 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")

חלק 10: ארכיטקטורת בוט ייחוס

לכל בוט Polymarket חזק יש את אותם שישה רכיבים. בנו כל אחד כמודול נפרד; שמרו על צימוד רופף ביניהם.

חלק 11: מצבי כשל נפוצים

• נתוני WebSocket מיושנים - עקבו אחרי זמן ההודעה האחרונה לכל asset; אם אין עדכונים במשך >30 שניות בשוק פעיל, כפו רענון REST.
• התנגשויות nonce - py-clob-client מטפל ב-order nonces עבורכם, אבל אם אתם בונים signer משלכם, הגדילו את ה-nonce בכל פקודה.
• יתרה לא מספקת - תמיד בדקו יתרת USDC לפני הנחה; הספר עשוי להציג את הפקודה שלכם, אבל המנוע ידחה במילוי.
• שוק מושהה או ביישוב - בדקו market.active && !market.closed לפני מסחר. עדכוני Gamma מפגרים אחרי CLOB בכמה שניות סביב היישוב.
• אי-התאמה ב-NegRisk adapter - שווקים רב-תוצאה נשלחים דרך adapter נפרד של NegRisk. ה-SDK מטפל בזה, אבל יש לוודא שהפקודה נשלחה לזירה הנכונה.

חלק 12: תגמולי נזילות דרך API

Polymarket מפעילה ~5M$/חודש בתגמולי נזילות כלליים ועוד 5M$+/חודש בתגמולים ייעודיים לספורט (ראו תגמולי נזילות). הרוב המוחלט זורם ל-market makers מונעי-API שמסוגלים לשמור על ציטוטים דו-צדדיים צרים לאורך אלפי שווקים.

נוסחת התגמול מתגמלת פקודות ליד מחיר אמצע, גודל וזמן על הספר. לולאת market making מינימלית:

1. קראו את ספר הפקודות עבור שוק היעד
2. חשבו midpoint הוגן (למשל VWAP של 3 הרמות העליונות בכל צד)
3. הניחו bid ב-mid - spread_target/2 ו-ask ב-mid + spread_target/2
4. בכל עדכון WebSocket, עשו repricing אם ה-quote שלכם סטה יותר מ-tick אחד מהיעד
5. בטלו וצאו אם הספר נעשה דק או אם מתפרסמת ידיעה

חלק 13: מעבר לייצור

• אחסון: VPS ב-6$ לחודש (Hetzner, DigitalOcean) באירופה או US-East מספיק לרוב הבוטים. ניתן למקם סמוך ל-Polygon RPC אם צריך השהיה של פחות מ-10ms.
• RPC: השתמשו ב-Alchemy, Infura, או QuickNode ל-Polygon RPC אמין. שכבות חינמיות מספיקות עד שמניחים מאות פקודות בדקה.
• ניטור: Prometheus + Grafana למדדים; בוט Telegram להתראות. רשמו כל order ID שאתם שולחים וכל מילוי שאתם מקבלים.
• גיבויים: שמרו מצב בכל דקה. אם ה-VPS מת באמצע מילוי, תרצו להמשיך תוך שניות, לא לבצע reconciliation ידני.
• מס: הלוג שלכם הוא גם trail הביקורת שלכם - ראו מדריך מס.

חלק 14 - טיפים מאומתים ל-Polymarket API

גיליון מצב → פעולה

מה הלאה?

• כלים ומשאבים - לוחות מחוונים של צד שלישי, אנליטיקה ופידי נתונים שמשלימים את ה-API
• אסטרטגיות מתקדמות - ארביטראז' מרובה רגליים ובניות דמויות-אופציות המתאימות לבוטים
• תגמולי נזילות - נוסחאות מדויקות להרוויח החזרי market-making
• מדריך ספר פקודות - אינטואיציה עמוקה יותר לקריאת הספר לפני כתיבה מולו
• מילון מונחים - הגדרות פשוטות באנגלית לכל מונח במדריך הזה