Una API key di exchange è una coppia composta da API Key e API Secret. Con questa key, programmi e servizi lavorano con un account tramite API: leggono il saldo, aprono e chiudono trade ed eseguono altre operazioni consentite per quella key senza accedere alla dashboard web.
Obiettivo del materiale: descrivere le restrizioni che un exchange applica alle richieste API: verifica della firma tramite API Secret, diritti della key (permissions), collegamento della fonte della richiesta a una IP whitelist, restrizioni sui prelievi tramite whitelist degli indirizzi e isolamento del saldo tramite sub-accounts. Queste restrizioni riducono il rischio che un leak della coppia API Key + API Secret porti al prelievo di asset o a trade in perdita.
🧭 Come funziona il controllo dell’accesso API sugli exchange crypto
Le API keys sono usate da trading bot, terminali, servizi di reporting e integrazioni interne. Un exchange esegue una richiesta API solo dopo aver verificato la firma (API Secret), i diritti sull’operazione (permissions), l’indirizzo IP della fonte (IP whitelist) e il tempo della richiesta (timestamp e recvWindow). Il controllo del tempo blocca una ripetizione successiva della richiesta, anche se la richiesta è stata intercettata.
Il rischio API viene ridotto tramite le impostazioni della key. IP whitelist accetta richieste solo dagli indirizzi IP specificati. Permissions limita l’insieme di operazioni che l’exchange eseguirà con la key. La whitelist degli indirizzi di prelievo limita la lista dei destinatari. Sub-accounts separa saldi e keys tra sub-accounts, così una sola key non ha accesso a tutti gli asset dell’account.
🔍 Come un exchange verifica una richiesta API: firma, diritti, IP e tempo
Una API key è composta da API Key (identificatore della key) e API Secret (secret per la firma). La firma conferma all’exchange che la richiesta è stata formata usando API Secret e non è stata modificata durante il transito.
- Formazione dei parametri della richiesta verso l’API endpoint dell’exchange (l’indirizzo API che accetta una specifica operazione)
- La richiesta definisce l’operazione: aprire o annullare un ordine, ottenere un saldo, eseguire un transfer o avviare un prelievo.
- La richiesta contiene un timestamp e talvolta una finestra temporale consentita (recvWindow). L’exchange confronta questi valori con il proprio tempo e rifiuta la richiesta se esce dall’intervallo consentito.
- Firma dei parametri della richiesta tramite HMAC
- HMAC è una firma hash generata con una secret key. La stringa dei parametri viene firmata con API Secret.
- L’exchange ricalcola l’HMAC sugli stessi parametri e confronta la firma. Una mancata corrispondenza significa che il mittente non possiede API Secret o che i parametri sono stati modificati.
- Verifica delle restrizioni della key e decisione sull’esecuzione
- Permissions definisce quali operazioni sono consentite per la key (read/trade/transfer/withdraw sulla maggior parte degli exchange centralizzati, CEX).
- IP whitelist limita le fonti delle richieste. L’exchange rifiuta una richiesta se l’IP del mittente non rientra nella whitelist della key.
- Esecuzione dell’operazione e restituzione del risultato
- Se i diritti sono insufficienti, l’exchange restituisce un rifiuto e non esegue l’operazione, anche con una firma corretta.
- Se l’IP non corrisponde, l’exchange restituisce un rifiuto nella fase di autorizzazione e non passa all’operazione di trading o prelievo.
Componenti di accesso API controllati dall’exchange
L’exchange riduce il rischio API con tre verifiche in ogni richiesta: firma tramite API Secret, permissions per le operazioni e IP whitelist per la fonte della richiesta.
- API Secret viene conservato solo in un archivio di secrets e nella memoria del processo che firma le richieste.
- Permissions viene attivato in base al compito della key: lettura per il reporting, trading per un bot, prelievo solo per pagamenti operativi.
- IP whitelist contiene solo gli IP dei server che inviano realmente richieste, in modo che la lista non ampli la superficie di attacco.
Se un attaccante ottiene una API Key senza API Secret, l’exchange rifiuta la richiesta a causa di una firma non valida. Se un attaccante ottiene sia API Key sia API Secret, l’exchange rifiuta la richiesta quando permissions non consente l’operazione o l’IP non rientra nella whitelist.
🎯 Quali perdite sono possibili tramite API: prelievi, transfer e perdita di trading
Il danno tramite API dipende dalle permissions attivate e dal saldo disponibile per quella key. Una trade-only key comporta un rischio minore su un sub-account con un piccolo saldo operativo e un rischio maggiore su un sub-account con capitale principale.
Tre scenari che un exchange esegue tramite API
Le perdite tramite API nascono da prelievo, transfer interno o trade che generano una perdita al prezzo di esecuzione.
- Prelievo diretto: una key con withdraw permission avvia un prelievo verso un indirizzo che l’exchange consente dopo le proprie verifiche e regole di whitelist.
- Transfer interno: una key con transfer permission sposta asset tra wallet di prodotto o tra sub-accounts, se l’exchange consente tali operazioni tramite API.
- Perdita di trading senza prelievo: una key con trade permission inserisce ordini su una coppia a bassa liquidità ed esegue trade a un prezzo peggiore, creando una perdita da slippage, spread e commissioni.
Withdraw permission disattivata elimina il prelievo diretto. Trade permission resta una fonte di perdita se nel trading wallet è conservato un saldo elevato e la key non è limitata per IP e strumenti.
Segnali dopo i quali una verifica API diventa necessaria
- Sono comparsi ordini che non corrispondono alla logica del trading system e al programma di avvio.
- Sono comparsi transfer tra wallet o sub-accounts senza una ragione operativa.
- Nelle impostazioni della key sono comparse nuove permissions oppure IP whitelist è stata rimossa.
- Nei log del trading system sono comparsi errori di firma e la frequenza delle richieste è aumentata mentre il codice è rimasto invariato.
🌐 IP whitelist: collegamento della key al server che invia le richieste
IP whitelist obbliga l’exchange ad accettare richieste solo da indirizzi IP indicati in anticipo. Se API Secret finisce nel codice, nei log, nei backup o in un servizio di terze parti, un attaccante non potrà inviare una richiesta da un IP assente dalla whitelist.
Scelta di una fonte stabile per le richieste API
- Un VPS (server virtuale privato) con IP pubblico statico è adatto a IP whitelist e al funzionamento continuo del trading system.
- Una connessione domestica con IP dinamico non è adatta, perché un cambio di IP provoca rifiuti delle richieste API fino all’aggiornamento della whitelist.
Configurazione di IP whitelist per una API key
- IP whitelist include l’IP del server del trading system e del server di backup, se il server di backup viene realmente usato.
- Se l’exchange supporta CIDR (notazione di sottorete, per esempio 203.0.113.10/32), viene impostato l’intervallo minimo per non ampliare la lista delle fonti.
Verifica della resilienza dell’accesso API
- Una API key di backup su un IP separato viene usata durante la migrazione dell’infrastruttura e il cambio dell’indirizzo del server.
- La procedura di aggiornamento di IP whitelist viene fissata in anticipo, affinché il cambio di IP non coincida con la perdita di controllo sugli ordini.
Nell’infrastruttura cloud, le richieste possono uscire verso Internet tramite NAT (traduzione degli indirizzi al bordo della rete). In questo caso, l’IP esterno visto dall’exchange può differire dall’IP del container o della macchina virtuale. In IP whitelist si indica l’egress IP (l’IP esterno del traffico in uscita), altrimenti l’exchange rifiuterà le richieste.
IP whitelist non protegge dalla compromissione del VPS. Se il server viene preso sotto controllo, un attaccante invierà richieste dallo stesso IP, quindi la protezione dell’accesso al VPS e il controllo degli aggiornamenti restano parte della protezione API.
IP whitelist blocca richieste da server non autorizzati, perché l’exchange confronta l’IP della fonte con la whitelist e rifiuta la richiesta prima dell’esecuzione di un’operazione di trading o prelievo.
🔑 Permissions: quali diritti vengono assegnati a una key per un compito specifico
Permissions definisce quali API endpoints l’exchange consentirà di chiamare con questa key. I nomi dei diritti dipendono dall’exchange, ma lo schema è di solito lo stesso: read per la lettura, trade per gli ordini, transfer per i transfer interni e withdraw per il prelievo su blockchain.
| Compito | Consentire | Bloccare | Operazione bloccata |
|---|---|---|---|
| Screener/analytics | Read | Trade; Transfer; Withdraw | Inserimento di ordini e spostamento di asset |
| Trading bot | Read; Trade | Withdraw | Prelievo diretto di fondi tramite API |
| Reporting | Read | Trade; Transfer; Withdraw | Operazioni in caso di compromissione del servizio di reporting |
| Transfer operativi | Read; Transfer | Trade; Withdraw | Operazioni di trading e prelievo su blockchain |
Read-only key per monitoraggio e reporting
Una read-only key viene usata quando un sistema deve leggere saldi, storico dei trade e stati delle posizioni, ma non deve modificare lo stato dell’account.
- Una read-only key blocca l’inserimento e l’annullamento di ordini, perché l’exchange rifiuta i trading endpoints per questa key.
- IP whitelist limita l’accesso ai dati a un server specifico e blocca richieste da IP non autorizzati in caso di leak di API Secret.
- Una read-only key separata per il reporting separa il rischio del servizio di reporting dal rischio della trading key.
Una read-only key espone saldo e storico, ma non consente prelievi o trade, perché l’exchange rifiuta gli endpoints trade/transfer/withdraw.
Trade key per un trading system senza prelievo
Una trade key viene usata per inserire e annullare ordini. Withdraw permission non è necessaria per le operazioni di trading.
- Trade permission dà accesso alla gestione di ordini e posizioni nei mercati dell’account.
- Withdraw permission disattivata blocca i prelievi, perché l’exchange rifiuta i withdrawal endpoints per questa key.
- IP whitelist collega la key al server del trading system e blocca richieste da macchine non autorizzate in caso di leak di API Secret.
Una trade-only key crea rischio per i fondi nel trading wallet, quindi il trading sub-account di solito mantiene un saldo operativo, non il capitale principale.
Transfer key per movimenti interni
Una transfer key viene usata per transfer all’interno dell’exchange: tra wallet di prodotto o tra sub-accounts, se l’exchange consente tali operazioni tramite API.
- Transfer permission consente transfer interni che non vanno sulla blockchain.
- Trade permission disattivata esclude i trade, perché la transfer key non può creare ordini.
- Withdraw permission disattivata esclude il prelievo su blockchain in caso di compromissione della transfer key.
Separare transfer e trade su keys diverse riduce il danno in caso di leak, perché una sola key non dà accesso contemporaneamente a trade e spostamento di asset.
Permissions definisce quale operazione l’exchange consentirà con questa key. Permissions superflue ampliano l’insieme di azioni che l’exchange eseguirà con una key compromessa, quindi i diritti vengono attivati solo per un processo specifico.
🏷️ Protezione dei prelievi: whitelist degli indirizzi, conferme e limiti
Withdraw permission consente a una API key di avviare un prelievo di fondi dal saldo dell’exchange verso una blockchain. La protezione del prelievo si basa sulla whitelist degli indirizzi del destinatario, sul controllo delle modifiche alla whitelist e sui limiti di prelievo.
Nelle integrazioni di trading, withdraw permission viene di solito disattivata. Ordini, annullamenti e lettura del saldo vengono eseguiti all’interno dell’exchange e non richiedono prelievi sulla rete. Read permission è sufficiente per monitoraggio e reporting. Trade permission è sufficiente per il trading algoritmico.
Esempio: un trading bot funziona con una key dotata di trade permission e senza withdraw permission. In caso di compromissione della key, un attaccante potrà aprire e chiudere trade tramite trading endpoints. L’exchange rifiuterà una richiesta di prelievo perché la key non ha withdraw permission.
La whitelist degli indirizzi limita il destinatario del prelievo: l’exchange invia fondi solo verso indirizzi aggiunti in anticipo. Su molti exchange, l’aggiunta di un indirizzo alla whitelist richiede 2FA (autenticazione a due fattori) e conferma tramite un canale separato, per esempio email, app o hardware key. In questo caso, il prelievo verso un nuovo indirizzo dipende non solo dalla API key, ma anche dal controllo di questi canali di conferma.
Il ritardo nella modifica della whitelist (security lock, hold) non attiva subito l’indirizzo aggiunto. Con il ritardo attivo, il prelievo verso un nuovo indirizzo viene bloccato per la durata dell’hold, quindi l’indirizzo aggiunto può essere notato prima del primo prelievo.
La connessione API dei trading bot, le trade-only keys e IP whitelist sono descritti nel materiale «Guadagnare con i trading bot crypto».
I limiti di prelievo limitano la somma delle perdite se un attaccante ottiene una key che supera le verifiche di whitelist e conferma. Il limite giornaliero viene impostato in base agli importi dei pagamenti operativi regolari, non in base al saldo totale dell’account, affinché un singolo ciclo di prelievo non possa svuotare l’intero deposito.
La compromissione dell’email aumenta il rischio, perché molti exchange collegano all’email le conferme di aggiunta degli indirizzi e i reset di sicurezza, inclusi link di conferma e notifiche sulla modifica della whitelist.
Withdraw permission senza whitelist degli indirizzi rende un leak della API key un canale diretto di prelievo su blockchain. Withdraw permission con whitelist degli indirizzi e ritardo nella modifica della whitelist sposta il rischio critico sulla compromissione dei canali di conferma. I limiti di prelievo limitano la somma delle perdite se le altre restrizioni vengono aggirate.
🛡️ Sub-accounts: isolamento di saldo, keys e processi
Sub-accounts separa saldi e API keys all’interno di un exchange. In caso di leak della key, le operazioni sono limitate agli asset dello specifico sub-account.
- Separazione di storage e trading su sub-accounts diversi
- Il sub-account di storage conserva il capitale principale e non utilizza trading API keys permanenti.
- I trading sub-accounts conservano saldi operativi per bot e strategie specifici.
- Controllo dei transfer interni tramite API
- La disattivazione di transfer permission sulle trading keys riduce la possibilità di spostare asset in caso di leak della trading key.
- Una transfer key dedicata viene usata quando i transfer interni fanno parte del processo operativo.
- Limitazione degli strumenti della key quando è supportata la whitelist delle coppie di trading
- La whitelist delle coppie di trading blocca trade su strumenti che non appartengono al trading system.
- La limitazione delle coppie riduce il rischio di perdita sui mercati a bassa liquidità.
Schema di isolamento per più trading systems
Lo schema di isolamento separa il saldo tramite sub-accounts e separa l’accesso tramite API keys, permissions e IP whitelist.
- Un trading system su un exchange opera tramite un sub-account separato e una trade-only key collegata all’IP del VPS.
- Il reporting viene collegato con una read-only key su un server separato, affinché un leak del reporting non esponga la trading key.
- I transfer operativi vengono eseguiti con una transfer key senza trade e withdraw permissions.
In caso di leak della key del trading system, l’exchange esegue operazioni solo nell’ambito del saldo del suo sub-account, quindi le perdite sono limitate al saldo operativo.
🗄️ Conservazione dei secrets e rotazione: come API Secret fuoriesce dall’infrastruttura
API Secret fuoriesce più spesso non dall’exchange, ma dall’infrastruttura del trading system: repository di codice, pipeline CI/CD (processi automatizzati di build e deployment), log delle applicazioni, dump dei database, screenshot e backup. La gestione dei secrets definisce i luoghi di conservazione di API Secret e i ruoli che possono accedervi.
API Secret non viene conservato nel codice dell’applicazione. Il valore del secret viene inserito all’avvio del servizio da un archivio protetto e non viene salvato nei file del progetto o nel repository. Nel codice e nella configurazione resta un riferimento al secret, non il suo valore.
Esempio: un trading bot viene distribuito tramite CI/CD. Nel repository viene conservato solo il nome del secret, mentre il valore di API Secret viene inserito nella fase di deployment da un archivio protetto. In caso di leak del codice e della cronologia dei commit, API Secret non è presente al loro interno.
In production, API Secret viene conservato in un secret manager — un servizio che mantiene i secrets in forma cifrata e li fornisce solo ai processi con autorizzazione tramite IAM (gestione degli accessi basata sui ruoli). Questo schema separa i production secrets dagli ambienti di sviluppo e dai servizi di test.
Le cause comportamentali degli errori nella gestione del rischio e nel piano di trading sono descritte nel materiale «Psicologia del trading».
La rotazione delle API keys riduce il rischio di un leak di lunga durata. La rotazione include la creazione di una nuova key sull’exchange, il passaggio del sistema al nuovo API Secret e la revoca della vecchia key, affinché l’exchange smetta di accettare firme con il vecchio secret.
Il passaggio viene pianificato in un periodo senza posizioni aperte e ordini limite attivi, affinché la modifica di API Secret non interrompa la gestione di ordini e rischio.
Regole minime per la conservazione di API Secret
- API Secret viene conservato in un secret manager o in un archivio cifrato con controllo degli accessi.
- API Secret non entra in Git, Docker image, CI artifacts e backup in chiaro.
- Il production secret non è accessibile dall’ambiente dev e non è accessibile a ruoli che non avviano il trading system.
- La rotazione include la revoca della vecchia key dopo il passaggio, affinché il vecchio secret smetta di funzionare lato exchange.
Permissions, IP whitelist e whitelist degli indirizzi proteggono lato exchange, mentre secret management riduce il rischio di leak di API Secret da codice e log lato infrastruttura.
🧩 Terminali e bot di terze parti: come la connessione influisce sul rischio
Un servizio di terze parti riceve API Key e API Secret per firmare richieste per conto dell’account. Se il servizio accetta la key nella dashboard web, API Secret viene conservato nell’infrastruttura del provider. In caso di incidente del provider, un attaccante potrà firmare richieste e superare la verifica della firma lato exchange.
✅ Segnali di rischio controllato
- Il servizio opera con read-only e trade-only keys e non richiede withdraw permission per trading e reporting.
- Il servizio mostra un registro delle azioni API: ordini creati ed endpoints chiamati.
- Il servizio supporta il collegamento tramite un sub-account separato con saldo operativo limitato.
❌ Segnali di rischio elevato
- Il servizio richiede withdraw permission per funzioni non collegate a pagamenti operativi.
- Il servizio richiede di disattivare IP whitelist e non offre un modello con agente lato utente e IP fisso.
- Il servizio non fornisce la cronologia delle azioni API, quindi l’indagine si basa su segnali indiretti.
Esempio di configurazione: segnali e reporting usano una read-only key, le operazioni di trading usano una trade-only key su un sub-account con saldo operativo, e i prelievi via API sono disattivati.
Un servizio di terze parti non annulla le restrizioni dell’exchange. Un sub-account, IP whitelist, permissions minime e withdraw permission disattivata limitano il rischio al saldo operativo.
🧯 Reazione al leak della key: arresto dell’esecuzione e conservazione delle tracce
Quando si sospetta un leak della coppia API Key + API Secret, il rischio si sviluppa rapidamente, perché l’exchange esegue operazioni subito dopo aver verificato firma, diritti, IP e tempo della richiesta. La reazione inizia con l’arresto dell’autorizzazione per la key e la conservazione delle tracce operative.
- Revoca della key lato exchange
- La disattivazione o eliminazione della key interrompe l’accettazione di richieste firmate con questa API Key.
- La disattivazione di tutte le keys del sub-account viene usata se la fonte del leak non è identificata.
- Conservazione delle tracce operative
- La lista degli ordini aperti e lo storico dei trade per il periodo dell’anomalia mostrano quali operazioni sono state eseguite.
- Lo storico dei prelievi e le modifiche alla whitelist degli indirizzi mostrano tentativi di prelievo e preparazione degli indirizzi.
- Chiusura di canali aggiuntivi di accesso all’account
- Il cambio password e la verifica 2FA riducono il rischio di accesso all’interfaccia web.
- La verifica della sicurezza dell’email è necessaria, perché conferme di prelievo e modifiche alla whitelist sono spesso collegate all’email.
- Ripristino dell’accesso operativo
- Una nuova key viene creata con permissions minime e IP whitelist sul server attuale.
- API Secret viene aggiornato nel secret manager, affinché il vecchio secret smetta di essere usato.
La revoca della key interrompe l’esecuzione delle azioni, perché l’exchange smette di accettare firme per questa API Key, anche se le richieste continuano ad arrivare.
✅ Configurazione che riduce il rischio di prelievo in caso di leak della key
Il rischio di prelievo dopo un leak della coppia API Key + API Secret si riduce quando la trade key non ha withdraw permission, le richieste sono limitate da IP whitelist e il capitale principale è separato dal trading sub-account.
Set minimo di parametri per la trade key di un trading system
- Il trading system funziona su un VPS con IP fisso, e questo IP è aggiunto alla IP whitelist della key.
- La key ha permissions read + trade e non ha withdraw permission.
- Il trading sub-account contiene il saldo operativo, mentre il capitale principale viene conservato separatamente senza trading keys permanenti.
- API Secret viene conservato in un secret manager o in un archivio cifrato e non entra in repository e log.
IP whitelist, permissions minime, whitelist degli indirizzi per prelievi rari e isolamento tramite sub-accounts limitano il danno al saldo operativo e riducono il rischio di prelievo su blockchain tramite una key compromessa.
❓ FAQ sulla sicurezza delle API keys
Perché IP whitelist protegge anche in caso di leak di API Secret?
L’exchange confronta l’IP della fonte della richiesta con la IP whitelist della key e rifiuta la richiesta se l’IP non corrisponde. La firma HMAC può essere corretta, ma l’operazione non verrà eseguita perché il controllo IP avviene lato exchange.
Quando withdraw permission è davvero necessaria?
Withdraw permission è necessaria per pagamenti operativi automatizzati su blockchain. Per trading, monitoraggio e reporting, withdraw permission non è necessaria, perché questi processi usano trading e read endpoints all’interno dell’exchange.
Perché una trade-only key può causare perdite senza prelievo?
Una trade-only key consente di inserire ordini. Con accesso a una trade-only key, un attaccante può eseguire trade a un prezzo peggiore su una coppia a bassa liquidità e creare una perdita da slippage, spread e commissioni quando nel trading wallet è presente un saldo elevato.
Perché usare un sub-account separato per ogni trading system?
Un sub-account limita il saldo disponibile per la key. In caso di leak della key del trading system, il danno è limitato agli asset di questo sub-account, perché l’exchange esegue operazioni all’interno del saldo dello specifico sub-account.
Come ruotare le keys senza perdere il controllo sugli ordini?
La rotazione include la creazione di una nuova key, il passaggio del trading system al nuovo API Secret e la revoca della vecchia key. Il passaggio viene pianificato in un periodo senza posizioni aperte e ordini limite attivi, affinché il cambio di key non interrompa la gestione degli ordini.
Come viene limitato il rischio nel collegamento di un terminale di terze parti?
Il rischio viene limitato da una trade-only key su un sub-account con saldo operativo, IP whitelist (se le richieste passano tramite un agente lato utente) e withdraw permission disattivata quando il terminale non partecipa ai prelievi operativi.
🧷 Come le restrizioni API riducono il rischio di prelievo e danno da trading
Il rischio API dipende dalle operazioni consentite e dalle verifiche che l’exchange applica a ogni richiesta: firma (API Secret), permissions, IP whitelist e parametri del tempo della richiesta.
- Withdraw permission disattivata blocca prelievi su blockchain tramite API, perché l’exchange rifiuta withdrawal endpoints per una key senza questo diritto.
- La whitelist degli indirizzi di prelievo limita il destinatario, perché l’exchange invia fondi solo a indirizzi aggiunti in anticipo.
- IP whitelist limita la fonte della richiesta, perché l’exchange rifiuta richieste da IP che non sono nella lista della key, anche con una firma corretta.
- Sub-accounts limita il volume delle perdite, perché la key ottiene accesso al saldo di uno specifico sub-account e non a tutti gli asset dell’account.