TypeScript SDK
@polytest/sdk — официальный клиент API PolyTest для TypeScript. Он читает исторические рынки, снимки и стаканы 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.
Методы
Каждый метод возвращает промис, и каждый результат содержит 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. С булевой переменной — 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)Отмена запроса
Каждый метод, как и page.next(), принимает необязательный последний аргумент с signal. Когда сигнал срабатывает, вызов отклоняется со значением 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-модуль.
| Конфигурация | Требования |
|---|---|
| import | Node 20 или новее |
| require() | Node 20.19 либо Node 22.12 или новее |
| TypeScript, скомпилированный в CommonJS | TypeScript 5.8 или новее с "module": "nodenext" |