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.
npm install @polytest/sdk
export POLYTEST_KEY="pt_live_your_key_here"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.
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ón | Predeterminado | Qué hace |
|---|---|---|
| key | process.env.POLYTEST_KEY | Tu clave de API, enviada como X-API-Key. Se eliminan los espacios y tabulaciones de ambos extremos. |
| origin | https://api.polytest.io | Adónde se envían las solicitudes. Debe usar https (o http en localhost) y no puede incluir una ruta. |
| fetch | globalThis.fetch | Una función fetch personalizada. El tiempo límite se sigue aplicando aunque esa función ignore su señal de cancelación. |
| timeoutMs | 30000 | Tiempo límite de cada solicitud en milisegundos, cuerpo incluido. Una llamada que lo supera lanza network. null desactiva el límite. |
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étodo | Campos | Devuelve |
|---|---|---|
| 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 | slug | Un 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_typees5m,15m,1hr,4hro24hr. La lista se exporta comoMARKET_TYPES.- Escribe
coinen minúsculas, por ejemplobtc,ethosol. Si lo omites, el servidor devuelve mercadosbtc. start_time,end_timeytimestampaceptan ISO 8601. Una hora sin zona horaria se interpreta como UTC, y se puede usar un espacio en lugar de laT.- Los argumentos se validan antes de la solicitud: uno no válido lanza
bad_requesty no se envía nada. Para omitir un campo opcional, no lo incluyas, porquenulllanza 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.
| stop | Significado | next() |
|---|---|---|
| more | Hay otra página a partir de nextOffset. | Obtiene la página siguiente. |
| end | Esta es la última página. | Devuelve null sin hacer ninguna solicitud. |
| tier_window | Llegaste al final de los datos que incluye tu plan. | Devuelve null sin hacer ninguna solicitud. |
| snapshot_offset_cap | El recorrido alcanzó el tope de offset de snapshots: 100000. | Devuelve null sin hacer ninguna solicitud. |
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.
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.
| Tipo | Cuándo |
|---|---|
| config | Opciones no válidas o falta de clave, antes de cualquier solicitud. |
| network | No llegó ninguna respuesta: la conexión falló o se agotó el tiempo límite de la solicitud. El error original está en error.cause. |
| unauthorized | HTTP 401. La API rechazó la clave. |
| trial_exhausted | HTTP 402. Se agotó un cupo de la prueba. Incluye dimension y limit. |
| subscription_inactive | HTTP 403. La suscripción no está activa. |
| forbidden | HTTP 403. Los datos están fuera de tu plan. Incluye tier. |
| rate_limited | HTTP 429. Superaste el límite de tasa. Incluye retry_after cuando el servidor lo envía. |
| concurrency_limited | HTTP 429. Tenías demasiadas solicitudes en curso a la vez. Incluye max_concurrent. |
| bad_request | HTTP 400, o un argumento que el cliente rechazó antes de enviar la solicitud. |
| not_found | HTTP 404. El mercado no existe o no hay ningún snapshot cerca de esa hora. |
| unavailable | HTTP 502 o 503. Puede incluir retry_after. |
| server | Cualquier otro 5xx, o un cuerpo de respuesta 200 que el cliente no pudo leer. |
| http | Cualquier 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.
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.
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.
| Campo | Cabeceras | Contenido |
|---|---|---|
| rate_limit | X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset | limit, remaining y reset_unix (segundos). null salvo que las tres cabeceras sean números. |
| trial_remaining_before | X-Trial-Budget-*-Remaining | Durante una prueba, los requests, records y bytes que quedaban antes de esta solicitud. En caso contrario, null. |
| server_clamp | X-Limit-Clamped | requested, applied y max cuando el servidor redujo tu limit. En caso contrario, 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 limitEntorno de ejecución
El paquete es un módulo ES.
| Configuración | Requisitos |
|---|---|
| import | Node 20 o posterior |
| require() | Node 20.19, o Node 22.12 o posterior |
| TypeScript compilado a CommonJS | TypeScript 5.8 o posterior, con "module": "nodenext" |