L'API di Polymarket in parole semplici

Polymarket espone tre API HTTP pubbliche. Gamma, su gamma-api.polymarket.com, elenca eventi e mercati. CLOB, su clob.polymarket.com, serve book degli ordini, prezzi e storico dei prezzi. Data, su data-api.polymarket.com, serve operazioni e posizioni. Tutti gli endpoint di lettura delle tre API funzionano senza autenticazione. Solo operare richiede credenziali e un wallet finanziato.

Quale API di Polymarket mi serve?

Scegli in base alla domanda che stai facendo. Se la domanda è "quali mercati esistono e di cosa parlano", è Gamma. Se è "quanto costa adesso questo esito, e quanto costava la settimana scorsa", è CLOB. Se è "chi ha scambiato cosa", è Data. Quasi tutto il lavoro in sola lettura usa Gamma per la scoperta e CLOB per una chiamata di prezzo per token.

La tabella qui sotto viene dal riferimento agent-skills di Polymarket e dalla pagina ufficiale dei limiti di frequenza, entrambi verificati il 4 settembre 2026.

API	URL di base	Autenticazione per le letture	Percorsi principali	Limite di lettura
Gamma	https://gamma-api.polymarket.com	No	/events, /markets, /tags, /sports, /public-search	4.000 richieste per 10s in generale, 500 su /events, 300 su /markets
CLOB	https://clob.polymarket.com	No	/book, /price, /midpoint, /spreads, /prices-history	9.000 richieste per 10s in generale, 1.500 su /book, /price e /midpoint
Data	https://data-api.polymarket.com	No	/trades, /positions, /closed-positions	1.000 richieste per 10s in generale, 200 su /trades, 150 su /positions

Fonti: Polymarket agent-skills, market-data.md e limiti di frequenza di Polymarket, entrambi consultati il 4 settembre 2026.

Come si leggono i mercati senza autenticazione?

Con una GET semplice a Gamma. Niente chiave, niente header, niente account. GET https://gamma-api.polymarket.com/events?active=true&closed=false&limit=100 restituisce gli eventi aperti. GET https://gamma-api.polymarket.com/events?slug=which-party-will-win-the-house-in-2026 restituisce un evento dal suo slug, la stessa stringa che compare nell'URL di Polymarket. I mercati funzionano allo stesso modo su /markets?slug=....

Tre parametri fanno quasi tutto il lavoro. limit accetta da 1 a 500 e vale 20 per impostazione predefinita. offset pagina i risultati. order ordina per volume_24hr, volume, liquidity, start_date, end_date, competitive o closed_time, con ascending che ne inverte la direzione. Per sfogliare una categoria, chiama prima GET /tags e poi filtra con tag_id.

Un evento è un contenitore. Un mercato è una singola domanda Sì o No al suo interno. "Quale partito vincerà la Camera nel 2026?" è un evento; "Il Partito Democratico controllerà la Camera dopo le elezioni di metà mandato del 2026?" è un mercato dentro quell'evento. Il codice che tratta le due cose come una sola si rompe al primo evento a più esiti che incontra.

Cosa significano i prezzi?

Un prezzo di Polymarket è un numero tra 0 e 1 che si legge direttamente come probabilità. Un mercato a 0,895 è la folla che dice 89,5 per cento. Gamma restituisce outcomePrices come array allineato con outcomes, più lastTradePrice, bestBid e bestAsk su ogni mercato.

Ecco una risposta reale, dall'evento Gamma which-party-will-win-the-house-in-2026, recuperata il 4 settembre 2026:

{
  "question": "Will the Democratic Party control the House after the 2026 Midterm elections?",
  "outcomes": ["Yes", "No"],
  "outcomePrices": ["0.895", "0.105"],
  "lastTradePrice": 0.9,
  "bestBid": 0.89,
  "bestAsk": 0.9,
  "volume": 5723307.96
}

Per qualsiasi cosa sensibile al tempo, usa CLOB invece di Gamma. GET /price?token_id=TOKEN_ID&side=BUY restituisce la migliore proposta in vendita, GET /midpoint?token_id=TOKEN_ID restituisce il punto medio tra migliore acquisto e migliore vendita, e GET /book?token_id=TOKEN_ID restituisce il book completo. Esistono versioni multiple come richieste POST su /prices, /midpoints, /spreads e /books, che accettano fino a 500 token per chiamata.

L'identificatore che conta qui è il tokenID, il token ERC1155 dell'esito. Ogni mercato ha un token per esito. Il conditionID identifica il mercato on chain, e questionID è l'hash dei dati ausiliari UMA che decidono l'esito. Un flag neg_risk segnala i mercati che appartengono a un gruppo a più esiti mutuamente esclusivi.

Come si ottengono i prezzi storici?

Con l'endpoint di storico prezzi del CLOB, /prices-history, indicizzato per token id. Accetta un intervallo (1h, 6h, 1d, 1w, 1m, max) oppure un intervallo assoluto con timestamp di inizio e fine, e restituisce voci nella forma {t: timestamp, p: prezzo}. Il suo limite di lettura è 1.000 richieste per 10 secondi, abbastanza generoso da rendere il recupero di qualche centinaio di mercati una questione di minuti, non di giorni.

Due note pratiche. Lo storico è per token, non per mercato, quindi un mercato Sì o No richiede due chiamate se vuoi entrambi i lati, e il secondo è quasi esattamente uno meno il primo. E la serie è un prezzo campionato, non un nastro delle operazioni. Se ti servono le esecuzioni vere, quelle stanno nell'API Data su /trades.

Come funziona la risoluzione?

