Configurazione della chiave API WEEX: autorizzazioni, associazione IP e limiti

Creare una chiave API WEEX richiede circa due minuti, e le decisioni prese in quella schermata determinano cosa potrebbe fare in seguito una chiave rubata sul tuo account. Ogni nuova chiave parte in modalità Read Only. Aggiungi l’ambito di trading Spot o Futures/Contract solo se un programma deve inviare ordini, puoi associare la chiave a indirizzi IP specifici e puoi avere al massimo 10 gruppi di chiavi API per account. Non esiste alcun ambito di prelievo. Questa guida illustra la configurazione, spiega il ruolo di ciascuna delle tre credenziali, mostra quale combinazione di permessi è adatta a ogni caso d’uso e tratta i piccoli dettagli operativi che spesso causano problemi, come la passphrase irrecuperabile e il breve ritardo prima che una nuova chiave inizi a funzionare.

Da cosa è composta realmente una chiave API WEEX

Quando crei una chiave, WEEX rilascia tre stringhe separate, ciascuna con una funzione distinta. Confonderle è il motivo più comune per cui la prima richiesta fallisce con un errore di autenticazione.

• APIKey: l’identificatore pubblico. Va nell’header ACCESS-KEY di ogni richiesta. Chiunque lo veda non ricava nulla di utile da solo.
• SecretKey: la chiave privata di firma. Non viaggia mai in una richiesta. Il tuo codice la usa per calcolare una firma HMAC SHA256 su timestamp, metodo HTTP, percorso della richiesta e corpo, quindi codifica il risultato in Base64 nell’header ACCESS-SIGN.
• Passphrase: una stringa scelta durante la creazione della chiave. Viene inviata nell’header ACCESS-PASSPHRASE sugli endpoint privati. WEEX dichiara chiaramente nella sua documentazione API che una passphrase persa non può essere recuperata; l’unica soluzione è creare una nuova chiave.

Conseguenza pratica: SecretKey e Passphrase vengono mostrate una sola volta. Copiale entrambe nel tuo gestore dei segreti prima di chiudere la scheda. Se ne perdi una, elimina il gruppo di chiavi e ricomincia invece di provare a indovinare.

Come creare una chiave API WEEX passo dopo passo

La procedura è uguale per spot e futures. Cambia solo l’ambito di trading selezionato.

1. Accedi dal Web e apri Gestione API nel menu del tuo account (il percorso della pagina è /account/newapi). Ti verrà richiesto il normale 2FA.
2. Dai alla chiave il nome del programma che la utilizzerà, ad esempio grid-bot-vps-a o portfolio-tracker. I nomi diventano importanti quando gestisci più chiavi.
3. Imposta una passphrase. Conservala subito.
4. Lascia il permesso su Read Only, a meno che quel programma specifico debba inserire o annullare ordini. In tal caso, abilita esattamente un ambito di trading: Spot per i mercati spot oppure Futures/Contract per i perpetual. Non abilitarli entrambi «per sicurezza».
5. Associa la chiave all’indirizzo o agli indirizzi IP della macchina che chiamerà l’API. La documentazione WEEX è chiara: una chiave senza associazione IP «comporta rischi per la sicurezza».
6. Completa il 2FA per confermare. Copia APIKey e SecretKey.
7. Attendi prima di testare. La guida API di WEEX nella sezione Learn indica che una chiave appena creata o modificata può impiegare circa 15 minuti per propagarsi globalmente; quindi un 401 immediato non è necessariamente un bug del tuo codice.

Un buon primo test è una chiamata pubblica non autenticata, seguita da una chiamata firmata in sola lettura, come una richiesta del saldo dell’account. Solo dopo il successo di entrambe dovresti provare un endpoint di trading.

Quali permessi API WEEX abilitare per ogni caso d’uso

Il modello dei permessi è volutamente ridotto, quindi è facile da valutare. Oltre alla lettura predefinita esistono due ambiti indipendenti, e nient’altro.

