Come costruire un bot di trading per Polymarket

Un bot per Polymarket è fatto di sei pezzi: trovare i mercati, leggere i prezzi, decidere, piazzare ordini, gestire le posizioni e restare in vita. I primi due sono facili, il quarto è macchinoso e il sesto è dove la maggior parte dei bot muore davvero. Questa guida percorre l’intero arco con codice verificato, ed è onesta sulle parti davvero difficili.

Passo 0: decidi su cosa opera il tuo bot

Vale la pena farlo prima di scrivere una sola riga, perché determina tutto il resto. I mercati di Polymarket si dividono in due famiglie che non hanno quasi nulla in comune:

Se stai automatizzando, quasi certamente ti interessa la seconda famiglia: alta frequenza, continua e abbastanza meccanica da poter essere codificata. Sono trattati in dettaglio in i mercati Up/Down spiegati.

Passo 1: installa l’SDK attuale

Entrambi gli SDK ti danno un’unica interfaccia client su tutte le API di Polymarket, modelli tipizzati, paginazione coerente e firma integrata: una grande quantità di lavoro macchinoso che non vuoi reimplementare.

pip install polymarket-client
# or: uv add polymarket-client / poetry add polymarket-client

Ci sono quattro client Python, e scegliere quello giusto conta più di quanto sembri:

Passo 2: trova i mercati

La scoperta dei mercati pubblici non richiede alcuna credenziale. Il paginatore dell’SDK è coerente su tutti i metodi di elenco, quindi questo schema vale in generale.

import asyncio
from polymarket import AsyncPublicClient


async def main() -> None:
    async with AsyncPublicClient() as client:
        pages = client.list_markets(closed=False, page_size=50)

        # Iterate items directly when page boundaries do not matter.
        async for market in pages.iter_items():
            if "updown" in (market.slug or ""):
                print(market.slug, market.condition_id)


asyncio.run(main())

Due cose da tenere a mente. Primo, page.next_cursor è un cursore opaco: salvalo così com’è se vuoi riprendere una scansione in seguito, e non provare ad analizzarlo o a costruirne uno. Secondo, /markets ha il rate limit più stretto di tutta la piattaforma, 300 req / 10s, quindi metti in cache i metadati dei mercati invece di rielencarli in un ciclo stretto. Tutti i numeri sono nel riferimento ai rate limit.

Passo 3: autenticati

Per fare trading serve un wallet. L’SDK Python costruisce il signer a partire da una chiave privata locale:

import os
from polymarket import AsyncSecureClient

client = await AsyncSecureClient.create(
    private_key=os.environ["POLYMARKET_PRIVATE_KEY"],
    wallet=os.environ["POLYMARKET_WALLET_ADDRESS"],
)

Sotto il cofano, Polymarket usa due livelli di autenticazione: L1 è una firma del wallet EIP-712 che dimostra che controlli l’indirizzo e ti permette di creare o derivare le credenziali API; L2 firma ogni richiesta privata con quelle credenziali usando HMAC-SHA256. L’SDK gestisce entrambi, ed è il motivo principale per usarlo.

Passo 4: ottieni i prezzi in tempo reale

L’errore architetturale più comune in un primo bot è fare polling di /book a intervalli regolari. Consuma il tuo budget di rate limit, aggiunge latenza e scala male. Usa invece le sottoscrizioni: l’SDK unisce più feed in un unico stream di eventi.

from polymarket.streams import MarketSpec

async with await client.subscribe([MarketSpec(token_ids=[token_id])]) as stream:
    async for event in stream:
        # MarketBookEvent | MarketPriceChangeEvent | MarketLastTradePriceEvent
        # | MarketTickSizeChangeEvent | MarketBestBidAskEvent
        # | NewMarketEvent | MarketResolvedEvent
        handle(event)

Se ti connetti al WebSocket grezzo invece di usare l’SDK, devi inviare un PING ogni 10 secondi o la connessione viene chiusa, e ti serve custom_feature_enabled: true per ricevere gli eventi best_bid_ask, new_market e market_resolved. Questi aspetti e gli schemi di riconnessione sono trattati nella guida ai WebSocket. A parte questo, i prezzi di riferimento sono passati a PolyBolt il 15 settembre 2026: se il tuo bot riceve lo spot in streaming, vedi la guida alla migrazione.

Passo 5: piazza un ordine

Un ordine a mercato è la cosa più semplice che funzioni, e amount è espresso in pUSD che sei disposto a spendere, non in quote:

market = await client.get_market(slug="<market-slug>")
token_id = market.outcomes.yes.token_id
assert token_id is not None

response = await client.place_market_order(
    token_id=token_id,
    side="BUY",
    amount="10",          # spend up to 10 pUSD
)

if not response.ok:
    raise RuntimeError(response.message)

# Settlement is on-chain and asynchronous — this waits for it.
hashes = await client.wait_for_order_fill_settlement(response)

