Polymarket Bot Tutorial · الفصل 6 من 32

مصادقة Polymarket bot وإعداد المحفظة: proxy wallets مقابل EOA، توليد API key عبر SDK، ‏sigType 2 لـ Gnosis Safe، أفضل ممارسات تخزين المفاتيح، والهجرة من Magic إلى Privy.

بقلم هارلي يونغ، الكاتبة الرئيسية في Polymarkets.co.il. آخر مراجعة: مايو 2026.

ما الذي يغطيه هذا الفصل

يعتمد نموذج المحفظة في Polymarket على ثلاثة أجزاء متحركة: حساب مملوك خارجيًا (EOA) يوقّع الأوامر، وproxy ذكي تحتفظ فيه الأموال، وPolymarket CLOB API key التي تصادق طلبات HTTP. إن توصيل هذه الأجزاء الثلاثة بشكل صحيح هو أكثر سبب شائع لفشل اليوم الأول لدى المطورين الجدد، وأصبح الأمر أكثر تعقيدًا بعد هجرة Magic Labs إلى Privy في أغسطس 2025. يشرح هذا الفصل كل جزء وفق ترتيب الإعداد، مع متغيرات البيئة المحددة وعلم نوع التوقيع الذي يحتاجه كود الإنتاج.

  • proxy wallet مقابل EOA: أيهما تستخدم للـ bot
  • توليد API key (خطوات SDK)
  • sigType 2 و POLY_FUNDER_ADDRESS (Gnosis Safe)
  • تخزين المفاتيح: .env، vault، KMS
  • الهجرة من Magic Labs إلى Privy
  • الموافقة على إنفاق USDC/pUSD
  • استعادة المحفظة والنسخ الاحتياطي

proxy wallet مقابل EOA: أيهما تستخدم للـ bot

تستخدم Polymarket نمط proxy wallet قائمًا على smart-contract. إن EOA الخاص بك - العنوان المرتبط بـ private key - يوقّع المعاملات والأوامر. أما Gnosis Safe المنشور عند عنوان حتمي فيحتفظ فعليًا بـ pUSD وحصص النتائج. عنوان الـ proxy هو ما يظهر في لوحة "wallet" داخل واجهة Polymarket؛ بينما EOA هو الذي يوقّع.

بالنسبة إلى bots، أنت دائمًا توقّع باستخدام EOA (PRIVATE_KEY في env) وتُشير إلى عنوان الـ proxy على أنه POLY_FUNDER_ADDRESS في إعدادات عميل CLOB. إرسال الأوامر مع استخدام EOA بوصفه المموّل يؤدي إلى أخطاء "insufficient balance" حتى عندما يكون الـ proxy ممولًا.

لا يمكنك تشغيل bot باستخدام EOA وحده - تدفق الويب في Polymarket ينشئ دائمًا proxy عند التسجيل. تأكد من العنوانين معًا باستخدام polymarket wallet show من CLI، أو اقرأ عنوان الـ proxy من إعدادات واجهة Polymarket.

توليد API key (خطوات SDK)

يتطلب CLOB API ثلاثة بيانات اعتماد: key وsecret وpassphrase. هذه ليست private key لمحفظتك - بل هي مجموعة بيانات اعتماد بنمط HMAC مرتبطة بمحفظتك، وتُستخدم فقط لمصادقة طلبات HTTP.

ولّدها مرة واحدة باستخدام SDK:

# Python
from py_clob_client.client import ClobClient
c = ClobClient(host="https://clob.polymarket.com", chain_id=137,
               key="<PRIVATE_KEY>", signature_type=2,
               funder="<PROXY_ADDRESS>")
creds = c.create_or_derive_api_creds()
print(creds.api_key, creds.api_secret, creds.api_passphrase)

خزّن المخرجات في ملف JSON ثم حمّلها عند كل تشغيل للـ bot؛ لا تعِد التوليد في كل جلسة - خادم API يخزّن مجموعة البيانات الاعتمادية، وتكرار التدوير قد يفعّل منطق rate-limit. لا تنتهي صلاحية هذه البيانات تلقائيًا. أعد تدويرها فقط إذا اشتبهت في حدوث تسريب.

sigType 2 و POLY_FUNDER_ADDRESS (Gnosis Safe)

تحدد الوسيطة signature_type كيفية تحقق CLOB من توقيعات الأوامر. توجد ثلاث قيم؛ اثنتان منها فعليتان:

  • 0 / EOA: يكون EOA هو الموقّع والمموّل معًا. يُستخدم في الإعدادات غير المعتادة حيث يستورد المستخدمون private key مباشرة.
  • 1 / POLY_PROXY: عقد proxy القديم الخاص بـ Magic Labs. معظم الحسابات التي أُنشئت قبل 2025.
  • 2 / POLY_GNOSIS_SAFE: المعيار الحالي. الأموال داخل Gnosis Safe، وEOA يوقّع.

