מדריך ה-API של פולימרקט — בנו את בוט המסחר הראשון שלכם ב-2026

בקצרה

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

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

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

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

חלק 2: אימות ומודל ארנק ה-Proxy

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

מה צריך

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

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

ה-SDK הרשמי של Python הוא הדרך המהירה ביותר להגיע מאפס להזמנה הראשונה. נשתמש בגרסה 0.34.6 — הגרסה העדכנית ב-PyPI (פברואר 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 אחרי ההרצה הראשונה, כדי שלא תפנו ל-endpoint של ההפקה בכל עלייה.

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

לפני שתוכלו לסחור, צריך למצוא שווקים ששווה לסחור בהם. Gamma מחזירה JSON עם כל מה שממשק פולימרקט מציג: השאלה, התוצאות, המחירים, מחזור 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

חלק 5: המיפוי condition_id → token_id

זו נקודת הכאב מספר 1 בבניית בוטים לפולימרקט. 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 והמערך clobTokenIds של Gamma תואמים באינדקס. תמיד קראו את תווית התוצאה. אל תניחו שאינדקס 0 הוא "Yes". בשווקים רב-תוצאתיים (NegRisk, האוסקרים, בחירות) אינדקס 0 יכול להיות "Kamala Harris" או "Taylor Swift". הסדר קבוע אבל ייחודי לכל שוק.

חלק 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. כדי להעריך slippage על הזמנה גדולה יותר, עברו על הספר וצברו את הסכום עד שמילאתם את הכמות שאתם מכוונים אליה.

חלק 6ב: ה-endpoints של CLOB v2 ב-REST (גולמי, בלי SDK)

ה-SDK עוטף את אלה, אבל היכרות עם ה-endpoints הגולמיים מאפשרת לכם לנפות באגים, לעבוד בשפה אחרת, או לבנות קליינט דק. כתובת בסיס: https://clob.polymarket.com. כל קריאה למטה היא ציבורית — בלי אימות. כולן אומתו חי ביוני 2026.

תגובות מאומתות, ישירות מה-API החי:

$ curl "https://clob.polymarket.com/price?token_id=7347...&side=buy"
{"price":"0.14"}

$ curl "https://clob.polymarket.com/midpoint?token_id=7347..."
{"mid":"0.21"}

$ curl "https://clob.polymarket.com/spread?token_id=7347..."
{"spread":"0.14"}

$ curl "https://clob.polymarket.com/tick-size?token_id=7347..."
{"minimum_tick_size":0.01}

כותרות אימות L2 (ל-REST גולמי בלי SDK)

ה-endpoints לקריאה הם ציבוריים. כדי לשלוח או לבטל הזמנות ב-REST גולמי אתם חותמים על כל בקשה עם פרטי ה-API שלכם. ה-SDK עושה זאת בשבילכם; כך זה בנוי מאחורי הקלעים:

חלק 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. אתם אף פעם לא שולחים מפתחות פרטיים גולמיים ברשת — רק הזמנות חתומות.

קודם יישרו את המחיר ל-tick

כל מחיר הזמנה חייב להיות כפולה מדויקת של ה-minimum_tick_size של השוק (0.01 ברוב השווקים, 0.001 בצמודים). מחיר שלא על ה-tick נדחה. משכו את ה-tick פעם אחת ועגלו אליו:

from py_clob_client.clob_types import OrderArgs, OrderType

tick = float(client.get_tick_size(token_id=yes_token))   # e.g. 0.01
def to_tick(p, tick): return round(round(p / tick) * tick, 4)

price = to_tick(0.453, tick)   # -> 0.45 on a 0.01 market

קנייה

side="BUY", וה-size נמדד במניות (לא בדולרים). 100 מניות ב-0.45 דולר עולות לכל היותר 45 דולר, ומשלמות 100 דולר אם התוצאה זוכה. שווי הזמנה מינימלי הוא בערך דולר אחד.

buy = OrderArgs(token_id=yes_token, price=to_tick(0.45, tick), size=100, side="BUY")
resp = client.post_order(client.create_order(buy), OrderType.GTC)
print(resp)   # {'success': True, 'orderID': '0x...', 'status': 'live', ...}

מכירה

מכירה היא אותה קריאה עם side="SELL". אתם יכולים למכור רק מניות שכבר יש לכם — מכירה של יותר מהפוזיציה נדחית בשגיאת "insufficient balance". כדי לסגור פוזיציה, מכרו את אותו token_id שקניתם.

sell = OrderArgs(token_id=yes_token, price=to_tick(0.62, tick), size=100, side="SELL")
resp = client.post_order(client.create_order(sell), OrderType.GTC)

פרמטרים של הזמנה במבט אחד

מחברים הכול: העסקה הראשונה שלכם דרך ה-API (סקריפט אחד שרץ)

זה כל התהליך מקצה לקצה — התחברות, מציאת שוק נזיל, קריאת הספר, יישור ל-tick, שליחת הזמנה אמיתית קטנה, ואז ביטולה. מלאו את שני הסודות שלכם והריצו. בהרצה הראשונה התחילו בכמות זעירה (כמה דולרים).

import os, json, requests
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON
from py_clob_client.clob_types import OrderArgs, OrderType

load_dotenv()

# 1) Connect (signing key in your EOA, funds in your proxy/funder)
client = ClobClient(
    "https://clob.polymarket.com",
    key=os.environ["POLY_PRIVATE_KEY"],
    chain_id=POLYGON,            # 137
    signature_type=1,            # 1 = email/Magic proxy, 2 = browser-wallet proxy
    funder=os.environ["POLY_FUNDER"],
)
client.set_api_creds(client.create_or_derive_api_creds())   # cache these after first run

# 2) Find the most-traded open market (Gamma, no auth)
m = requests.get(
    "https://gamma-api.polymarket.com/markets",
    params={"active": "true", "closed": "false", "order": "volume24hr",
            "ascending": "false", "limit": 1}, timeout=10,
).json()[0]
token_id = json.loads(m["clobTokenIds"])[0]   # index 0 = first outcome (read the label!)
print("Trading:", m["question"])

# 3) Read the book + the tick size
tick = float(client.get_tick_size(token_id))
book = client.get_order_book(token_id)
best_ask = float(book.asks[0].price)
print("best ask", best_ask, "| tick", tick)

# 4) Place a small BUY at the ask (tiny size to start)
price = round(round(best_ask / tick) * tick, 4)      # snap to tick
order = OrderArgs(token_id=token_id, price=price, size=5, side="BUY")  # 5 shares
resp = client.post_order(client.create_order(order), OrderType.GTC)
print(resp)                                          # {'success': True, 'orderID': '0x...', ...}

# 5) Cancel it (clean up)
# client.cancel(order_id=resp["orderID"])

סוגי הזמנות

ביטול

# 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

לתשאל את 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: מגבלות קצב ונסיגה

כשאתם מקבלים HTTP 429, השרת מחזיר כותרת Retry-After. השתמשו ב-נסיגה אקספוננציאלית עם 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: ארכיטקטורת בוט לדוגמה

לכל בוט אמין לפולימרקט יש את אותם שישה רכיבים. בנו כל אחד כמודול נפרד, ושמרו עליהם מקושרים באופן רופף.

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

• דחיית מחיר שלא על ה-tick — המחיר חייב להיות כפולה מדויקת של ה-minimum_tick_size של השוק. משכו אותו דרך /tick-size?token_id= ועגלו לפני החתימה, אחרת ההזמנה נדחית.
• 404 "No orderbook exists" — תשאלתם את /book, /price או /midpoint על טוקן סגור/שנסגר. השתמשו ב-/sampling-markets כדי למצוא טוקנים עם ספר חי.
• נתוני WebSocket מיושנים — עקבו אחר זמן ההודעה האחרונה לכל נכס; אם אין עדכונים יותר מ-30 שניות בשוק פעיל, אכפו רענון דרך REST.
• התנגשויות nonce — py-clob-client מטפל ב-nonce של ההזמנות בשבילכם, אבל אם אתם בונים signer משלכם, הגדילו את ה-nonce בכל הזמנה.
• יתרה לא מספקת — תמיד בדקו את יתרת ה-USDC לפני שליחה; הספר עשוי להציג את ההזמנה שלכם אבל ההתאמה תידחה אותה.
• שוק מושהה או בתהליך סגירה — בדקו market.active && !market.closed לפני מסחר. עדכוני Gamma מפגרים אחרי CLOB בכמה שניות סביב הסגירה.
• אי-התאמה במתאם NegRisk — שווקים רב-תוצאתיים מנותבים דרך מתאם NegRisk נפרד. ה-SDK מטפל בזה, אבל ודאו שההזמנה הגיעה למקום הנכון.

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

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

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

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

חלק 13: עלייה לפרודקשן

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

חלק 14 — טיפים מקצועיים מאומתים ל-API של פולימרקט

טבלת מצב → פעולה

מה הלאה?

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

בדיקה מהירה