SDK TypeScript

@polytest/sdk è il client TypeScript ufficiale per l’API di PolyTest. Legge mercati, snapshot e order book storici di Polymarket su Node 20 o versioni successive. I tipi sono inclusi nel pacchetto, che non ha dipendenze a runtime.

Sono previsti SDK per Python e Go. Finché non saranno disponibili, la Guida rapida mostra ogni richiesta in curl e Python.

Installazione

Installa il pacchetto da npm e imposta la tua chiave API nella variabile d’ambiente POLYTEST_KEY.

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

Il pacchetto è su npm e il codice sorgente su GitHub.

Prima richiesta

polytest() legge la tua chiave da POLYTEST_KEY. Questo esempio elenca i mercati BTC 5m, stampa cinque snapshot di un mercato già risolto, poi recupera di nuovo il primo di quei momenti con entrambi gli order book.

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

Configurare il client

polytest() accetta quattro opzioni, tutte facoltative.

OpzionePredefinitoCosa fa
keyprocess.env.POLYTEST_KEYLa tua chiave API, inviata come X-API-Key. Gli spazi e le tabulazioni all’inizio e alla fine vengono rimossi.
originhttps://api.polytest.ioDove vengono inviate le richieste. Deve usare https (o http su localhost) e non può includere un percorso.
fetchglobalThis.fetchUna funzione fetch personalizzata. Il timeout si applica comunque, anche se la funzione ignora il proprio segnale di interruzione.
timeoutMs30000Tempo massimo per ogni richiesta in millisecondi, body incluso. Una chiamata che lo supera lancia un errore network. null disattiva il limite.
TypeScript
import { polytest } from "@polytest/sdk"

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

health() funziona senza chiave. Se non è impostata alcuna chiave, tutti gli altri metodi lanciano PolyTestFailure di tipo config prima di inviare qualsiasi cosa.

Il client non segue mai i reindirizzamenti, quindi la tua chiave arriva solo all’origine che hai impostato. Una risposta 3xx lancia un errore http.

Metodi

Ogni metodo restituisce una promise e ogni risultato include meta (vedi metadati della risposta).

MetodoCampiRestituisce
health()status (ok o degraded) e timestamp. Non invia la chiave.
limits()I limiti del tuo piano: tier, rate_limits, concurrency, data_access, api_keys e trial_budget.
markets(query)market_type, coin?, limit?, offset?, start_time?, end_time?Una pagina di mercati, prima i più recenti.
market(ref)market_id | slugUn singolo mercato, tramite market_id o slug.
snapshots(market_id, query?)limit?, offset?, start_time?, end_time?, include_orderbook?Una pagina di snapshot, prima i più vecchi.
snapshotAt(market_id, query)timestamp, include_orderbook?Lo snapshot più vicino a timestamp, entro due secondi prima o dopo.
  • market_type può essere 5m, 15m, 1hr, 4hr o 24hr. L’elenco è esportato come MARKET_TYPES.
  • Scrivi coin in minuscolo, ad esempio btc, eth o sol. Se lo ometti, il server restituisce i mercati btc.
  • start_time, end_time e timestamp accettano il formato ISO 8601. Un orario senza fuso orario viene interpretato come UTC, e al posto della T si può usare uno spazio.
  • Gli argomenti vengono controllati prima della richiesta: se uno non è valido viene lanciato un errore bad_request e non viene inviato nulla. Per saltare un campo facoltativo omettilo: null lancia un errore.

Pagine

markets e snapshots restituiscono una pagina. Le righe sono in items e stop indica se ne seguono altre. page.next() recupera la pagina successiva, oppure restituisce null se non ce n’è un’altra.

stopSignificatonext()
moreSegue un’altra pagina a partire da nextOffset.Recupera la pagina successiva.
endQuesta è l’ultima pagina.Restituisce null senza fare richieste.
tier_windowHai raggiunto la fine dei dati inclusi nel tuo piano.Restituisce null senza fare richieste.
snapshot_offset_capLa paginazione ha raggiunto il limite di offset degli snapshot, pari a 100000.Restituisce null senza fare richieste.
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()
}

Le righe che il client non riesce a leggere vengono escluse da items e conteggiate in skipped. L’offset successivo le conta comunque, quindi una riga saltata non interrompe mai la paginazione in anticipo.

total è una stima del server. Continua a paginare finché stop non assume un valore diverso da more.