استخدم signature_type=2 لأي حساب أُنشئ بعد أغسطس 2025 (هجرة Privy) أو لأي حساب ترى فيه عنوان Gnosis Safe في واجهة Polymarket. يجب أن يكون متغير البيئة POLY_FUNDER_ADDRESS هو عنوان الـ Safe، وليس EOA. عدم تطابق signature_type مع نوع المموّل يؤدي بصمت إلى رفض الأوامر بما يبدو كـ "insufficient allowance" أو "balance: 0" - ورسالة الخطأ مضللة.

تخزين المفاتيح: .env، vault، KMS

ثلاثة مستويات معقولة لتخزين private key الخاص بـ EOA.

  1. ملف .env (تطوير على جهاز واحد). يوجد الملف على VPS، ويقرأه الـ bot عند التشغيل، ولا يغادر المفتاح المضيف أبدًا. مناسب للمحافظ التي تقل قيمتها عن <$1k. استخدم chmod 600 .env وتأكد من أن .gitignore في المستودع يستثنيه.
  2. vault مُستضاف ذاتيًا (HashiCorp Vault، أو ملف مشفّر بـ age، أو systemd-creds). يضيف خطوة إلغاء قفل عند تشغيل الـ bot. يستحق ذلك للمحافظ في نطاق $1k-$10k.
  3. Cloud KMS (AWS KMS، GCP KMS). يستدعي الـ bot خدمة KMS لفك تشفير المفتاح في الذاكرة؛ ولا يلمس المفتاح القرص أبدًا. لا تستحق هذه التعقيدات التشغيلية إلا فوق $10k أو لأساطيل متعددة من bots.

ما يجب ألا تفعله أبدًا: لا تودع private key في git، ولا تلصقه في محادثة، ولا تخزّنه في password manager يزامن إلى خدمات سحابية دون وضع local-only. إن نطاق الضرر على السلسلة الناتج عن تسريب EOA في Polymarket هو كامل رصيد pUSD ومخزون حصص النتائج لديك.

الهجرة من Magic Labs إلى Privy

في أغسطس 2025 هاجرت Polymarket من مزود embedded-wallet الأساسي من Magic Labs إلى Privy. التأثير على الـ bot صغير لكنه محدد.

الحسابات السابقة للهجرة (التي أُنشئت عبر Magic) تستخدم عادةً signature_type=1 (POLY_PROXY). الحسابات اللاحقة للهجرة تستخدم signature_type=2 (POLY_GNOSIS_SAFE). بعض المستخدمين هاجروا حساباتهم القديمة؛ وبعضهم أبقى على الأصل. لا توجد طريقة لمعرفة النوع الذي يستخدمه حسابك من خلال الـ public API - عليك التحقق بمحاولة توقيع أمر وملاحظة الرفض.

كما غيّرت الهجرة طريقة عرض عنوان المموّل في الواجهة. كانت تدفقات Polymarket الأقدم تعرض عنوان الـ proxy في لوحة التحكم؛ أما التدفق الحالي فيخبئه داخل إعدادات الحساب. يعد أمر CLI polymarket wallet show الطريقة الأنظف لتأكيد القيمتين معًا، بغض النظر عن وقت إنشاء الحساب.

الموافقة على إنفاق USDC/pUSD

لكي يتمكن CLOB من نقل pUSD عند تطابق الأمر، يجب أن يكون الـ proxy قد فوّض عقود تبادل Polymarket باعتبارها spenders. تضبط واجهة Polymarket هذه الموافقات أثناء الإيداع الأول. أما بالنسبة إلى bots التي تموّل الـ proxy مباشرة، فيجب ضبطها يدويًا.

ثلاث موافقات يجب ضبطها، مرة واحدة لكل محفظة:

  1. pUSD (ERC-20) → عقد التبادل
  2. Conditional Tokens (ERC-1155) → عقد التبادل (لبيع الحصص)
  3. Conditional Tokens (ERC-1155) → عقد تبادل NegRisk (لبيع حصص NegRisk)

شغّل polymarket approve من CLI عند الإعداد الأول. تكلف المعاملة بضعة سنتات من MATIC gas. تحقّق باستخدام polymarket approve check - يجب أن تعرض الثلاثة جميعًا "approved." أكثر خطأ صامت شائع لدى المطورين الجدد هو نسيان موافقة NegRisk، والذي يفشل فقط عند بيع الحصص من أسواق متعددة النتائج ويبدو كأنه خطأ في الرصيد.

