Polymarket Bot Tutorial · Capitolo 10 di 32

Spiegazione dei tipi di order di Polymarket per chi costruisce bot: Fill-or-Kill (FOK), Fill-and-Kill (FAK), Good-til-Cancelled (GTC) e i compromessi limit-vs-market. Con decision rules di livello production.

Di Harley Young, redattrice principale di Polymarkets.co.il. Ultima revisione: maggio 2026.

Cosa copre questo capitolo

La confusione sui order type è la classe di bug più costosa per i nuovi bot builders. Inviare FOK quando serviva GTC produce ingressi mancati; inviare GTC quando serviva FOK lascia order in resting che si riempiono ore dopo a prezzi pessimi. Questo capitolo è il decision tree e i default di produzione che hanno retto su migliaia di order.

Questo è il capitolo 10 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 rilasciato capitolo per capitolo; le risposte FAQ e i riferimenti sono già completi e riflettono l’esperienza di produzione derivata dal nostro trader.

  • Quick decision tree
  • FOK: quando devi fillare o saltare
  • FAK: quando i partial sono accettabili
  • GTC: quando vuoi restare sul book
  • Limit vs market e la spread tax
  • I nostri default di produzione (FOK buys, GTC sells]
  • Code: inserire ogni tipo di order

Quick decision tree

Tre domande decidono ogni order placement.

  1. Hai bisogno di un fill garantito subito, e per niente se non puoi ottenerlo ora? → FOK.
  2. Vuoi il massimo fill possibile subito, accetti i partial, senza order in resting? → FAK.
  3. Vuoi restare sul book al tuo prezzo e aspettare che qualcuno venga da te? → GTC.

Tutto qui. La maggior parte dei bug dei bot legati ai order type nasce dal scegliere #1 quando volevi #3 (un "buy" si trasforma in "no position perché lo spread era troppo largo") oppure dal scegliere #3 quando volevi #1 (un "buy" si trasforma in un order in resting che si filla ore dopo nel momento sbagliato).

FOK: quando devi fillare o saltare

Fill-or-Kill abbina l’intero order al prezzo richiesto o migliore, istantaneamente. Se l’intera size non può essere fillata subito, l’order viene rifiutato e non succede nulla. Nessun resting, nessun partial.

Usa FOK per: news-arbitrage entries (vuoi entrare solo al prezzo della news, non dove sarà il mercato tra 30s); take-profit exits a un target specifico dove i partial renderebbero confusa la contabilità; ogni volta che la strategia presuppone execution atomica.

Il trade-off: FOK viene rifiutato più spesso degli altri order type, soprattutto su book illiquidi. Avere sempre un fallback path — rivaluta la strategy condition e ritenta se è ancora valida, oppure passa oltre.

FAK: quando i partial sono accettabili

Fill-and-Kill (chiamato anche "immediate or cancel") abbina subito quanto più può, poi cancella il resto non fillato. Puoi ottenere la size completa, un partial oppure zero.

Usa FAK per: market-buy con un price ceiling specifico (alzare l’ask fino a N cents sopra il mid); sweep-the-book sells quando devi ridurre l’inventory con urgenza; qualsiasi strategy in cui "una posizione parziale è meglio di nessuna".

Operativamente è più complicato di FOK perché il bot deve sapere se ha ottenuto il 100% o il 30% prima di decidere il passo successivo. La fill response include un campo filled_size — leggilo sempre.

GTC: quando vuoi restare sul book

Good-til-Cancelled resta sul book al tuo prezzo finché non viene fillato o lo cancelli. Nessun timeout (altri order type nella v2 API includono GTD con una scadenza).

Usa GTC per: take-profit sells a +Nc sopra l’entry; stop-loss sells a -Nc sotto l’entry (con caveat — vedi sotto); market-making con quote su entrambi i lati; qualsiasi position per cui il bot è disposto ad aspettare un prezzo migliore.

La regola dura: GTC richiede ≥ 5 shares. Gli order sotto 5 shares vengono rifiutati dal CLOB con Size (X) lower than the minimum: 5. Un bot che pubblica un GTC sell da 4 shares fallisce silenziosamente nel configurare l’exit e porta la position fino alla resolution. Controlla sempre inventory ≥ 5 prima di pubblicare GTC; in caso di size più piccola, fai fallback a FAK o ride-to-resolve.

Limit vs market e la spread tax

Ogni order di Polymarket è tecnicamente un limit order — anche quello che i bot chiamano "market buy" specifica un price ceiling. La distinzione è se quel prezzo è al best ask (di fatto un market order, filla contro il book) oppure sotto di esso (resta sul book).

La spread tax è il costo del crossing — bid 0.45, ask 0.47, mid 0.46. Un round trip che compra all’ask e vende al bid paga 2 cent per share. Su una strategy con win-rate del 60% e target +3c/-4c, quello spread da 2c fa la differenza tra profitto e perdita.

