L’SDK Python di Polymarket nel 2026 (e la migrazione da py-clob-client)

Conta più di un normale aggiornamento di versione per un motivo: quasi tutti gli esempi di codice per Polymarket su internet sono precedenti. Articoli, risposte su Stack Overflow, esempi su GitHub e, siccome sono stati addestrati su quel materiale, il codice che il tuo assistente AI scrive quando gli chiedi un bot per Polymarket. Se ti sei ritrovato a fare debug di import che non esistono, il motivo è questo.

Cosa è cambiato davvero

Il vecchio approccio ti dava un client per ogni servizio di Polymarket. Importavi un client CLOB per l’order book, chiamavi Gamma via HTTP grezzo per scoprire i mercati, interrogavi la Data API a parte per le posizioni e aggiungevi un pacchetto di builder-signing se ti servivano transazioni tramite relayer. Quattro modelli mentali, quattro forme di errore, quattro stili di paginazione.

L’SDK unificato riunisce tutto in un solo client che copre ogni superficie.

Installazione

pip install polymarket-client
# uv add polymarket-client
# poetry add polymarket-client

Quattro client: scegli con criterio

import asyncio
from polymarket import AsyncPublicClient


async def main() -> None:
    async with AsyncPublicClient() as client:
        pages = client.list_markets(closed=False)
        first = await pages.first_page()
        for market in first.items:
            print(market.slug)


asyncio.run(main())

I dati pubblici non richiedono credenziali, quindi costruisci e testa tutto il possibile con AsyncPublicClient prima di introdurre una chiave. Scoperta dei mercati, parsing, paginazione, generazione dei segnali e backoff si possono esercitare tutti senza rischiare nulla.

Paginazione

Un’unica interfaccia di paginazione per tutti i metodi di elenco. Tre modi di usarla, a seconda che ti interessino o meno i confini delle pagine:

pages = client.list_markets(closed=False, page_size=10)

# 1. Page at a time — use this when you need to control pacing
#    against the tight /markets rate limit (300 req / 10s).
async for page in pages:
    for market in page.items:
        ...

# 2. Item at a time, boundaries ignored.
async for market in pages.iter_items():
    ...

# 3. Manual, resumable.
page = await pages.first_page()
if page.next_cursor:
    nxt = await pages.from_cursor(page.next_cursor).first_page()

Modelli tipizzati

I metodi restituiscono tipi veri invece di dizionari, esportati dal pacchetto principale:

from polymarket import Event, Market, OrderBook, PriceHistoryPoint

È il miglioramento meno vistoso e probabilmente quello di maggior valore. Con i vecchi client, un campo rinominato o mancante emergeva come KeyError in fondo al ciclo della tua strategia, a runtime, spesso in produzione e spesso mentre avevi una posizione aperta. I modelli tipizzati spostano quell’errore dove deve stare.

Sottoscrizioni in tempo reale

subscribe() unisce più feed in un unico stream di eventi tipizzati, un vero miglioramento rispetto a gestire a mano diverse connessioni WebSocket.

from polymarket.streams import MarketSpec, SportsSpec

async with await client.subscribe(
    [MarketSpec(token_ids=[token_id]), SportsSpec()],
) as stream:
    async for event in stream:
        # MarketBookEvent | MarketPriceChangeEvent
        # | MarketLastTradePriceEvent | MarketTickSizeChangeEvent
        # | MarketBestBidAskEvent | NewMarketEvent
        # | MarketResolvedEvent | SportsEvent
        handle(event)

L’SDK gestisce l’heartbeat, il framing e le riconnessioni che altrimenti implementeresti tu, compreso l’obbligo di inviare PING ogni 10 secondi su una connessione grezza. I dettagli sono nella guida ai WebSocket.

Piazzare un ordine

market = await client.get_market(slug="<market-slug>")
token_id = market.outcomes.yes.token_id
assert token_id is not None