استعادة المحفظة والنسخ الاحتياطي

تتكون محفظة الـ bot من عنصرين قابلين للاستعادة: private key الخاص بـ EOA، وكلمة مرور حساب Polymarket (التي تقيّد الوصول عبر الويب UI ولكن ليس عبر SDK).

private key الخاص بـ EOA هو الشيء الوحيد المهم بالنسبة إلى الـ bot. فقدانه = فقدان كل ما في الـ proxy. النسخ الاحتياطي البارد: اكتبه على ورق، وأغلقه في ظرف، وخزّنه خارج الموقع. النسخ الاحتياطي الساخن: USB مشفّر. لا ترسله إلى نفسك بالبريد الإلكتروني أبدًا؛ ولا تخزّنه غير مشفّر في التخزين السحابي.

يمكن استعادة كلمة مرور حساب Polymarket عبر استعادة البريد الإلكتروني في Magic Labs / Privy ما دمت لا تزال تتحكم في البريد الأصلي للتسجيل. لكنها لا تقيّد وصول الـ bot - فالـ bot يستخدم private key الخاص بـ EOA مباشرة.

إذا اشتبهت في تسريب مفتاح: فورًا اسحب pUSD ورموز النتائج إلى محفظة جديدة، وولّد EOA جديدًا، وأعد نشر الـ bot بالمفتاح الجديد. لا يمكن إلغاء المفتاح المسرّب؛ يمكن فقط تفريغه من الرصيد.

الأسئلة الشائعة

هل أحتاج إلى محفظة منفصلة للـ bot الخاص بي؟
نعم، ويوصى بذلك بشدة. استخدم EOA جديدًا أو proxy wallet جديدًا مشتقًا من حساب بريد إلكتروني، ولا تضع فيه إلا رأس المال الذي خصصته للـ bot. إذا تسرب مفتاح الـ bot، فإن الأموال المخصصة للـ bot فقط تكون معرضة للخطر - أما مقتنياتك الرئيسية فتبقى آمنة.
ما هو sigType 2 في Polymarkets API؟
يشير sigType 2 إلى توقيع Gnosis Safe (proxy wallet)، ويُستخدم عندما تسجّل الدخول عبر البريد الإلكتروني/Google وتنشئ Polymarket الـ proxy نيابةً عنك. بالنسبة إلى sigType 2، يجب أن يكون متغير البيئة POLY_FUNDER_ADDRESS هو عنوان الـ PROXY (الذي يظهر في واجهة Polymarket)، وليس EOA الأساسي. هذا خطأ إعداد شائع.
كيف أُولّد Polymarket API key؟
استخدم SDK. في Python: يكون ApiCreds الناتج من client.create_api_key() بعد أن تصادق باستخدام محفظتك. في Node.js: بطريقة مشابهة عبر @polymarket/clob-client-v2 و client.createApiKey(). احفظ key/secret/passphrase الناتجة في .env (ولا تودعها أبدًا في git).
هل يمكن إلغاء Polymarket API keys؟
نعم. يمكنك توليد مفاتيح جديدة في أي وقت عبر SDK؛ وتظل المفاتيح القديمة صالحة إلى أن تُلغى صراحةً عبر client.deleteApiKey(creds). أفضل ممارسة هي تدوير المفاتيح دوريًا وإلغاء أي مفتاح لامس جهازًا مُخترقًا.
ما الذي تغيّر عندما هاجرت Polymarket من Magic Labs إلى Privy؟
انتقلت رموز OTP الخاصة بتسجيل الدخول من 3 أرقام (وهو ما كان عرضة للتخمين القسري، واستُغل في اختراق ديسمبر 2025) إلى رموز أطول مع ربط الجهاز عبر Privy. بالنسبة إلى bots، التغيير العملي هو إجراء المصادقة - إذ يتولى SDK تجريد معظم التفاصيل. إذا كان الـ bot لديك يعتمد بشكل صريح على Magic Labs API endpoints (وهو أمر نادر)، فحدّثه إلى تدفق Privy.
هل ينبغي لي تخزين المفاتيح في ملف .env؟
بالنسبة إلى bot يعمل على VPS واحد - نعم، مع صلاحيات ملفات مناسبة (chmod 600 .env، وأن يكون مملوكًا لمستخدم الـ bot). أما في الإعدادات متعددة الأجهزة أو التشغيل على مستوى الإنتاج - فانتقل إلى secrets manager (AWS Secrets Manager، Vault، doppler.com). لا تودع .env في git، أبدًا.