Un offset degli snapshot superiore a 100000 lancia un errore bad_request prima della richiesta. Per leggere più avanti in un mercato lungo, restringi l’intervallo con start_time ed end_time.

Order book

Passa include_orderbook: true a snapshots o snapshotAt. Ogni snapshot conterrà allora orderbook_up e orderbook_down, e ogni book 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)
  }
}

Ogni livello è un oggetto con price e size, anche quando l’API invia una coppia [price, size]. I campi aggiuntivi del book, come depth, vengono mantenuti.

Un book che il client non riesce a leggere viene restituito come null, con orderbook_up_invalid o orderbook_down_invalid impostato a true. Un book null senza il flag era assente. In entrambi i casi il resto dello snapshot viene mantenuto.

Con un true letterale, le righe sono tipizzate come SnapshotWithBooks. Con una variabile booleana il tipo è Snapshot o SnapshotWithBooks.

Errori e retry

I metodi lanciano PolyTestFailure. Per distinguere i casi, controlla error.failure.kind. error.status è lo stato HTTP, mentre error.meta contiene i metadati della risposta, o vale null se non è arrivata alcuna risposta.

TipoQuando
configOpzioni non valide o chiave mancante, prima di qualsiasi richiesta.
networkNon è arrivata alcuna risposta: la connessione non è riuscita o la richiesta è andata in timeout. L’errore originale si trova in error.cause.
unauthorizedHTTP 401. L’API ha rifiutato la chiave.
trial_exhaustedHTTP 402. Uno dei budget della prova si è esaurito. Include dimension e limit.
subscription_inactiveHTTP 403. L’abbonamento non è attivo.
forbiddenHTTP 403. I dati non rientrano nel tuo piano. Include tier.
rate_limitedHTTP 429. Hai superato il rate limit. Include retry_after quando il server lo invia.
concurrency_limitedHTTP 429. Avevi troppe richieste in corso contemporaneamente. Include max_concurrent.
bad_requestHTTP 400, oppure un argomento che il client ha rifiutato prima dell’invio.
not_foundHTTP 404. Il mercato non esiste, oppure non c’è alcuno snapshot vicino a quell’orario.
unavailableHTTP 502 o 503. Può includere retry_after.
serverQualsiasi altro 5xx, oppure il body di una risposta 200 che il client non è riuscito a leggere.
httpQualsiasi altra risposta, compreso un reindirizzamento.

isRetryable(error) restituisce true per rate_limited, concurrency_limited, unavailable e network, per server quando deriva da un HTTP 5xx e per http quando deriva da un 408 o un 425. Tutte le richieste dell’SDK sono GET, quindi ripeterle è sicuro.

retryDelayMs(error) restituisce l’attesa in millisecondi, con un massimo di un’ora. Usa retry_after quando il server lo ha inviato. Per rate_limited senza questo valore, l’attesa dura fino al reset del tuo rate limit. Negli altri casi restituisce null, come succede sempre con concurrency_limited: in quel caso usa un ritardo scelto da te. Nessuna delle due funzioni mette in pausa l’esecuzione.

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)

Annullare una richiesta

Ogni metodo accetta un ultimo argomento facoltativo con un signal, e lo stesso vale per page.next(). Quando il segnale richiede l’interruzione, la chiamata viene rifiutata con signal.reason, come fa fetch. Quel valore non è un PolyTestFailure e per esso isRetryable restituisce false.

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 resta attivo insieme al tuo segnale. Il primo dei due che scatta termina la chiamata, e un timeout lancia un errore network.

Metadati della risposta

Ogni risultato ha meta. Un errore generato da una risposta HTTP riporta lo stesso oggetto in error.meta, così anche un 429 mostra il tuo rate limit.

CampoHeaderContenuto
rate_limitX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Resetlimit, remaining e reset_unix (in secondi). null se i tre header non sono tutti numerici.
trial_remaining_beforeX-Trial-Budget-*-RemainingDurante la prova, quanto restava di requests, records e bytes prima di questa richiesta. Altrimenti null.
server_clampX-Limit-Clampedrequested, applied e max quando il server ha ridotto il tuo limit. Altrimenti 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

Runtime

Il pacchetto è un modulo ES.

ConfigurazioneRequisiti
importNode 20 o versioni successive
require()Node 20.19, oppure Node 22.12 o versioni successive
TypeScript compilato in CommonJSTypeScript 5.8 o versioni successive, con "module": "nodenext"