Come collegare in sicurezza l'account dell'exchange a uno strumento di terze parti (API in sola lettura)

Probabilmente ti ha portato qui uno scenario del genere: hai installato un'app di contabilità o di tracciamento del portafoglio, e ti dice «collega il tuo account dell'exchange e sincronizzerai le posizioni in automatico, senza inserirle a mano». Ti alletta, ma la mano si ferma: se collego l'account a uno strumento che non conosco, non potrebbe di nascosto trasferirmi via le monete? È una preoccupazione più che legittima. La buona notizia è che la stragrande maggioranza degli strumenti di tracciamento seri non si collega affatto con un permesso che «può muovere i tuoi fondi», bensì con una chiave che può solo vedere, non muovere. A patto che sia tu ad attivarla come «può solo vedere». Questa guida scompone la cosa nei dettagli, così ti colleghi con serenità e con cognizione di causa.

Perché gli strumenti di contabilità e tracciamento si collegano via API

Chiariamo prima cosa ci fanno. Il compito centrale di uno strumento di gestione del portafoglio o di un software di contabilità e dichiarazione fiscale è comporre in un quadro completo gli asset che hai sparsi qua e là: quanti BTC e quanti USDT hai sull'exchange, il prezzo medio di acquisto, se questo mese sei in guadagno o in perdita. Questi numeri o li inserisci a mano uno per uno (faticoso e soggetto a errori) oppure lasci che sia lo strumento a «leggerli» direttamente dall'exchange.

Questa azione di «lettura» si basa proprio sull'API. Puoi immaginarla come una finestra sui dati che l'exchange mette a disposizione: consegni una chiave designata a un programma, e quel programma può guardare attraverso la finestra cosa c'è nel tuo account e quali sono gli scambi recenti. Ciò che vede dipende da cosa quella chiave è autorizzata a vedere. Per la spiegazione ufficiale del meccanismo puoi consultare la documentazione API di OKX o la pagina di presentazione delle API di Binance: non serve capire tutto, basta assimilare il concetto che «l'API è l'interfaccia di programmazione fornita ufficialmente dall'exchange». Per vedere come una singola piattaforma gestisce i permessi in fase di creazione, la guida di Kraken alla creazione di una API key è un esempio scritto in modo piuttosto dettagliato.

Il valore del collegamento via API è quindi molto diretto: elimina l'inserimento manuale, e saldi e scambi si conciliano da soli. Ma il rischio nasce dallo stesso punto: hai consegnato una chiave che può accedere all'account. Se la chiave è configurata bene, è solo un innocuo lettore di dati; se è configurata male, può diventare la porta d'ingresso con cui qualcuno ti svuota l'account. Il resto di questa guida parla in sostanza di come configurare bene quella chiave.

Cosa sono davvero API key, secret e passphrase

Quando «crei un'API» sull'exchange, di solito ottieni due o tre stringhe di caratteri apparentemente casuali, chiamate in genere API Key e Secret Key; su alcuni exchange (come OKX) ce n'è anche una terza, la Passphrase. La prima volta un po' disorienta, ma la corrispondenza è facile da ricordare:

Il punto chiave da capire è: una volta generata la Secret Key e chiusa la pagina, nemmeno l'exchange te la mostra più — appare una sola volta, al momento della creazione. Questo significa due cose: primo, devi salvarla subito (su come farlo c'è una sezione apposta più avanti); secondo, se la fai trapelare non puoi rimediare «cambiando password», puoi solo invalidare l'intera chiave e ricrearla.

Un altro equivoco frequente tra i principianti: la API key non è la tua password di accesso, non serve per entrare nel sito o nell'app, non può cambiare il tuo indirizzo di prelievo né le impostazioni di sicurezza. Le sue capacità sono rigidamente limitate ai «pochi permessi che hai selezionato in fase di creazione». Ecco perché come spunti quei permessi è ciò che davvero decide la sicurezza.

Permesso in sola lettura: è la sezione più importante di tutta la guida

Se di questa guida leggi una sola sezione, leggi questa.

Sulla maggior parte degli exchange, in fase di creazione dell'API i permessi si spuntano separatamente; le categorie più comuni sono:

