Come scegliere un’API di dati per Polymarket

Se stai cercando dati storici di Polymarket, hai già sbattuto contro il muro che porta tutti qui: l’API di Polymarket fornisce solo lo stato attuale. Chiedi l’order book di un mercato risolto e ricevi un 404; lo storico dei prezzi che conserva ha circa un punto al minuto, senza nulla sulla profondità. Nessuno dei due è bloccato dietro un piano. Il book semplicemente non c’è.

Quindi ti serve un fornitore che abbia registrato il book mentre i mercati erano attivi. Il problema è che ogni fornitore del settore sbandiera lo stesso numero di punta, ed è quasi il meno informativo che ci sia. Ecco cosa controllare invece.

1. Snapshot per mercato al minuto, non snapshot totali

Il numero totale di snapshot è il dato di punta ovunque, ed è quasi privo di significato. Un totale è solo frequenza di acquisizione × mercati monitorati × tempo di raccolta. Un fornitore con un numero più grande potrebbe avere una risoluzione migliore, oppure potrebbe semplicemente raccogliere dati da più tempo, o contare righe ridondanti su mercati che nessuno scambia.

Quello che ti serve davvero sapere è: sul mercato specifico che mi interessa, quanti snapshot al minuto ottengo? Un mercato a 5 minuti campionato due volte al minuto ti dà dieci punti dati per modellare l’intero ciclo di vita del mercato. Non basta per testare nulla.

# Pull the same market from each provider, then compare density.
snaps = fetch_snapshots(market_id)          # provider-specific call

span_s  = (snaps[-1]["timestamp"] - snaps[0]["timestamp"]) / 1000
per_min = len(snaps) / (span_s / 60)

print(f"{len(snaps)} snapshots over {span_s:.0f}s = {per_min:.1f}/min")

# Gaps matter more than the average. One 90-second hole in a 5-minute
# market means you cannot model the part where it was decided.
gaps = [
    (b["timestamp"] - a["timestamp"]) / 1000
    for a, b in zip(snaps, snaps[1:])
]
print(f"max gap: {max(gaps):.1f}s   median: {sorted(gaps)[len(gaps)//2]:.1f}s")

2. Vera profondità del book, o solo top of book?

È il fattore più determinante per capire se il tuo backtest significa qualcosa, ed è dove il linguaggio del marketing diventa più sfuggente. "Dati dell’order book" può voler dire qualsiasi cosa, dalla scala completa a una singola coppia bid/ask.

Se prevedi di operare con size significative, ti serve la scala. Un ordine da 500 quote su un mercato Up/Down sottile non viene eseguito al primo livello: scorre il book, e la differenza tra il primo livello e il tuo vero prezzo medio di esecuzione è spesso più grande del vantaggio che stai cercando di testare.

def simulate_fill(levels, qty):
    """Walk the ladder. This is what actually happens to your order."""
    filled = cost = 0.0
    for lvl in levels:
        take = min(lvl["size"], qty - filled)
        cost += take * lvl["price"]
        filled += take
        if filled >= qty:
            break
    if filled < qty:
        return None            # Not enough liquidity to fill at all.
    return cost / filled

book = snapshot["orderbook"]["asks"]
print("top of book:", book[0]["price"])
print("true fill  :", simulate_fill(book, 500))
# A gap of 2-3c here on a $1 binary is routine, and it is
# larger than most claimed edges.

3. I mercati risolti vengono davvero conservati?

L’unico motivo per pagare questi dati è che Polymarket li scarta. Quindi verifica che il fornitore li conservi davvero, invece di fare da proxy agli endpoint live con una cache.

Il test richiede un minuto: trova un mercato risolto settimane fa, chiedi i suoi snapshot e verifica di ottenere un percorso dei prezzi completo con la profondità, non solo un record di metadati che dice quale lato ha vinto. Conoscere l’esito non è un dato; ogni strategia che valga la pena testare riguarda il percorso, non la risposta.

4. Finestra storica contro profondità storica

I fornitori vendono lo storico in due forme diverse, e la distinzione conta più del numero di giorni:

• Una finestra mobile: gli ultimi N giorni, con i dati più vecchi che escono dalla finestra. Va bene per tarare la strategia sulle condizioni di mercato attuali.
• Un archivio conservato: tutto dall’inizio della raccolta. Necessario se vuoi testare su regimi di volatilità diversi.

Quale ti serve dipende onestamente dalla tua strategia. Se operi sui mercati a 5 minuti e ritari ogni settimana, 30 giorni bastano e avanzano, e pagarne di più è uno spreco. Se vuoi sapere se il tuo vantaggio è sopravvissuto alle condizioni dell’anno scorso, una finestra mobile non può risponderti a nessun prezzo.

5. Un throughput che puoi davvero usare

