SDK TypeScript
O @polytest/sdk é o cliente TypeScript oficial da API da PolyTest. Ele lê mercados, snapshots e livros de ofertas históricos da Polymarket no Node 20 ou superior. Os tipos vêm com o pacote, e ele não tem dependências em tempo de execução.
SDKs em Python e Go estão planejados. Até que sejam lançados, o Início rápido mostra cada requisição em curl e Python.
Instalação
Instale o pacote pelo npm e coloque sua chave de API na variável de ambiente POLYTEST_KEY.
npm install @polytest/sdk
export POLYTEST_KEY="pt_live_your_key_here"Primeira requisição
polytest() lê sua chave de POLYTEST_KEY. Este exemplo lista mercados BTC 5m, imprime cinco snapshots de um que já foi resolvido e depois busca de novo o primeiro desses momentos com os dois livros de ofertas.
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)
}Configure o cliente
polytest() aceita quatro opções. Você pode omitir qualquer uma delas.
| Opção | Padrão | O que faz |
|---|---|---|
| key | process.env.POLYTEST_KEY | Sua chave de API, enviada como X-API-Key. Espaços e tabulações no início e no fim são removidos. |
| origin | https://api.polytest.io | Para onde as requisições vão. Precisa usar https (ou http em localhost) e não pode incluir um caminho. |
| fetch | globalThis.fetch | Uma função fetch personalizada. O tempo limite continua valendo mesmo que ela ignore o sinal de cancelamento. |
| timeoutMs | 30000 | Tempo limite de cada requisição em milissegundos, incluindo o corpo da resposta. Uma chamada que passa do limite lança network. null desativa o limite. |
import { polytest } from "@polytest/sdk"
const api = polytest({
key: "pt_live_your_key_here",
timeoutMs: 10_000,
})health() funciona sem chave. Sem uma chave definida, todos os outros métodos lançam PolyTestFailure do tipo config antes de enviar qualquer coisa.
O cliente nunca segue um redirecionamento, então sua chave só vai para a origem que você definiu. Uma resposta 3xx lança http.
Métodos
Todo método retorna uma promise, e todo resultado inclui meta (veja metadados da resposta).
| Método | Campos | Retorna |
|---|---|---|
| health() | status (ok ou degraded) e timestamp. Não envia a chave. | |
| limits() | Os limites do seu plano: tier, rate_limits, concurrency, data_access, api_keys e trial_budget. | |
| markets(query) | market_type, coin?, limit?, offset?, start_time?, end_time? | Uma página de mercados, mais novos primeiro. |
| market(ref) | market_id | slug | Um mercado, por market_id ou slug. |
| snapshots(market_id, query?) | limit?, offset?, start_time?, end_time?, include_orderbook? | Uma página de snapshots, mais antigos primeiro. |
| snapshotAt(market_id, query) | timestamp, include_orderbook? | O snapshot mais próximo de timestamp, até dois segundos antes ou depois. |
market_typepode ser5m,15m,1hr,4hrou24hr. A lista é exportada comoMARKET_TYPES.- Escreva
coinem minúsculas, comobtc,ethousol. Sem ele, o servidor retorna mercadosbtc. start_time,end_timeetimestampaceitam ISO 8601. Um horário sem fuso é lido como UTC, e um espaço pode substituir oT.- Os argumentos são verificados antes da requisição: um argumento inválido lança
bad_requeste nada é enviado. Para pular um campo opcional, omita-o, porquenulllança erro.
Páginas
markets e snapshots retornam uma página. As linhas ficam em items, e stop indica se há mais páginas a seguir. page.next() busca a próxima página, ou retorna null quando não há mais nenhuma.
| stop | Significado | next() |
|---|---|---|
| more | Há outra página a partir de nextOffset. | Busca a próxima página. |
| end | Esta é a última página. | Retorna null sem fazer requisição. |
| tier_window | Você chegou ao fim dos dados incluídos no seu plano. | Retorna null sem fazer requisição. |
| snapshot_offset_cap | A paginação chegou ao teto de 100000 do offset de snapshots. | Retorna null sem fazer requisição. |
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()
}Linhas que o cliente não consegue ler ficam fora de items e são contadas em skipped. O próximo offset continua contando essas linhas, então uma linha pulada nunca encerra a paginação antes da hora.
total é uma estimativa do servidor. Continue paginando até que stop seja diferente de more.
Um offset de snapshots acima de 100000 lança bad_request antes da requisição. Para ler mais adiante em um mercado longo, restrinja o intervalo com start_time e end_time.
Livros de ofertas
Passe include_orderbook: true para snapshots ou snapshotAt. Assim, cada snapshot traz orderbook_up e orderbook_down, e cada livro tem bids e 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)
}
}Cada nível é um objeto com price e size, inclusive quando a API envia um par [price, size]. Campos extras do livro, como depth, são mantidos.
Um livro que o cliente não consegue ler volta como null, com orderbook_up_invalid ou orderbook_down_invalid definido como true. Um livro null sem a flag estava ausente. O resto do snapshot é mantido em ambos os casos.
Com um true literal, as linhas são tipadas como SnapshotWithBooks. Uma variável booleana resulta em Snapshot ou SnapshotWithBooks.
Erros e novas tentativas
Os métodos lançam PolyTestFailure. Decida o que fazer com base em error.failure.kind. error.status é o status HTTP, e error.meta contém os metadados da resposta, ou é null quando nenhuma resposta chegou.
| Tipo | Quando |
|---|---|
| config | Opções inválidas ou chave ausente, antes de qualquer requisição. |
| network | Nenhuma resposta chegou: a conexão falhou ou a requisição excedeu o tempo limite. O erro original fica em error.cause. |
| unauthorized | HTTP 401. A API rejeitou a chave. |
| trial_exhausted | HTTP 402. Uma cota do teste grátis se esgotou. Traz dimension e limit. |
| subscription_inactive | HTTP 403. A assinatura não está ativa. |
| forbidden | HTTP 403. Os dados estão fora do seu plano. Traz tier. |
| rate_limited | HTTP 429. Você excedeu o limite de requisições. Traz retry_after quando o servidor o envia. |
| concurrency_limited | HTTP 429. Você tinha requisições demais em andamento ao mesmo tempo. Traz max_concurrent. |
| bad_request | HTTP 400, ou um argumento que o cliente rejeitou antes do envio. |
| not_found | HTTP 404. O mercado não existe, ou não há snapshot perto desse horário. |
| unavailable | HTTP 502 ou 503. Pode incluir retry_after. |
| server | Qualquer outro 5xx, ou um corpo de resposta 200 que o cliente não conseguiu ler. |
| http | Qualquer outra resposta, incluindo um redirecionamento. |
isRetryable(error) retorna true para rate_limited, concurrency_limited, unavailable e network, para server vindo de um HTTP 5xx e para http vindo de 408 ou 425. Toda requisição do SDK é um GET, então repeti-la é seguro.
retryDelayMs(error) retorna a espera em milissegundos, limitada a uma hora. Usa retry_after quando o servidor o enviou. Para rate_limited sem ele, calcula a espera até o seu limite de requisições ser renovado. Caso contrário, retorna null, o que sempre acontece com concurrency_limited, então use seu próprio atraso. Nenhuma das duas funções pausa a execução.
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)Cancele uma requisição
Todo método aceita um último argumento opcional com um signal, assim como page.next(). Quando o sinal é acionado, a chamada é rejeitada com signal.reason, como faz o fetch. Esse valor não é um PolyTestFailure, e isRetryable retorna false para ele.
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 continua ativo junto com o seu sinal. O que disparar primeiro encerra a chamada, e o estouro do tempo limite lança network.
Metadados da resposta
Todo resultado tem meta. Uma falha criada a partir de uma resposta HTTP traz o mesmo objeto em error.meta, então um 429 ainda mostra seu limite de requisições.
| Campo | Headers | Conteúdo |
|---|---|---|
| rate_limit | X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset | limit, remaining e reset_unix (em segundos). null, a menos que os três headers sejam números. |
| trial_remaining_before | X-Trial-Budget-*-Remaining | Durante o teste grátis, os requests, records e bytes que restavam antes desta requisição. Caso contrário, null. |
| server_clamp | X-Limit-Clamped | requested, applied e max quando o servidor reduziu seu limit. Caso contrário, 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 limitAmbiente de execução
O pacote é um módulo ES.
| Configuração | Requisitos |
|---|---|
| import | Node 20 ou superior |
| require() | Node 20.19, ou Node 22.12 ou superior |
| TypeScript compilado para CommonJS | TypeScript 5.8 ou superior, com "module": "nodenext" |