• Lettura / Read (da attivare): consente di consultare saldo, posizioni, storico degli scambi, estratti conto. A uno strumento di tracciamento serve solo questo.
• Trading / Trade (di norma da non attivare): consente di piazzare e annullare ordini al posto tuo. Serve solo se vuoi esplicitamente usare strumenti tipo «trading automatico» o «bot di copy trading», e i rischi di quel tipo di strumenti sono un altro discorso, che affrontiamo nella guida Copy trading e rischi dei bot.
• Prelievo / Withdraw (da non attivare mai): consente di trasferire monete fuori dal tuo account. Nessuno strumento di contabilità o tracciamento ha bisogno di questo permesso. Attivarlo equivale a consegnare a terzi il diritto di ritiro dalla tua cassaforte.

Perché questo punto è così cruciale? Perché i permessi sono il «soffitto» della sicurezza dell'API. Anche se lo strumento viene violato, anche se il suo server viene attaccato, anche se lo sviluppatore ha cattive intenzioni, finché la tua chiave ha solo il permesso di lettura, il risultato peggiore è che qualcuno veda i tuoi dati sulle posizioni (certo non è bello, ma è di un ordine di grandezza diverso rispetto a farsi trasferire via i fondi). Se invece ti scappa e attivi il permesso di prelievo, quella chiave diventa una chiave che preleva direttamente denaro, e la sicurezza si gioca tutta sul «questo strumento non avrà mai problemi»: una scommessa che non vale la pena.

Una nota su una misura di sicurezza comune: molti exchange, anche se hai attivato il permesso di prelievo, al momento del prelievo effettivo aggiungono ulteriori limiti come verifica in due passaggi, indirizzi in whitelist e ritardi (è anche il motivo per cui le piattaforme in genere consigliano vivamente di disattivare il prelievo via API). Ma non dovresti affidare la tua sicurezza a questi meccanismi di riserva. Non attivarlo alla fonte è l'approccio più pulito. Sui principi generali di sicurezza di chiavi e credenziali, valgono la spiegazione delle API su Investopedia e le pagine di sicurezza dei singoli exchange; per consigli generici sulla custodia di password e credenziali, puoi vedere anche la checklist sulle password della FTC statunitense.

Whitelist IP: un lucchetto in più

Dopo aver spuntato solo il permesso di lettura, se vuoi un livello di sicurezza in più puoi usare la «whitelist IP» (chiamata anche restrizione IP o binding IP). In pratica: questa chiave può inviare richieste solo dagli indirizzi IP che specifichi tu, e altrove non funziona nemmeno se qualcuno ce l'ha in mano.

Per gli strumenti di tracciamento, un fornitore serio di solito indica nella sua documentazione un elenco del tipo «aggiungi questi IP alla whitelist»: sono gli IP di uscita dei suoi server. Inserendo quegli IP nella whitelist dell'exchange, è come dire all'exchange: «accetta solo i server di questo strumento, rifiuta tutto il resto». Così, anche se la chiave dovesse trapelare, un attaccante dalla propria macchina non riuscirebbe a usarla.

Un altro promemoria: se scrivi uno script per te e leggi i dati a uso personale, la whitelist IP è quasi d'obbligo, perché il tuo IP di casa o del server è di solito fisso o controllabile. Per gli strumenti SaaS di terze parti, se e come impostarla dipende dalla documentazione del fornitore.

Come custodire le chiavi senza lasciarle in giro alla rinfusa

Come detto, la Secret Key si mostra una sola volta. In quel momento devi salvarla bene. Ma «salvarla bene» non significa «incollarla al volo nei preferiti di una chat / in un promemoria / in un file txt sul desktop»: sono proprio i posti in cui non andrebbe messa. Abbiamo visto troppe persone che, per fare prima, si sono ritrovate la chiave trapelata il giorno in cui hanno cambiato telefono o quando il promemoria si è sincronizzato su un account compromesso.

Alcuni principi semplici per custodire una API key:

• Non salvarla in chiaro dove si sincronizza o dove qualcuno può curiosare. Preferiti delle app di chat, note su cloud non cifrate, bozze delle email sono tutti ad alto rischio.
• Salvala in un gestore di password. Un gestore di password serio (di quelli con cifratura tramite password principale) è fatto proprio per questo, molto meglio di un file txt. Salva API Key / Secret / Passphrase come un blocco di «password».
• Se puoi non salvarla, non salvarla. Molti strumenti SaaS di tracciamento fanno inserire la chiave nella loro pagina e la custodiscono loro: in locale non serve tenerne una copia a lungo. Una volta inserita e verificato che funziona, cancella la copia temporanea che avevi salvato. Se cambi strumento, al massimo ne ricrei una.
• Una chiave per un solo uso. Non usare la stessa chiave per alimentare tre o quattro strumenti insieme. Creane di separate: se uno strumento ha problemi, revochi solo quella chiave senza coinvolgere le altre.

