حزمة TypeScript SDK
@polytest/sdk هو عميل TypeScript الرسمي لواجهة PolyTest API. يقرأ أسواق Polymarket التاريخية ولقطاتها ودفاتر أوامرها، ويعمل على Node 20 أو أحدث. تعريفات الأنواع مضمّنة في الحزمة، وليست لها أي تبعيات وقت التشغيل.
حزمتا SDK للغتي Python وGo قيد التخطيط. وإلى أن تصدرا، يعرض دليل البدء السريع كل طلب باستخدام curl وPython.
التثبيت
ثبّت الحزمة من npm وضع مفتاح API الخاص بك في متغير البيئة POLYTEST_KEY.
npm install @polytest/sdk
export POLYTEST_KEY="pt_live_your_key_here"أول طلب
تقرأ الدالة polytest() مفتاحك من POLYTEST_KEY. يسرد هذا المثال أسواق BTC 5m، ويطبع خمس لقطات من سوق حُسم، ثم يجلب أولى تلك اللحظات مرة أخرى مع دفتري الأوامر.
import { polytest } from "@polytest/sdk"
const api = polytest() // reads POLYTEST_KEY
// The newest BTC 5m markets, then the first one that has resolved
const markets = await api.markets({ market_type: "5m", coin: "btc", limit: 10 })
const market = markets.items.find((m) => m.winner !== null)
if (!market) throw new Error("No resolved market on this page")
console.log(market.slug, market.winner)
// Its first five snapshots
const page = await api.snapshots(market.market_id, { limit: 5 })
for (const shot of page.items) {
console.log(shot.time, shot.price_up, shot.price_down)
}
// The first moment again, now with both order books
const [first] = page.items
if (first) {
const { snapshot } = await api.snapshotAt(market.market_id, {
timestamp: first.time,
include_orderbook: true,
})
console.log(snapshot.orderbook_up?.bids, snapshot.orderbook_up?.asks)
}إعداد العميل
تقبل الدالة polytest() أربعة خيارات، ويمكنك الاستغناء عن أي منها.
| الخيار | القيمة الافتراضية | ما يفعله |
|---|---|---|
| key | process.env.POLYTEST_KEY | مفتاح API الخاص بك، ويُرسل في الترويسة X-API-Key. وتُزال المسافات وعلامات الجدولة من طرفيه. |
| origin | https://api.polytest.io | الوجهة التي تُرسل إليها الطلبات. يجب أن تستخدم https (أو http على localhost) ولا يمكن أن تتضمن مسارًا. |
| fetch | globalThis.fetch | دالة fetch مخصصة. وتظل المهلة سارية حتى لو تجاهلت الدالة إشارة الإلغاء الخاصة بها. |
| timeoutMs | 30000 | المهلة القصوى لكل طلب بالملّي ثانية، بما في ذلك جسم الاستجابة. الاستدعاء الذي يتجاوزها يرمي network. وتُعطّل القيمة null هذا الحد. |
import { polytest } from "@polytest/sdk"
const api = polytest({
key: "pt_live_your_key_here",
timeoutMs: 10_000,
})تعمل health() دون مفتاح. وإذا لم يُضبط أي مفتاح، ترمي كل دالة أخرى PolyTestFailure من النوع config قبل أن ترسل أي شيء.
لا يتبع العميل أي إعادة توجيه، لذا لا يصل مفتاحك إلا إلى الأصل الذي حددته. وأي استجابة 3xx ترمي http.
الدوال
تُرجع كل دالة كائن Promise، وتتضمن كل نتيجة meta (راجع البيانات الوصفية للاستجابة).
| الدالة | الحقول | القيمة المُرجعة |
|---|---|---|
| health() | status (ok أو degraded) وtimestamp. لا تُرسل أي مفتاح. | |
| limits() | حدود خطتك: tier وrate_limits وconcurrency وdata_access وapi_keys وtrial_budget. | |
| markets(query) | market_type, coin?, limit?, offset?, start_time?, end_time? | صفحة من الأسواق، الأحدث أولًا. |
| market(ref) | market_id | slug | سوق واحد، بحسب market_id أو slug. |
| snapshots(market_id, query?) | limit?, offset?, start_time?, end_time?, include_orderbook? | صفحة من اللقطات، الأقدم أولًا. |
| snapshotAt(market_id, query) | timestamp, include_orderbook? | اللقطة الأقرب إلى timestamp، في حدود ثانيتين قبله أو بعده. |
- قيمة
market_typeهي5mأو15mأو1hrأو4hrأو24hr. وهذه القائمة مُصدَّرة باسمMARKET_TYPES. - اكتب
coinبأحرف صغيرة، مثلbtcأوethأوsol. وإن لم تحدده، يُرجع الخادم أسواقbtc. - تقبل
start_timeوend_timeوtimestampصيغة ISO 8601. والوقت الذي لا يحدد منطقة زمنية يُقرأ بتوقيت UTC، ويمكن أن تحل مسافة محلT. - تُفحص الوسائط قبل الطلب: أي وسيط غير صالح يرمي
bad_requestولا يُرسل أي شيء. لتخطي حقل اختياري احذفه تمامًا، لأن تمريرnullيرمي خطأً.
الصفحات
تُرجع markets وsnapshots صفحةً. الصفوف موجودة في items، ويخبرك stop هل توجد صفحات أخرى بعدها. وتجلب page.next() الصفحة التالية، أو تُرجع null إن لم توجد.
| stop | المعنى | next() |
|---|---|---|
| more | تليها صفحة أخرى تبدأ عند nextOffset. | تجلب الصفحة التالية. |
| end | هذه هي الصفحة الأخيرة. | تُرجع null دون إرسال طلب. |
| tier_window | وصلت إلى نهاية البيانات التي تشملها خطتك. | تُرجع null دون إرسال طلب. |
| snapshot_offset_cap | بلغ التنقل بين الصفحات الحد الأقصى لإزاحة اللقطات، وهو 100000. | تُرجع null دون إرسال طلب. |
import { polytest, type Page, type Snapshot } from "@polytest/sdk"
const api = polytest()
const marketId = "1496946"
let page: Page<Snapshot> | null = await api.snapshots(marketId, { limit: 500 })
let rows = 0
while (page) {
rows += page.items.length
if (page.stop !== "more") console.log(rows, "rows, stopped by", page.stop)
page = await page.next()
}الصفوف التي لا يستطيع العميل قراءتها تُستبعد من items وتُحسب في skipped. وتظل الإزاحة التالية تحسبها، لذا لا يؤدي تخطي صف إلى إنهاء التنقل بين الصفحات مبكرًا.
قيمة total تقدير من الخادم. واصل الترقيم حتى تصبح قيمة stop شيئًا غير more.
أي قيمة offset للقطات تتجاوز 100000 ترمي bad_request قبل إرسال الطلب. ولقراءة ما بعد ذلك في سوق طويل، ضيّق النطاق باستخدام start_time وend_time.
دفاتر الأوامر
مرّر include_orderbook: true إلى snapshots أو snapshotAt. عندها تحتوي كل لقطة على orderbook_up وorderbook_down، ويحتوي كل دفتر على bids وasks.
import { polytest } from "@polytest/sdk"
const api = polytest()
const marketId = "1496946"
const page = await api.snapshots(marketId, { limit: 100, include_orderbook: true })
for (const shot of page.items) {
if (shot.orderbook_up_invalid) continue // the client could not read this book
for (const { price, size } of shot.orderbook_up?.asks ?? []) {
console.log(shot.time, price, size)
}
}كل مستوى كائن يحتوي على price وsize، حتى عندما ترسل API زوجًا بصيغة [price, size]. وتُحفظ حقول الدفتر الإضافية مثل depth.
الدفتر الذي لا يستطيع العميل قراءته يُرجَع بقيمة null، مع ضبط orderbook_up_invalid أو orderbook_down_invalid على true. أما الدفتر الذي قيمته null دون هذه العلامة فكان غائبًا. وفي الحالتين تُحفظ بقية اللقطة.
عند تمرير القيمة الحرفية true، يكون نوع الصفوف SnapshotWithBooks. أما المتغير المنطقي (boolean) فيعطي Snapshot أو SnapshotWithBooks.
الأخطاء وإعادة المحاولة
ترمي الدوال PolyTestFailure. فرّع منطق المعالجة بحسب error.failure.kind. وتمثل error.status حالة HTTP، وerror.meta البيانات الوصفية للاستجابة، أو null إذا لم تصل أي استجابة.
| النوع | متى |
|---|---|
| config | خيارات غير صالحة أو مفتاح مفقود، قبل أي طلب. |
| network | لم تصل أي استجابة: فشل الاتصال أو انتهت مهلة الطلب. والخطأ الأصلي في error.cause. |
| unauthorized | HTTP 401. رفضت API المفتاح. |
| trial_exhausted | HTTP 402. نفدت إحدى ميزانيات الفترة التجريبية. يتضمن dimension وlimit. |
| subscription_inactive | HTTP 403. الاشتراك غير نشط. |
| forbidden | HTTP 403. البيانات خارج نطاق خطتك. يتضمن tier. |
| rate_limited | HTTP 429. تجاوزت حد المعدل. يتضمن retry_after عندما يرسله الخادم. |
| concurrency_limited | HTTP 429. كان عدد كبير جدًا من طلباتك قيد التنفيذ في آن واحد. يتضمن max_concurrent. |
| bad_request | HTTP 400، أو وسيط رفضه العميل قبل الإرسال. |
| not_found | HTTP 404. السوق غير موجود، أو لا توجد لقطة قريبة من ذلك الوقت. |
| unavailable | HTTP 502 أو 503. قد يتضمن retry_after. |
| server | أي استجابة 5xx أخرى، أو جسم استجابة 200 تعذّر على العميل قراءته. |
| http | أي استجابة أخرى، بما في ذلك إعادة التوجيه. |
تُرجع isRetryable(error) القيمة true للأنواع rate_limited وconcurrency_limited وunavailable وnetwork، وللنوع server الناتج عن HTTP 5xx، وللنوع http الناتج عن 408 أو 425. كل طلبات SDK من نوع GET، لذا فإن تكرار أي منها آمن.
تُرجع retryDelayMs(error) مدة الانتظار بالملّي ثانية، بحد أقصى ساعة واحدة. وتستخدم retry_after إذا أرسله الخادم. ومع rate_limited دونه، تمتد مدة الانتظار حتى يُعاد ضبط حد المعدل لديك. وفي غير ذلك تُرجع null، وهذا ما يحدث دائمًا مع concurrency_limited، فاعتمد حينها على تأخير من عندك. ولا تنتظر أيٌّ من الدالتين بنفسها.
import { polytest, isRetryable, retryDelayMs, PolyTestFailure } from "@polytest/sdk"
const api = polytest()
async function marketBySlug(slug: string) {
try {
return await api.market({ slug })
} catch (error) {
if (error instanceof PolyTestFailure && error.failure.kind === "not_found") return null
if (!isRetryable(error)) throw error
await new Promise((resolve) => setTimeout(resolve, retryDelayMs(error) ?? 1000))
return api.market({ slug })
}
}
const market = await marketBySlug("btc-updown-5m-1772689200")
console.log(market?.winner)إلغاء طلب
تقبل كل دالة وسيطًا أخيرًا اختياريًا يحتوي على signal، وكذلك page.next(). وعند إلغاء الإشارة، يُرفض الاستدعاء بقيمة signal.reason، كما تفعل fetch. وهذه القيمة ليست PolyTestFailure، وتُرجع لها isRetryable القيمة false.
import { polytest } from "@polytest/sdk"
const api = polytest()
const controller = new AbortController()
setTimeout(() => controller.abort(), 5_000)
const page = await api.markets({ market_type: "15m" }, { signal: controller.signal })
const nextPage = await page.next({ signal: controller.signal })تظل timeoutMs سارية إلى جانب إشارتك. أيهما يقع أولًا يُنهي الاستدعاء، وانتهاء المهلة يرمي network.
البيانات الوصفية للاستجابة
تحتوي كل نتيجة على meta. والإخفاق المبني على استجابة HTTP يحمل الكائن نفسه في error.meta، لذا تُظهر الاستجابة 429 حد المعدل لديك أيضًا.
| الحقل | الترويسات | المحتوى |
|---|---|---|
| rate_limit | X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset | limit وremaining وreset_unix (بالثواني). وتكون null ما لم تكن الترويسات الثلاث كلها أرقامًا. |
| trial_remaining_before | X-Trial-Budget-*-Remaining | أثناء الفترة التجريبية، ما تبقّى من requests وrecords وbytes قبل هذا الطلب. وفي غير ذلك تكون null. |
| server_clamp | X-Limit-Clamped | requested وapplied وmax عندما يخفّض الخادم قيمة limit التي أرسلتها. وفي غير ذلك تكون null. |
import { polytest } from "@polytest/sdk"
const api = polytest()
const page = await api.markets({ market_type: "5m", limit: 100 })
console.log(page.meta.rate_limit?.remaining) // requests left in this window
console.log(page.meta.server_clamp) // null unless the server lowered limitبيئة التشغيل
الحزمة وحدة ES (ES module).
| الإعداد | المتطلبات |
|---|---|
| import | Node 20 أو أحدث |
| require() | Node 20.19، أو Node 22.12 أو أحدث |
| شيفرة TypeScript مُصرَّفة إلى CommonJS | TypeScript 5.8 أو أحدث، مع "module": "nodenext" |