SDK de TypeScript

@polytest/sdk es el cliente oficial de TypeScript para la API de PolyTest. Lee mercados, snapshots y libros de órdenes históricos de Polymarket en Node 20 o posterior. Incluye sus propios tipos y no tiene dependencias en tiempo de ejecución.

Los SDK de Python y Go están previstos. Hasta que estén disponibles, el Inicio rápido muestra cada solicitud en curl y Python.

Instalación

Instala el paquete desde npm y pon tu clave de API en la variable de entorno POLYTEST_KEY.

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

El paquete está en npm y el código fuente, en GitHub.

Primera solicitud

polytest() lee tu clave de POLYTEST_KEY. Este ejemplo lista mercados BTC 5m, imprime cinco snapshots de uno que ya se resolvió y luego vuelve a obtener el primero de esos momentos con ambos libros de órdenes.

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

Configurar el cliente

polytest() acepta cuatro opciones. Puedes omitir cualquiera de ellas.

OpciónPredeterminadoQué hace
keyprocess.env.POLYTEST_KEYTu clave de API, enviada como X-API-Key. Se eliminan los espacios y tabulaciones de ambos extremos.
originhttps://api.polytest.ioAdónde se envían las solicitudes. Debe usar https (o http en localhost) y no puede incluir una ruta.
fetchglobalThis.fetchUna función fetch personalizada. El tiempo límite se sigue aplicando aunque esa función ignore su señal de cancelación.
timeoutMs30000Tiempo límite de cada solicitud en milisegundos, cuerpo incluido. Una llamada que lo supera lanza network. null desactiva el límite.
TypeScript
import { polytest } from "@polytest/sdk"

const api = polytest({
  key: "pt_live_your_key_here",
  timeoutMs: 10_000,
})

health() funciona sin clave. Si no hay ninguna clave configurada, todos los demás métodos lanzan PolyTestFailure de tipo config antes de enviar nada.

El cliente nunca sigue una redirección, así que tu clave solo va al origen que configuraste. Una respuesta 3xx lanza http.

Métodos

Todos los métodos devuelven una promesa y todos los resultados incluyen meta (consulta los metadatos de la respuesta).

MétodoCamposDevuelve
health()status (ok o degraded) y timestamp. No envía ninguna clave.
limits()Los límites de tu plan: tier, rate_limits, concurrency, data_access, api_keys y trial_budget.
markets(query)market_type, coin?, limit?, offset?, start_time?, end_time?Una página de mercados, los más nuevos primero.
market(ref)market_id | slugUn mercado, por market_id o slug.
snapshots(market_id, query?)limit?, offset?, start_time?, end_time?, include_orderbook?Una página de snapshots, los más antiguos primero.
snapshotAt(market_id, query)timestamp, include_orderbook?El snapshot más cercano a timestamp, hasta dos segundos antes o después.
  • market_type es 5m, 15m, 1hr, 4hr o 24hr. La lista se exporta como MARKET_TYPES.
  • Escribe coin en minúsculas, por ejemplo btc, eth o sol. Si lo omites, el servidor devuelve mercados btc.
  • start_time, end_time y timestamp aceptan ISO 8601. Una hora sin zona horaria se interpreta como UTC, y se puede usar un espacio en lugar de la T.
  • Los argumentos se validan antes de la solicitud: uno no válido lanza bad_request y no se envía nada. Para omitir un campo opcional, no lo incluyas, porque null lanza un error.

Páginas

markets y snapshots devuelven una página. Las filas están en items, y stop te indica si hay más. page.next() obtiene la página siguiente o devuelve null cuando no hay ninguna.

stopSignificadonext()
moreHay otra página a partir de nextOffset.Obtiene la página siguiente.
endEsta es la última página.Devuelve null sin hacer ninguna solicitud.
tier_windowLlegaste al final de los datos que incluye tu plan.Devuelve null sin hacer ninguna solicitud.
snapshot_offset_capEl recorrido alcanzó el tope de offset de snapshots: 100000.Devuelve null sin hacer ninguna solicitud.
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()
}

Las filas que el cliente no puede leer se dejan fuera de items y se cuentan en skipped. El siguiente offset las sigue contando, así que una fila omitida nunca termina el recorrido antes de tiempo.

total es una estimación del servidor. Sigue paginando hasta que stop tenga un valor distinto de more.

