دليل Polymarket API - ابنِ أول روبوت تداول لك في 2026

الخلاصة السريعة

توفّر لك Polymarket ثلاث واجهات API عامة (واجهة API هي طريقة تتيح للبرامج قراءة التداولات أو تنفيذها تلقائيًا): CLOB للتداول، وGamma لاكتشاف الأسواق، وData للتحليلات. حزمة Python SDK الرسمية هي py-clob-client 0.34.6. تعتمد المصادقة على مفتاح API + توقيع ECDSA، وتُوقَّع الطلبات عبر EIP-712 من خلال محفظة وكيلة على Polygon. تضع حدود المعدّل سقفًا يقارب 60 طلبًا في الدقيقة لكل مفتاح. أكبر عقبة تواجه المطوّرين الجدد هي مشكلة ربط condition_id → token_id بين Gamma وCLOB. ابدأ بحلّها، وستصبح بقية الخطوات أوضح وأسهل. تُحقَّق على Polymarket مكافآت سيولة وفروق أسعار تلتقطها البوتات بنحو 40 مليون دولار شهريًا، ومعظمها تقريبًا من مستخدمي API.

الجزء 1: واجهات API الثلاث

تقسّم Polymarket العمل بوضوح بين ثلاث خدمات منفصلة. استخدام API المناسبة لكل مهمة يُبقي البوت سريعًا وبسيطًا وضمن حدود المعدّل.

تستخدم حلقة البوت النموذجية Gamma للعثور على الأسواق، وCLOB لجلب دفاتر الأوامر وتنفيذ التداولات، وData لاختبار أداء الاستراتيجية تاريخيًا دون اتصال. يمكنك اعتبار Gamma «الفهرس»، وCLOB «البورصة»، وData «المستودع».

الجزء 2: المصادقة ونموذج المحفظة الوكيلة

لا توقّع Polymarket التداولات باستخدام المفتاح الخاص لمحفظتك الرئيسية. بدلًا من ذلك، تستخدم محفظة وكيلة بأسلوب Gnosis Safe. تفوّض محفظتك الرئيسية محفظة وكيلة، وتتولى المحفظة الوكيلة تنفيذ جميع التداولات على Polygon. يتواصل بوت API الخاص بك مع تلك المحفظة الوكيلة.

ما تحتاج إليه

• مفتاح API - أنشئه من Polymarket Settings → Developer
• المفتاح الخاص - مفتاح محفظة التداول لديك (وليس عبارة الاسترداد لمحفظتك الرئيسية في MetaMask)
• عنوان المموّل - عنوان محفظتك الوكيلة (يظهر في Settings → Wallet)
• معرّف السلسلة - 137 (شبكة Polygon الرئيسية)
• نوع التوقيع - 1 (POLY_PROXY، وهو المعيار للمستخدمين الأفراد)

الجزء 3: تثبيت py-clob-client

تُعدّ حزمة Python SDK الرسمية أسرع طريقة للانتقال من البداية إلى إرسال أول طلب لك. سنستخدم الإصدار 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 وسرّ وعبارة مرور. خزّن هذه القيم في .env بعد التشغيل الأول، حتى لا تستدعي derive endpoint عند كل بدء تشغيل.

الجزء 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 المفيدة

الجزء 5: ربط condition_id → token_id

هذه هي أكبر نقطة إزعاج عند بناء بوتات 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". الترتيب ثابت، لكنه خاص بكل سوق.

الجزء 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. لتقدير الانزلاق السعري لطلب أكبر، مرّ على الدفتر واجمع القيمة الاسمية حتى تصل إلى الحجم المستهدف.

الجزء 6b: CLOB v2 REST Endpoints (مباشرة، بدون SDK)

تغلّف SDK هذه الواجهات، لكن معرفة endpoints المباشرة تساعدك على تصحيح الأخطاء، أو استخدام لغة أخرى، أو بناء عميل خفيف. عنوان Base URL: 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)

نقاط القراءة عامة. ولإجراء إرسال أو إلغاء الأوامر عبر 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

Buy

side="BUY"، تكون size بوحدة الأسهم (وليس بالدولار). 100 سهم بسعر 0.45 دولارًا تكلف 45 دولارًا كحد أقصى، وتدفع 100 دولار إذا فازت النتيجة. الحد الأدنى لقيمة الأمر حوالي 1 دولار.

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', ...}

Sell

البيع يتم بالاستدعاء نفسه مع 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 (سكربت واحد قابل للتشغيل)

هذا هو المسار الكامل من البداية إلى النهاية: الاتصال، العثور على سوق ذات سيولة، قراءة دفتر الأوامر، مواءمة السعر مع التكة، وضع أمر حقيقي صغير، ثم إلغاؤه. املأ القيمتين السريتين وشغّله. في أول تشغيل لك، ابدأ بحجم صغير جدًا (بضعة دولارات).

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: بنية بوت مرجعية

كل بوت موثوق على Polymarket يتكوّن من المكوّنات الستة نفسها. ابنِ كل مكوّن كوحدة مستقلة، واجعل الترابط بينها خفيفًا.