Il pattern maker (postare GTC al bid o sotto, aspettare di essere colpiti) incassa lo spread invece di pagarlo. Il costo è l’incertezza del fill — potresti non essere mai colpito. Per trade ad alta convinzione, paga lo spread. Per accumulo passivo, lavora il book.

I nostri default di produzione (FOK buys, GTC sells]

Il pattern verso cui convergono la maggior parte dei nostri bot in produzione:

  • Entries: FOK a ask + 0-2 cents. Se il bot ha deciso di comprare, dovrebbe comprare ora o saltare. Restare in resting con un entry order raramente vale la pena — la situazione che ha triggerato la decisione di buy cambia più velocemente di quanto l’order resti lì.
  • Take-profit exits: GTC al target price. Pubblicati subito dopo il fill dell’entry. Lasciamo che il mercato venga da noi; non inseguiamo il bid verso il basso. Con ≥ 5 shares.
  • Stop-loss: caso per caso. GTC funziona per strategy lente dove i price change sono limitati. Per mercati in rapido movimento uno stop GTC non si filla se il prezzo lo attraversa di corsa; arriviamo fino alla resolution in modalità option-D (memory: trader-gtc-sell.md).

Il pattern è conservativo — meno fill, meno slippage. Una variante più aggressiva usa entry FAK e exit FAK, accettando partial fill. Scegline uno e mantienilo coerente; mischiare decisioni trade per trade invita la confusione.

Code: inserire ogni tipo di order

Reference per l’inserimento di order in Python con py-clob-client (v0.34.6).

from py_clob_client.client import ClobClient
from py_clob_client.clob_types import OrderArgs, OrderType
c = ClobClient(host="https://clob.polymarket.com", chain_id=137,
               key=PRIVATE_KEY, signature_type=2, funder=PROXY)
c.set_api_creds(creds)

# FOK buy: fill 10 shares at price 0.45 or skip
args = OrderArgs(token_id=TOKEN, price=0.45, size=10, side="BUY")
resp = c.create_and_post_order(args, OrderType.FOK)

# FAK buy: take as much as you can at 0.45 or below
resp = c.create_and_post_order(args, OrderType.FAK)

# GTC sell: rest a sell at 0.85 for 10 shares
sell_args = OrderArgs(token_id=TOKEN, price=0.85, size=10, side="SELL")
resp = c.create_and_post_order(sell_args, OrderType.GTC)

Le stesse operazioni in Node con @polymarket/clob-client-v2: sostituisci OrderType.FOK con clob.OrderType.GTC ecc.; il metodo è createAndPostOrder. Il flag negRisk (capitolo 11) deve essere impostato nel secondo argomento per i mercati multi-outcome — se manca, si instrada verso il contract di exchange sbagliato.

Domande frequenti

Cos’è FOK su Polymarket?
Fill-or-Kill. L’order deve fillarsi per intero immediatamente oppure viene cancellato - niente partial fill, niente resting sul book. Usiamo FOK di default per i buy nel nostro trader di produzione perché elimina l’ambiguità dei phantom fill (l’order è o completamente fillato o completamente sparito, mai a metà).
Cos’è FAK su Polymarket?
Fill-and-Kill (chiamato anche IOC, Immediate-or-Cancel). L’order prende tutta la liquidity disponibile immediatamente e cancella il resto non fillato. Utile quando accetti partial fill ma non vuoi mai un rest. Più veloce di FOK in order book frammentati.
Cos’è GTC su Polymarket?
Good-til-Cancelled. L’order resta sul book finché non viene fillato o lo cancelli. GTC è ciò che usi per fare da maker (fornire liquidity), guadagnare rebates ed evitare taker fees. Usiamo GTC per i sell nel nostro setup di produzione così catturiamo lo spread in uscita.
Il mio bot dovrebbe usare limit order o market order?
Quasi sempre limit order. I market order pagano la taker fee (0.75% to 1.80%) e lo spread; i limit order guadagnano il maker rebate (20-25% delle taker fee). L’unico buon motivo per usare un market order è quando la news è arrivata e il prezzo sta per muoversi oltre lo spread prima che il tuo limit possa fillarsi.
Polymarket supporta nativamente gli stop-loss order?
No. Lo stop-loss è un concetto client-side: il tuo bot osserva il prezzo e, quando la condizione di trigger è soddisfatta, inserisce un market order o un FAK sell order. L’exchange non ha un primitive nativo di stop, quindi devi costruire la logica nel tuo bot.
Quali sono i minimum degli order?
Market order: minimum notional di 1 USD. Limit order: minimum di 5 shares. Alcuni mercati sottili rifiutano order molto piccoli - l’SDK restituisce un codice di errore specifico che puoi intercettare e usare per ridimensionare l’order.