Read Only è sufficiente per più programmi di quanto si pensi. Un tracker del portafoglio, un export fiscale, un avviso Telegram sulle esecuzioni, una dashboard delle posizioni aperte e un monitor del funding rate: nessuno di questi deve inserire ordini. Mantienili in sola lettura. Se la chiave trapela, l’aggressore può vedere saldi e cronologia, cosa spiacevole, ma non può spostare nulla.

L’ambito di trading Spot è per i programmi che comprano e vendono su coppie spot: script DCA, bot grid spot e ribilanciatori. Non concede accesso ai futures.

L’ambito di trading Futures/Contract è per l’automazione dei futures perpetual: strategie trend-following, coperture del funding rate e script di protezione dalla liquidazione che chiudono le posizioni. Non concede accesso allo spot. Poiché la leva amplifica i danni che un programma malfunzionante può causare, questo è l’ambito da proteggere con più attenzione e quello che giustifica maggiormente l’associazione IP.

Ciò che non è disponibile sono i prelievi. A differenza di diversi exchange che espongono un ambito di prelievo da lasciare disattivato, la documentazione API WEEX per spot e futures elenca solo i tipi di permesso Read e Trade. Spostare fondi fuori dall’exchange richiede ancora il flusso Web o app, con il proprio 2FA e i controlli sugli indirizzi. Questo limite è la cosa più importante da capire sulla sicurezza delle chiavi API WEEX: una chiave di trading divulgata non può effettuare prelievi. Cosa può fare e come gli aggressori la sfruttano comunque sarà il tema del prossimo articolo della serie.

Il limite di 10 chiavi e come utilizzarlo

WEEX consente fino a 10 gruppi di chiavi API per account. Sembra generoso finché non inizi a gestire correttamente le chiavi, cioè una chiave per programma e per macchina.

Una distribuzione sensata per un utente attivo è questa: una chiave in sola lettura per un tracker, una per gli export fiscali, una chiave Spot per un bot DCA su un server domestico, una chiave Futures/Contract per una strategia su VPS, una chiave Futures/Contract per una seconda strategia sullo stesso VPS e due o tre chiavi di riserva per la rotazione, così da poter emettere una sostituta prima di revocare quella vecchia. Sono già sette o otto slot.

Due abitudini aiutano a restare entro il limite. Primo, elimina le chiavi appena un programma viene dismesso; una chiave dimenticata con ambito di trading e senza associazione IP è il classico rischio silenzioso. Secondo, non condividere mai una chiave tra due programmi per risparmiare uno slot. Se uno dei due funziona male o perde la chiave, dovrai revocarla per entrambi e non potrai capire dalla cronologia degli ordini quale abbia eseguito una determinata operazione.

Firme, timestamp ed errori che sembrano problemi di permessi

Molti errori che i nuovi integratori attribuiscono ai permessi sono in realtà problemi di firma o di orologio. Conoscere le regole fa risparmiare un pomeriggio.

Il messaggio della firma è la concatenazione del timestamp in millisecondi, del metodo HTTP in maiuscolo, del percorso della richiesta, della query string se presente (con il suo ? iniziale) e del corpo JSON se presente. La stringa viene firmata con HMAC SHA256 usando la SecretKey e codificata in Base64. La documentazione spot di WEEX fornisce l’esempio 1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20 per una chiamata depth.

I timestamp vengono verificati. WEEX rifiuta ogni richiesta il cui ACCESS-TIMESTAMP si discosta di oltre 30 secondi dall’orologio del server. Un VPS con l’ora non sincronizzata produce errori di autenticazione intermittenti che sembrano casuali. Esegui NTP e, se i rifiuti continuano, recupera l’ora del server dall’endpoint pubblico e correggi le richieste.

I limiti di frequenza sono separati dai permessi ma producono sintomi altrettanto confusi. La maggior parte degli endpoint REST è limitata per IP con un sistema di peso, gli endpoint di inserimento ordini sono limitati per account nel bucket ORDERS e il superamento di uno dei due limiti restituisce HTTP 429 seguito da un ban di 10 secondi. Leggi gli header di risposta X-USED-WEIGHT e X-ORDER-COUNT invece di indovinare il budget. Un programma che martella l’API dopo un 429 prolunga il proprio ban.

