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

الفصل 27 من 33

النسخة المختصرة

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

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

تفصل بوليماركت بوضوح بين المهام عبر ثلاث خدمات مميزة. استخدام الواجهة المناسبة لكل مهمة يجعل روبوتك سريعًا وبسيطًا وضمن حدود المعدل.

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

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

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

ما الذي تحتاجه

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

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

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

الجزء 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

هذه هي أكبر نقطة ألم في تطوير روبوتات بوليماركت. تعيد 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}")

تُعاد دفاتر الأوامر كمصفوفات مرتبة (طلبات الشراء تنازليًا، وطلبات البيع تصاعديًا). لكل مستوى price وsize. لتقدير slippage لأمر أكبر، امشِ عبر الدفتر واجمع القيمة الاسمية حتى تستهلك الحجم المستهدف.

الجزء 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

إن الاستعلام عن 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. طبّق التراجع الأسي مع العشوائية:

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: أنماط الفشل الشائعة

• بيانات WebSocket قديمة - تتبع وقت آخر رسالة لكل أصل؛ إذا لم تصل تحديثات لأكثر من >30s في سوق نشط، فافرض تحديثًا عبر REST.
• تضارب Nonce - يتولى py-clob-client أرقام nonce الخاصة بالأوامر عنك، ولكن إذا كنت تبني الموقّع بنفسك، فزد nonce مع كل أمر.
• رصيد غير كافٍ - تحقّق دائمًا من رصيد pUSD قبل التقديم؛ قد يظهر دفترك أمرًا، لكن المطابقة سترفضه.
• السوق متوقف أو قيد التسوية - تحقّق من market.active && !market.closed قبل التداول. تتأخر تحديثات Gamma بضع ثوانٍ عن CLOB حول التسوية.
• عدم تطابق NegRisk adapter - تتدفق الأسواق متعددة النتائج عبر موائم NegRisk منفصل. تتولى SDK ذلك، لكن تأكد من أن أمرك ذهب إلى المكان الصحيح.

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

تشغّل بوليماركت ما يقارب ~$5M/month في مكافآت السيولة العامة بالإضافة إلى $5M+/month في مكافآت الرياضة (انظر مكافآت السيولة). يذهب معظم ذلك إلى صانعي السوق المعتمدين على API الذين يستطيعون الحفاظ على عروض ثنائية الجانب ضيقة عبر آلاف الأسواق.

تكافئ معادلة المكافآت الأوامر القريبة من سعر الوسط، والحجم، والوقت على الدفتر. حلقة صناعة سوق دنيا:

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

الجزء 13: الانتقال إلى الإنتاج

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

الجزء 14 - نصائح عملية معتمدة لواجهة بوليماركت API

ورقة غش الحالة → الإجراء

ما التالي؟

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