response = await client.place_market_order(
    token_id=token_id,
    side="BUY",
    amount="10",     # pUSD to spend, not shares to buy
)

if not response.ok:
    raise RuntimeError(response.message)

# Settlement is on-chain and asynchronous.
hashes = await client.wait_for_order_fill_settlement(response)

# Reconcile rather than assuming.
page = await client.list_positions(market=[market.condition_id]).first_page()
position = next((p for p in page.items if p.token_id == token_id), None)

Migrare da py-clob-client

1. Fai l’inventario di ogni chiamata a Polymarket, comprese le chiamate requests grezze a Gamma e alla Data API. Rientrano anche quelle: l’SDK unificato le copre, e integrarle è gran parte del vantaggio.
2. Installa polymarket-client e rimuovi i vecchi pacchetti. Tenerli entrambi installati per migrare gradualmente invita a importare il simbolo client sbagliato.
3. Sostituisci la costruzione del client. Un solo AsyncSecureClient.create(...) sostituisce i vecchi client per servizio e la loro gestione separata delle credenziali.
4. Sostituisci l’accesso ai dizionari con l’accesso agli attributi. market["condition_id"] diventa market.condition_id. È noioso, ed è lì che il type checker inizia a ripagarsi.
5. Riscrivi la paginazione con l’interfaccia del paginatore invece dei loop manuali su offset o cursori.
6. Sostituisci il codice WebSocket scritto a mano con subscribe() ed elimina la tua logica di heartbeat e riconnessione.
7. Riesegui prima i percorsi in sola lettura, con il client pubblico, prima di lasciare che qualcosa piazzi un ordine.

Perché il tuo assistente AI sbaglia

Vale la pena affrontarlo direttamente, perché è così che molte persone arrivano qui. Chiedi a un LLM del codice Python per Polymarket e molto spesso otterrai import di py_clob_client, costruzioni di ClobClient(...) e oggetti OrderArgs. Il modello non è guasto: sta riproducendo la stragrande maggioranza del codice Polymarket che ha visto, che è precedente agli SDK unificati.

• Controlla prima la riga di import. from polymarket import ... è attuale; from py_clob_client... no.
• Incolla la documentazione attuale nel contesto. Polymarket pubblica Markdown leggibile dalle macchine su docs.polymarket.com/llms.txt, e ogni pagina ha una variante .md. Dare al modello quella vera funziona meglio che discuterci.
• Diffida del codice sicuro di sé che non gira. Il codice generato mescola spesso API vecchie e nuove in qualcosa che non è mai esistito.

Lo stesso problema vale per i fornitori di dati. Pubblichiamo llms.txt, llms-full.txt e una specifica OpenAPI, e permettiamo l’accesso ai crawler AI, proprio perché gli assistenti possano scrivere integrazioni PolyTest corrette senza tirare a indovinare. Alcuni fornitori bloccano quei crawler, una scelta legittima che però significa che il tuo assistente improvviserà la loro API.

Cosa l’SDK non può ancora fare

L’SDK unificato è un’interfaccia molto migliore verso le API di Polymarket. Non cambia ciò che quelle API contengono, e la cosa che chi costruisce bot vuole più spesso non c’è.

Non esiste un order book storico. client.get_market() restituisce i metadati di un mercato risolto, ma il suo book è sparito: /book restituisce 404 e prices-history conserva solo circa un punto al minuto. Nessun metodo dell’SDK, piano o credenziale recupera il book.

Per il backtesting ti servono snapshot registrati mentre i mercati erano attivi. PolyTest li fornisce per i mercati crypto Up/Down: 240M+ snapshot point-in-time, 8 livelli di profondità per lato, timestamp sotto il secondo, mercati risolti conservati. È una semplice API REST con un header X-API-Key, quindi si inserisce nello stesso codice async accanto all’SDK. Inizia gratis, oppure leggi come costruire un bot per il percorso completo.