Costruire un bot per Polymarket: scanner, sizing, esecuzione, monitoraggio

Questa guida mostra come costruire un bot per Polymarket che scansiona continuamente i mercati, dimensiona le opportunità, esegue tramite il CLOB e monitora le prestazioni. Si concentra sull'architettura e sui pattern per sviluppatori che puoi implementare usando le API pubbliche di Polymarket e il modello del Relayer.

Punti chiave

• Architettare il bot come quattro servizi indipendenti: scanner, sizer, executor e monitor.
• Usare le API Gamma e CLOB di Polymarket per listing e invio ordini; WebSocket per aggiornamenti realtime del book.
• Preferire ordini di mercato FAK per esecuzioni a velocità arbitraria ma tenere sempre conto di slippage e commissioni.
• Strumentare il monitoraggio e interruttori rapidi per dispute oracle, ritardi di settlement o fill inattesi.

Perché questa struttura

I sistemi di trading sono più facili da ragionare quando le responsabilità sono separate. Uno scanner trova edge candidati, uno sizer converte l'edge in una posizione, un executor piazza ordini tramite il CLOB e un monitor assicura correttezza e sicurezza. Questa separazione ti permette di scalare, testare e ragionare su latenza e rischio in modo indipendente.

H2: Data sources and APIs

Inizia collegando questi endpoint Polymarket ai tuoi servizi:

• Gamma (metadata di mercato): https://gamma-api.polymarket.com — markets, events, tags, series. Usa la paginazione con after_cursor; evita offset.
• CLOB (order book e trading): https://clob.polymarket.com — le letture dell'orderbook sono pubbliche; il trading richiede API key + HMAC. Gli SDK CLOB gestiscono l'invio ordini.
• Market WebSocket (book in realtime): wss://ws-subscriptions-clob.polymarket.com/ws/market — sottoscrivi per book, price_change, best_bid_ask e tick_size_change. PING ogni 10s.
• Data API (posizioni, open interest): https://data-api.polymarket.com per analytics post-trade.

Nota di design: combina i listing di Gamma con il feed WebSocket per uno scanning live efficiente. Rispetta i limiti di rate di Gamma (es. il /markets ha cap) e i requisiti di chiavi CLOB per il piazzamento ordini.

H2: Scanner — trovare opportunità candidate

Funzione

Lo scanner scopre opportunità che corrispondono alla tua strategia: spread intra-market binari, somme multi-outcome o pattern endgame. Deve essere stateless, scalabile orizzontalmente e concentrato sul calcolo degli edge grezzi.

Input e cadenza

• Sottoscrivi il Market WebSocket con custom_feature_enabled: true per ricevere best_bid_ask e cambi di tick.
• Backfilla con Gamma /markets quando incontri per la prima volta uno strumento per ottenere metadata e outcome.
• Mantieni una piccola vista in memoria di best ask/bid per ogni outcome.

Calcolo dell'edge

• Binary intra-market: calcola edge = 1.00 - (bestAsk(YES) + bestAsk(NO)). Un edge positivo è un candidato.
• Multi-outcome: edge = 1.00 - sum(bestAsk(outcomes)).

Soglie e filtri

• Soglia minima di edge (es. > configurati centesimi) per coprire commissioni taker e rischio di esecuzione.
• Controlli di liquidità minima: la profondità al best ask deve soddisfare la dimensione minima di fill.
• Consapevolezza del tick-size: tenere conto degli eventi tick_size_change — la granularità di prezzo può cambiare a $0.001 vicino agli estremi.

H2: Sizing — rischio e allocazione del capitale

Obiettivi

Il sizing trasforma un edge grezzo in un piano d'ordine: quante azioni comprare per outcome e come suddividerle in ordini per limitare lo slippage.

Componenti

