API · مرجع

قراءة بيانات سوق بوليماركت لا تحتاج إلى مفتاح. وضع الأوامر أو إلغاؤها يحتاج إلى طبقتين من المصادقة: توقيع محفظة L1 (EIP-712) لإنشاء بيانات اعتماد API الخاصة بك، وتوقيع L2 من نوع HMAC على كل طلب مُصادَق عليه. تغطي هذه الصفحة كلتيهما، إضافة إلى أنواع التوقيع الأربعة وعنوان الممول - وهما الأمران اللذان يسببان معظم أخطاء المصادقة.

لمحة سريعة
  • القراءة (Gamma، Data، CLOB العام) - بلا مصادقة.
  • L1 - محفظتك توقّع رسالة EIP-712 (نطاق ClobAuth الإصدار "1") لـ إنشاء أو اشتقاق بيانات اعتماد API.
  • L2 - كل طلب أمر يُوقَّع بتوقيع HMAC من api_key / api_secret / api_passphrase.

إنشاء أو اشتقاق بيانات اعتماد API (L1)

محفظتك توقّع مرة واحدة لسَكّ (أو إعادة اشتقاق) مجموعة حتمية من بيانات اعتماد API. استخدم حزمة V2 SDK - فحزمة V1 py-clob-client (0.34.x) مؤرشفة وغير صالحة للعمل.

from py_clob_client_v2 import ClobClient   # pip install py-clob-client-v2

# L1: your wallet signs to derive API credentials
client = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=PRIVATE_KEY)
creds = client.create_or_derive_api_key()    # api_key, api_secret, api_passphrase

# L1 + L2: rebuild the client WITH creds for authenticated calls (no set_api_creds in v2)
client = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=PRIVATE_KEY, creds=creds)
// polymarket_client_sdk_v2 - official Rust client (repo rs-clob-client-v2)
use polymarket_client_sdk_v2::clob::{Client, Config};
use polymarket_client_sdk_v2::clob::types::SignatureType;
let client = Client::new("https://clob.polymarket.com", Config::default())?
    .authentication_builder(&signer)
    .funder(deposit_wallet)                   // deposit wallets work in Rust today
    .signature_type(SignatureType::Poly1271)
    .authenticate().await?;

احفظ القيم الثلاث كأسرار (متغيرات بيئة). قراءة بيانات السوق لا تحتاجها أبداً.

أنواع التوقيع (0-3)

يخبر نوع التوقيع المنصة كيف يرتبط توقيع أمرك بالمحفظة التي تحتفظ بالأموال (الممول). اختر النوع الذي يطابق طريقة إنشاء حسابك.

النوعالاسممتى
0EOAمحفظة عادية (مثل MetaMask) توقّع وتحتفظ بالأموال معاً.
1POLY_PROXYتسجيل عبر البريد الإلكتروني / Magic.link - محفظة وكيل تحتفظ بالأموال؛ ومفتاحك يوقّع نيابة عنها.
2POLY_GNOSIS_SAFEمحفظة Gnosis Safe تحتفظ بالأموال؛ ومفتاح موقّع يوقّع لها.
3POLY_1271محفظة إيداع (توقيع عقد ذكي بمعيار EIP-1271).

عندما يختلف مفتاح التوقيع عن عنوان الاحتفاظ بالأموال (الأنواع 1-3)، يجب أن تمرّر كليهما: المفتاح الخاص و عنوان funder.

محافظ الإيداع (النوع 3) - استخدم Rust اليوم. اعتباراً من يونيو 2026 يعاني عميلا Python (py-clob-client-v2) وTypeScript (@polymarket/clob-client-v2) من علة مفتوحة: مصادقة L1 تربط مفتاح API بمحفظة EOA الخاصة بك بدلاً من محفظة الإيداع، فتُرفض الأوامر ("maker address not allowed, please use the deposit wallet flow"). أما عميل Rust الرسمي فيتعامل مع توقيع محفظة الإيداع EIP-1271 بشكل صحيح. الحل البديل بدون Rust: استخدم حساب بريد إلكتروني/Magic ووقّع بـ signature_type = POLY_PROXY (النوع 1). راجع من جديد مشكلتي بوليماركت #70 (Python) / #65 (TS) لمعرفة الإصلاح.

توقيع الطلبات (L2)

يحمل كل طلب مُصادَق عليه توقيع HMAC مبنياً من سرّ API الخاص بك مضافاً إليه أسلوب الطلب والمسار والمتن وطابع زمني. تبني حزمة V2 SDK هذه الترويسات نيابة عنك. أمران يجب إبقاؤهما صحيحين:

  • الساعة - الانحراف الأكبر من ~60 ثانية يؤدي إلى رفض توقيعك. زامِن عبر NTP.
  • النطاقات - يبقى إصدار نطاق L2/ClobAuth بمعيار EIP-712 هو "1"؛ ونطاق Exchange (الأوامر) في V2 وحده هو الذي انتقل إلى "2". عميل V1 يوقّع نطاق الأمر الخاطئ فيفشل - انظر order_version_mismatch.

سلامة المفاتيح

  • لا تُضمّن المفاتيح الخاصة أو أسرار API في الكود أبداً - استخدم متغيرات البيئة؛ ولا تُودِعها في المستودع أبداً.
  • افصل مفتاح التوقيع وعنوان الممول عن محفظتك اليومية قدر الإمكان.
  • البوتات المخصصة للقراءة فقط لا تحتاج إلى أي بيانات اعتماد على الإطلاق - ابدأ من هناك.

التالي: CLOB API: وضع أمر · إصلاح خطأ مصادقة · الترحيل من v1 إلى v2.