حزمة Polymarket Python SDK في 2026 (والانتقال من py-clob-client)

هذا أهم من ترقية إصدار عادية لسبب واحد: كل عيّنات شيفرة Polymarket على الإنترنت تقريبًا أقدم منها. المقالات، وإجابات Stack Overflow، وأمثلة GitHub، و— لأنها دُرّبت على تلك المواد — الشيفرة التي يكتبها مساعدك الذكي حين تطلب منه بوتًا لـ Polymarket. إذا وجدت نفسك تصحح استيرادات غير موجودة، فهذا هو السبب.

ما الذي تغيّر فعلًا

كان النهج القديم يمنحك عميلًا لكل خدمة من خدمات Polymarket. كنت تستورد عميل CLOB لدفتر الأوامر، وتستدعي Gamma عبر HTTP خام لاكتشاف الأسواق، وتستدعي Data API بشكل منفصل للمراكز، وتجلب حزمة builder-signing إذا احتجت إلى معاملات relayer. أربعة نماذج ذهنية، وأربعة أشكال للأخطاء، وأربعة أنماط لترقيم الصفحات.

تدمج SDK الموحّدة ذلك كله في عميل واحد يغطي كل الواجهات.

التثبيت

pip install polymarket-client
# uv add polymarket-client
# poetry add polymarket-client

أربعة عملاء — اختر عن قصد

import asyncio
from polymarket import AsyncPublicClient


async def main() -> None:
    async with AsyncPublicClient() as client:
        pages = client.list_markets(closed=False)
        first = await pages.first_page()
        for market in first.items:
            print(market.slug)


asyncio.run(main())

البيانات العامة لا تحتاج إلى بيانات اعتماد، لذا ابنِ واختبر كل ما تستطيع مقابل AsyncPublicClient قبل إدخال مفتاح. يمكن تجربة الاكتشاف والتحليل وترقيم الصفحات وتوليد الإشارات والتراجع كلها دون أي مخاطرة.

ترقيم الصفحات

واجهة ترقيم واحدة عبر كل دوال السرد. وثلاث طرق لاستهلاكها، بحسب ما إذا كانت حدود الصفحات تهمك:

pages = client.list_markets(closed=False, page_size=10)

# 1. Page at a time — use this when you need to control pacing
#    against the tight /markets rate limit (300 req / 10s).
async for page in pages:
    for market in page.items:
        ...

# 2. Item at a time, boundaries ignored.
async for market in pages.iter_items():
    ...

# 3. Manual, resumable.
page = await pages.first_page()
if page.next_cursor:
    nxt = await pages.from_cursor(page.next_cursor).first_page()

نماذج ذات أنواع محددة

تُرجع الدوال أنواعًا حقيقية بدلًا من القواميس، مُصدَّرة من الحزمة على المستوى الأعلى:

from polymarket import Event, Market, OrderBook, PriceHistoryPoint

هذا أقل التحسينات بريقًا وربما أعلاها قيمة. مع العملاء القدامى، كان الحقل المُعاد تسميته أو المفقود يظهر كـ KeyError في عمق حلقة استراتيجيتك وقت التشغيل — غالبًا في بيئة الإنتاج، وغالبًا أثناء حيازة مركز. النماذج ذات الأنواع المحددة تنقل هذا الفشل إلى مكانه الصحيح.

الاشتراكات الآنية

تدمج subscribe() عدة تغذيات في تدفق أحداث واحد محدد الأنواع، وهذا تحسن حقيقي مقارنةً بإدارة عدة اتصالات WebSocket يدويًا.

from polymarket.streams import MarketSpec, SportsSpec

async with await client.subscribe(
    [MarketSpec(token_ids=[token_id]), SportsSpec()],
) as stream:
    async for event in stream:
        # MarketBookEvent | MarketPriceChangeEvent
        # | MarketLastTradePriceEvent | MarketTickSizeChangeEvent
        # | MarketBestBidAskEvent | NewMarketEvent
        # | MarketResolvedEvent | SportsEvent
        handle(event)

تتولى SDK نبض الاتصال والتأطير وإعادة الاتصال التي كنت ستنفّذها بنفسك — بما في ذلك اشتراط إرسال PING كل 10 ثوانٍ على الاتصال الخام. التفاصيل في دليل WebSocket.

تقديم أمر

market = await client.get_market(slug="<market-slug>")
token_id = market.outcomes.yes.token_id
assert token_id is not None

response = await client.place_market_order(
    token_id=token_id,
    side="BUY",
    amount="10",     # pUSD to spend, not shares to buy
)

if not response.ok:
    raise RuntimeError(response.message)

