L’API di Polymarket in una mappa: Gamma, CLOB e Data API
Chi inizia perde un giorno sempre sullo stesso problema: Polymarket non ha un’API, ne ha quattro, e l’endpoint che cerchi raramente è su quella che hai provato per prima. Questa è la mappa completa.
La prima cosa da capire sull’API di Polymarket è che non esiste. Ci sono quattro API REST e quattro stream WebSocket, ognuno al servizio di una parte diversa di un’integrazione, ognuno con il proprio hostname, i propri rate limit e i propri requisiti di autenticazione.
Quasi ogni domanda del tipo "l’API di Polymarket non ha X" si rivela essere "X è su un altro host". Ecco l’intera superficie in un solo posto.
Le quattro API REST
| API | URL di base | A cosa serve | Autenticazione |
|---|---|---|---|
| Gamma | gamma-api.polymarket.com | Scoprire eventi e mercati; metadati | Nessuna |
| CLOB | clob.polymarket.com | Prezzi, order book, invio e gestione degli ordini | Nessuna per leggere, L1/L2 per fare trading |
| Data | data-api.polymarket.com | Posizioni, attività, partecipazione ai mercati | Nessuna |
| Relayer | relayer-v2.polymarket.com | Inviare transazioni del wallet senza tenere POL per il gas | Firmata |
La regola di instradamento in 30 secondi
Quali mercati esistono? → Gamma. Qual è il prezzo / voglio fare trading → CLOB. Cosa detiene questo wallet? → Data API. Devo spostare fondi senza gas → Relayer. Se stai cercando un endpoint degli eventi su CLOB, o un order book su Gamma, l’errore è quello.
API Gamma: scoperta e metadati
Gamma è il punto di partenza. Risponde a cosa esiste: eventi, i mercati al loro interno, tag, ricerca e i metadati che ti servono per lavorare con tutto il resto, in particolare i token ID richiesti da ogni endpoint del CLOB.
/events: elenca gli eventi, con paginazione keyset disponibile/markets: elenca i mercati; ancheby id,by slug,by token/public-search: ricerca tra eventi e mercati/tags,/comments: tassonomia e discussione- Open interest, volume live, principali detentori
/markets ha il limite più stretto della piattaforma
300 req / 10s: 13 volte più stretto del limite generale di Gamma, che è di 4,000 req / 10s. Se stai paginando l’intero elenco dei mercati in un loop, è la prima cosa che si rompe. Metti in cache i metadati dei mercati; cambiano pochissimo durante la vita di un mercato. Tutti i numeri sono nel riferimento ai rate limit.
API CLOB: prezzi, book e ordini
L’order book vero e proprio, e l’unico posto dove puoi fare trading. La lettura è pubblica; il trading richiede credenziali.
| Gruppo | Endpoint | Autenticazione |
|---|---|---|
| Order book | /book, /books, /midpoint, /midpoints, /spread, /spreads | Pubblica |
| Prezzi | /price, /prices, /prices-history, prezzo dell’ultimo trade, /tick-size, fee rate | Pubblica |
| Ordini | POST /order, POST /orders, DELETE /order, /orders, /cancel-all, /cancel-market-orders | L2 + firma del wallet |
| Registro | /trades, /data/orders, /data/trades, /notifications | L2 |
| Autenticazione | /auth/api-key, /auth/api-keys, /auth/derive-api-key | L1 |
| Account | balance allowance (lettura / aggiornamento) | L2 |
Singolare e plurale sono una vera distinzione
Quasi ogni endpoint di dati di mercato del CLOB ha un gemello batch: /book e /books, /price e /prices. Gli endpoint al singolare hanno 1,500 req / 10s e quelli al plurale 500 req / 10s, ma una chiamata al plurale copre molti token, quindi il batching ti dà molti più dati per unità di budget di rate limit. Preferisci /books a un loop di /book praticamente sempre.
Data API: posizioni e attività
Domande di tipo portafoglio: /positions, /closed-positions, /trades, più l’API del PNL utente. Nota che è la più stretta delle tre API principali: un limite generale di 1,000 req / 10s, con /positions e /closed-positions a soli 150 req / 10s ciascuno. È pensata per le dashboard, non per i loop di polling.
I quattro stream WebSocket
Se stai facendo polling di /book a intervalli regolari, smetti: gli stream servono a questo. Il polling è il modo più comune in assoluto per bruciare un budget di rate limit senza alcun beneficio.
| Stream | URL | Trasporta |
|---|---|---|
| CLOB Market | wss://ws-subscriptions-clob.polymarket.com/ws/market | Aggiornamenti pubblici di order book, prezzi e ciclo di vita dei mercati |
| CLOB User | wss://ws-subscriptions-clob.polymarket.com/ws/user | Aggiornamenti autenticati di ordini e trade del tuo account |
| RTDS | wss://ws-live-data.polymarket.com | Prezzi di riferimento pubblici, commenti, attività di trading |
| Sports | wss://sports-api.polymarket.com/ws | Stato e punteggi delle partite in diretta |
Il canale User è quello che molti trascurano. Se il tuo bot fa polling di /data/orders per sapere se il suo ordine è stato eseguito, stai spendendo budget di rate limit per un’informazione che il canale User ti avrebbe inviato nel momento stesso in cui è successo, e con meno latenza.
Autenticazione: L1 e L2
I dati di mercato pubblici non richiedono alcuna credenziale: puoi interrogare Gamma, gli endpoint di lettura del CLOB e la Data API con un semplice curl. Il trading richiede due livelli, e capire quale è quale risolve la maggior parte degli errori di autenticazione.
| Livello | Come funziona | Scopo |
|---|---|---|
| L1 | Il wallet firma un messaggio EIP-712 | Dimostrare il controllo del wallet; creare o derivare le credenziali API |
| L2 | Richieste firmate con le credenziali API usando HMAC-SHA256 | Autenticare le richieste private al CLOB |
L’invio di un ordine usa entrambi: L2 autentica la richiesta e una firma del wallet autorizza l’ordine. I typed data L1 sono un payload ClobAuth su chainId: 137 (Polygon), con l’indirizzo del tuo signer, un timestamp Unix in secondi, un nonce (usa 0 a meno che tu non gestisca più set di credenziali) e la stringa di messaggio fissa.
Ottenere una chiave API
- Firma il payload EIP-712
ClobAuthcon la tua chiave privata Polygon. - Chiama
POST /auth/api-keycon gli header L1 per creare le credenziali. Ricevi una chiave, un secret e una passphrase: tutti e tre sono necessari per L2. - Nelle esecuzioni successive, chiama
GET /auth/derive-api-keyper recuperare le credenziali esistenti invece di crearne di nuove.
I due errori di autenticazione dietro la maggior parte delle richieste di supporto
Credenziali incomplete: L2 richiede la chiave, il secret e la passphrase; averne due su tre produce una richiesta ben formata con una firma non verificabile. Deriva dell’orologio: la firma contiene un timestamp, quindi un container con l’orologio sballato di qualche secondo produce firme che il server rifiuta come non valide. Entrambi si presentano come Unauthorized/Invalid api key, ed è per questo che quel messaggio è così cercato. Vedi il riferimento agli errori.
SDK
Polymarket mantiene SDK unificati per TypeScript e Python che incapsulano tutto quanto sopra con un’interfaccia tipizzata e gestiscono paginazione, forme degli errori e configurazione del wallet. Se parti da zero in uno dei due linguaggi, usali: scrivere a mano la firma EIP-712 e la firma HMAC delle richieste è un modo davvero soggetto a errori di passare un weekend.
Passa direttamente a REST quando il tuo runtime non è coperto da un SDK, quando ti serve un controllo preciso su firma, header, retry o trasporto, o quando ti serve un endpoint che l’SDK non espone ancora. Nota che questi sono gli SDK unificati: se usi un client più vecchio, esiste un percorso di migrazione documentato, e i client vecchi sono la fonte di molti bug da credenziali scadute.
Quanto costa l’API di Polymarket?
Niente. Non esiste un piano a pagamento, una pagina di prezzi dell’API né un abbonamento: le API di Polymarket sono gratuite, con un accesso regolato dai rate limit invece che dalla fatturazione. I dati di mercato pubblici non richiedono nemmeno una chiave.
L’unica cosa che cresce con il denaro sono i limiti di trading per signer, suddivisi in livelli in base al volume a 30 giorni del tuo wallet maker, da Standard con 40 order token/sec fino a Elite con 600; ma si tratta di un’allocazione di throughput, non di una tariffa.
L’unica cosa che nessuna di queste API ti darà
Dopo aver mappato l’intera superficie, la cosa utile da sapere è cosa non c’è: la profondità storica dell’order book.
Ogni endpoint qui sopra fornisce lo stato attuale. /book restituisce il book adesso. /prices-history ti dà i prezzi ma non la profondità, quindi non può dirti a che prezzo saresti stato eseguito. E quando un mercato si risolve, /book restituisce 404. Quello che sopravvive è una serie di prezzi ridotta, circa un punto al minuto, che puoi ottenere con un inizio e una fine espliciti. Nessun piano o livello di rate limit cambia questa situazione.
| Domanda | Si può rispondere con l’API di Polymarket? |
|---|---|
| Com’è il book in questo momento? | Sì: /book |
| Qual era il prezzo ieri? | Sì, circa un punto al minuto, da /prices-history con un inizio e una fine |
| Qual era la profondità ieri alle 14:03:17? | No |
| A che prezzo sarebbe stato eseguito il mio ordine da 500 quote? | No |
| Mostrami un mercato risolto la settimana scorsa | Il suo record e l’esito sì (closed=true). Il suo book no. |
Questo vuoto è il motivo per cui il backtest di una strategia su Polymarket richiede una fonte di dati separata che abbia registrato il book mentre i mercati erano attivi. PolyTest fa esattamente questo per i mercati crypto Up/Down: 240M+ snapshot point-in-time con 8 livelli di profondità per lato, timestamp sotto il secondo e mercati risolti conservati invece che scartati. Un header, JSON pulito e una prova gratuita di 3 giorni:
curl -H "X-API-Key: $POLYTEST_KEY" \
"https://api.polytest.io/api/v1/markets?coin=btc&market_type=5m&limit=20"Il riferimento completo degli endpoint è nella documentazione di PolyTest, oppure inizia una prova gratuita.
Domande frequenti
- Quali sono gli endpoint dell’API di Polymarket?
- Polymarket gestisce quattro API REST: Gamma (gamma-api.polymarket.com) per eventi, mercati e metadati; CLOB (clob.polymarket.com) per prezzi, order book e trading; Data API (data-api.polymarket.com) per posizioni e attività; e Relayer (relayer-v2.polymarket.com) per le transazioni senza gas. Ci sono anche quattro stream WebSocket che coprono il canale pubblico dei mercati, il canale autenticato dell’utente, i dati in tempo reale e lo sport.
- L’API di Polymarket è gratuita?
- Sì. Non c’è un piano a pagamento, un abbonamento né una pagina di prezzi dell’API: l’accesso è regolato dai rate limit invece che dalla fatturazione, e i dati di mercato pubblici non richiedono alcuna chiave API. L’unica cosa che cresce è il livello di throughput di trading per signer, basato sul volume di trading a 30 giorni del tuo wallet, non su un pagamento.
- Come ottengo una chiave API di Polymarket?
- Firma il payload typed-data EIP-712 ClobAuth con la tua chiave privata Polygon, poi chiama POST /auth/api-key con gli header L1 per creare le credenziali. Ricevi una chiave, un secret e una passphrase: servono tutti e tre per firmare le richieste L2. Nelle esecuzioni successive usa GET /auth/derive-api-key per recuperare le credenziali esistenti invece di crearne di nuove. I dati di mercato pubblici non richiedono una chiave.
- Qual è la differenza tra l’API Gamma e l’API CLOB?
- Gamma serve per la scoperta: quali eventi e mercati esistono, i loro metadati e i token ID richiesti dagli altri endpoint. CLOB serve per l’order book: prezzi attuali, profondità del book e invio o cancellazione degli ordini. Se devi trovare un mercato, usa Gamma; se devi prezzarlo o farci trading, usa CLOB.
- Polymarket ha un SDK Python?
- Sì. Polymarket mantiene SDK unificati per TypeScript e Python che coprono tutte e quattro le API REST con un’interfaccia tipizzata e gestiscono paginazione, forme degli errori e configurazione del wallet. Esiste un percorso di migrazione documentato dai client più vecchi. Passare direttamente a REST ha senso quando il tuo runtime non è supportato, ti serve un controllo preciso su firma e retry, o ti serve un endpoint che l’SDK non espone ancora.
- Posso ottenere la profondità storica dell’order book dall’API di Polymarket?
- No. Ogni endpoint di Polymarket fornisce lo stato attuale. L’endpoint /prices-history restituisce una serie di prezzi di circa un punto al minuto senza la profondità sottostante, quindi non può dirti a che prezzo sarebbe stata eseguita una data size, e l’order book di un mercato risolto restituisce 404. Il backtesting richiede snapshot point-in-time registrati mentre i mercati erano attivi, come l’archivio di 240M+ snapshot dei mercati crypto Up/Down di PolyTest.
Ottieni i dati storici che Polymarket non conserva
PolyTest registra i mercati crypto Up/Down di Polymarket mentre sono attivi: 240M+ snapshot con 8 livelli di profondità dell’order book, timestamp sotto il secondo e mercati risolti conservati. Inizia con una prova gratuita di 3 giorni.
Continua a leggere
L’SDK Python di Polymarket nel 2026 (e la migrazione da py-clob-client)
Se il tuo codice importa ancora ClobClient da py_clob_client, è costruito su un pacchetto superato, come la maggior parte del codice Polymarket che un assistente AI scriverà per te. Ecco l’SDK attuale e come fare il passaggio.
WebSocket di Polymarket: dati in tempo reale che non cadono
Fare polling dell’order book è il modo più comune di bruciare un budget di rate limit senza alcun beneficio. Ecco i quattro stream, le opzioni di sottoscrizione che nessuno documenta e il guasto in cui il tuo bot riceve silenzio e lo scambia per calma.
Rate limit dell’API di Polymarket: il riferimento completo
Polymarket pubblica i suoi rate limit su diverse pagine, in due sistemi completamente diversi, usando una finestra di 10 secondi che quasi nessuno si aspetta. Qui c’è tutto in un unico set di tabelle, più cosa succede davvero quando superi un limite.