API · Riferimento

Leggere i dati di mercato di Polymarket non richiede alcuna chiave. Inviare o annullare ordini richiede due livelli di autenticazione: una firma del wallet L1 (EIP-712) per creare le tue credenziali API e una firma HMAC L2 su ogni richiesta autenticata. Questa pagina copre entrambi, più i quattro tipi di firma e l'indirizzo funder - le due cose che causano la maggior parte degli errori di autenticazione.

In sintesi
  • Lettura (Gamma, Data, CLOB pubblico) - nessuna autenticazione.
  • L1 - il tuo wallet firma un messaggio EIP-712 (ClobAuth, versione del dominio "1") per creare o derivare le credenziali API.
  • L2 - ogni richiesta di ordine viene firmata con un HMAC di api_key / api_secret / api_passphrase.

Crea o deriva le tue credenziali API (L1)

Il tuo wallet firma una volta per generare (o riderivare) un set deterministico di credenziali API. Usa l'SDK V2 - il py-clob-client V1 (0.34.x) è archiviato e non funzionante.

from py_clob_client_v2 import ClobClient   # pip install py-clob-client-v2

# L1: your wallet signs to derive API credentials
client = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=PRIVATE_KEY)
creds = client.create_or_derive_api_key()    # api_key, api_secret, api_passphrase

# L1 + L2: rebuild the client WITH creds for authenticated calls (no set_api_creds in v2)
client = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=PRIVATE_KEY, creds=creds)
// polymarket_client_sdk_v2 - official Rust client (repo rs-clob-client-v2)
use polymarket_client_sdk_v2::clob::{Client, Config};
use polymarket_client_sdk_v2::clob::types::SignatureType;
let client = Client::new("https://clob.polymarket.com", Config::default())?
    .authentication_builder(&signer)
    .funder(deposit_wallet)                   // deposit wallets work in Rust today
    .signature_type(SignatureType::Poly1271)
    .authenticate().await?;

Conserva i tre valori come segreti (variabili d'ambiente). La lettura dei dati di mercato non ne ha mai bisogno.

Tipi di firma (0-3)

Il tipo di firma indica all'exchange come la firma del tuo ordine si collega al wallet che detiene i fondi (il funder). Scegli quello che corrisponde a come è stato creato il tuo account.

TipoNomeQuando
0EOAUn wallet semplice (es. MetaMask) che firma e detiene i fondi.
1POLY_PROXYRegistrazione via email / Magic.link - un proxy wallet detiene i fondi; la tua chiave firma per suo conto.
2POLY_GNOSIS_SAFEUn Gnosis Safe detiene i fondi; una chiave di firma firma per esso.
3POLY_1271Un deposit wallet (firma smart-contract EIP-1271).

Quando la chiave di firma è diversa dall'indirizzo che detiene i fondi (tipi 1-3), devi passare sia la chiave privata sia l'indirizzo funder.

Deposit wallet (tipo 3) - oggi usa Rust. A giugno 2026 i client Python (py-clob-client-v2) e TypeScript (@polymarket/clob-client-v2) hanno un bug aperto: l'autenticazione L1 lega la chiave API al tuo EOA invece che al deposit wallet, quindi gli ordini vengono rifiutati ("maker address not allowed, please use the deposit wallet flow"). Il client Rust ufficiale gestisce correttamente la firma con deposit wallet EIP-1271. Soluzione senza Rust: usa un account email/Magic e firma con signature_type = POLY_PROXY (tipo 1). Ricontrolla le issue Polymarket #70 (Python) / #65 (TS) per una correzione.

Firmare le richieste (L2)

Ogni richiesta autenticata porta una firma HMAC costruita dal tuo API secret più il metodo della richiesta, il path, il body e un timestamp. L'SDK V2 costruisce questi header per te. Due cose da tenere corrette:

  • Orologio - uno scostamento superiore a ~60 secondi fa rifiutare la tua firma. Sincronizza via NTP.
  • Domini - la versione del dominio EIP-712 L2/ClobAuth resta "1"; solo il dominio Exchange (ordini) V2 è passato a "2". Un client V1 firma il dominio ordine sbagliato e fallisce - vedi order_version_mismatch.

Sicurezza delle chiavi

  • Non inserire mai chiavi private o API secret nel codice - usa variabili d'ambiente; non farne mai il commit.
  • Tieni la chiave di firma e l'indirizzo funder separati dal tuo wallet di uso quotidiano dove possibile.
  • I bot in sola lettura non hanno bisogno di alcuna credenziale - inizia da lì.

Prossimo: API CLOB: invia un ordine · Risolvi un errore di autenticazione · Migra da v1 a v2.