خريطة Polymarket API: Gamma مقابل CLOB مقابل Data API
يخسر القادمون الجدد يومًا بسبب المشكلة نفسها: ليست لدى Polymarket واجهة API واحدة، بل أربع، ونقطة النهاية التي تريدها نادرًا ما تكون في الواجهة التي جربتها أولًا. هذه هي الخريطة الكاملة.
أول ما يجب فهمه عن Polymarket API هو أنه لا يوجد شيء بهذا الاسم. هناك أربع واجهات REST API وأربعة تدفقات WebSocket، تخدم كل منها جزءًا مختلفًا من التكامل، ولكل منها اسم مضيف خاص، وحدود معدل خاصة، ومتطلبات مصادقة خاصة.
يتبيّن أن كل سؤال تقريبًا من نوع "ليس في Polymarket API كذا" هو في الحقيقة "كذا موجود على مضيف آخر". إليك الواجهة كلها في مكان واحد.
واجهات REST API الأربع
| API | عنوان URL الأساسي | الغرض منها | المصادقة |
|---|---|---|---|
| Gamma | gamma-api.polymarket.com | اكتشاف الأحداث والأسواق؛ البيانات الوصفية | لا شيء |
| CLOB | clob.polymarket.com | الأسعار، ودفاتر الأوامر، وتقديم الأوامر وإدارتها | لا شيء للقراءة، وL1/L2 للتداول |
| Data | data-api.polymarket.com | المراكز، والنشاط، والمشاركة في الأسواق | لا شيء |
| Relayer | relayer-v2.polymarket.com | إرسال معاملات المحفظة دون الاحتفاظ بـ POL لرسوم الغاز | موقَّعة |
قاعدة التوجيه في 30 ثانية
ما الأسواق الموجودة؟ ← Gamma. ما السعر / أريد التداول ← CLOB. ماذا تملك هذه المحفظة؟ ← Data API. أحتاج إلى نقل أموال دون غاز ← Relayer. إذا كنت تبحث في CLOB عن نقطة نهاية للأحداث، أو في Gamma عن دفتر أوامر، فهذا هو الخطأ.
Gamma API — الاكتشاف والبيانات الوصفية
Gamma هي نقطة البداية. تجيب عن سؤال ما الموجود: الأحداث، والأسواق داخلها، والوسوم، والبحث، والبيانات الوصفية التي تحتاج إليها للعمل مع أي شيء آخر — والأهم، معرّفات التوكنات التي تتطلبها كل نقطة نهاية في CLOB.
/events— سرد الأحداث، مع ترقيم بالمفاتيح متاح/markets— سرد الأسواق؛ وأيضًاby idوby slugوby token/public-search— البحث عبر الأحداث والأسواق/tagsو/comments— التصنيف والنقاش- الفائدة المفتوحة، وحجم التداول المباشر، وكبار الحائزين
تملك /markets أضيق حد في المنصة
300 طلب / 10 ثوانٍ — أضيق بـ 13× من الحد العام لـ Gamma نفسها البالغ 4,000 طلب / 10 ثوانٍ. إذا كنت ترقّم قائمة الأسواق الكاملة في حلقة، فهذا ما ينكسر أولًا. خزّن البيانات الوصفية للأسواق مؤقتًا؛ فهي بالكاد تتغير خلال عمر السوق. الأرقام الكاملة في مرجع حدود المعدل.
CLOB API — الأسعار والدفاتر والأوامر
دفتر الأوامر نفسه، والمكان الوحيد الذي يمكنك التداول فيه. القراءة عامة؛ والتداول يتطلب بيانات اعتماد.
| المجموعة | نقاط النهاية | المصادقة |
|---|---|---|
| دفتر الأوامر | /book، /books، /midpoint، /midpoints، /spread، /spreads | عامة |
| التسعير | /price، /prices، /prices-history، سعر آخر صفقة، /tick-size، معدل الرسوم | عامة |
| الأوامر | POST /order، POST /orders، DELETE /order، /orders، /cancel-all، /cancel-market-orders | L2 + توقيع المحفظة |
| السجل | /trades، /data/orders، /data/trades، /notifications | L2 |
| المصادقة | /auth/api-key، /auth/api-keys، /auth/derive-api-key | L1 |
| الحساب | سماحية الرصيد (جلب / تحديث) | L2 |
المفرد مقابل الجمع فرق حقيقي
لكل نقطة نهاية لبيانات السوق في CLOB تقريبًا توأم مجمّع: /book و/books، و/price و/prices. تحصل نقاط النهاية المفردة على 1,500 طلب / 10 ثوانٍ والجمعية على 500 طلب / 10 ثوانٍ — لكن استدعاءً جمعيًا واحدًا يغطي توكنات كثيرة، لذا يمنحك التجميع بيانات أكثر بكثير لكل وحدة من ميزانية حد المعدل. فضّل /books على حلقة من /book في كل الأحوال تقريبًا.
Data API — المراكز والنشاط
أسئلة على شكل محفظة استثمارية: /positions و/closed-positions و/trades، بالإضافة إلى API أرباح وخسائر المستخدم. لاحظ أن هذه هي الأضيق بين الواجهات الثلاث الرئيسية — حد عام قدره 1,000 طلب / 10 ثوانٍ، مع 150 طلبًا / 10 ثوانٍ فقط لكل من /positions و/closed-positions. صُممت للوحات المعلومات، لا لحلقات الاستطلاع.
تدفقات WebSocket الأربعة
إذا كنت تستطلع /book على مؤقت، فتوقف — هذا هو الغرض من التدفقات. الاستطلاع هو الطريقة الأكثر شيوعًا لاستهلاك ميزانية حد المعدل بلا فائدة.
| التدفق | URL | ما يحمله |
|---|---|---|
| CLOB Market | wss://ws-subscriptions-clob.polymarket.com/ws/market | تحديثات عامة لدفتر الأوامر والأسعار ودورة حياة السوق |
| CLOB User | wss://ws-subscriptions-clob.polymarket.com/ws/user | تحديثات مصادَق عليها للأوامر والصفقات في حسابك |
| RTDS | wss://ws-live-data.polymarket.com | الأسعار المرجعية العامة، والتعليقات، ونشاط التداول |
| Sports | wss://sports-api.polymarket.com/ws | حالة المباريات المباشرة والنتائج |
قناة User هي التي يغفل عنها الناس. إذا كان بوتك يستطلع /data/orders ليعرف ما إذا نُفّذ أمره، فأنت تدفع من ميزانية حد المعدل مقابل معلومات كانت قناة User ستدفعها إليك لحظة حدوثها — وبزمن استجابة أقل.
المصادقة: L1 وL2
بيانات الأسواق العامة لا تحتاج إلى أي بيانات اعتماد — يمكنك استدعاء Gamma ونقاط نهاية القراءة في CLOB وData API بأمر curl مجرد. أما التداول فيحتاج إلى طبقتين، وفهم أيهما أيهما يحل معظم أخطاء المصادقة.
| الطبقة | كيف تعمل | الغرض |
|---|---|---|
| L1 | توقّع المحفظة رسالة EIP-712 | إثبات التحكم في المحفظة؛ إنشاء بيانات اعتماد API أو اشتقاقها |
| L2 | طلبات موقّعة ببيانات اعتماد API باستخدام HMAC-SHA256 | مصادقة طلبات CLOB الخاصة |
يستخدم تقديم الأوامر كلتيهما: تصادق L2 على الطلب، ويخوّل توقيع المحفظة الأمر. البيانات ذات الأنواع في L1 هي حمولة ClobAuth على chainId: 137 (Polygon)، مع عنوان الموقّع، وطابع Unix زمني بالثواني، وnonce (استخدم 0 ما لم تكن تدير عدة مجموعات من بيانات الاعتماد)، ونص الرسالة الثابت.
الحصول على مفتاح API
- وقّع حمولة
ClobAuthمن نوع EIP-712 بمفتاحك الخاص على Polygon. - استدعِ
POST /auth/api-keyمع ترويسات L1 لـإنشاء بيانات الاعتماد. ستحصل على مفتاح وسر وعبارة مرور — والثلاثة مطلوبة لـ L2. - في التشغيلات اللاحقة، استدعِ
GET /auth/derive-api-keyلـاسترجاع بيانات الاعتماد الموجودة بدلًا من إنشاء جديدة.
فشلا المصادقة اللذان يمثلان معظم أسئلة الدعم
بيانات اعتماد ناقصة — تحتاج L2 إلى المفتاح والسر وعبارة المرور؛ وامتلاك اثنين من ثلاثة ينتج طلبًا سليم الشكل بتوقيع لا يمكن التحقق منه. انحراف الساعة — يتضمن التوقيع طابعًا زمنيًا، لذا تنتج الحاوية التي تنحرف ساعتها بضع ثوانٍ توقيعات يرفضها الخادم بوصفها غير صالحة. وكلاهما يظهر بالرسالة Unauthorized/Invalid api key، ولهذا يُبحث عن هذه الرسالة على نطاق واسع. راجع مرجع الأخطاء.
حزم SDK
تصون Polymarket حزم SDK موحّدة بلغتي TypeScript وPython تغلّف كل ما سبق بواجهة ذات أنواع محددة، وتتولى ترقيم الصفحات وأشكال الأخطاء وإعداد المحفظة. إذا كنت تبدأ من الصفر بأي من اللغتين، فاستخدمها — فكتابة توقيع EIP-712 وتوقيع طلبات HMAC يدويًا طريقة معرّضة للأخطاء حقًا لقضاء عطلة نهاية الأسبوع.
توجّه مباشرة إلى REST عندما لا تغطي أي SDK بيئة التشغيل لديك، أو عندما تحتاج إلى تحكم دقيق في التوقيع أو الترويسات أو إعادة المحاولة أو النقل، أو عندما تحتاج إلى نقطة نهاية لم تكشفها SDK بعد. لاحظ أن هذه هي حزم SDK الموحّدة — إذا كنت على عميل أقدم، فهناك مسار انتقال موثّق، والعملاء الأقدم هم مصدر كثير من أخطاء بيانات الاعتماد القديمة.
كم تكلف Polymarket API؟
لا شيء. لا يوجد مستوى مدفوع، ولا صفحة أسعار لـ API، ولا اشتراك — واجهات API الخاصة بـ Polymarket مجانية الاستخدام، ويخضع الوصول إليها لحدود المعدل لا للفوترة. بيانات الأسواق العامة لا تتطلب حتى مفتاحًا.
الشيء الوحيد الذي يتدرج مع المال هو حدود التداول لكل موقّع، وهي متدرجة حسب حجم تداول محفظة صانع السوق لديك خلال 30 يومًا — من Standard بمعدل 40 توكن أمر/ثانية حتى Elite بمعدل 600 — لكن ذلك تخصيص للإنتاجية، لا رسوم.
الشيء الوحيد الذي لن تمنحك إياه أي من هذه الواجهات
بعد رسم خريطة الواجهة كلها، الأمر المفيد معرفته هو ما ليس موجودًا فيها: العمق التاريخي لدفتر الأوامر.
كل نقطة نهاية أعلاه تقدّم الحالة الراهنة. تُرجع /book الدفتر الآن. وتمنحك /prices-history الأسعار بلا عمق، لذا لا يمكنها أن تخبرك بما كان سيكون عليه تنفيذك. وعندما يُحسم السوق، تُرجع /book الرمز 404. ما يبقى هو سلسلة أسعار ضئيلة، بنحو نقطة واحدة في الدقيقة، يمكنك جلبها ببداية ونهاية صريحتين. ولا تغيّر أي خطة أو مستوى من حدود المعدل ذلك.
| السؤال | هل يمكن الإجابة عنه عبر Polymarket API؟ |
|---|---|
| ما حال الدفتر الآن؟ | نعم — /book |
| ما السعر بالأمس؟ | نعم، بنحو نقطة واحدة في الدقيقة، من /prices-history ببداية ونهاية |
| ما العمق عند 14:03:17 بالأمس؟ | لا |
| بأي سعر كان سيُنفَّذ أمري البالغ 500 سهم؟ | لا |
| أرني سوقًا حُسم الأسبوع الماضي | سجله ونتيجته، نعم (closed=true). دفتره، لا. |
هذه الفجوة هي سبب حاجة الاختبار الرجعي لاستراتيجية على Polymarket إلى مصدر بيانات منفصل سجّل الدفتر أثناء تشغيل الأسواق. تفعل PolyTest ذلك بالضبط لأسواق Up/Down للعملات المشفرة — 240M+ لقطة عند لحظات زمنية محددة مع 8 مستويات من العمق لكل جانب، وطوابع زمنية بدقة أقل من الثانية، مع الاحتفاظ بالأسواق المحسومة بدلًا من التخلص منها. ترويسة واحدة، وJSON نظيفة، وفترة تجريبية مجانية لمدة 3 أيام:
curl -H "X-API-Key: $POLYTEST_KEY" \
"https://api.polytest.io/api/v1/markets?coin=btc&market_type=5m&limit=20"مرجع نقاط النهاية الكامل في وثائق PolyTest، أو ابدأ فترة تجريبية مجانية.
الأسئلة الشائعة
- ما نقاط نهاية Polymarket API؟
- تشغّل Polymarket أربع واجهات REST API: Gamma (gamma-api.polymarket.com) للأحداث والأسواق والبيانات الوصفية؛ وCLOB (clob.polymarket.com) للأسعار ودفاتر الأوامر والتداول؛ وData API (data-api.polymarket.com) للمراكز والنشاط؛ وRelayer (relayer-v2.polymarket.com) للمعاملات بلا غاز. وهناك أيضًا أربعة تدفقات WebSocket تغطي قناة السوق العامة، وقناة المستخدم المصادَق عليها، والبيانات الآنية، والرياضة.
- هل Polymarket API مجانية؟
- نعم. لا يوجد مستوى مدفوع ولا اشتراك ولا صفحة أسعار لـ API — يخضع الوصول لحدود المعدل لا للفوترة، وبيانات الأسواق العامة لا تتطلب أي مفتاح API. الشيء الوحيد الذي يتدرج هو مستوى إنتاجية التداول لكل موقّع، وهو مبني على حجم تداول محفظتك خلال 30 يومًا، لا على الدفع.
- كيف أحصل على مفتاح Polymarket API؟
- وقّع حمولة البيانات ذات الأنواع ClobAuth من نوع EIP-712 بمفتاحك الخاص على Polygon، ثم استدعِ POST /auth/api-key مع ترويسات L1 لإنشاء بيانات الاعتماد. ستتلقى مفتاحًا وسرًا وعبارة مرور — والثلاثة مطلوبة لتوقيع طلبات L2. وفي التشغيلات اللاحقة استخدم GET /auth/derive-api-key لاسترجاع بيانات الاعتماد الموجودة بدلًا من إنشاء جديدة. بيانات الأسواق العامة لا تحتاج إلى مفتاح.
- ما الفرق بين Gamma API وCLOB API؟
- Gamma للاكتشاف: ما الأحداث والأسواق الموجودة، وبياناتها الوصفية، ومعرّفات التوكنات التي تحتاج إليها نقاط النهاية الأخرى. أما CLOB فلدفتر الأوامر: الأسعار الحالية، وعمق الدفتر، وتقديم الأوامر أو إلغاؤها. إذا كنت تحتاج إلى إيجاد سوق، فاستخدم Gamma؛ وإذا كنت تحتاج إلى تسعيره أو التداول فيه، فاستخدم CLOB.
- هل لدى Polymarket حزمة Python SDK؟
- نعم. تصون Polymarket حزم SDK موحّدة بلغتي TypeScript وPython تغطي واجهات REST API الأربع بواجهة ذات أنواع محددة، وتتولى ترقيم الصفحات وأشكال الأخطاء وإعداد المحفظة. وهناك مسار انتقال موثّق من العملاء الأقدم. التوجه مباشرة إلى REST منطقي عندما تكون بيئة التشغيل لديك غير مدعومة، أو تحتاج إلى تحكم دقيق في التوقيع وإعادة المحاولة، أو تحتاج إلى نقطة نهاية لم تكشفها SDK بعد.
- هل يمكنني الحصول على العمق التاريخي لدفتر الأوامر من Polymarket API؟
- لا. كل نقطة نهاية في Polymarket تقدّم الحالة الراهنة. تُرجع نقطة النهاية /prices-history سلسلة أسعار بنحو نقطة واحدة في الدقيقة دون العمق الكامن وراءها، لذا لا يمكنها أن تخبرك بالسعر الذي كان سيُنفَّذ عنده أمر بحجم معيّن، ودفتر أوامر السوق المحسوم يُرجع 404. يتطلب الاختبار الرجعي لقطات عند لحظات زمنية محددة سُجّلت أثناء تشغيل الأسواق، مثل أرشيف PolyTest الذي يضم 240M+ لقطة لأسواق Up/Down للعملات المشفرة.
احصل على البيانات التاريخية التي لا تحتفظ بها Polymarket
يسجّل PolyTest أسواق Up/Down للعملات المشفرة على Polymarket أثناء تشغيلها — 240M+ لقطة مع 8 مستويات من عمق دفتر الأوامر، وطوابع زمنية بدقة أقل من الثانية، مع الاحتفاظ بالأسواق المحسومة. ابدأ بفترة تجريبية مجانية لمدة 3 أيام.
تابع القراءة
حزمة Polymarket Python SDK في 2026 (والانتقال من py-clob-client)
إذا كانت شيفرتك لا تزال تستورد ClobClient من py_clob_client، فهي مبنية على حزمة حلّت محلها أخرى — وكذلك معظم شيفرات Polymarket التي سيكتبها لك مساعد الذكاء الاصطناعي. إليك حزمة SDK الحالية وكيف تنتقل إليها.
WebSockets في Polymarket: بيانات آنية لا تنقطع
استطلاع دفتر الأوامر هو الطريقة الأكثر شيوعًا لاستنزاف ميزانية حد المعدل بلا فائدة. إليك التدفقات الأربعة، وخيارات الاشتراك التي لا يوثقها أحد، ونمط الفشل الذي يتلقى فيه بوتك الصمت فيظنه هدوءًا.
حدود المعدل في Polymarket API: المرجع الكامل
تنشر Polymarket حدود المعدل الخاصة بها عبر عدة صفحات، في نظامين مختلفين تمامًا، باستخدام نافذة 10 ثوانٍ لا يتوقعها أحد تقريبًا. هذا كله في مجموعة جداول واحدة — بالإضافة إلى ما يحدث فعلًا حين تتجاوز حدًا.