حزمة TypeScript SDK

@polytest/sdk هو عميل TypeScript الرسمي لواجهة PolyTest API. يقرأ أسواق Polymarket التاريخية ولقطاتها ودفاتر أوامرها، ويعمل على Node 20 أو أحدث. تعريفات الأنواع مضمّنة في الحزمة، وليست لها أي تبعيات وقت التشغيل.

حزمتا SDK للغتي Python وGo قيد التخطيط. وإلى أن تصدرا، يعرض دليل البدء السريع كل طلب باستخدام curl وPython.

التثبيت

ثبّت الحزمة من npm وضع مفتاح API الخاص بك في متغير البيئة POLYTEST_KEY.

Terminal
npm install @polytest/sdk
export POLYTEST_KEY="pt_live_your_key_here"

الحزمة منشورة على npm، وشيفرتها المصدرية على GitHub.

أول طلب

تقرأ الدالة polytest() مفتاحك من POLYTEST_KEY. يسرد هذا المثال أسواق BTC 5m، ويطبع خمس لقطات من سوق حُسم، ثم يجلب أولى تلك اللحظات مرة أخرى مع دفتري الأوامر.

TypeScript
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() أربعة خيارات، ويمكنك الاستغناء عن أي منها.

الخيارالقيمة الافتراضيةما يفعله
keyprocess.env.POLYTEST_KEYمفتاح API الخاص بك، ويُرسل في الترويسة X-API-Key. وتُزال المسافات وعلامات الجدولة من طرفيه.
originhttps://api.polytest.ioالوجهة التي تُرسل إليها الطلبات. يجب أن تستخدم https (أو http على localhost) ولا يمكن أن تتضمن مسارًا.
fetchglobalThis.fetchدالة fetch مخصصة. وتظل المهلة سارية حتى لو تجاهلت الدالة إشارة الإلغاء الخاصة بها.
timeoutMs30000المهلة القصوى لكل طلب بالملّي ثانية، بما في ذلك جسم الاستجابة. الاستدعاء الذي يتجاوزها يرمي network. وتُعطّل القيمة null هذا الحد.
TypeScript
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 دون إرسال طلب.
TypeScript
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.

TypeScript
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.
unauthorizedHTTP 401. رفضت API المفتاح.
trial_exhaustedHTTP 402. نفدت إحدى ميزانيات الفترة التجريبية. يتضمن dimension وlimit.
subscription_inactiveHTTP 403. الاشتراك غير نشط.
forbiddenHTTP 403. البيانات خارج نطاق خطتك. يتضمن tier.
rate_limitedHTTP 429. تجاوزت حد المعدل. يتضمن retry_after عندما يرسله الخادم.
concurrency_limitedHTTP 429. كان عدد كبير جدًا من طلباتك قيد التنفيذ في آن واحد. يتضمن max_concurrent.
bad_requestHTTP 400، أو وسيط رفضه العميل قبل الإرسال.
not_foundHTTP 404. السوق غير موجود، أو لا توجد لقطة قريبة من ذلك الوقت.
unavailableHTTP 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، فاعتمد حينها على تأخير من عندك. ولا تنتظر أيٌّ من الدالتين بنفسها.

TypeScript
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.

TypeScript
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_limitX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Resetlimit وremaining وreset_unix (بالثواني). وتكون null ما لم تكن الترويسات الثلاث كلها أرقامًا.
trial_remaining_beforeX-Trial-Budget-*-Remainingأثناء الفترة التجريبية، ما تبقّى من requests وrecords وbytes قبل هذا الطلب. وفي غير ذلك تكون null.
server_clampX-Limit-Clampedrequested وapplied وmax عندما يخفّض الخادم قيمة limit التي أرسلتها. وفي غير ذلك تكون null.
TypeScript
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).

الإعدادالمتطلبات
importNode 20 أو أحدث
require()Node 20.19، أو Node 22.12 أو أحدث
شيفرة TypeScript مُصرَّفة إلى CommonJSTypeScript 5.8 أو أحدث، مع "module": "nodenext"