Guida alle API di WEEX: Configurazione, Chiamate, Permessi e Sicurezza

Se desideri che il codice recuperi prezzi, effettui ordini e gestisca il tuo account al posto tuo, la prima cosa da fare correttamente è capire come le API di WEEX vengono aperte, chiamate e, soprattutto, come vengono definiti i loro permessi. Le API di WEEX sono un insieme di interfacce di programmazione che WEEX mette a disposizione di sviluppatori e trader quantitativi, esponendo sia l'accesso REST che WebSocket in modo da poter estrarre dati di mercato, piazzare e annullare ordini e interrogare gli account senza dover guardare lo schermo. Questa guida segue un unico filo conduttore: cosa sono, come usarle, come chiamarle e se sono sicure, concentrandosi sulla parte che la maggior parte dei tutorial tralascia: permessi e sicurezza delle API, ovvero esattamente dove le cose possono andare storte con i fondi.

Tutti i parametri dell'interfaccia riportati di seguito provengono dalla documentazione ufficiale delle API di WEEX e riflettono le informazioni pubbliche a partire da luglio 2026. Le regole delle API possono cambiare, quindi verifica con il centro sviluppatori live prima di procedere all'integrazione.

Cosa sono le API di WEEX: Una rapida mappa delle funzionalità

In sintesi: le API di WEEX sono il canale che permette al codice di operare sul tuo account, suddiviso in "pubblico" e "privato". Gli endpoint pubblici restituiscono dati di mercato e configurazioni di sistema e non richiedono autenticazione; gli endpoint privati gestiscono l'inserimento e la cancellazione degli ordini e la gestione dell'account, e ogni richiesta deve essere firmata. Dal punto di vista del prodotto, copre sia lo spot che i futures con margine in USDT su oltre 100 asset.

Scegliere tra REST e WebSocket dipende dal fatto che tu voglia "chiedere una volta" o "rimanere in ascolto". Controlla un saldo o invia un singolo ordine tramite REST; per ricevere tick di prezzo in tempo reale, variazioni di profondità o esecuzioni di ordini, mantieni una connessione WebSocket: è più semplice e tempestiva.

Come ottenere la tua chiave API WEEX

Accedi alla piattaforma web di WEEX e crea una chiave dalla pagina di gestione delle API. Il sistema genera tre elementi contemporaneamente, e ti servono tutti e tre:

• APIKey — un identificatore generato algoritmicamente, in pratica il tuo "nome utente".
• SecretKey — la chiave privata emessa dal sistema utilizzata per firmare ogni richiesta.
• Passphrase — una frase di accesso che definisci tu stesso. Nota bene: se la Passphrase viene persa non può essere recuperata; devi eliminare il gruppo di chiavi e crearne uno nuovo.

Ogni account può creare fino a 10 gruppi di chiavi API, il che ti permette di emettere chiavi separate per strategia e per ambiente. Due scelte al momento della creazione definiscono il livello di sicurezza di una chiave: i permessi che selezioni (sezione successiva) e l'IP che vincoli. WEEX segnala esplicitamente che una chiave "senza restrizioni" senza vincolo IP rappresenta un rischio per la sicurezza: se l'IP del tuo server è fisso, compila la whitelist IP.

Permessi API di WEEX: Dove finiscono la sola lettura e il trading

Questa è la sezione da leggere due volte. Una chiave API appena creata è impostata di default su "Sola lettura". Per fare trading tramite le API, devi abilitare manualmente il permesso di trading "Spot" corrispondente. Troppi permessi significano una perdita maggiore se la chiave viene compromessa; troppo pochi e la strategia non può essere eseguita. La regola è una sola: concedi il minimo necessario alla strategia.

