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.
npm install @polytest/sdk
export POLYTEST_KEY="pt_live_your_key_here"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.
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.
| Opzione | Predefinito | Cosa fa |
|---|---|---|
| key | process.env.POLYTEST_KEY | La tua chiave API, inviata come X-API-Key. Gli spazi e le tabulazioni all’inizio e alla fine vengono rimossi. |
| origin | https://api.polytest.io | Dove vengono inviate le richieste. Deve usare https (o http su localhost) e non può includere un percorso. |
| fetch | globalThis.fetch | Una funzione fetch personalizzata. Il timeout si applica comunque, anche se la funzione ignora il proprio segnale di interruzione. |
| timeoutMs | 30000 | Tempo massimo per ogni richiesta in millisecondi, body incluso. Una chiamata che lo supera lancia un errore network. null disattiva il limite. |
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).
| Metodo | Campi | Restituisce |
|---|---|---|
| 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 | slug | Un 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_typepuò essere5m,15m,1hr,4hro24hr. L’elenco è esportato comeMARKET_TYPES.- Scrivi
coinin minuscolo, ad esempiobtc,ethosol. Se lo ometti, il server restituisce i mercatibtc. start_time,end_timeetimestampaccettano il formato ISO 8601. Un orario senza fuso orario viene interpretato come UTC, e al posto dellaTsi può usare uno spazio.- Gli argomenti vengono controllati prima della richiesta: se uno non è valido viene lanciato un errore
bad_requeste non viene inviato nulla. Per saltare un campo facoltativo omettilo:nulllancia 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.
| stop | Significato | next() |
|---|---|---|
| more | Segue un’altra pagina a partire da nextOffset. | Recupera la pagina successiva. |
| end | Questa è l’ultima pagina. | Restituisce null senza fare richieste. |
| tier_window | Hai raggiunto la fine dei dati inclusi nel tuo piano. | Restituisce null senza fare richieste. |
| snapshot_offset_cap | La paginazione ha raggiunto il limite di offset degli snapshot, pari a 100000. | Restituisce null senza fare richieste. |
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.
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.
| Tipo | Quando |
|---|---|
| config | Opzioni non valide o chiave mancante, prima di qualsiasi richiesta. |
| network | Non è arrivata alcuna risposta: la connessione non è riuscita o la richiesta è andata in timeout. L’errore originale si trova in error.cause. |
| unauthorized | HTTP 401. L’API ha rifiutato la chiave. |
| trial_exhausted | HTTP 402. Uno dei budget della prova si è esaurito. Include dimension e limit. |
| subscription_inactive | HTTP 403. L’abbonamento non è attivo. |
| forbidden | HTTP 403. I dati non rientrano nel tuo piano. Include tier. |
| rate_limited | HTTP 429. Hai superato il rate limit. Include retry_after quando il server lo invia. |
| concurrency_limited | HTTP 429. Avevi troppe richieste in corso contemporaneamente. Include max_concurrent. |
| bad_request | HTTP 400, oppure un argomento che il client ha rifiutato prima dell’invio. |
| not_found | HTTP 404. Il mercato non esiste, oppure non c’è alcuno snapshot vicino a quell’orario. |
| unavailable | HTTP 502 o 503. Può includere retry_after. |
| server | Qualsiasi altro 5xx, oppure il body di una risposta 200 che il client non è riuscito a leggere. |
| http | Qualsiasi 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.
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.
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.
| Campo | Header | Contenuto |
|---|---|---|
| rate_limit | X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset | limit, remaining e reset_unix (in secondi). null se i tre header non sono tutti numerici. |
| trial_remaining_before | X-Trial-Budget-*-Remaining | Durante la prova, quanto restava di requests, records e bytes prima di questa richiesta. Altrimenti null. |
| server_clamp | X-Limit-Clamped | requested, applied e max quando il server ha ridotto il tuo limit. Altrimenti 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 limitRuntime
Il pacchetto è un modulo ES.
| Configurazione | Requisiti |
|---|---|
| import | Node 20 o versioni successive |
| require() | Node 20.19, oppure Node 22.12 o versioni successive |
| TypeScript compilato in CommonJS | TypeScript 5.8 o versioni successive, con "module": "nodenext" |