Cosa i trader trascurano di solito nella schermata di configurazione

Tre cose vengono trascurate più di ogni altra.

La passphrase non è una password che puoi reimpostare. Gli utenti la trattano come un campo secondario, scelgono qualcosa rapidamente e la perdono quando ricostruiscono un server. WEEX richiede caratteri alfanumerici: scegli quindi una stringa casuale lunga e conservala insieme alla SecretKey.

L’associazione IP viene saltata perché l’IP di casa cambia. La soluzione corretta non è lasciare la chiave aperta, ma eseguire il programma su un VPS o un’istanza cloud con indirizzo statico e associarla a quello. Se devi usare un IP dinamico, mantieni la chiave in sola lettura e inserisci gli ordini manualmente.

L’ambito di trading viene attivato su una chiave che deve solo leggere. Succede spesso perché un tutorial per un altro exchange diceva di selezionare tutto. Su WEEX il valore predefinito è Read Only per un motivo: parti da lì e aggiungi l’ambito solo quando una richiesta fallisce per mancanza del permesso.

Configurare correttamente una chiave API WEEX, in breve

Una chiave API WEEX configurata bene è in sola lettura a meno che un programma non abbia dimostrato di dover fare trading, ha esattamente un ambito di trading quando serve, è associata all’IP statico della macchina che la usa, ha una passphrase conservata insieme alla SecretKey e occupa uno dei 10 slot per un solo programma. Se sistemi questi cinque elementi fin dal primo giorno, gran parte dei consigli sulla sicurezza API che leggerai altrove diventa superflua. Crea la prima chiave in Read Only, verifica che una chiamata firmata al saldo funzioni e solo dopo decidi se deve inserire ordini.

FAQ

1. Una chiave API WEEX consente i prelievi?

No. A settembre 2026, la documentazione API spot e futures di WEEX elenca solo i permessi Read Only e Trade (Spot o Futures/Contract). I prelievi richiedono il flusso Web o app con 2FA.

2. Quante chiavi API posso creare su WEEX?

Fino a 10 gruppi di chiavi API per account. Ogni gruppo ha permessi, passphrase e associazione IP opzionale propri.

3. Una chiave API WEEX può fare trading sia spot sia futures?

Spot e Futures/Contract sono ambiti di trading separati. Abilita solo quello necessario al programma; un bot spot non dovrebbe avere il permesso futures.

4. Perché la mia nuova chiave restituisce un errore di autenticazione?

Le cause comuni sono un ritardo di propagazione fino a circa 15 minuti dopo la creazione, un timestamp distante più di 30 secondi dall’ora del server, una passphrase errata oppure una chiamata da un IP che non compare nell’elenco associato alla chiave.

5. Cosa succede se perdo la passphrase?

Non può essere recuperata. Elimina il gruppo di chiavi e creane uno nuovo, quindi aggiorna ogni programma che usava la vecchia chiave.

6. L’associazione IP è obbligatoria?

È facoltativa ma fortemente raccomandata dalla documentazione WEEX. Per qualsiasi chiave con ambito di trading, considerala obbligatoria.

Avviso sui rischi

Il trading di criptovalute spot e futures comporta un rischio sostanziale di perdita, inclusa la perdita dell’intero saldo; le posizioni futures con leva possono essere liquidate rapidamente nei mercati volatili. L’accesso API aggiunge rischi operativi al rischio di mercato: una chiave configurata male, un bug del programma, un server compromesso o una SecretKey divulgata possono inserire ordini indesiderati che non possono essere annullati. Le chiavi con ambito di trading devono essere associate a un IP e monitorate, e ogni programma deve essere testato in modalità demo prima di toccare fondi reali. Nulla in questo articolo costituisce consulenza d’investimento; le funzioni della piattaforma descritte sono accurate a settembre 2026 e possono cambiare.