Motore di esecuzione dei bot
Come i bot girano via cron, paper vs live
Il motore di esecuzione dei bot è il runtime guidato dal cron che esegue concretamente le strategie dei tuoi bot. Capire come funziona ti aiuta a fare il debug di comportamenti inattesi dei bot e a ottimizzarli per le prestazioni.
Architettura
Il motore di esecuzione è un cron job di Vercel che viene eseguito ogni 15 minuti:
- Trigger. Il cron di Vercel raggiunge /api/cron/execute-bots ai minuti 0/15/30/45 di ogni ora.
- Autenticazione. L'endpoint verifica che la richiesta provenga da Vercel utilizzando un token firmato.
- Enumerazione dei bot. Recupera dal database tutti i bot con status="running".
- Dispatch delle strategie. Per ogni bot, carica il template di strategia appropriato (EV Follower, ARB Hunter, ecc.).
- Valutazione del mercato. La strategia esamina lo stato attuale del mercato rispetto ai parametri del bot.
- Inserimento degli ordini. Quando le condizioni corrispondono, il motore invia gli ordini tramite la CLOB API di Polymarket (modalità Live) oppure registra fill simulati (modalità Paper).
- Audit logging. Ogni azione — valutazione, trade, errore — viene registrata nell'audit trail.
Perché 15 minuti?
La scelta di intervalli di 15 minuti bilancia diversi fattori:
- •Rate limit di Polymarket. La CLOB API consente 10 trade al minuto per utente. Su tutti i bot × tutti gli utenti, dobbiamo rimanere al di sotto dei limiti aggregati.
- •Costo. Ogni tick del cron analizza tutti i mercati per tutti i bot. Più frequente = più calcolo = costi più elevati.
- •Rendimenti decrescenti. I prediction market si muovono più lentamente rispetto a crypto o azioni. Una granularità di 5 minuti rispetto a 15 minuti raramente cattura più alpha.
- •Compatibilità con il piano gratuito di Vercel. La nostra pianificazione del cron rientra nei limiti dell'hobby tier di Vercel.
Per gli utenti del piano Bot che desiderano un'esecuzione più rapida, gli ordini TWAP non sono vincolati al cron di 15 minuti — vengono eseguiti su slice al minuto tramite un cron separato.
Limiti Davvero Applicati
I freni del bot agiscono sul DENARO e sulle posizioni aperte, non su un contatore di trade:
- •Per trade: 25 $ di default in automazione, modificabile in Impostazioni → Trading.
- •Per bot, al giorno: 100 $ di default, più un tetto opzionale sul numero di trade che imposti sul bot stesso.
- •Per bot, in contemporanea: 3 posizioni live aperte, e mai due sullo stesso mercato nello stesso giorno.
- •Per profilo, al giorno: un budget totale riservato atomicamente prima di ogni ordine, così due bot non spendono lo stesso dollaro.
Al raggiungimento di un tetto l'ordine viene rifiutato, registrato e segnalato — il bot prosegue invece di ritentare. ## Cosa Succede Quando un Trade Fallisce
L'API del CLOB può fallire per diversi motivi:
- •Errore di rete. La prenotazione di idempotenza resta e l'ordine va in riconciliazione — non viene mai inviato un secondo ordine alla cieca.
- •Saldo insufficiente. Rifiutato prima di raggiungere la venue, registrato e segnalato; il bot non viene messo in pausa per questo.
- •Mercato chiuso. Registrato, e il bot passa all'opportunità successiva.
- •Prezzo spostato. Se il prezzo si è allontanato dal tuo limite, l'ordine non incrocia e il bot ritenta al ciclo successivo.
Un trade fallito non interrompe l'esecuzione: viene registrato e il bot continua. ## Monitorare i tuoi bot
Tre superfici ti dicono cosa stanno facendo i tuoi bot:
- •Performance (piano Bot) — PnL per bot con live e paper separati, tasso di successo, numero di operazioni e le posizioni ancora aperte.
- •Sicurezza → registro di audit — la traccia di ogni azione sensibile dell'account, compreso un ordine reale rifiutato e il motivo (kill switch, tetto giornaliero, piano, regione).
- •Notifiche — esecuzioni ed errori arrivano nell'app e, se hai verificato il canale, su Telegram o WhatsApp. Un bot che tocca la perdita massima si mette in pausa da solo e te lo dice.
Se un bot non ha operato quando te lo aspettavi, il motivo è nel registro di audit. Non esiste un log di skip per ciclo: un ciclo che non trova nulla semplicemente non fa nulla.
Attivare manualmente l'esecuzione
Il pulsante "Execute now" nella pagina Bot (disponibile per gli utenti del piano Bot) ti consente di attivare un ciclo immediato senza attendere il successivo tick del cron. Utile per:
- •Testare modifiche ai parametri senza attendere 15 minuti
- •Catturare segnali time-sensitive che hai identificato manualmente
- •Verificare la connettività dopo la manutenzione della CLOB API
I trigger manuali contano ai fini del tuo rate limit giornaliero. Non abusare di questo pulsante.
Fermare un bot
Tre modi per fermare un bot:
- Pause. Il bot mantiene le posizioni esistenti, non ne apre di nuove. Da usare per brevi pause.
- Stop. Il bot viene completamente disattivato. Le posizioni aperte rimangono; chiudile manualmente.
- Kill switch (globale). Settings → Trading → Kill Switch ferma immediatamente TUTTI i bot e TUTTA l'esecuzione automatizzata. Da usare per le emergenze.
Il kill switch è la scelta giusta se noti un comportamento inatteso — mettilo in pausa per indagare, poi riabilitalo quando sei sicuro.
Audit trail
Ogni azione del bot viene registrata nella tabella bot_audit_logs con:
- •Timestamp
- •ID del bot
- •Tipo di azione (evaluate, place_order, close_order, error)
- •Mercato coinvolto
- •Motivazione della decisione (quale condizione si è attivata o perché è stata saltata)
- •Dettagli dell'ordine (dimensione, prezzo, direzione)
- •Esito (filled, rejected, partial)
Puoi esportare gli audit log in formato CSV dalla pagina di dettaglio del bot. Utile per:
- •Dichiarazione fiscale (è disponibile l'esportazione del Form 8949)
- •Revisione della strategia ("perché il bot ha lasciato passare questo mercato?")
- •Debug quando il comportamento non corrisponde alle aspettative
- •Documentazione di compliance se fai trading a livello professionale
Problemi comuni di esecuzione dei bot
Il bot mostra "running" ma non fa mai trade.
- •Controlla il log degli skip — probabilmente tutti i segnali sono al di sotto della tua soglia di edge minimo.
- •Prova ad abbassare leggermente min_edge, ma non scendere sotto i 5pp.
- •Verifica che i filtri di categoria non siano troppo restrittivi.
Il bot fa troppi trade.
- •Il limite giornaliero di trade è troppo alto.
- •L'edge minimo è troppo basso — stai catturando rumore.
- •Aggiungi filtri ulteriori (confidence minima, volume minimo).
Il bot opera solo su una piattaforma.
- •Controlla il toggle Polymarket vs Kalshi nella configurazione del bot.
- •Verifica che l'indicatore di stato dell'altra piattaforma sia verde.
Un bot Live ha smesso improvvisamente di fare trade.
- •Controlla lo stato della CLOB API (potrebbe essere offline).
- •Controlla che le tue credenziali della CLOB API non siano scadute.
- •Controlla che il tuo wallet Polymarket abbia saldo in USDC.