تعد أسواق التنبؤ من بين المجالات الأكثر تطلبًا من الناحية الفنية لبناء واجهات برمجة التطبيقات (APIs) لها. فأنت تتعامل مع أدوات مالية تنتهي صلاحيتها، واحتمالات يتم تسعيرها في الوقت الفعلي، وأحداث متعددة النتائج ذات علاقات رأسمالية معقدة، وقاعدة مستخدمين تشمل كلاً من البشر الذين ينقرون على واجهة المستخدم وروبوتات التداول الآلية التي تدير استراتيجيات المراجحة. كل قرار تصميم يتم اختباره تحت الضغط على الفور.
لقد قامت Polymarket، وهي حاليًا أكبر منصة لأسواق التنبؤ في العالم من حيث الحجم، ببناء نظام بيئي لواجهات برمجة التطبيقات (API ecosystem) يستحق الدراسة لهذا السبب تحديدًا. إنها ليست مجرد واجهة برمجة تطبيقات CRUD فوق قاعدة بيانات. بل هي بنية معمارية طبقية بعناية تعالج التوتر الأساسي بين الانفتاح والأمان، وبين البيانات في الوقت الفعلي والبيانات التاريخية، وبين أنماط التمويل التقليدية والأصول المشفرة الأصلية (crypto-native primitives).
إليك ثمانية أنماط تصميم تستحق الاستخلاص من الطريقة التي اتبعوها.
النمط 1: طبقات API مفصولة حسب النطاق
تكشف Polymarket عن ثلاث واجهات برمجة تطبيقات متميزة، لكل منها نطاق واضح:
- Gamma API (
gamma-api.polymarket.com) — اكتشاف السوق، الأحداث، العلامات، البحث - CLOB API (
clob.polymarket.com) — بيانات دفتر الأوامر، التسعير، وضع الأوامر - Data API (
data-api.polymarket.com) — مراكز المستخدم، التداولات، التحليلات، لوحات الصدارة
هذا ليس مجرد اصطلاح تسمية — فكل واجهة برمجة تطبيقات (API) لها متطلبات مصادقة مختلفة، وتواتر تحديث مختلف، وملفات تعريف مستهلكين مختلفة. إن Gamma API عامة بالكامل، ومُحسّنة للتصفح والاكتشاف. بينما CLOB API لديها كل من نقاط النهاية العامة (يمكن لأي شخص قراءة دفتر الأوامر) ونقاط النهاية الموثقة (يتطلب التداول بيانات اعتماد). Data API عامة ولكنها موجهة للمحفظة — حيث يمكنك الاستعلام عن المراكز بواسطة عنوان المستخدم.
الدرس المستفاد من التصميم هنا هو أن الفصل حسب النطاق بدلاً من الفصل حسب الكيان ينتج عنه واجهات برمجة تطبيقات أكثر تماسكًا. سيعطيك النهج الساذج /markets، /orders، /users كلها تحت سقف واحد. بينما تسأل Polymarket بدلاً من ذلك: "لأي غرض تُستخدم واجهة برمجة التطبيقات هذه؟" ثم تبني حول هذا السؤال. فالاكتشاف له أنماط وصول مختلفة عن التداول. والتداول له متطلبات زمن انتقال مختلفة عن التحليلات. إن إعطاء كل منها عنوان URL أساسيًا خاصًا بها يعني أن كل منها يمكن أن يتطور ويتوسع ويصادق بشكل مستقل.
النمط 2: الوصول إلى البيانات العام أولاً
كل ما يتعلق ببيانات السوق — الأسعار، دفاتر الأوامر، البيانات الوصفية للأحداث، التداولات التاريخية — عام بالكامل:
curl "https://gamma-api.polymarket.com/events?limit=5"
لا مفتاح API. لا OAuth. لا قيود على معدل الطلبات على نقاط النهاية المخصصة للقراءة. تحصل على البيانات مباشرة.
هذا اختيار مقصود لا تقوم به معظم المنصات المالية. فالبورصات التقليدية تحمي بيانات السوق كمصدر للإيرادات. بينما تتعامل Polymarket معها كبنية تحتية — فكلما زاد عدد الأشخاص الذين يمكنهم قراءة البيانات والبناء عليها، أصبح السوق أكثر سيولة وفائدة. إنه منطق المنافع العامة المطبق على واجهة برمجة التطبيقات.
النتيجة العملية لمصممي واجهات برمجة التطبيقات تستحق الملاحظة: فصل الوصول للقراءة عن الوصول للكتابة كاهتمام أساسي، بدلاً من تطبيق المصادقة بشكل موحد، هو دائمًا الخيار الصحيح للمنصات التي يتجاوز فيها استهلاك البيانات إنتاج البيانات بكثير. إذا تمكن المستخدم من قراءة أسعار السوق بدون بيانات اعتماد، فقد أزلت الاحتكاك عن 95% من جمهورك المحتمل. أنت تضيف الاحتكاك فقط عند النقطة التي يهم فيها الأمر حقًا — عندما يرغبون في وضع أمر حقيقي.
النمط 3: مصادقة بمستويين تعكس الثقة الحقيقية
تتطلب نقاط نهاية التداول المصادقة، ولكن نموذج المصادقة الخاص بـ Polymarket له هيكل لم يره معظم مصممي واجهات برمجة التطبيقات من قبل: مستويان بأغراض مميزة.
تستخدم المصادقة من المستوى الأول (L1 Authentication) توقيع EIP-712 من المفتاح الخاص للمستخدم. وهي تثبت ملكية المحفظة. تستخدمها مرة واحدة فقط (أو نادرًا) لاشتقاق بيانات اعتماد API:
// L1: Use your private key to derive API credentials
const credentials = await client.createOrDeriveApiKey();
// → { key: "...", secret: "...", passphrase: "..." }
تستخدم المصادقة من المستوى الثاني (L2 Authentication) خوارزمية HMAC-SHA256 مع بيانات الاعتماد المشتقة تلك. وهي ما تُرفقه بكل طلب تداول:
// L2 headers on every trading request
{
"POLY_ADDRESS": "0x...",
"POLY_SIGNATURE": "<hmac-sha256>",
"POLY_TIMESTAMP": "1716000000",
"POLY_API_KEY": "550e8400-...",
"POLY_PASSPHRASE": "..."
}
الفكرة هي أن العمليات المختلفة تستحق مراسم أمنية مختلفة. إنشاء مفاتيح API يتطلب إثبات التحكم في المحفظة — وهذا إجراء عالي المخاطر يجب أن يتطلب توقيعًا تشفيريًا من المفتاح الخاص. ولكن بمجرد إنشاء هذه الثقة، لا ينبغي أن تتطلب طلبات التداول الروتينية إعادة التوقيع بمفتاحك الخاص في كل استدعاء. بيانات اعتماد L2 خفيفة الوزن بما يكفي للاستخدام عالي التردد مع بقائها مرتبطة بهوية L1.
ينطبق هذا النمط بشكل جيد خارج نطاق العملات المشفرة: فكر فيه على أنه الفرق بين "أثبت أنك هذا الشخص" (L1، يتم إجراؤه بشكل غير متكرر بأقوى بيانات الاعتماد المتاحة) و"أثبت أن هذا الطلب جاء منك" (L2، يتم إجراؤه باستمرار ببيانات اعتماد الجلسة). معظم تطبيقات الويب تدمج هذه المستويات في تدفق مصادقة واحد وتفقد الفروق الدقيقة في الأمان.
النمط 4: الأوامر كرسائل موقعة، وليست استدعاءات API
هنا تختلف أسواق التنبؤ بشكل حاد عن تصميم واجهة برمجة التطبيقات التقليدية. عندما تضع أمرًا في Polymarket، فإنك لا ترسل بيانات إلى خادم فحسب — بل تنشئ رسالة موقعة تشفيريًا وهي *التزام مالي قابل للتنفيذ*:
const response = await client.createAndPostOrder(
{
tokenID: "71321045679...",
price: 0.65,
size: 100,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false,
},
OrderType.GTC
);
تحت الغطاء، تقوم حزمة تطوير البرمجيات (SDK) ببناء بنية بيانات من نوع EIP-712، وتوقعها بمفتاحك الخاص، وتقدم التوقيع مع الأمر. يعمل محرك المطابقة خارج السلسلة، ولكن عند مطابقة التداولات، يتم تسويتها على السلسلة عبر Polygon باستخدام تلك التوقيعات. لا يمكن للمشغل اختلاق التداولات أو تحريك الأموال — فالرسالة الموقعة هي التفويض.
يغير هذا دلالات ما يعنيه "استدعاء API". عادةً، يعني الإرسال إلى نقطة نهاية "يرجى القيام بذلك نيابة عني". هنا، يعني إرسال أمر "هنا أداة موقعة تفوض هذا التداول". واجهة برمجة التطبيقات ليست وسيطًا يتخذ القرارات — بل هي وسيلة لنقل الرسائل ذاتية التفويض تشفيريًا.
لمصممي واجهات برمجة التطبيقات خارج مجال العملات المشفرة، الخلاصة هي: عندما يمكن لـ *الحمولة نفسها* حمل التفويض بدلاً من الاعتماد كليًا على بيانات اعتماد طبقة النقل، فإنك تحصل على عدم إنكار وقابلية للتحقق مجانًا. الأنظمة المالية، الوثائق القانونية، والعمليات عالية المخاطر كلها مرشحة لهذا النمط.
النمط 5: علم الوجود الصريح في نموذج البيانات
تنظم Polymarket بياناتها حول كائنين: الأحداث (Events) والأسواق (Markets). التمييز بينهما مهم.
الحدث هو سؤال: *"من سيفوز بسباق مجلس الشيوخ الأمريكي لعام 2026 في بنسلفانيا؟"* وله عنوان، وفئة، وتاريخ حل. السوق هو نتيجة ثنائية محددة قابلة للتداول ضمن هذا الحدث: *"هل سيفوز بوب كيسي؟"* يمكن أن يحتوي حدث واحد على العديد من الأسواق.
{
"id": "501",
"title": "2026 Pennsylvania Senate Race",
"negRisk": true,
"markets": [
{ "id": "2301", "question": "Will Bob Casey win?", "outcomePrices": "[\"0.42\", \"0.58\"]" },
{ "id": "2302", "question": "Will Dave McCormick win?", "outcomePrices": "[\"0.35\", \"0.65\"]" },
{ "id": "2303", "question": "Will a third candidate win?", "outcomePrices": "[\"0.23\", \"0.77\"]" }
]
}
هذا علم وجود صريح — واجهة برمجة التطبيقات لا تخزن البيانات فحسب، بل تقوم بترميز *العلاقات المفاهيمية* بين الكيانات. يتم تمثيل الأسعار كمصفوفات متوازية حيث يكون موضع الفهرس هو اتفاقية الربط: outcomes[0] يتوافق مع outcomePrices[0]. تشير علامة negRisk على مستوى الحدث إلى أن الأسواق الموجودة بداخله لها علاقات رأسمالية غير موجودة في الأسواق المستقلة.
معظم واجهات برمجة التطبيقات تقوم بتسطيح هذه العلاقات. بينما تُبرز Polymarket هذه العلاقات لأنها أساسية لكيفية عمل النظام. إذا كنت تقوم ببناء متداول آلي وفاتتك negRisk: true، فسوف تبني نموذج مركز خاطئ وربما تخسر المال. يجعل تصميم API الهيكل المفاهيمي مرئيًا بحيث يكون إغفاله اختيارًا واعيًا، وليس إعدادًا افتراضيًا صامتًا.
النمط 6: NegRisk — العلاقات الرأسمالية كاهتمام من الدرجة الأولى
تشير علامة negRisk في الأحداث إلى أحد أنماط تصميم API الأكثر إثارة للاهتمام في Polymarket: جعل التكافؤات المالية قابلة للبرمجة.
في حدث قياسي متعدد النتائج، يكون كل سوق مستقلاً. ولكن في حدث NegRisk، حيث يمكن لنتيجة واحدة فقط أن تفوز، توجد علاقة رياضية بين المراكز:
1 رمز "لا" (No token) على النتيجة A ≡ 1 رمز "نعم" (Yes token) على كل نتيجة أخرى
هذا ليس مجرد رياضيات — بل يتم تنفيذه في العقود الذكية ويظهر من خلال واجهة برمجة التطبيقات. عندما تحتفظ بمركز "لا" على "آخر" في سباق مجلس الشيوخ في بنسلفانيا، يمكنك تحويله:
| قبل (Before) | بعد (After) |
|---|---|
| 1× لا (أخرى) (1× No (Other)) | 1× نعم (كيسي) (1× Yes (Casey)) + 1× نعم (ماكورميك) (1× Yes (McCormick)) |
توضح واجهة برمجة التطبيقات ذلك بشكل صريح: negRisk: true في كائن السوق، و negRisk: true مطلوب في خيارات أمرك عند تداول هذه الأسواق. إذا أخطأت، فسيتم رفض أمرك أو تسويته بشكل غير صحيح.
نمط التصميم هنا هو ترميز ثوابت النطاق كحقول API مُعلنة الأنواع بدلاً من تركها كهوامش في الوثائق. لا توجد علامة NegRisk لأنها مريحة — بل توجد لأن إغفالها يسبب سلوكًا غير صحيح. عندما يكون لنطاقك قيود صارمة (يمكن لنتيجة واحدة فقط أن تفوز، المراكز لديها تكافؤات تحويل)، يجب أن تظهر هذه القيود في سطح API، وليس فقط في الوثائق.
النمط 7: حجم التجزئة الديناميكي كحالة سوق
تتعامل معظم واجهات برمجة التطبيقات المالية مع حجم التجزئة (tick size) كإعداد ثابت. أما Polymarket، فتقدم شيئًا أكثر إثارة للاهتمام: يتغير حجم التجزئة ديناميكيًا بناءً على سعر السوق، وتكشف واجهة برمجة التطبيقات عن ذلك كتدفق أحداث في الوقت الفعلي.
عندما يقترب سعر السوق من الأطراف (أعلى من 0.96 أو أقل من 0.04)، يضيق الحد الأدنى لحجم التجزئة من 0.01 إلى 0.001:
{
"event_type": "tick_size_change",
"asset_id": "65818619657...",
"old_tick_size": "0.01",
"new_tick_size": "0.001",
"timestamp": "100000000"
}
المنطق بديهي: عند الاحتمالات القصوى، يمثل حجم تجزئة 1 سنت حركة بنسبة 25% (الانتقال من 0.04 إلى 0.03). وهذا تقريب فج للغاية لاكتشاف الأسعار بشكل ذي معنى. تسمح أحجام التجزئة الأدق بالقرب من الأطراف للسوق بالتعبير عن احتمالات مثل 97.3% بدلاً من التقريب إلى 97%.
ما يجعل هذا الخيار التصميمي لواجهة برمجة التطبيقات جديرًا بالملاحظة هو أن حجم التجزئة ليس معلمة تقوم بجلبها مرة واحدة — إنه *حالة* تتغير ويجب تتبعها. يكشف WebSocket عن أحداث tick_size_change بدقة لكي يتمكن العملاء من الحفاظ على منطق بناء أوامرهم متسقًا مع حالة السوق الحالية. إذا قمت بتشفير حجم التجزئة بشكل ثابت وفاتك هذا الحدث، فسيتم رفض أوامرك.
يعكس هذا مبدأ أوسع: يجب أن يتبنى تصميم واجهة برمجة التطبيقات للأنظمة المالية مفهوم "الحالة" كفئة أولى. معلمات السوق ليست ثابتة. تتغير قواعد الحل. تتضح النتائج. تحتاج واجهة برمجة التطبيقات إلى توصيل هذه التحولات في الحالة بشكل صريح، وعدم ترك العملاء يكتشفونها من خلال الطلبات المرفوضة.
النمط 8: طبقتان من WebSocket لملفات تعريف مستهلكين مختلفة
تدير Polymarket نظامين منفصلين لـ WebSocket، وفهم السبب يكشف عن نمط حول تجزئة الجمهور.
تم بناء قناة السوق (Market Channel) (wss://ws-subscriptions-clob.polymarket.com/ws/market) لمستهلكي التداول. اشترك بواسطة معرف الرمز المميز، واستقبل لقطات دفتر الأوامر، وتغيرات الأسعار، وتنفيذ التداولات، وتغيرات حجم التجزئة. كل شيء مرتبط بمعرفات الأصول ومُحسّن لبناء الأوامر بزمن انتقال منخفض:
{
"assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
"type": "market"
}
تم بناء مقبس البيانات في الوقت الفعلي (Real-Time Data Socket) (wss://ws-live-data.polymarket.com) لملف تعريف مختلف تمامًا. يقوم ببث التعليقات، وأسعار العملات المشفرة من Binance وChainlink، وأسعار الأسهم، وأحداث التفاعل الاجتماعي. اشترك حسب الموضوع:
{
"action": "subscribe",
"subscriptions": [
{ "topic": "crypto_prices", "type": "update", "filters": "btcusdt,ethusd" }
]
}
يخدم هذان النظامان جماهير ذات احتياجات مختلفة جوهريًا. صانع السوق يحتاج إلى فروق دفتر الأوامر ذات الصلة بالمايكروثانية. واجهة المستخدم التي تعرض "ما يحدث على Polymarket الآن" تحتاج إلى خلاصات تعليقات ونشاط اجتماعي. دمجها سيعني إما المبالغة في هندسة خلاصات التواصل الاجتماعي بمتطلبات زمن انتقال بمستوى التداول، أو التقليل من هندسة خلاصات دفتر الأوامر بافتراضات موثوقية بمستوى التواصل الاجتماعي.
الدرس بسيط ولكنه غالبًا ما يتم تجاهله: عندما يكون لدى مستهلكي بياناتك في الوقت الفعلي تفاوتات مختلفة بشكل كبير في زمن الاستجابة، وأحجام البيانات، وأنماط الفشل، امنحهم بنية تحتية منفصلة. تميل نقاط نهاية WebSocket المشتركة التي تحاول خدمة أغراض متعددة إلى الانهيار إلى القاسم المشترك الأعلى للتعقيد وإلى القاسم المشترك الأدنى للأداء.
ما تشترك فيه هذه الأنماط
يعكس تصميم واجهة برمجة التطبيقات الخاصة بـ Polymarket فلسفة معينة: يجب أن تجعل واجهة برمجة التطبيقات الهيكل الفعلي للنطاق مرئيًا، لا أن تجرده.
تتطابق البنية المعمارية ثلاثية الطبقات مع حدود النطاق الحقيقية. يعكس الوصول العام أولاً كيفية عمل قيمة سوق التنبؤ. تعكس المصادقة ذات المستويين الفرق الحقيقي بين إثبات الهوية وتفويض الإجراء. الأوامر كرسائل موقعة تُرمز إلى الضمان غير الاحتجازي. يكشف التسلسل الهرمي للأحداث/الأسواق وعلامة NegRisk عن العلاقات التي قد تكون غير مرئية بخلاف ذلك. تحافظ أحجام التجزئة الديناميكية على حالة العميل متوافقة مع حالة السوق. تخدم طبقات WebSocket المنفصلة جماهير منفصلة.
تركز معظم نصائح تصميم واجهة برمجة التطبيقات على سهولة الاستخدام: اجعلها سهلة الاستدعاء، متسقة في التسمية، ومتوقعة في معالجة الأخطاء. تفعل واجهة برمجة التطبيقات الخاصة بـ Polymarket كل ذلك — ولكن الخيارات الأكثر إثارة للاهتمام تدور حول *الإخلاص للنطاق*. عندما يكون للنطاق تمييز ذو معنى، تظهره واجهة برمجة التطبيقات. عندما يكون للنطاق قيد، تفرضه واجهة برمجة التطبيقات. عندما يكون للنطاق حالة تتغير، تبثها واجهة برمجة التطبيقات.
والنتيجة هي واجهة برمجة تطبيقات تتطلب المزيد من مستهلكيها، ولكنها واجهة حيث يعني فهمها بشكل صحيح أنك تفهم بالفعل النظام الذي تتداول عليه. وهذا ليس مصادفة — فبالنسبة لسوق التنبؤ، حيث النقطة الأساسية هي أن الأسعار تعكس المعلومات، فإن واجهة برمجة التطبيقات التي تجبرك على فهم هيكل السوق تقوم بما يجب عليها فعله بالضبط.