WebSocket di Polymarket: dati in tempo reale che non cadono

Se il tuo bot fa polling di GET /book a intervalli regolari, questa pagina ti farà risparmiare gran parte del budget di rate limit e un bel po’ di latenza. Polymarket invia gli aggiornamenti del book via WebSocket, e una sottoscrizione ti costa una connessione invece di migliaia di richieste.

I quattro stream

Sottoscriversi al canale market

Connettiti, poi invia un messaggio di sottoscrizione JSON. assets_ids accetta token ID (gli stessi che ottieni dai metadati del mercato) e type deve essere "market".

{
  "assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
  "type": "market",
  "initial_dump": true,
  "level": 2,
  "custom_feature_enabled": true
}

Mantieni initial_dump: true a meno che tu non abbia un motivo specifico per non farlo. Senza, parti senza alcuno stato del book e devi aspettare gli aggiornamenti incrementali per ricostruirlo, il che significa che il tuo bot inizia la sua vita con un quadro incompleto.

Tipi di messaggio

Ogni messaggio ha un event_type. Gestiscili tutti in modo esaustivo: un tipo non riconosciuto va registrato nei log, non scartato in silenzio, perché è così che scopri che il protocollo è cambiato.

Restare connessi: PING ogni 10 secondi

È il requisito che coglie tutti impreparati. Il client deve inviare un PING ogni 10 secondi; il server risponde PONG. Salta l’heartbeat e la connessione viene chiusa.

Nota la direzione: è un heartbeat del client. Non stai aspettando che sia il server a mandarti un ping. Il keepalive WebSocket integrato in una libreria, a un altro intervallo, non lo sostituisce: invia tu il PING a livello applicativo.

import asyncio, json, time
import websockets

URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"
STALE_AFTER = 30          # seconds without any message = treat as dead


async def stream(token_ids, on_event):
    backoff = 1
    while True:
        try:
            async with websockets.connect(URL) as ws:
                await ws.send(json.dumps({
                    "assets_ids": token_ids,
                    "type": "market",
                    "initial_dump": True,
                    "custom_feature_enabled": True,   # or lose 3 event types
                }))
                backoff = 1                            # reconnected cleanly
                last_msg = time.monotonic()

                async def heartbeat():
                    while True:
                        await asyncio.sleep(10)        # required cadence
                        await ws.send("PING")

                hb = asyncio.create_task(heartbeat())
                try:
                    while True:
                        # Silence is a failure mode, not a quiet market.
                        raw = await asyncio.wait_for(ws.recv(), timeout=STALE_AFTER)
                        last_msg = time.monotonic()
                        if raw == "PONG":
                            continue
                        for msg in json.loads(raw) if raw.startswith("[") else [json.loads(raw)]:
                            on_event(msg)
                finally:
                    hb.cancel()

        except Exception as exc:
            # Reconnect with capped exponential backoff + jitter.
            wait = min(backoff, 30) * (0.5 + 0.5 * asyncio.get_event_loop().time() % 1)
            print(f"ws down ({exc}); reconnecting in {wait:.1f}s")
            await asyncio.sleep(wait)
            backoff = min(backoff * 2, 30)

Cambiare le sottoscrizioni senza riconnettersi

I mercati a cinque minuti scadono di continuo, quindi un bot che segue i "mercati BTC 5m correnti" deve cambiare continuamente il suo insieme di sottoscrizioni. Non devi chiudere la connessione per farlo: il canale market supporta sottoscrizione e annullamento della sottoscrizione su una connessione attiva.

Conta più di quanto sembri. Riconnettersi a ogni rotazione dei mercati significa pagare ripetutamente il costo di apertura della connessione, richiedere di nuovo gli initial dump e creare una finestra in cui non ricevi nulla proprio nel momento in cui si apre un nuovo mercato.

Il guasto che costa soldi

Un WebSocket caduto non genera un’eccezione. Smette di consegnare messaggi. Per un bot ingenuo, "nessun aggiornamento" è indistinguibile da "il mercato non si muove", quindi un bot con una posizione aperta resterà a tempo indeterminato su un prezzo vecchio, convinto che non sia cambiato nulla.

• Tieni traccia dell’età dell’ultimo messaggio. Se su un mercato attivo non arriva nulla da ~30 secondi, sei disconnesso, non in una fase tranquilla. Il timeout di asyncio.wait_for qui sopra fa esattamente questo lavoro.
• Tratta i dati vecchi come una condizione di errore. Smetti di quotare, chiudi le posizioni se le tue regole di rischio lo richiedono e riconnettiti: non continuare a fare trading su un book congelato.
• Usa un backoff con jitter in riconnessione. Un loop di riconnessione stretto durante un disservizio è il modo per farti limitare oltre a essere disconnesso, e una flotta che si riconnette tutta insieme peggiora le cose.
• Risincronizza lo stato dopo la riconnessione. Mentre eri via hai perso degli aggiornamenti. Prendi il nuovo initial_dump come verità e scarta il book precedente, invece di fondere aggiornamenti incrementali in uno snapshot vecchio.
• Riconcilia le posizioni dopo ogni interruzione. Se eri disconnesso dal canale User, potresti aver perso un’esecuzione. Rileggi le posizioni prima di agire su uno stato presunto.

WebSocket e rate limit

Una domanda frequente, e la risposta è il senso di tutto l’esercizio: una sottoscrizione non consuma budget di rate limit per richiesta come fa il polling. I limiti documentati di Polymarket sono limiti HTTP per endpoint, e lo streaming li aggira quasi del tutto.

Continuerai a fare chiamate HTTP (scoperta dei mercati, dimensioni dei tick, invio degli ordini, riconciliazione delle posizioni), e quelle restano soggette ai rate limit documentati. Lo streaming elimina solo la fonte di volume di richieste più grande e meno utile.

Cosa gli stream non ti daranno

Un confine che vale la pena dichiarare chiaramente, perché è la cosa che la gente prova subito dopo. Un WebSocket ti dà il book dal momento in cui ti sottoscrivi. Non può darti il book di martedì scorso.

Polymarket non conserva alcun order book storico. Una volta che un mercato si risolve, il suo book restituisce 404, e prices-history conserva solo circa un punto al minuto. Se vuoi testare una strategia su come i mercati sono stati davvero scambiati, ti servono snapshot registrati da qualcuno all’epoca. PolyTest lo fa per i mercati crypto Up/Down, con 8 livelli di profondità per lato e i mercati risolti conservati. Oppure avvia oggi il tuo collector, accetta di partire con zero storico e aspetta.