Come Collegare il Tuo Exchange a Freya Finance: le Chiavi API Spiegate
Prima che un bot possa operare per te, Freya ha bisogno di una connessione all'exchange dove risiedono i tuoi fondi — Binance, OKX o Bybit. Per farlo non sposti i tuoi fondi né condividi la tua password. Crei invece una chiave API: una credenziale limitata che consente a Freya di piazzare operazioni per tuo conto, mentre il tuo denaro resta sul tuo account dell'exchange.
Questa guida spiega esattamente quali permessi concedere (e quali non concedere mai), come aggiungere la chiave a Freya e cosa fare se la connessione non viene convalidata. Se vuoi il quadro più ampio sul perché tutto questo sia sicuro, leggi prima Il Mio Denaro è al Sicuro su Freya Finance?.
Key Takeaways
- Colleghi un exchange con una chiave API — una credenziale limitata — non spostando fondi o condividendo la password del tuo exchange.
- La chiave ha bisogno dei permessi di lettura e di trading Spot e/o Futures. Non deve MAI avere il permesso di prelievo.
- Le chiavi OKX richiedono una passphrase che imposti al momento della creazione; Binance e Bybit no.
- Aggiungi la chiave in Freya sotto Impostazioni → Chiavi API → Aggiungi Chiave API, e Freya la convalida istantaneamente.
- Se la convalida fallisce, Freya ti dice esattamente perché — chiave non valida, IP non in whitelist o un permesso mancante — e ognuno ha una soluzione semplice.
Una Rapida Panoramica dei Passaggi
- Crea una chiave API sul tuo exchange con i permessi di lettura e trading, ma non di prelievo.
- Copia le credenziali — la chiave API, il secret e (per OKX) la passphrase.
- Aggiungi la chiave a Freya sotto Impostazioni → Chiavi API → Aggiungi Chiave API, e seleziona il tuo exchange.
- Lascia che Freya la convalidi — Freya verifica immediatamente la connessione e i permessi.
- Risolvi qualsiasi errore segnalato — Freya ti dice esattamente cosa non va se la convalida fallisce.
Cos'è una Chiave API — e Quali Permessi Servono a Freya
Una chiave API è una coppia di credenziali (una chiave e un secret) che consente a un'app di comunicare con il tuo account dell'exchange in modo limitato. Sei tu a decidere cosa quella chiave può fare. Per Freya, abilita solo:
- Lettura — così Freya può vedere i tuoi saldi, le posizioni e lo stato degli ordini.
- Trading Spot e/o Trading Futures — così il tuo bot può piazzare gli ordini di cui ha bisogno. Abilita quello corrispondente ai bot che intendi eseguire.
Freya piazza operazioni; non ha mai bisogno di spostare denaro fuori dal tuo account. Lascia sempre il permesso di prelievo disabilitato sulla chiave che colleghi. Questo è un permesso che controlli tu sull'exchange — con esso disattivato, né Freya né chiunque dovesse ottenere la chiave può prelevare i tuoi fondi. È l'abitudine più importante nel collegare qualsiasi piattaforma di bot.
Passaggio 1: Crea una Chiave API sul Tuo Exchange
Nella sezione gestione API del tuo exchange, crea una nuova chiave API:
- Binance — crea la chiave sotto API Management, abilita la lettura e il trading Spot e/o Futures, e lascia i prelievi disattivati.
- OKX — crea la chiave e imposta una passphrase (ti servirà in Freya); abilita la lettura e il trading, non i prelievi.
- Bybit — crea la chiave con i permessi di lettura e di trading per i prodotti che utilizzerai, e lascia i prelievi disattivati.
Se il tuo exchange offre la whitelist degli IP, è buona pratica limitare la chiave agli indirizzi IP di Freya. Se lo fai, assicurati di inserire in whitelist gli IP di Freya, altrimenti la connessione verrà rifiutata (vedi la tabella degli errori più sotto).
Quando crei la chiave, l'exchange mostra il secret una sola volta. Copialo immediatamente e conservalo al sicuro. Se lo perdi, non puoi recuperarlo — dovrai eliminare la chiave e crearne una nuova.
Passaggio 2: Aggiungi la Chiave a Freya
In Freya, vai su Impostazioni → Chiavi API e seleziona Aggiungi Chiave API. Poi:
- Scegli il tuo exchange (Binance, OKX o Bybit).
- Incolla la chiave API e il secret. Per OKX, inserisci anche la passphrase che hai impostato.
- Dai un nome alla chiave così potrai riconoscerla in seguito.
Puoi collegare più di un exchange, e gestire o eliminare le tue chiavi da questa stessa pagina in qualsiasi momento.
Passaggio 3: Freya Convalida la Tua Chiave
Non appena aggiungi la chiave, Freya verifica la connessione e i permessi — niente congetture. Se tutto è corretto, la chiave è verificata e pronta all'uso. Se qualcosa non va, Freya mostra un messaggio chiaro che spiega esattamente cosa correggere.
Comprendere gli Errori di Convalida
Se la convalida fallisce, abbina il messaggio che Freya mostra alla soluzione qui sotto:
| Cosa mostra Freya | Cosa significa | Come risolverlo |
|---|---|---|
| Chiave API Non Valida | La chiave è stata copiata in modo errato o eliminata sull'exchange | Ricopia la chiave API con precisione, oppure creane una nuova |
| Secret Non Valido | Il secret non corrisponde alla chiave | Ricopia il secret; se lo hai perso, crea una nuova chiave |
| Indirizzo IP Non in Whitelist | La chiave è limitata per IP e l'indirizzo di Freya non è consentito | Inserisci gli IP di Freya in whitelist sulla chiave, oppure rimuovi la restrizione IP |
| Permessi Mancanti | Alla chiave mancano i permessi di lettura o di trading | Abilita la lettura e il trading Spot/Futures sulla chiave |
| Permesso di Lettura Disabilitato | Freya non può leggere il tuo account | Abilita il permesso di lettura/visualizzazione sulla chiave |
| Permesso Spot/Futures Disabilitato | La chiave non può piazzare gli ordini di cui il tuo bot ha bisogno | Abilita il tipo di trading (Spot o Futures) corrispondente al tuo bot |
| Connessione Fallita | Un problema temporaneo di rete o dell'exchange | Attendi un momento e prova ad aggiungere di nuovo la chiave |
Freya segnalerà anche una chiave in modalità «Unrestricted» — ovvero senza restrizione IP. Per la tua sicurezza, Freya ti chiede di attivare la restrizione IP e aggiungere l'indirizzo che mostra prima che la chiave possa essere salvata. Abilita solo la lettura e il trading (mai il prelievo), e limita la chiave all'IP di Freya. (Maggiori dettagli sugli errori di connessione in Non Riesci a Collegare il Tuo Exchange?.)
Una Nota sulla Sicurezza
La connessione è sicura per progettazione, ma alcune abitudini fanno sì che rimanga tale:
- Prelievo disattivato, sempre — Freya non ne ha mai bisogno.
- Usa la whitelist degli IP quando il tuo exchange la supporta.
- Una chiave, uno scopo — ed elimina le chiavi che non usi più.
Per il quadro completo di come i tuoi fondi e le tue chiavi sono protetti, vedi Il Mio Denaro è al Sicuro su Freya Finance? e Sicurezza delle API dell'Exchange e Mitigazione del Rischio.
Domande Frequenti
Quali permessi servono a Freya sulla mia chiave API?
Lettura (per vedere i tuoi saldi, le posizioni e gli ordini) e trading Spot e/o Futures (per piazzare gli ordini del tuo bot). Abilita il tipo di trading corrispondente ai bot che eseguirai. Freya non ha mai bisogno del permesso di prelievo, quindi lascialo sempre disabilitato.
Freya ha bisogno del permesso di prelevare i miei fondi?
No. Freya piazza e gestisce solo operazioni; non può e non deve poter spostare fondi fuori dal tuo exchange. Lascia sempre il permesso di prelievo disattivato sulla chiave che colleghi — è un permesso che controlli tu sull'exchange.
Perché Freya dice «Indirizzo IP Non in Whitelist»?
La tua chiave API è limitata a indirizzi IP specifici, e l'indirizzo di Freya non è nell'elenco. Aggiungi gli indirizzi IP di Freya alla whitelist della chiave sul tuo exchange, oppure rimuovi la restrizione IP dalla chiave. Dopo averla aggiornata, aggiungi di nuovo la chiave in Freya.
Perché dice «Chiave API Non Valida» o «Secret Non Valido»?
Di solito la chiave o il secret sono stati copiati in modo errato, oppure la chiave è stata eliminata o rigenerata sull'exchange. Ricopia entrambi i valori con precisione. Poiché il secret viene mostrato solo una volta al momento della creazione della chiave, se non lo hai più, elimina la chiave sull'exchange e creane una nuova.
Cos'è la passphrase e perché OKX la richiede?
Le chiavi API OKX includono una passphrase che imposti tu stesso quando crei la chiave — è una credenziale aggiuntiva accanto alla chiave e al secret. Inserisci la stessa passphrase in Freya quando aggiungi una chiave OKX. Binance e Bybit non usano una passphrase.
Posso collegare più di un exchange?
Sì. Puoi aggiungere chiavi API per Binance, OKX e Bybit, e gestirle o eliminarle in qualsiasi momento da Impostazioni → Chiavi API.
È sicuro dare a Freya la mia chiave API?
Sì, quando la chiave è configurata correttamente — solo lettura e trading, nessun prelievo e, dove possibile, con whitelist IP. I tuoi fondi restano sul tuo exchange, e la chiave che condividi non può spostarli. Per la spiegazione completa, vedi Il Mio Denaro è al Sicuro su Freya Finance?
Quali exchange supporta Freya?
Freya attualmente si collega a Binance, OKX e Bybit (spot e futures). Altri exchange potrebbero essere aggiunti nel tempo. Fai trading su quello tra questi che colleghi — i tuoi fondi e i mercati disponibili restano su quell'exchange.
Quali monete o coppie di trading posso scambiare?
Le coppie disponibili provengono dai listini del tuo exchange collegato, non da un elenco separato di Freya — quindi se il tuo exchange elenca una coppia (es. BTC/USDT, ETH/USDT), puoi costruirci un bot. La maggior parte del trading avviene contro USDT come valuta di quotazione. Se un exchange rimuove una coppia dal listino, questa smette di essere negoziabile lì.