Polymarket Bot Tutorial · Capitolo 6 di 32
Autenticazione del Polymarket bot e configurazione del wallet: proxy wallet vs EOA, generazione della API key via SDK, sigType 2 per Gnosis Safe, best practice per la conservazione delle key e la migrazione da Magic a Privy.
Cosa copre questo capitolo
Il wallet model di Polymarket ha tre elementi mobili: un externally owned account (EOA) che firma gli ordini, un smart-contract proxy che detiene i fondi e la Polymarket CLOB API key che autentica le richieste HTTP. Farli funzionare correttamente tutti e tre è di gran lunga il problema più comune del Day 1 per i nuovi builder, e dopo la migrazione di agosto 2025 da Magic Labs a Privy la cosa è diventata ancora più confusa. Questo capitolo illustra ogni elemento nell'ordine di setup, con le specifiche environment variables e il signature-type flag richiesti dal codice in produzione.
Questo è il capitolo 6 della nostra serie in 32 parti su come costruire un Polymarket trading bot. Trattiamo l'argomento in profondità nelle sezioni qui sotto. Il contenuto principale di ciascuna sezione viene scritto e pubblicato capitolo per capitolo; le risposte FAQ e i riferimenti sono già completi e riflettono l'esperienza di produzione derivata dall'esecuzione del nostro trader.
- Proxy wallet vs EOA: quale usare per il bot
- Generazione di una API key (passaggi SDK]
- sigType 2 e POLY_FUNDER_ADDRESS (Gnosis Safe)
- Conservazione delle key: .env, vault, KMS
- La migrazione da Magic Labs a Privy
- Approving della spesa USDC/pUSD
- Wallet recovery e backup
Proxy wallet vs EOA: quale usare per il bot
Polymarket utilizza un pattern di smart-contract proxy wallet. Il tuo EOA — l'indirizzo legato alla tua private key — firma transazioni e ordini. Un Gnosis Safe deployato a un indirizzo deterministico detiene il vero pUSD e le outcome shares. L'indirizzo proxy è quello che compare nel pannello "wallet" dell'interfaccia Polymarket; l'EOA è quello che firma.
Per i bot, firmi sempre con l'EOA (PRIVATE_KEY nell'env) e fai riferimento all'indirizzo proxy come POLY_FUNDER_ADDRESS nella configurazione del client CLOB. Inviare ordini con l'EOA come funder produce errori "insufficient balance" anche quando il proxy è finanziato.
Non puoi fare botting solo con l'EOA — il flusso web di Polymarket crea sempre un proxy alla registrazione. Conferma entrambi gli indirizzi con polymarket wallet show dalla CLI, oppure leggi l'indirizzo proxy dalle impostazioni dell'interfaccia Polymarket.
Generazione di una API key (passaggi SDK]
La CLOB API richiede tre credential: key, secret, passphrase. Non sono la private key del tuo wallet — sono un set di credential in stile HMAC legate al tuo wallet, usate solo per l'autenticazione delle richieste HTTP.
Generale una volta con l'SDK:
# Python
from py_clob_client.client import ClobClient
c = ClobClient(host="https://clob.polymarket.com", chain_id=137,
key="<PRIVATE_KEY>", signature_type=2,
funder="<PROXY_ADDRESS>")
creds = c.create_or_derive_api_creds()
print(creds.api_key, creds.api_secret, creds.api_passphrase)Salva l'output in un file JSON e caricalo a ogni avvio del bot; non rigenerarlo per sessione — l'API server mette in cache il set di credential, e ruotarlo troppo spesso può attivare la logica di rate-limit. Le credential non scadono automaticamente. Ruotale solo se sospetti una fuga.
sigType 2 e POLY_FUNDER_ADDRESS (Gnosis Safe)
L'argomento signature_type controlla come la CLOB valida le firme dei tuoi ordini. Esistono tre valori; due sono reali:
- 0 / EOA: l'EOA è sia signer sia funder. Usato per setup insoliti in cui gli utenti hanno importato direttamente una private key.
- 1 / POLY_PROXY: legacy Magic Labs proxy contract. La maggior parte degli account pre-2025.
- 2 / POLY_GNOSIS_SAFE: standard attuale. I fondi sono in un Gnosis Safe, l'EOA firma.
Usa signature_type=2 per qualsiasi account creato dopo agosto 2025 (la migrazione a Privy) o per qualsiasi account in cui puoi vedere un indirizzo Gnosis Safe nell'interfaccia Polymarket. La variabile d'ambiente POLY_FUNDER_ADDRESS deve essere l'indirizzo Safe, non l'EOA. Un signature_type non coerente con il tipo di funder produce in modo silenzioso rifiuti degli ordini che sembrano "insufficient allowance" o "balance: 0" — il messaggio di errore è fuorviante.
Conservazione delle key: .env, vault, KMS
Tre livelli ragionevoli di conservazione per la private key dell'EOA.
- File .env (sviluppo su una singola macchina). Il file vive sul VPS, il bot lo legge all'avvio, la key non lascia mai l'host. Adeguato per wallet <$1k. Usa
chmod 600 .enve assicurati che il.gitignoredel tuo repo lo escluda. - Vault self-hosted (HashiCorp Vault, file cifrato con age o systemd-creds). Aggiunge un passaggio di unlock all'avvio del bot. Ne vale la pena per wallet nella fascia $1k-$10k.
- Cloud KMS (AWS KMS, GCP KMS). Il bot chiama KMS per decifrare la key in memoria; la key non tocca mai il disco. Vale la complessità operativa solo sopra i $10k o per flotte multi-bot.
Cosa non fare mai: committare una private key su git, incollarla in una chat, archiviarla in un password manager che sincronizza con servizi cloud senza modalità solo locale. L'impatto on-chain di una fuga della EOA di Polymarket è l'intero saldo pUSD e l'inventario delle outcome share.
La migrazione da Magic Labs a Privy
Ad agosto 2025 Polymarket ha migrato il proprio fornitore principale di embedded-wallet da Magic Labs a Privy. L'effetto lato bot è piccolo ma specifico.
Gli account pre-migrazione (creati tramite Magic) usano in genere signature_type=1 (POLY_PROXY). Gli account post-migrazione usano signature_type=2 (POLY_GNOSIS_SAFE). Alcuni utenti hanno migrato il vecchio account; altri hanno mantenuto l'originale. Non c'è modo di capire dall'API pubblica quale tipo usa il tuo account — lo verifichi provando a firmare un ordine e osservando il rifiuto.
La migrazione ha anche cambiato il modo in cui la UI espone l'indirizzo funder. I vecchi flussi UI di Polymarket mostravano l'indirizzo proxy nel dashboard; il flusso attuale lo nasconde nelle impostazioni dell'account. Il comando CLI polymarket wallet show è il modo più pulito per confermare entrambi i valori, indipendentemente da quando l'account è stato creato.
Approving della spesa USDC/pUSD
Affinché la CLOB possa muovere il tuo pUSD al momento del match dell'ordine, il proxy deve aver approvato i contratti di exchange di Polymarket come spender. La UI di Polymarket imposta queste approval durante il primo deposito. Per i bot che finanziano direttamente il proxy, devi impostarle manualmente.
Tre approval da impostare, una volta per wallet:
- pUSD (ERC-20) → exchange contract
- Conditional Tokens (ERC-1155) → exchange contract (per vendere share)
- Conditional Tokens (ERC-1155) → NegRisk exchange contract (per vendere share NegRisk)
Esegui polymarket approve dalla CLI alla prima configurazione. La transazione costa pochi centesimi in gas MATIC. Verifica con polymarket approve check — tutte e tre dovrebbero restituire "approved." Il bug silenzioso più comune per i nuovi builder è la mancanza dell'approvazione NegRisk, che fallisce solo quando si vendono share da mercati multi-outcome e sembra un errore di balance.
Wallet recovery e backup
Il wallet del bot ha due elementi recuperabili: la private key dell'EOA e la password dell'account Polymarket (che controlla l'accesso tramite la web UI ma non tramite l'SDK).
La private key dell'EOA è l'unica cosa che conta per il bot. Perderla = perdere tutto ciò che si trova nel proxy. Backup a freddo: scrivila su carta, sigillala in una busta, conservala fuori sede. Backup a caldo: chiavetta USB cifrata. Non inviarla mai via email a te stesso; non conservarla mai non cifrata in cloud storage.
La password dell'account Polymarket è recuperabile tramite email recovery di Magic Labs / Privy finché controlli ancora l'email originale usata per la registrazione. Non controlla l'accesso al bot — il bot usa direttamente la private key dell'EOA.
Se sospetti una fuga della key: immediatamente ritira pUSD e token di outcome verso un nuovo wallet, genera una nuova EOA, ridistribuisci il bot con la nuova key. La key compromessa non può essere revocata; può solo essere svuotata.
