Quando aggiungi una chiave API dell'exchange, Freya la verifica prima di salvarla — e se qualcosa non va, ti dice cosa correggere. Questa guida ti aiuta a leggere quel risultato e a risolverlo. (Se la tua chiave si era già connessa correttamente ma un bot si è poi fermato, quello è un problema diverso — vedi Perché il Mio Bot si è Messo in Pausa o si è Fermato?.)
Per i passaggi della configurazione iniziale, parti da Come Connettere il Tuo Exchange; questo articolo riguarda cosa fare quando quella connessione fallisce.
Punti chiave
- Quando aggiungi una chiave, Freya verifica che si connetta e abbia i permessi corretti prima di salvarla — se qualcosa fallisce, l'errore ti dice cosa correggere.
- «Chiave/Segreto API Non Valido» di solito indica un errore di copia/incolla o una chiave rigenerata; gli errori «IP» indicano che la restrizione IP della chiave non corrisponde a ciò di cui Freya ha bisogno.
- La tua chiave deve avere i permessi di lettura e trade (mai di prelievo) ed essere abilitata per il mercato giusto — spot o futures — per corrispondere al tuo bot.
- Le chiavi OKX richiedono una passphrase che deve corrispondere esattamente; per le chiavi futures, Freya prepara automaticamente il tuo conto affinché il bot possa operare correttamente.
- Un generico «Connessione Fallita» è spesso un problema momentaneo di rete o dell'exchange — basta riprovare.
Quando una Chiave Non si Connette
Aggiungere una chiave non è un salvataggio alla cieca — Freya verifica che la chiave funzioni e abbia i permessi corretti prima che venga memorizzata, cifrata. Se qualcosa non va, l'errore ti indica direttamente la causa — di solito la chiave o il segreto, la restrizione IP o un permesso mancante. Le sezioni seguenti illustrano ciascun errore e come risolverlo.
«Chiave API Non Valida» o «Chiave Segreta Non Valida»
L'errore di connessione più comune, e di solito il più semplice:
- Un errore di copia/incolla — uno spazio di troppo o un carattere mancante. Ricopia con attenzione sia la chiave sia il segreto.
- Il segreto viene mostrato una sola volta. Gli exchange rivelano la chiave segreta una singola volta quando la crei. Se non l'hai salvata, non puoi recuperarla — crea una nuova chiave.
- La chiave è stata eliminata o rigenerata sull'exchange, quindi non corrisponde più.
Soluzione: reinserisci la chiave e il segreto esattamente, oppure crea una nuova chiave e riprova.
Errori di Restrizione IP
Freya si connette dai propri server, quindi le impostazioni IP della chiave sono importanti. Ci sono due casi distinti:
- «IP Non in Whitelist» — la tua chiave ha restrizioni IP, ma l'indirizzo del server di Freya non è nel suo elenco di indirizzi consentiti. La schermata Aggiungi Chiave API ti mostra l'indirizzo (o gli indirizzi) IP da aggiungere (con un pulsante per copiarli) — aggiungili alla whitelist della chiave sull'exchange.
- «Unrestricted» — la tua chiave non ha alcuna restrizione IP. Per la tua sicurezza, Freya ti chiede di attivare la restrizione IP e aggiungere l'indirizzo che mostra, poi riprova.
In entrambi i casi la soluzione segue la stessa idea: limitare la chiave all'IP che Freya visualizza nella finestra.
Errori di Permessi
La chiave si è connessa, ma non può fare ciò di cui il tuo bot ha bisogno:
- Lettura disabilitata — abilita il permesso di lettura/visualizzazione sulla chiave.
- Permesso di trade mancante — abilita il trading (spot e/o futures, in base al tuo bot).
- Discrepanza tra Spot e Futures — un bot futures ha bisogno di una chiave con il trading futures abilitato; un bot spot ha bisogno del trading spot. Se hai aggiunto una chiave solo-spot per un bot futures (o viceversa), Freya lo segnala. Assicurati che il mercato abilitato sulla chiave corrisponda al bot che stai creando.
Ricorda: a Freya servono sempre e solo i permessi di lettura e trade — mai di prelievo. Una chiave senza permesso di prelievo è esattamente ciò che desideri.
Particolarità Specifiche degli Exchange
- OKX richiede una passphrase. Quando crei una chiave OKX, imposti una passphrase — inserisci quella stessa passphrase in Freya, esattamente come l'hai impostata. Una passphrase errata è una causa comune di fallimento della connessione OKX.
- Configurazione futures OKX. Il trading futures OKX richiede una specifica modalità del conto, che Freya configura automaticamente per te — non devi impostarla manualmente.
- Modalità Hedge (futures). Freya usa la modalità hedge per i conti futures. Se hai già posizioni One-Way aperte che sono in conflitto, potresti vedere un avviso anziché un errore — la chiave viene comunque salvata, e il tuo bot potrà operare una volta chiuse quelle posizioni esistenti.
- Binance e Bybit non usano una passphrase — per loro non c'è alcun campo passphrase.
«Connessione Fallita» Senza un Motivo Chiaro
Un generico fallimento della connessione spesso non è colpa tua — un momentaneo problema di rete o l'exchange temporaneamente occupato. Attendi un istante e riprova. Se continua a fallire dopo alcuni tentativi, ricontrolla la chiave/il segreto e le impostazioni IP viste sopra.
Ancora Bloccato? Una Rapida Checklist
- Ricrea la chiave sull'exchange con solo lettura + trade (mai prelievo).
- Limitala all'IP che Freya mostra nella schermata Aggiungi Chiave API.
- Fai corrispondere il mercato — chiave spot per un bot spot, chiave futures per un bot futures.
- OKX: inserisci la passphrase esatta.
- Continua a fallire? Contatta [email protected].
Domande Frequenti
Freya dice «Chiave API Non Valida» ma sono sicuro di averla copiata correttamente — cosa c'è che non va?
Di solito un carattere nascosto o uno spazio si è insinuato nella chiave o nel segreto, oppure la chiave è stata rigenerata/eliminata sull'exchange e non corrisponde più. Ricopia con attenzione entrambi i campi, e ricorda che il segreto viene mostrato solo una volta al momento della creazione — se non ce l'hai, crea una nuova chiave.
Qual è la differenza tra «IP Non in Whitelist» e «Unrestricted»?
«IP Non in Whitelist» significa che la tua chiave ha restrizioni IP ma l'indirizzo del server di Freya non è ancora consentito — aggiungi alla whitelist della chiave l'indirizzo che Freya mostra. «Unrestricted» significa che la chiave non ha alcuna restrizione IP; per sicurezza, Freya ti chiede di attivare la restrizione IP e aggiungere il suo indirizzo prima di salvare.
La mia chiave OKX non si connette — mi serve la passphrase?
Sì. Le chiavi OKX hanno una passphrase che imposti quando crei la chiave. Devi inserire quella passphrase esatta in Freya — una passphrase errata o mancante è una causa comune di fallimento della connessione OKX. Binance e Bybit non ne usano una.
Freya dice che la mia chiave non può piazzare trade — come lo risolvo?
La tua chiave non ha il trading abilitato per il mercato che il tuo bot usa. Sull'exchange, abilita il permesso di trade — trading spot per un bot spot, trading futures per un bot futures — poi riconnetti. A Freya servono i permessi di lettura e trade, mai di prelievo.
La mia chiave futures richiede una configurazione aggiuntiva (modalità del conto / modalità hedge) — è un problema?
No. Il trading futures richiede una specifica modalità del conto e la modalità hedge, che Freya configura automaticamente per te. Se hai posizioni One-Way esistenti, potresti vedere un avviso di modalità hedge anziché un errore — la chiave viene comunque salvata, e il tuo bot potrà operare una volta chiuse quelle posizioni.
Ho aggiunto una chiave spot ma il mio bot futures non la usa (o viceversa) — perché?
Una chiave è abilitata per un mercato specifico. Un bot futures ha bisogno di una chiave con il trading futures abilitato, e un bot spot ha bisogno del trading spot. Se non corrispondono, Freya lo segnala. Connetti una chiave il cui mercato abilitato corrisponda al bot che stai creando.
La connessione è semplicemente «fallita» senza un motivo chiaro — è colpa mia o dell'exchange?
Spesso è un problema momentaneo di rete o dell'exchange piuttosto che delle tue impostazioni. Riprova tra un istante. Se continua a fallire, ricontrolla la chiave e il segreto per errori di copia e conferma che la restrizione IP corrisponda all'indirizzo che Freya mostra.