Le chiavi API forniscono a sistemi automatizzati, bot di trading, script operativi, pipeline di reportistica e sessioni di trading FIX accesso programmatico agli account della tua Organizzazione. Questo articolo illustra il modello di autorizzazione delle chiavi API, come le chiavi vengono associate agli account, come la governance dell'Organizzazione si applica alle operazioni avviate tramite chiave e come viene gestita l'amministrazione delle chiavi stesse.
Le chiavi API non sono Member dotati di credenziali. Seguono un modello di autorizzazione proprio, più semplice:
Membro | API key | |
|---|---|---|
Autenticazione | Accesso individuale con 2FA | Credenziali della chiave API |
Accesso all'interfaccia | Sì | No, solo tramite API |
Modello di autorizzazione | Workflow Profile + ruoli per account | Autorizzazioni della chiave API applicate agli account selezionati |
Variazione per account | Sì, i ruoli possono assegnare autorizzazioni diverse su account diversi | No, le autorizzazioni della chiave si applicano in modo uniforme a tutti gli account selezionati |
Può avviare richieste di prelievo e trasferimento | Sì, se consentito | Sì, se consentito |
Può approvare richieste | Sì, tranne le proprie | Mai |
Workflow amministrativi | Sì, in base al proprio Workflow Profile | Mai |
I due modelli sono deliberatamente distinti. I Member ricevono ruoli, profili e granularità per account perché le persone accumulano responsabilità diverse. Le chiavi seguono un modello piatto basato su ambito e account perché l'automazione deve essere circoscritta, uniforme e verificabile a colpo d'occhio.
Una chiave API racchiude due scelte: cosa può fare (i suoi permessi) e dove (i suoi account).
Permessi
Raggruppamento | Autorizzazione | Cosa consente |
|---|---|---|
Fondi | Consulta i fondi | Visualizza i saldi e lo stato dei versamenti |
Deposito | Genera indirizzi di deposito e visualizza lo storico dei depositi | |
Preleva | Avvia richieste di prelievo (vedi «Governance e chiavi API») | |
Guadagna | Alloca e dealloca prodotti Earn | |
Ordini | Consulta gli ordini aperti | Visualizza gli ordini aperti e i trade attivi |
Consulta gli ordini chiusi | Visualizza lo storico degli ordini e i trade completati | |
Crea e modifica gli ordini | Inserisci e modifica ordini | |
Cancella e chiudi ordini | Cancella ordini aperti e chiudi posizioni | |
Indirizzi | Aggiungi indirizzo di prelievo | Avvia richieste per aggiungere indirizzi in whitelist |
Aggiorna indirizzo di prelievo | Avvia richieste per modificare indirizzi in whitelist | |
Dati | Consulta il ledger | Visualizza lo storico delle transazioni e del ledger |
Esporta dati | Esporta i dati dell'account per reportistica e riconciliazione |
Associazione account
Ogni chiave è associata a uno o più account, selezionati al momento della creazione e modificabili in seguito. I permessi della chiave si applicano in modo uniforme a tutti gli account selezionati:
Connettività FIX
Le chiavi con permessi sugli ordini supportano la connettività FIX per lo spot trading, insieme alle API REST e WebSocket. Una sessione FIX eredita gli stessi permessi e la stessa associazione account della chiave collegata: opera esclusivamente sugli account selezionati per quella chiave, nei limiti dei suoi permessi. Le aziende che gestiscono flussi di ordini FIX dedicano in genere una chiave per sessione, circoscritta agli account su cui opera il desk.
Il trading tramite WebSocket su account diversi dall'account principale non è ancora disponibile per le chiavi API: per ora rimane una funzionalità riservata al titolare (Owner). I flussi di ordini automatizzati su account aggiuntivi dovrebbero usare REST o FIX. Consulta Disponibilità e limitazioni.
Impostazioni di sicurezza
Configurazione | Descrizione |
|---|---|
Scadenza della chiave | Data opzionale oltre la quale la chiave cessa di essere valida |
Data di inizio / fine query | Limita le query sui dati a un intervallo di date |
Connessioni WebSocket | Abilita o disabilita lo streaming in tempo reale |
Finestra nonce personalizzata | Ottimizzazione della protezione anti-replay per utilizzo ad alta frequenza |
Restrizioni IP | Limita l'utilizzo della chiave a indirizzi IP o intervalli CIDR specifici |
Assegna a ogni chiave i permessi minimi, il minor numero di account e le restrizioni IP più stringenti necessari per svolgere il suo compito. Usa chiavi separate per ogni sistema — una per il bot di trading, una per il reporting — in modo che la revoca sia mirata e senza effetti collaterali.
La governance dell'organizzazione si applica sia a ciò che le chiavi possono fare, sia a come vengono gestite.
Cosa possono fare le chiavi
La regola delle due categorie applicata ai Membri vale allo stesso modo per le chiavi:
Una chiave può soltanto avviare richieste soggette a governance. Le chiavi non possono mai approvare: la separazione dei ruoli richiede un Membro per ogni approvazione, e nessuno script può sostituire tale giudizio. Quando la policy delle richieste di prelievo richiede due approvazioni, un prelievo avviato da una chiave attende l'approvazione di due Membri, esattamente come uno avviato da un Membro.
Progetta l'automazione tenendo conto di questa asincronia: una chiamata API riuscita significa che la richiesta è stata creata, non che i fondi siano stati trasferiti. Monitora la richiesta fino al completamento e considera l'attuale limitazione per cui una richiesta in sospeso non riserva i fondi: se il saldo cambia durante la revisione, la richiesta approvata fallisce e va reinviata. Consulta Mantieni i fondi disponibili fino all'approvazione.
Le chiavi non hanno inoltre accesso ai flussi di lavoro amministrativi. La gestione degli accessi del team, delle chiavi API, degli account, degli indirizzi (al di là dell'avvio di richieste di indirizzo) e delle policy è riservata esclusivamente ai Membri.
Come vengono gestite le chiavi
La creazione, la modifica e la revoca delle chiavi API sono operazioni soggette a governance nell'ambito del workflow dedicato Gestisci chiavi API, separato da Gestisci team e accessi. Questa separazione ha due implicazioni importanti:
Il segreto della chiave viene mostrato una sola volta, al momento della creazione. Salvalo in modo sicuro prima di uscire dalla schermata: non sarà possibile recuperarlo in seguito.
La modifica dei permessi o degli account di una chiave e la revoca di una chiave seguono lo stesso percorso sottoposto a governance.
La chiamata ha creato una richiesta di prelievo, che la policy Richiesta di prelievo sta trattenendo in attesa di approvazione. Controlla la pagina Richieste: la richiesta risulta in elenco con la chiave come autore, in attesa delle approvazioni dei Member necessarie. Il modello di governance funziona come previsto: l'automazione propone, le persone approvano.
Se la richiesta è stata approvata ma i fondi non si sono mossi, verifica che il saldo di origine coprisse l'importo al momento del completamento: una richiesta in attesa non blocca i fondi, quindi l'attività durante la revisione può causare il fallimento di una richiesta già approvata. Reinvia la richiesta non appena il saldo è ripristinato.
L'account che genera l'errore non è incluso nel mapping degli account della chiave. Una chiave opera esclusivamente sugli account selezionati. Modifica la chiave per aggiungere l'account, tenendo presente che l'intero set di permessi si applicherà anche lì, poiché le chiavi non supportano variazioni per account. Se l'ambito risulta troppo ampio, crea una seconda chiave associata esclusivamente al nuovo account.
Una singola chiave non può avere permessi diversi per account. Crea due chiavi: una chiave di trading associata all'account A e una di sola lettura associata all'account B. Le chiavi con ambito più ristretto sono anche più facili da controllare e più sicure da revocare.
Il flusso di lavoro Gestione chiavi API richiede probabilmente un'approvazione e la richiesta è ancora in attesa. La chiave viene emessa e il relativo secret visualizzato solo dopo aver raccolto le approvazioni necessarie. Verifica lo stato della richiesta nella pagina Richieste.
No. L'approvazione richiede sempre l'intervento di un membro umano. Si tratta di una regola di sistema, non di una policy configurabile: è ciò che rende efficace l'approvazione multi-parte quando un'automazione avvia movimenti di fondi.