I rate limit sembrano un dettaglio finché non esegui il tuo primo backtest reale. Scaricare ogni snapshot di un mese di mercati a 5 minuti su tre monete richiede molte richieste, e un limite di 10 req/sec trasforma un pomeriggio di ricerca in un lavoro notturno.

Contano due numeri, e spesso i fornitori ne pubblicano solo uno: il throughput sostenuto (richieste al minuto) e la capacità di burst (richieste al secondo). Un limite al minuto alto con un burst basso blocca comunque un download in parallelo.

Se scarichi regolarmente storico in blocco, chiedi anche se esiste un percorso di esportazione in blocco. Paginare un milione di snapshot attraverso un endpoint REST è possibile, ma non è lo strumento giusto.

6. Puoi valutarlo prima di pagare?

Non puoi valutare la qualità dei dati da una pagina di marketing. Qualsiasi fornitore sicuro dei propri dati ti lascerà guardarli prima di pagare, con un piano gratuito o una prova, e idealmente con un riferimento API che puoi leggere senza registrarti.

Sii lucido, però, su a cosa serve un piano gratuito o una prova. La nostra è una prova di 3 giorni del piano Builder completo, profondità dell’order book inclusa, così puoi controllare copertura, densità degli snapshot e forma delle risposte prima di impegnarti; ma tre giorni e una finestra di 14 giorni ne fanno uno strumento di valutazione, non un piano per la ricerca. Qualunque sia il fornitore, capisci quali parti si possono davvero provare gratis prima di trarre conclusioni.

7. I tuoi strumenti riescono a leggere la documentazione?

Una considerazione più recente, e che vale la pena verificare perché è invisibile finché non ti morde. Se sviluppi con Cursor, Claude Code o Codex, la capacità del tuo assistente di scrivere un’integrazione corretta dipende dal fatto che possa leggere la documentazione del fornitore.

Alcuni fornitori di dati bloccano i crawler AI in robots.txt: una scelta legittima sui dati di addestramento, ma significa che i modelli non possono vedere la loro documentazione e si inventeranno l’API. Puoi controllare qualsiasi fornitore in circa cinque secondi:

curl -s https://<provider>/robots.txt | grep -iA1 "GPTBot\|ClaudeBot\|Google-Extended"

# "Disallow: /" under those agents means your AI assistant
# cannot read their docs and will guess at the API instead.

Come riferimento, PolyTest permette l’accesso a quei crawler e pubblica llms.txt, llms-full.txt e una specifica OpenAPI. Il test pratico però è più semplice che leggere file di policy: chiedi al tuo assistente di scrivere un’integrazione per ogni fornitore e guarda quale produce codice funzionante.

Quando non dovresti pagare nessuno

Vale la pena dirlo chiaramente, perché vale per noi come per chiunque altro. Non ti serve un fornitore di dati a pagamento se:

• Ti servono solo dati live. L’API pubblica e gli stream WebSocket di Polymarket sono gratuiti, non richiedono autenticazione per i dati di mercato e vanno benissimo. I fornitori di dati storici esistono per lo storico, nient’altro.
• Stai testando l’infrastruttura, non una strategia. Autenticazione, parsing, riconnessioni e gestione dei rate limit si possono esercitare tutti sugli endpoint live gratuiti.
• La tua strategia non dipende dalle esecuzioni. Se studi tassi di base o frequenze di risoluzione, quelle informazioni sopravvivono nei metadati pubblici.
• Sei disposto a registrarli da solo. Far girare un collector sul WebSocket pubblico è un’opzione davvero praticabile. Costa un piccolo server e la disciplina di tenerlo in funzione; il problema è che parti con zero storico e non puoi recuperare il passato, quindi serve solo se inizi ben prima di aver bisogno dei dati.

Il motivo per pagare è ristretto e specifico: vuoi uno storico che non hai registrato, a partire da oggi.

Un test che puoi fare oggi pomeriggio

1. Registrati al piano gratuito o alla prova di ogni fornitore della tua lista.
2. Scegli un mercato (stessa moneta, stesso timeframe, stesso giorno) e scaricalo da ciascuno.
3. Confronta gli snapshot al minuto e il buco massimo. Densità e continuità battono qualsiasi numero di punta.
4. Controlla i livelli del book per snapshot. Se non è una scala, non puoi modellare le esecuzioni.
5. Chiedi un mercato risolto un mese fa e verifica di ottenere un percorso completo, non solo un esito.
6. Esegui lo schema di query realistico più pesante che hai e guarda quale fornitore ti limita per primo.
7. Chiedi al tuo assistente AI di scrivere un’integrazione per ciascuno e guarda quale documentazione riesce davvero a leggere.

Questa sequenza richiede un pomeriggio e ti dice più di qualsiasi tabella comparativa, compresa questa. Se vuoi iniziare dalla nostra, c’è una prova gratuita di 3 giorni, e il riferimento degli endpoint si può leggere senza nemmeno registrarsi.