• Limiti di esposizione: limiti di esposizione in pUSD per mercato e globali.
• Sizing limitato dalla profondità: calcola il volume cumulativo disponibile ai livelli di prezzo successivi sul lato ask; dimensiona solo fino al volume che mantiene lo slippage atteso entro la tolleranza.
• Margine per commissioni: sottrai la commissione taker prevista (variabile, fino all'1.8% in alcune categorie) dall'edge lordo prima di decidere di tradare.

Pattern pratico

• Inizia con fill conservativi: preferisci più ordini FAK piccoli piuttosto che un singolo ordine grande a meno che tu non controlli il book.
• Se compri un set completo tramite i flussi CTF split/merge, includi il costo di split/merge (coperto dal Relayer) e l'eventuale arrotondamento dovuto al tick size.

H2: Executor — piazzare ordini e gestire i fill

Tipi di ordine e vincoli

• Usa l'endpoint trading del CLOB per piazzare ordini: https://clob.polymarket.com. L'SDK CLOB e il Relayer gestiscono il deployment del wallet, le approvazioni e la firma degli ordini.
• Per velocità, usa ordini FAK (Fill-And-Kill) dove appropriato. I FAK eseguono immediatamente o cancellano; aiutano a evitare esposizioni durature ma possono parzializzarsi.

Flow di esecuzione

1. Prepara l'intento di trade: lista di outcome token ids e quantità target restituite dallo sizer.
2. Se esegui un set completo multi-outcome, potresti invece eseguire un CTF split (mint di un set completo) e poi vendere le leg — il Relayer e gli SDK astraggono le operazioni CTF.
3. Invia ordini tramite l'API trading del CLOB con intestazioni di attribuzione appropriate se fai parte del Builder Program.
4. Osserva i fill dal WebSocket last_trade_price e dagli aggiornamenti best_bid_ask o dalle risposte di trade del CLOB.

Sicurezza e riconciliazione

• Traccia i partial fills e cancella il resto o riprezza immediatamente.
• Riconcilia i saldi on-chain CTF (via Data API) dopo i fill per assicurarti di detenere effettivamente i token outcome attesi.
• Implementa chiavi di idempotenza e gestione dei nonce per i retry degli ordini.

H2: Monitoraggio e sicurezza operativa

Cosa monitorare

• Tassi di fill, slippage medio rispetto al previsto, edge realizzato dopo le commissioni.
• Latenza tra update WebSocket e invio ordine.
• Eventi anomali: dispute UMA, tick_size_change, outage della piattaforma.

Allarmi e kill-switch

• Soft kill automatizzato: mettere in pausa il piazzamento di nuovi ordini quando il P&L realizzato netto scende sotto una soglia o quando lo slippage di fill supera i limiti.
• Hard kill: fermare immediatamente tutto il traffico se UMA segnala una disputa per un mercato in cui detieni posizioni, o se il Relayer segnala problemi di settlement.

Log di audit e osservabilità

• Conserva tutti gli intenti d'ordine, gli snapshot grezzi di mercato e i fill eseguiti. Usa questi log per post-mortem e backtesting.
• Etichetta i log con market id, condition_ids e request ids per corrispondere ai record Gamma e CLOB.

H2: Builder Program, credenziali e limiti di rate

Se prevedi di instradare ordini con attribuzione, iscriviti al Builder Program e gestisci le chiavi tramite Polymarket settings. I tier dei Builder controllano i limiti giornalieri del Relayer e le ricompense. Per tradare tramite il CLOB avrai bisogno di API key + HMAC e devi rispettare i limiti di rate e le quote del Relayer.

H2: Rischi comuni e mitigazioni

Non dare mai per scontato che l'edge matematico sia garantito. Rischi da considerare:

• Rischio di risoluzione: le dispute UMA possono mettere in pausa o alterare i payout.
• Slippage e partial fills: i FAK possono parzializzarsi; prevedi esposizione residua.
• Commissioni: le commissioni taker variano per categoria e possono erodere piccoli edge (Geopolitics è senza commissioni).
• Tempi di settlement: tempi di redeem/merge e ritardi di risoluzione dell'oracle possono vincolare capitale.
• Guasti smart-contract o del Relayer: prevedi fallback e alerting umano.

Come questo influenza il tuo trading

Progetta il tuo bot in modo che ogni unità di trade sia piccola, osservabile e reversibile entro i tuoi limiti di rischio. Sizing conservativo, monitoraggio rapido e condizioni di kill chiare riducono il rischio di coda. Usa gli endpoint Gamma e CLOB per stato di mercato deterministico e preferisci ordini FAK per esecuzioni rapide, ma misura sempre lo slippage realizzato rispetto alle aspettative.

Chiusura

L'architettura sopra fornisce un blueprint pragmatico per costruire un bot di trading per Polymarket: uno scanner ad alto throughput, uno sizer conservativo, un executor robusto che usa il CLOB e il Relayer, e un monitoraggio stratificato. Parti in piccolo, strumenta in modo aggressivo e iterare su sizing e filtri man mano che accumuli dati live.

Domande frequenti

Quali API devo usare per ottenere listing di mercato e dati del book in realtime?

Usa https://gamma-api.polymarket.com per metadata di mercato (/markets) e wss://ws-subscriptions-clob.polymarket.com/ws/market per order book realtime e eventi best_bid_ask. Usa https://clob.polymarket.com per letture dell'order-book e trading; le letture sono pubbliche ma il trading richiede API key + HMAC.

Dovrei usare limit orders o ordini di mercato (FAK) per l'arbitraggio?

I FAK (Fill-And-Kill) sono comunemente usati per velocità e per evitare esposizione persistente. Possono parzializzarsi, quindi progetta sizing e riconciliazione di conseguenza. L'SDK CLOB espone helper per creare ordini di mercato FAK.

Come conto le commissioni quando dimensiono i trade?

Sottrai le commissioni taker previste dal tuo edge lordo prima di tradare. Le commissioni taker variano per categoria (0% a 1.8% attualmente). Usa una soglia di net-edge che copra commissioni più lo slippage atteso e i buffer di monitoraggio.

Quale monitoraggio è essenziale per un bot live?

Monitora tassi di fill, slippage realizzato, latenza, avvisi di disputa UMA, eventi tick_size_change e lo stato del Relayer. Implementa soft e hard kill-switch per slippage elevato, drawdown di P&L o dispute oracle.

Posso instradare ordini tramite il Builder Program?

Sì. Il Builder Program permette a terze parti di instradare ordini con attribuzione e guadagnare builder fees. I tier controllano i limiti giornalieri del Relayer e le ricompense; le credenziali si ottengono su polymarket.com/settings.