TypeScript SDK

@polytest/sdk — официальный клиент API PolyTest для TypeScript. Он читает исторические рынки, снимки и стаканы 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.

Методы

Каждый метод возвращает промис, и каждый результат содержит 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. С булевой переменной — 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)

Отмена запроса

Каждый метод, как и page.next(), принимает необязательный последний аргумент с signal. Когда сигнал срабатывает, вызов отклоняется со значением 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-модуль.

КонфигурацияТребования
importNode 20 или новее
require()Node 20.19 либо Node 22.12 или новее
TypeScript, скомпилированный в CommonJSTypeScript 5.8 или новее с "module": "nodenext"