Un mercato Polymarket paga sull'esito deciso dall'oracolo ottimistico di UMA, non da personale di Polymarket che sceglie una risposta. Il questionID di ogni mercato è l'hash dei dati ausiliari che l'oracolo legge, ed è per questo che il testo esatto della risoluzione conta così tanto. Due mercati con titoli quasi identici possono risolversi in modo diverso perché le loro regole scritte differiscono su una data o su una fonte.

Per un bot la conseguenza pratica è semplice. Leggi la descrizione del mercato, non il titolo. Un mercato il cui titolo dice "La Fed taglia i tassi a ottobre" può risolversi su una dichiarazione precisa del FOMC pubblicata in una data precisa, e un titolo di giornale che sembra un taglio può non esserlo secondo quella regola.

Quali sono i limiti di frequenza?

Polymarket pubblica limiti per endpoint e li fa rispettare rallentando. Le richieste oltre la soglia vengono ritardate e messe in coda invece che rifiutate subito, il che vuol dire che un ciclo scritto male degenera in lentezza invece che in un pulito 429. Al 4 settembre 2026 i limiti pubblicati includono un tetto generale di 15.000 richieste per 10 secondi, 4.000 per 10 secondi su Gamma, 9.000 per 10 secondi su CLOB e 1.000 per 10 secondi sull'API Data (limiti di frequenza di Polymarket).

Gli endpoint di negoziazione hanno sia un limite di picco sia uno sostenuto. POST /order è indicato a 5.000 richieste per 10 secondi di picco e 120.000 per 10 minuti sostenute. Un'integrazione in sola lettura non si avvicinerà mai a nessuno di questi numeri.

Quale libreria client conviene usare?

Gli SDK unificati. Al 4 settembre 2026 i repository py-clob-client e clob-client risultano archiviati su GitHub, entrambi con ultimo push il 25 maggio 2026, e il README Python dichiara che il client non è più funzionante e non va usato per integrazioni nuove o esistenti (Polymarket/py-clob-client). I sostituti sono py-sdk, che si installa con pip install polymarket-client, e ts-sdk (Polymarket/py-sdk).

Se ti servono solo letture, non ti serve nessuna libreria. Tre richieste GET con requests o fetch coprono scoperta, prezzo e storico. Una dipendenza che non aggiungi è una dipendenza che non può essere archiviata sotto i tuoi piedi.

Un esempio Python in sola lettura

import requests

GAMMA = "https://gamma-api.polymarket.com"
CLOB = "https://clob.polymarket.com"

# 1. Venti eventi aperti, dai piu' attivi.
events = requests.get(
    f"{GAMMA}/events",
    params={"active": "true", "closed": "false", "limit": 20,
            "order": "volume_24hr", "ascending": "false"},
    timeout=20,
).json()

for event in events:
    print(event["title"])
    for market in event.get("markets", []):
        # outcomePrices e clobTokenIds arrivano come stringhe JSON.
        prices = market.get("outcomePrices")
        print("   ", market["question"], prices)

# 2. Punto medio in tempo reale per un token di esito.
token_id = "REPLACE_WITH_A_CLOB_TOKEN_ID"
mid = requests.get(f"{CLOB}/midpoint", params={"token_id": token_id}, timeout=20).json()
print("midpoint:", mid)

L'output atteso è una riga per evento, poi una riga rientrata per mercato con i prezzi degli esiti come stringhe, poi un singolo dizionario tipo {'mid': '0.895'}. Attenzione alla codifica: Gamma restituisce outcomePrices e clobTokenIds come stringhe JSON dentro il JSON, quindi vanno interpretate una seconda volta prima dell'uso.

Casi di errore da gestire prima di mettere tutto in schedulazione: un evento con zero mercati, un mercato il cui outcomePrices manca perché non ha ancora scambiato, uno slug che non esiste più dopo che Polymarket ha rinominato un evento, e il rallentamento che si presenta come risposta lenta invece che come errore.

Dove tutto questo si rompe

I blocchi nazionali sono il primo muro, ed è il muro che riguarda direttamente chi sviluppa dall'Italia. Polymarket è bloccato in Italia dal 27 luglio 2026 per disposizione dell'Agenzia delle Dogane e dei Monopoli, applicata dai provider a livello DNS (Key4biz, 28 luglio 2026). Quel blocco risolve anche i nomi host dell'API verso la pagina di avviso dell'agenzia, quindi una richiesta a gamma-api.polymarket.com da una connessione italiana fallisce con un certificato non corrispondente invece di restituire dati. Non è un caso isolato: nel dicembre 2025 il TAR del Lazio aveva dato ragione alla piattaforma e ADM aveva revocato l'oscuramento, lasciando il sito consultabile ma con le funzioni di scambio disattivate per gli utenti italiani (Italian Gaming News, 21 febbraio 2026). Il Brasile ha bloccato le piattaforme di mercati predittivi a maggio 2026 su una base giuridica diversa. Se il tuo bot gira su un server in un paese bloccato, il problema non è l'API, è la rete.

Il secondo muro è che leggere i prezzi non è la stessa cosa che avere uno storico. L'API di Polymarket ti dice cosa pensa il mercato. Non ti dice cosa pensavi tu, quando lo pensavi, e se avevi ragione. Quello è uno strato separato, ed è quello che trasforma una pipeline di dati in uno storico.

È quello che fa l'API di insiderz. Elenca gli stessi eventi, accetta una call bloccata con l'ora e il prezzo di mercato di quel momento, e valuta la call contro il mercato quando l'evento si risolve. Non si muove denaro. I bot usano gli stessi endpoint, le stesse regole e la stessa classifica delle persone. Se stai costruendo il lato previsione invece del lato trading, leggi poi come costruire un bot di previsione, oppure vai diretto alla versione Python in 100 righe.