# Settlement is on-chain and asynchronous.
hashes = await client.wait_for_order_fill_settlement(response)

# Reconcile rather than assuming.
page = await client.list_positions(market=[market.condition_id]).first_page()
position = next((p for p in page.items if p.token_id == token_id), None)

الانتقال من py-clob-client

1. أحصِ كل استدعاء لـ Polymarket، بما في ذلك استدعاءات requests الخام إلى Gamma وData API. فهي ضمن النطاق أيضًا — SDK الموحّدة تغطيها، ودمجها هو معظم الفائدة.
2. ثبّت polymarket-client، وأزل الحزم القديمة. إبقاء الاثنتين مثبتتين للانتقال التدريجي يفتح الباب لاستيراد رمز client الخاطئ.
3. استبدل إنشاء العملاء. استدعاء AsyncSecureClient.create(...) واحد يحل محل العملاء القدامى لكل خدمة ومعالجتهم المنفصلة لبيانات الاعتماد.
4. استبدل الوصول بالقاموس بالوصول بالخاصية. يصبح market["condition_id"] هو market.condition_id. عمل ممل، وهنا يبدأ مدقق الأنواع في رد الجميل.
5. أعد كتابة ترقيم الصفحات وفق واجهة أداة الترقيم بدلًا من حلقات offset أو المؤشرات اليدوية.
6. استبدل شيفرة WebSocket المكتوبة يدويًا بـ subscribe()، واحذف منطق نبض الاتصال وإعادة الاتصال لديك.
7. أعد تشغيل مسارات القراءة فقط أولًا، مقابل العميل العام، قبل السماح لأي شيء بتقديم أمر.

لماذا يخطئ مساعدك الذكي في هذا

يستحق تناوله مباشرة، لأن كثيرين يصلون إلى هنا بسببه. اطلب من نموذج لغوي شيفرة Python لـ Polymarket وستحصل في أحيان كثيرة جدًا على استيرادات py_clob_client وإنشاء ClobClient(...) وكائنات OrderArgs. النموذج لا يعمل بشكل خاطئ — بل يعيد إنتاج الغالبية الساحقة من شيفرات Polymarket التي رآها، وهي أقدم من حزم SDK الموحّدة.

• تحقّق من سطر الاستيراد أولًا. from polymarket import ... حديث؛ أما from py_clob_client... فليس كذلك.
• الصق الوثائق الحالية في السياق. تنشر Polymarket وثائق Markdown قابلة للقراءة آليًا على docs.polymarket.com/llms.txt، ولكل صفحة نسخة .md. إعطاء النموذج المادة الحقيقية أفضل من الجدال معه.
• لا تثق بالشيفرة الواثقة التي لا تعمل. الشيفرة المولّدة كثيرًا ما تخلط الواجهات القديمة والجديدة في شيء لم يوجد قط.

المشكلة نفسها تنطبق على مزوّدي البيانات. ننشر llms.txt وllms-full.txt ومواصفات OpenAPI، ونسمح لزواحف الذكاء الاصطناعي، تحديدًا ليتمكن المساعدون من كتابة تكاملات صحيحة مع PolyTest دون تخمين. بعض المزوّدين يحجبون تلك الزواحف، وهو خيار مشروع لكنه يعني أن مساعدك سيرتجل واجهة API الخاصة بهم.

ما لا تزال SDK عاجزة عنه

SDK الموحّدة واجهة أفضل بكثير لواجهات Polymarket API. لكنها لا تغيّر ما تحتويه تلك الواجهات — والشيء الذي يريده بنّاؤو البوتات أكثر من غيره ليس فيها.

لا يوجد دفتر أوامر تاريخي. ستُرجع client.get_market() البيانات الوصفية لسوق محسوم، لكن دفتره اختفى: تُرجع /book الرمز 404، ولا تحتفظ prices-history إلا بنقطة واحدة تقريبًا في الدقيقة. لا توجد دالة في SDK أو خطة أو بيانات اعتماد تستعيد الدفتر.

للاختبار الرجعي تحتاج إلى لقطات سُجّلت أثناء تشغيل الأسواق. توفرها PolyTest لأسواق Up/Down للعملات المشفرة — 240M+ لقطة عند لحظات زمنية محددة، و8 مستويات من العمق لكل جانب، وطوابع زمنية بدقة أقل من الثانية، مع الاحتفاظ بالأسواق المحسومة. إنها REST API بسيطة بترويسة X-API-Key، لذا تندمج في الشيفرة غير المتزامنة نفسها إلى جانب SDK. ابدأ مجانًا، أو اقرأ كيف تبني بوتًا للمسار الكامل.