Lo spirito di questa sezione è in fondo lo stesso della custodia della seed phrase di un wallet: la sequenza di caratteri più sensibile determina il limite inferiore della tua esposizione agli attacchi, quindi deve stare nel posto più difficile da raggiungere. La differenza è che la fuga di una API key, al massimo, espone dati in sola lettura (a patto che tu non abbia attivato il prelievo), mentre la fuga della seed phrase significa perdere direttamente le monete: quest'ultima è molto più grave, ma prima si costruiscono le buone abitudini di igiene, meglio è.

Rotazione e revoca periodica: anche le chiavi hanno una scadenza

Molti creano un'API e poi non se ne occupano più: una chiave attivata anni fa per uno strumento disinstallato da tempo è ancora oggi attiva e collegata all'account. È un rischio latente. La buona abitudine è trattare le API key come «cose che scadono»:

• Fai un inventario periodico. Ogni tanto (per esempio ogni trimestre) accedi alla pagina di gestione API dell'exchange e controlla quali chiavi sono ancora attive e a chi le hai date. Quelle che non riconosci o che non usi da tempo, cancellale.
• Smesso di usare uno strumento, revoca la chiave. Se disinstalli un'app di tracciamento, revoca subito anche la chiave corrispondente sull'exchange. Cancellare l'app non annulla l'autorizzazione: l'autorizzazione sta dal lato dell'exchange e devi disattivarla tu.
• Nel dubbio, ruota. Anche solo per un «di questo strumento girano notizie poco chiare» o «mi sa che l'ho inserito su una rete non sicura», vale la pena creare una nuova chiave e revocare la vecchia. Il costo della rotazione è basso (basta ricollegare), ma taglia in modo netto i rischi che la vecchia chiave potrebbe portare.

Fin dove arriva uno strumento di terze parti che legge i tuoi dati

Anche avendo concesso solo il permesso di lettura, vale la pena chiarirsi: cosa può vedere davvero questo strumento di me, cosa non può vedere e cosa farà con questi dati.

Ciò che può vedere sono i dati dell'account nel raggio d'azione della chiave: saldo, posizioni, storico degli scambi, movimenti degli estratti conto e simili. In altre parole, può ricostruire «quanti soldi hai su questo exchange e cosa hai comprato e venduto». È necessario per uno strumento di contabilità, ma devi renderti conto che si tratta di informazioni finanziarie piuttosto riservate.

Ciò che non può vedere sono le tue credenziali di accesso, la password di prelievo, la verifica in due passaggi, la carta bancaria. Attraverso il canale dell'API queste cose non passano affatto, quindi anche se il database del fornitore venisse violato, un attaccante non otterrebbe le tue credenziali di accesso (di nuovo: a patto che tu non abbia attivato il permesso di prelievo, altrimenti la storia cambia).

Ciò su cui devi vigilare tu è se questo fornitore è affidabile e come tratta i tuoi dati. Nello scegliere uno strumento, guarda con più attenzione: ha un'informativa privacy chiara? È un prodotto noto e con una reputazione verificabile nel tempo, oppure spuntato da poco e di provenienza incerta? Nelle recensioni singole come CoinStats e Koinly mettiamo sempre «modalità di connessione, quali permessi richiede, come tratta i dati» tra i punti da guardare per forza; per un confronto, nella tabella comparativa strumenti vedi a colpo d'occhio la soglia di connessione di ciascuno. A chi affidi i dati conta più di come li affidi.

Come si crea, a grandi linee, una chiave in sola lettura su OKX

Prendiamo OKX come esempio e vediamo il procedimento generale per creare un'API in sola lettura. Un avvertimento prima: su ogni exchange i nomi delle voci, la posizione dei pulsanti e la denominazione dei permessi cambiano con gli aggiornamenti di versione, quindi l'interfaccia concreta fa fede sulla pagina ufficiale attuale; qui ti diamo solo una mappa di «cosa cercare, cosa spuntare».