Un dettaglio facile da perdere ma importante per la sicurezza: a partire da luglio 2026, i permessi elencati nelle guide di avvio rapido delle API spot di WEEX sono esattamente questi due (Sola lettura e Trading Spot), senza un toggle separato per i "prelievi". Per la maggior parte delle strategie questa è una caratteristica, non una lacuna: anche se una chiave viene compromessa, chi la detiene non può prelevare asset direttamente. Considera le opzioni mostrate nella tua pagina di creazione chiave come la fonte di verità.

Come chiamarle: Cosa serve per una richiesta firmata

L'intera barriera per gli endpoint privati è il passaggio della "firma". WEEX genera firme con HMAC SHA256: crittografa la stringa pre-firma con la tua SecretKey, quindi codifica il risultato in Base64. La stringa pre-firma è assemblata in un ordine fisso:

timestamp + method (maiuscolo) + requestPath + "?" + queryString + body

La queryString viene omessa quando è vuota. Prendi come esempio una richiesta di profondità GET: /api/v3/market/depth?symbol=BTCUSDT&limit=20 con timestamp 1591089508404 produce la stringa pre-firma 1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20.

Una volta firmata, ogni richiesta privata trasporta quattro intestazioni:

I canali WebSocket privati funzionano allo stesso modo: firma il timestamp più il percorso della richiesta /v3/ws/private per accedere. Il punto in cui la maggior parte dei principianti si blocca non è la crittografia, ma il timestamp: se il timestamp della tua richiesta devia dall'orario del server di oltre 30 secondi, la richiesta viene respinta immediatamente. Un orologio locale errato o un timestamp memorizzato nella cache non aggiornato causeranno un inspiegabile errore 401. Sincronizzare l'ora NTP prima di andare live risparmia metà del debugging. Campi ed esempi completi sono disponibili nella documentazione di preparazione all'integrazione ufficiale e nel riferimento per la firma.

Limiti di frequenza e regole di accesso da conoscere

Non puoi chiamare le API alla velocità che desideri. Il limite predefinito è di 10 richieste/secondo, con alcuni endpoint che indicano i propri limiti nella documentazione; superarlo restituisce 429 Too Many Requests. Fai attenzione alla base di conteggio: le richieste autenticate sono misurate per chiave API, quelle non autenticate per IP pubblico; ciò significa che diversi script di sola lettura su un unico server che condividono un IP in uscita possono escludersi a vicenda dalla quota degli endpoint pubblici.

Una regola di raggruppamento vale la pena ricordare: un ordine batch che copre 4 coppie di trading con 10 ordini ciascuna conta come una singola richiesta. Raggruppare gli ordini permette a una strategia ad alta frequenza di aumentare il throughput e conservare la quota allo stesso tempo.

Le API di WEEX sono sicure? Separare ciò che è controllabile da ciò che non lo è

"È sicuro" merita una risposta più articolata di un semplice sì o no. Dal lato della piattaforma ottieni autenticazione firmata, vincolo IP, permessi a livelli e protezione contro il replay basata su timestamp. Ma negli scenari API la maggior parte degli incidenti avviene dal lato dell'utente: chiavi conservate con negligenza, permessi troppo ampi, credenziali inserite in un front-end o in un repository pubblico. La parte controllabile è interamente nelle tue mani:

• Limita i permessi al minimo; una strategia di sola lettura non dovrebbe mai avere permessi di trading.
• Vincola un IP fisso a ogni chiave: niente chiavi senza restrizioni.
• Conserva SecretKey e Passphrase in variabili d'ambiente o in un gestore di segreti, mai hard-coded nel codice lato client o inviate su Git.
• Usa chiavi diverse per lo sviluppo e la produzione in modo che non possano contaminarsi a vicenda.
• Ruota le chiavi regolarmente e, nel momento in cui noti chiamate anomale, elimina la chiave nella piattaforma web: una chiave può essere revocata e ricostruita in qualsiasi momento, ed è il modo più veloce per fermare l'emorragia.
• Imposta monitoraggio e avvisi sull'attività dell'account e sul volume delle chiamate in modo che frequenze o ordini insoliti emergano immediatamente.

