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.

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

O pacote está no npm, e o código-fonte está no GitHub.

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.

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)
}

Configure o cliente

polytest() aceita quatro opções. Você pode omitir qualquer uma delas.

OpçãoPadrãoO que faz
keyprocess.env.POLYTEST_KEYSua chave de API, enviada como X-API-Key. Espaços e tabulações no início e no fim são removidos.
originhttps://api.polytest.ioPara onde as requisições vão. Precisa usar https (ou http em localhost) e não pode incluir um caminho.
fetchglobalThis.fetchUma função fetch personalizada. O tempo limite continua valendo mesmo que ela ignore o sinal de cancelamento.
timeoutMs30000Tempo 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.
TypeScript
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étodoCamposRetorna
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 | slugUm 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_type pode ser 5m, 15m, 1hr, 4hr ou 24hr. A lista é exportada como MARKET_TYPES.
  • Escreva coin em minúsculas, como btc, eth ou sol. Sem ele, o servidor retorna mercados btc.
  • start_time, end_time e timestamp aceitam ISO 8601. Um horário sem fuso é lido como UTC, e um espaço pode substituir o T.
  • Os argumentos são verificados antes da requisição: um argumento inválido lança bad_request e nada é enviado. Para pular um campo opcional, omita-o, porque null lanç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.

stopSignificadonext()
moreHá outra página a partir de nextOffset.Busca a próxima página.
endEsta é a última página.Retorna null sem fazer requisição.
tier_windowVocê chegou ao fim dos dados incluídos no seu plano.Retorna null sem fazer requisição.
snapshot_offset_capA paginação chegou ao teto de 100000 do offset de snapshots.Retorna null sem fazer requisição.
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()
}

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.

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)
  }
}

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.

TipoQuando
configOpções inválidas ou chave ausente, antes de qualquer requisição.
networkNenhuma resposta chegou: a conexão falhou ou a requisição excedeu o tempo limite. O erro original fica em error.cause.
unauthorizedHTTP 401. A API rejeitou a chave.
trial_exhaustedHTTP 402. Uma cota do teste grátis se esgotou. Traz dimension e limit.
subscription_inactiveHTTP 403. A assinatura não está ativa.
forbiddenHTTP 403. Os dados estão fora do seu plano. Traz tier.
rate_limitedHTTP 429. Você excedeu o limite de requisições. Traz retry_after quando o servidor o envia.
concurrency_limitedHTTP 429. Você tinha requisições demais em andamento ao mesmo tempo. Traz max_concurrent.
bad_requestHTTP 400, ou um argumento que o cliente rejeitou antes do envio.
not_foundHTTP 404. O mercado não existe, ou não há snapshot perto desse horário.
unavailableHTTP 502 ou 503. Pode incluir retry_after.
serverQualquer outro 5xx, ou um corpo de resposta 200 que o cliente não conseguiu ler.
httpQualquer 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.

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)

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.

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

CampoHeadersConteúdo
rate_limitX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Resetlimit, remaining e reset_unix (em segundos). null, a menos que os três headers sejam números.
trial_remaining_beforeX-Trial-Budget-*-RemainingDurante o teste grátis, os requests, records e bytes que restavam antes desta requisição. Caso contrário, null.
server_clampX-Limit-Clampedrequested, applied e max quando o servidor reduziu seu limit. Caso contrário, 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

Ambiente de execução

O pacote é um módulo ES.

ConfiguraçãoRequisitos
importNode 20 ou superior
require()Node 20.19, ou Node 22.12 ou superior
TypeScript compilado para CommonJSTypeScript 5.8 ou superior, com "module": "nodenext"