Tutorial sui bot di Polymarket · Capitolo 30 di 32
Codice di gestione del rischio di livello produzione per Polymarket bot: tetto di posizione, limite di perdita giornaliero, halt sentinel, fill-rate watchdog, reconcile-on-restart, retry idempotenti. Pattern di codice da un vero trader in produzione.
Cosa copre questo capitolo
Il codice di rischio è la maggior parte di un trading bot di produzione. La logica di strategia è la parte facile; i tetti, gli halt, i watchdog e i reconciler che la circondano sono ciò che determina se il bot sopravvive alla sua prima settimana negativa. Questo capitolo è il pattern di rischio di livello produzione.
Questo è il capitolo 30 della nostra serie in 32 parti su come costruire un Polymarket trading bot. Trattiamo l’argomento in profondità nelle sezioni qui sotto. Il corpo di ogni sezione viene scritto e pubblicato capitolo per capitolo; le risposte della FAQ e i riferimenti sono già completi e riflettono l’esperienza di produzione maturata gestendo il nostro trader.
- Perché il codice di rischio è la parte più importante di un vero trading bot
- Tetto di posizione (per mercato, per strategia, totale)
- Kill switch per perdita giornaliera
- Halt sentinel (arresto di emergenza basato su file)
- Fill-rate watchdog
- Riconciliazione del diario vs on-chain al riavvio
- Codice: loop di livello produzione con consapevolezza degli halt
Perché il codice di rischio è la parte più importante di un vero trading bot
Una misurazione che abbiamo fatto sul codebase del nostro bot: il 60% delle LOC è codice di rischio (tetti, halt, watchdog, riconciliazione). Il 30% è strategia. Il 10% è codice di collegamento.
Quel rapporto è corretto. La strategia è la parte facile - descrivere quando entrare e quando uscire sta in poche decine di righe. Il codice di rischio è tutto il resto: cosa fare quando il prezzo si muove contro di te più velocemente del previsto, cosa fare quando i fill smettono di arrivare, cosa fare quando il WebSocket cade, cosa fare quando la strategia si rivela non profittevole.
Le storie di fallimento degli sviluppatori hanno quasi sempre la stessa forma: la strategia funzionava, ma il bot ha continuato a tradare durante un cambio di regime perché non è scattato nessun halt. Scrivi gli halt prima di scrivere la strategia.
Tetto di posizione (per mercato, per strategia, totale)
Tre tetti, applicati nel codice.
- Tetto per mercato: massimo $X per mercato indipendentemente dalla fiducia nel vantaggio. Tipico: $25-100 per bot piccoli, $200-500 per la produzione. Limita il raggio d’impatto di una singola chiamata errata su un mercato.
- Tetto per strategia: se esegui più strategie, ciascuna riceve una quota del capitale totale. Tipico: 30-50% per strategia. Impedisce che una giornata storta di una strategia consumi il capitale delle altre.
- Tetto totale: massima % del saldo wallet impiegata simultaneamente. Tipico: 50-70%. Lascia capitale per opportunità inattese o per intercettare i bug di contabilità del bot stesso.
Tutti e tre i tetti devono essere applicati dentro la funzione di piazzamento degli ordini, non solo nella logica della strategia. La strategia può avere un bug; il gate di piazzamento degli ordini è l’ultima linea di difesa.
Kill switch per perdita giornaliera
Il singolo controllo di rischio più importante: un kill switch per perdita giornaliera.
Regola: se il PnL realizzato + non realizzato da mezzanotte UTC scende sotto -X% del saldo giornaliero iniziale, il bot smette di aprire nuove posizioni e, opzionalmente, chiude quelle esistenti. X tipico: 5-10%.
La matematica: un bot con win rate atteso del 60% ha forse una probabilità del 5% di una serie perdente di 10 trade. Senza kill switch, quella serie si compone: perdita di $200 → il bot continua a tradare → un’altra perdita di $200 → wallet a -40%. Con lo switch che scatta a -10%, la giornata negativa si ferma a $200, e domani il bot riparte da zero.
Lo switch viene applicato lato server: scrivi un file di halt o imposta un flag in database che il trading loop controlla a ogni iterazione. Riavvia solo dopo una revisione manuale.
Halt sentinel (arresto di emergenza basato su file)
Il meccanismo di halt più semplice possibile: il bot controlla la presenza di un file (per esempio /opt/pmt/HALT) a ogni iterazione del loop e smette di tradare se il file esiste.
def trading_loop():
while True:
if os.path.exists("/opt/pmt/HALT"):
log("HALT file detected, sleeping")
time.sleep(30)
continue
run_one_iteration()
time.sleep(5)Per fermare immediatamente da qualsiasi punto (SSH, Telegram bot, sistema di monitoraggio): touch /opt/pmt/HALT. Per riprendere: rm /opt/pmt/HALT.
L’approccio basato su file è volutamente essenziale perché funziona in condizioni in cui meccanismi di halt più sofisticati falliscono: quando il bot è parzialmente crashato, quando il database non è raggiungibile, quando la API key è soggetta a rate limit. L’accesso al filesystem è sempre disponibile.
Fill-rate watchdog
La strategia assume che gli ordini FOK vengano filled a un certo tasso (spesso 60-80%). Quando il tasso scende in modo significativo, qualcosa è cambiato: i market maker si sono ritirati, la tua strategia è stata identificata, c’è un’interruzione dell’API in corso. Qualunque sia il motivo, l’assunzione che guidava la matematica del PnL della strategia è rotta.
Logica del watchdog: conteggio mobile del fill-rate nelle ultime 24 ore. Se < 30% (o 50% dell’atteso), avviso + auto-halt. Riprendi solo dopo una revisione manuale.
Il watchdog è utile anche come diagnostica. Un calo improvviso del fill-rate di solito è correlato a un evento esterno (deploy di Polymarket, congestione di Polygon, il tuo IP che viene rate-limited) che vorresti comunque conoscere, indipendentemente dall’impatto sul trading.
Riconciliazione del diario vs on-chain al riavvio
Il bot mantiene un diario delle posizioni che pensa di detenere. La chain mantiene la verità. Dovrebbero sempre coincidere; quando non coincidono, il bot sta operando con una convinzione errata e tradarà in modo sbagliato.
Logica di riconciliazione: a ogni riavvio e una volta all’ora durante il normale funzionamento, recupera i saldi on-chain per ogni token che il bot ha toccato. Confrontali con il diario; avviso + halt se il saldo di un token differisce dal diario oltre la tolleranza di arrotondamento.
La causa più comune della divergenza è un ordine riuscito che la chiamata API del bot si è persa (timeout, retry mai registrato). La chain ha la posizione; il bot pensa di no. Senza riconciliazione, il bot non pubblicherà l’uscita take-profit e la posizione andrà fino alla risoluzione.
Codice: loop di livello produzione con consapevolezza degli halt
Riferimento: il trading loop di produzione con tutti i controlli di rischio collegati.
def production_loop():
while True:
# Halt checks
if os.path.exists("/opt/pmt/HALT"):
sleep_with_log(30); continue
if daily_pnl_below_threshold():
create_halt("daily PnL kill"); continue
# Reconcile every hour
if now() - last_reconcile > 3600:
ok = reconcile_diary_vs_chain()
last_reconcile = now()
if not ok: create_halt("reconciliation failed"); continue
# Fill-rate watchdog
if recent_fill_rate() < 0.30:
create_halt("fill rate collapse"); continue
# Strategy
try:
run_strategy_once()
except Exception as e:
log_exception(e)
if consecutive_exceptions >= 5:
create_halt(f"exceptions: {e}"); continue
time.sleep(5)Il pattern: ogni iterazione passa attraverso il gate. I bug della strategia non possono bypassare i controlli, per costruzione.