الجزء 11: أنماط الإخفاق الشائعة

• رفض السعر غير المطابق للحد الأدنى للتغير - يجب أن يكون السعر مضاعفًا دقيقًا لقيمة minimum_tick_size الخاصة بالسوق. اجلبها عبر /tick-size?token_id= وقرّب السعر قبل التوقيع، وإلا فسيُرفض الأمر.
• 404 "No orderbook exists" - استعلمت عن /book أو /price أو /midpoint لرمز مغلق أو محسوم. استخدم /sampling-markets للعثور على رموز لها دفتر أوامر نشط.
• بيانات WebSocket المتقادمة - تتبّع وقت آخر رسالة لكل أصل؛ إذا لم تصل تحديثات لأكثر من 30 ثانية في سوق نشط، فافرض تحديثًا عبر REST.
• تصادمات nonce - يتولى py-clob-client إدارة قيم nonce للأوامر نيابةً عنك، لكن إذا كنت تطوّر الموقّع الخاص بك، فزد قيمة nonce مع كل أمر.
• رصيد غير كافٍ - تحقق دائمًا من رصيد USDC قبل وضع الأمر؛ فقد يعرض الدفتر أمرك، لكن نظام المطابقة سيرفضه.
• السوق متوقف مؤقتًا أو قيد الحسم - تحقق من market.active && !market.closed قبل التداول. تتأخر تحديثات Gamma عن CLOB بضع ثوانٍ قرب الحسم.
• عدم تطابق محوّل NegRisk - تُوجَّه الأسواق متعددة النتائج عبر محوّل NegRisk منفصل. يتولى SDK ذلك، لكن تأكد من أن أمرك ذهب إلى وجهة التداول الصحيحة.

الجزء 12: مكافآت السيولة عبر API

تدير Polymarket مكافآت سيولة عامة بقيمة نحو 5 ملايين دولار شهريًا إضافةً إلى مكافآت مخصصة للرياضة بقيمة أكثر من 5 ملايين دولار شهريًا (راجع مكافآت السيولة). يذهب معظمها إلى صنّاع السوق المعتمدين على API. فهم يحافظون على عروض شراء وبيع بفوارق ضيقة عبر آلاف الأسواق.

تفضّل صيغة المكافآت الأوامر القريبة من نقطة المنتصف، مع أخذ الحجم ومدة بقاء الأمر في الدفتر في الحسبان. فيما يلي حلقة مبسطة لصناعة السوق:

1. اقرأ دفتر الأوامر للسوق المستهدف
2. احسب نقطة منتصف عادلة (مثلًا، VWAP لأفضل 3 مستويات على كل جانب)
3. ضع عرض شراء عند mid − spread_target/2 وعرض بيع عند mid + spread_target/2
4. مع كل تحديث WebSocket، أعد التسعير إذا ابتعد عرضك عن الهدف بأكثر من وحدة تغير سعرية واحدة
5. ألغِ الأوامر واخرج إذا ضعفت السيولة في الدفتر أو ظهرت أخبار مؤثرة

الجزء 13: الانتقال إلى بيئة الإنتاج

• الاستضافة: يكفي خادم VPS بسعر 6 دولارات شهريًا (Hetzner، DigitalOcean) في أوروبا أو شرق الولايات المتحدة لمعظم البوتات. استضِفه قرب Polygon RPC إذا احتجت إلى زمن تأخير أقل من 10 مللي ثانية.
• RPC: استخدم Alchemy أو Infura أو QuickNode للحصول على Polygon RPC موثوق. تكفي الباقات المجانية إلى أن تبدأ بوضع مئات الأوامر في الدقيقة.
• المراقبة: استخدم Prometheus + Grafana للمقاييس، وبوت Telegram للتنبيهات. سجّل كل معرّف أمر ترسله وكل تنفيذ تستلمه.
• النسخ الاحتياطي: احفظ الحالة كل دقيقة. إذا تعطل خادم VPS أثناء تنفيذ جزئي، فستحتاج إلى الاستئناف خلال ثوانٍ، لا إلى المطابقة يدويًا.
• الضرائب: المسجّل لديك هو أيضًا سجل التدقيق؛ راجع دليل الضرائب.

الجزء 14 - نصائح احترافية مجرّبة لاستخدام Polymarket API

ورقة مختصرة: الموقف → الإجراء

ماذا بعد؟

• الأدوات والموارد - لوحات معلومات وتحليلات ومصادر بيانات من جهات خارجية تكمل API
• استراتيجيات متقدمة - موازنة متعددة legs وتركيبات شبيهة بالخيارات مناسبة للبوتات
• مكافآت السيولة - الصيغ الدقيقة لكسب حسومات صناعة السوق
• دليل دفتر الأوامر - فهم أعمق لقراءة الدفتر قبل أن تبرمج ضده
• المصطلحات - تعريفات مبسطة لكل مصطلح في هذا الدليل

فحص سريع