Un offset de snapshots mayor que 100000 lanza bad_request antes de la solicitud. Para leer más allá en un mercado largo, acota el rango con start_time y end_time.

Libros de órdenes

Pasa include_orderbook: true a snapshots o snapshotAt. Así, cada snapshot tiene orderbook_up y orderbook_down, y cada libro tiene bids y 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 nivel es un objeto con price y size, también cuando la API envía un par [price, size]. Los campos adicionales del libro, como depth, se conservan.

Un libro que el cliente no puede leer se devuelve como null, con orderbook_up_invalid u orderbook_down_invalid en true. Un libro null sin ese indicador no estaba presente. En ambos casos, el resto del snapshot se conserva.

Con un true literal, las filas se tipan como SnapshotWithBooks. Con una variable booleana, el tipo es Snapshot o SnapshotWithBooks.

Errores y reintentos

Los métodos lanzan PolyTestFailure. Distingue los casos con error.failure.kind. error.status es el estado HTTP, y error.meta son los metadatos de la respuesta, o null si no llegó ninguna respuesta.

TipoCuándo
configOpciones no válidas o falta de clave, antes de cualquier solicitud.
networkNo llegó ninguna respuesta: la conexión falló o se agotó el tiempo límite de la solicitud. El error original está en error.cause.
unauthorizedHTTP 401. La API rechazó la clave.
trial_exhaustedHTTP 402. Se agotó un cupo de la prueba. Incluye dimension y limit.
subscription_inactiveHTTP 403. La suscripción no está activa.
forbiddenHTTP 403. Los datos están fuera de tu plan. Incluye tier.
rate_limitedHTTP 429. Superaste el límite de tasa. Incluye retry_after cuando el servidor lo envía.
concurrency_limitedHTTP 429. Tenías demasiadas solicitudes en curso a la vez. Incluye max_concurrent.
bad_requestHTTP 400, o un argumento que el cliente rechazó antes de enviar la solicitud.
not_foundHTTP 404. El mercado no existe o no hay ningún snapshot cerca de esa hora.
unavailableHTTP 502 o 503. Puede incluir retry_after.
serverCualquier otro 5xx, o un cuerpo de respuesta 200 que el cliente no pudo leer.
httpCualquier otra respuesta, incluida una redirección.

isRetryable(error) devuelve true para rate_limited, concurrency_limited, unavailable y network, para server cuando viene de un HTTP 5xx y para http cuando viene de un 408 o un 425. Todas las solicitudes del SDK son GET, así que repetirlas es seguro.

retryDelayMs(error) devuelve la espera en milisegundos, con un máximo de una hora. Usa retry_after cuando el servidor lo envió. Para rate_limited sin ese valor, devuelve el tiempo que falta para que se restablezca tu límite de tasa. En los demás casos devuelve null, que es siempre lo que ocurre con concurrency_limited, así que usa tu propio retraso. Ninguna de las dos funciones pausa la ejecución.

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)

Cancelar una solicitud

Todos los métodos aceptan un último argumento opcional con un signal, y page.next() también. Cuando la señal se aborta, la llamada se rechaza con signal.reason, igual que hace fetch. Ese valor no es un PolyTestFailure, e isRetryable devuelve false para él.

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 sigue activo junto con tu señal. Lo que se dispare primero termina la llamada, y si se agota el tiempo límite se lanza network.

Metadatos de la respuesta

Todos los resultados tienen meta. Un fallo creado a partir de una respuesta HTTP lleva el mismo objeto en error.meta, así que un 429 también muestra tu límite de tasa.

CampoCabecerasContenido
rate_limitX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Resetlimit, remaining y reset_unix (segundos). null salvo que las tres cabeceras sean números.
trial_remaining_beforeX-Trial-Budget-*-RemainingDurante una prueba, los requests, records y bytes que quedaban antes de esta solicitud. En caso contrario, null.
server_clampX-Limit-Clampedrequested, applied y max cuando el servidor redujo tu limit. En caso contrario, 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

Entorno de ejecución

El paquete es un módulo ES.

ConfiguraciónRequisitos
importNode 20 o posterior
require()Node 20.19, o Node 22.12 o posterior
TypeScript compilado a CommonJSTypeScript 5.8 o posterior, con "module": "nodenext"