1. Trova la voce di gestione API. Di solito, dentro «Impostazioni account / Impostazioni di sicurezza» trovi la voce «API» o «Gestione API». Accedi ed entra lì.
2. Crea una nuova API. Clicca un pulsante tipo «Crea API». Il sistema ti farà dare un nome alla chiave (a scopo promemoria: scrivi chiaramente «per lo strumento di contabilità tal dei tali», così poi la riconosci nell'inventario) e impostare una Passphrase (su OKX c'è questa voce, tienila a mente).
3. Spunta solo «Lettura / sola lettura». È il passaggio più importante: lascia vuote tutte le spunte di trading e prelievo, tieni solo la lettura. Se vedi opzioni relative a «Withdraw / Prelievo», assicurati che siano disattivate.
4. Se puoi, imposta la whitelist IP. Se lo strumento che usi fornisce IP fissi dei server, inseriscili nel binding IP; se è uno script a uso personale, metti il tuo IP. Se non è possibile, lascia vuoto per ora e affidati al permesso di sola lettura.
5. Completa la verifica di sicurezza e salva bene le stringhe restituite. L'exchange di solito ti fa passare una verifica in due passaggi. Superata, mostrerà API Key / Secret Key (e Passphrase). La Secret si mostra solo questa volta: salvala subito con il metodo della quinta sezione.
6. Torna nello strumento, inseriscile e collega. Inserisci queste stringhe nella pagina «Collega exchange» dello strumento di tracciamento e, una volta connesso, verifica che i saldi coincidano. Se coincidono, puoi cancellare la copia temporanea.

Le indicazioni ufficiali di OKX sulle API si raggiungono dalla documentazione API di OKX; se usi un altro exchange, per esempio Binance, la documentazione corrispondente è sulla pagina API di Binance; la documentazione per sviluppatori di Coinbase è sulla piattaforma Coinbase Developer. Il principio «sola lettura, niente prelievo» è lo stesso per tutti: cambia solo come si chiama il pulsante e dove si trova.

Cosa fare se una chiave trapela

Niente panico, procedi con ordine. Se hai attivato solo il permesso di lettura, anche se la chiave trapela l'altra parte può solo vedere i tuoi dati, non muovere i tuoi fondi: è proprio tutto il senso per cui, fin dall'inizio, abbiamo insistito sulla «sola lettura». Ma le misure da prendere non vanno saltate:

1. Revoca subito quella chiave. Accedi alla pagina di gestione API dell'exchange e cancella direttamente la chiave trapelata. Cancellandola diventa subito inutilizzabile: è il modo più rapido e completo di fermare l'emorragia.
2. Controlla se l'account presenta anomalie. Guarda lo storico degli accessi e se ci sono attività non avviate da te. Se per sbaglio avevi attivato il permesso di trading o prelievo, controlla subito posizioni e storico dei prelievi e, se necessario, contatta l'assistenza ufficiale e congela le relative funzioni seguendo le indicazioni della piattaforma.
3. Sostituisci le credenziali coinvolte. Se sospetti che la fuga sia dovuta a un'intrusione nell'account (e non solo alla chiave in sé), aggiorna anche password di accesso e verifica in due passaggi, e verifica se il dispositivo è stato compromesso.
4. Ricrea una chiave pulita. Accertato che l'ambiente è sicuro, crea una nuova chiave per lo strumento seguendo il principio della sola lettura e questa volta imposta anche la whitelist IP.

In definitiva, la risposta al «cosa fare se qualcosa va storto» è per l'80% già scritta prima: se all'inizio hai spuntato solo la sola lettura, poi è solo un grande spavento; se ti è scappato di attivare il prelievo, poi è una vera crisi. Ecco perché questa guida torna sempre allo stesso punto: ridurre i permessi al minimo è l'assicurazione più economica ed efficace che puoi darti.

Una checklist rapida

Ecco quanto sopra condensato in poche voci da confrontare quando crei una chiave:

Collegare un'API, a ben vedere, non è così spaventoso: è solo una chiave che controlli del tutto tu. Quanto le fai vedere, da dove può essere usata, quando invalidarla: tutto è nelle tue mani. Tieni fermo il limite della «sola lettura» e il resto è comodità e risparmio di tempo. Una volta configurato, torna a leggere come scegliere uno strumento di gestione del portafoglio, oppure usa la tabella comparativa strumenti per sceglierne uno con una soglia di connessione che ti va bene, e delega a lui il lavoro noioso della contabilità.

I nomi dei permessi e le posizioni nell'interfaccia citati in questo articolo sono verificati a giugno 2026; gli exchange li modificano con le versioni, fa fede quanto mostrato attualmente sulle pagine ufficiali.