Per una panoramica più ampia delle funzionalità e domande comuni, consulta la spiegazione di WEEX su se WEEX supporta il trading API. Segui la lista di controllo sopra indicata e la sicurezza delle API di WEEX dipenderà principalmente dall'igiene delle tue chiavi piuttosto che da qualcosa di misterioso.

La versione breve

Il percorso verso le API di WEEX è in realtà pulito: crea una chiave API con permessi minimi sulla piattaforma web (Sola lettura di default, trading abilitato manualmente), raccogli il trio APIKey / SecretKey / Passphrase e vincola un IP; quando chiami endpoint privati, firma con HMAC SHA256 nel formato fisso, invia tutte e quattro le intestazioni e rispetta la finestra temporale di 30 secondi e il limite di 10 richieste al secondo; infine, blocca l'igiene delle chiavi, i permessi di privilegio minimo, la whitelist IP e gli avvisi. Per iniziare, esegui la tua prima richiesta contro gli endpoint di mercato pubblici nel centro sviluppatori di WEEX, quindi aggiungi l'inserimento di ordini privati.

FAQ

1. WEEX supporta il trading API?

Sì. WEEX offre interfacce REST e WebSocket per dati di mercato automatizzati, inserimento e cancellazione ordini e gestione account, su spot e futures con margine USDT: adatto per bot quantitativi, grid e market-making.

2. Quante chiavi API può creare un account?

Fino a 10 gruppi. È meglio dividerle per strategia e ambiente (una chiave di monitoraggio in sola lettura, una chiave di trading spot, una chiave dev/test) in modo che funzionino in modo indipendente e possano essere revocate singolarmente.

3. Cosa succede se dimentico la Passphrase?

Non può essere recuperata. La Passphrase è una frase che definisci alla creazione e il sistema non la memorizza in testo normale. Se persa, devi eliminare quel gruppo di chiavi API e crearne uno nuovo.

4. Perché le mie richieste private vengono costantemente rifiutate?

La causa più comune è il timestamp. Se il timestamp della tua richiesta devia dall'orario del server WEEX di oltre 30 secondi, viene rifiutata: sincronizza prima il tuo orologio locale. Quindi controlla l'ordine della stringa pre-firma, che il nome del metodo sia in maiuscolo e che tutte e quattro le intestazioni siano presenti.

5. Se la mia chiave API viene compromessa, un utente malintenzionato può prelevare le mie monete?

Per le API spot il rischio è relativamente contenuto: a luglio 2026 i permessi documentati sono solo Sola lettura e Trading Spot, senza un permesso di prelievo autonomo. Anche così, elimina immediatamente la chiave compromessa nella piattaforma web e controlla eventuali ordini anomali.

6. Ci sono limiti di frequenza sulle chiamate?

Sì. Il limite predefinito è di 10 richieste/secondo; superarlo restituisce 429. Le richieste autenticate sono contate per chiave API e quelle non autenticate per IP. Un ordine batch (es. 4 coppie con 10 ordini ciascuna) conta come una richiesta, che le strategie ad alta frequenza possono usare per risparmiare quota.

Avviso sui rischi

Gli asset digitali sono altamente volatili e il trading programmatico tramite API può amplificare anziché ridurre il rischio, portando potenzialmente a una perdita parziale o totale del capitale. I rischi specifici del trading API includono furto o ordini non autorizzati da una chiave compromessa, ordini errati a cascata da un errore di logica del codice, ordini falliti a causa di latenza di rete o deriva del timestamp, essere limitati nella frequenza superando i limiti di chiamata e perdere il mercato, e rischio di liquidazione sotto leva sui futures. Limita sempre le chiavi al privilegio minimo, vincola un IP, proteggi la tua SecretKey e Passphrase e testa accuratamente in un ambiente di piccole dimensioni prima di andare live. Questo articolo è solo una guida tecnica all'integrazione e non costituisce consulenza sugli investimenti.