Per gli ordini limite in attesa, ci sono due regole che ti morderanno prima di qualsiasi altra cosa. I prezzi devono stare sulla griglia dei tick del mercato: chiama GET /tick-size per ogni mercato invece di dare per scontato 0.01, perché la dimensione del tick varia e può restringersi man mano che un mercato matura. E gli ordini sotto la size minima del mercato vengono respinti subito. Entrambi tornano come 400 con messaggi specifici, elencati nel riferimento agli errori.

Passo 6: scopri se la strategia funziona

Tutto ciò che c’è sopra è idraulica, e l’idraulica è la metà facile. La domanda difficile è se la tua strategia fa soldi, ed è qui che costruire un bot per Polymarket si separa nettamente dal costruire un bot per il crypto spot.

Non esiste una testnet. Niente sandbox, niente API demo, niente endpoint di paper trading. Queste parole non compaiono da nessuna parte nella documentazione di Polymarket. Il tuo primo ordine reale è fatto con soldi veri contro controparti reali. Vedi Polymarket ha una testnet? per i quattro modi di aggirare il problema.

E non esiste un order book storico. Una volta che un mercato si risolve, il suo book restituisce 404. Conserva una serie di prezzi di circa un punto al minuto, e solo se la chiedi con un inizio e una fine espliciti:

TOK=<token_id_of_a_resolved_market>
START=<epoch seconds the window opened>
END=$((START + 300))

curl -s "https://clob.polymarket.com/book?token_id=$TOK"
# {"error":"No orderbook exists for the requested token id"}   HTTP 404

curl -s "https://clob.polymarket.com/prices-history?market=$TOK&startTs=$START&endTs=$END&fidelity=1"
# about 6 points for a 5-minute market; interval=max returns [] for older ones

Quindi non puoi fare backtest partendo da Polymarket. Ti servono snapshot point-in-time che qualcuno ha registrato mentre i mercati erano attivi. È quello che PolyTest fornisce per i mercati crypto Up/Down: 240M+ snapshot, 8 livelli di profondità del book per lato, timestamp sotto il secondo, mercati risolti conservati:

import os, requests

BASE = "https://api.polytest.io/api/v1"
H = {"X-API-Key": os.environ["POLYTEST_KEY"]}

markets = requests.get(f"{BASE}/markets",
                       params={"coin": "btc", "market_type": "5m", "limit": 50},
                       headers=H).json()["markets"]

snaps = requests.get(f"{BASE}/markets/{markets[0]['id']}/snapshots",
                     params={"include_orderbook": "true"},
                     headers=H).json()["snapshots"]


def simulate_fill(levels, qty):
    """Walk the ladder. Mid-price is not a price you can trade at."""
    filled = cost = 0.0
    for lvl in levels:
        take = min(lvl["size"], qty - filled)
        cost += take * lvl["price"]
        filled += take
        if filled >= qty:
            break
    return cost / filled if filled >= qty else None


print(simulate_fill(snaps[0]["orderbook"]["asks"], 500))

Passo 7: sopravvivi al contatto con la produzione

Un bot che opera correttamente per un’ora e poi si blocca è peggio di nessun bot. Questi sono i problemi che si verificano davvero, in ordine approssimativo di frequenza:

• Testa il percorso di cancellazione prima di quello di ingresso. Non riuscire a uscire è molto peggio che non riuscire a entrare.
• Limita l’esposizione nel codice, non nella tua testa. Un limite rigido di posizione trasforma un bug logico in una piccola perdita invece che in una perdita illimitata.
• Costruisci un kill switch e testalo davvero. Un kill switch non testato è un commento.
• Aggiungi jitter al lavoro schedulato. Worker che si svegliano esattamente allo stesso secondo creano un picco sincronizzato molto sopra la tua frequenza media.
• Registra ogni richiesta e risposta per la prima settimana. Ti serviranno, e non potrai ricostruirle dopo.
• Genera alert per categorie, non per messaggi. Polymarket inserisce ID degli ordini e prezzi nelle stringhe di errore, quindi gli alert sulla stringa grezza sono puro rumore.

Un ordine di sviluppo realistico

La sequenza che fa perdere meno tempo e soldi:

1. Integrazione in sola lettura, client pubblico, niente chiavi. Verifica scoperta dei mercati, parsing, paginazione e backoff. Un giorno, gratis.
2. Backtest della strategia su book storici con una simulazione onesta delle esecuzioni. La maggior parte delle idee muore qui. È proprio questo lo scopo.
3. Paper trading live per almeno una settimana: registra gli ordini previsti invece di inviarli. Verifica uptime, riconnessioni e tempistiche.
4. Vai live con la size minima, con un limite rigido all’esposizione e un kill switch testato.
5. Aumenta le dimensioni solo quando i numeri live corrispondono a quelli su carta. Se divergono, il tuo modello di esecuzione era sbagliato: torna al passo 2.

I passi 1, 3 e 4 li costruisci in pochi giorni. Il passo 2 richiede dati che Polymarket non conserva, ed è anche il passo che più sicuramente fa risparmiare soldi. Inizia una prova gratuita su PolyTest: basta per scoprire se la tua idea sopravvive allo spread.