API di un exchange crypto: permessi, firma e limiti di velocità

La prima cosa che affidi a un API di un exchange crypto non è il codice. È una chiave. Ogni guida ti dice di tenerla al sicuro; quasi nessuna ti mostra cosa può effettivamente fare la chiave su uno specifico exchange, che è dove risiede il vero rischio. Questa guida utilizza la documentazione API ufficiale di WEEX come esempio pratico e risponde a quattro domande in ordine: cos'è l'API, cosa può fare, come viene costruita una chiamata firmata e cosa succede se la chiave viene compromessa.

Ogni parametro, limite di velocità e codice di errore qui sotto proviene dalla documentazione API ufficiale di WEEX (FAQ spot e futures aggiornate al 2026-04-14), verificata nell'agosto 2026. La documentazione cambia tra le versioni: verifica sempre le pagine live prima di andare in produzione.

Cosa fa effettivamente un'API di un exchange crypto

Un API di un exchange crypto espone due famiglie di endpoint, e la distinzione dipende dal fatto che la richiesta contenga o meno la tua identità.

• Endpoint pubblici restituiscono dati di mercato e configurazione: candele, profondità del book, scambi recenti, lista dei simboli tradabili. Nessuna autenticazione, aperti a chiunque, limitati per IP.
• Endpoint privati toccano il tuo account: saldi, posizioni, piazzamento ordini, cancellazione. Ogni richiesta deve contenere una firma che il server verifica prima di eseguire qualsiasi operazione.

Questa distinzione dovrebbe guidare la tua architettura. I dati di mercato possono girare ovunque: un endpoint pubblico compromesso non ti costa nulla. Le chiamate private appartengono a un host di cui controlli l'IP in uscita. Molti team eseguono entrambi in un unico processo perché è conveniente, e poi una vulnerabilità di dipendenza sul lato dati di mercato espone la chiave di trading.

WEEX serve il REST spot da https://api-spot.weex.com, con percorsi spot sotto /api/v3/ e futures sotto /capi/v3/. I prefissi non sono intercambiabili e mescolarli è la causa più comune di un errore 404 inspiegabile.

Permessi delle API Key: l'errore più comune nelle guide

Quasi ogni articolo sulla "sicurezza delle API key" nella prima pagina di Google assume tre livelli di permesso (lettura, trading, prelievo) e ti dice di lasciare disabilitato il prelievo. Quel consiglio va bene, ma nasconde una domanda più utile: l'exchange offre davvero un permesso di prelievo?

Su WEEX, non è così. I permessi disponibili quando crei una chiave sono questi e sono indipendenti l'uno dall'altro:

Questo conta più di qualsiasi dettaglio di crittografia. Quando leggi di "una fuga di API key che ha svuotato un account", i fondi di solito non sono stati prelevati: l'attaccante ha usato il permesso di trading per eseguire un pump-and-dump su una coppia illiquida, acquistando sull'account della vittima a prezzi gonfiati e vendendo i propri asset. L'assenza del permesso di prelievo non significa che gli asset siano al sicuro. Significa che l'attacco si sposta dal furto alla perdita indotta.

Le chiavi sono impostate di default su Readonly. Devi spuntare deliberatamente un permesso di trading, che è il default corretto e anche il motivo per cui un primo ordine restituisce spesso -1052 (Permessi insufficienti). Ogni account può contenere fino a 10 gruppi di chiavi; dividili per scopo invece di condividerne una sola. Una chiave in sola lettura per il monitoraggio e una chiave di trading separata per la strategia significano che quando qualcosa va storto puoi identificare e revocare esattamente una chiave.

La creazione di una chiave ti fornisce tre credenziali con tre ruoli diversi:

La passphrase non può essere cambiata o recuperata. Conservala in un secrets manager insieme alla SecretKey, non in un file di configurazione nel tuo repository. I dettagli a livello di campo si trovano nella documentazione di preparazione all'integrazione API di WEEX.

Come firmare una richiesta: costruire l'header ACCESS-SIGN

Gli endpoint privati dipendono dall'header ACCESS-SIGN. La regola è breve; il problema è che un solo carattere sbagliato nella concatenazione rompe tutto con un errore che punta altrove.

WEEX concatena in questo ordine, esegue HMAC SHA256 con la tua SecretKey, quindi codifica il risultato in Base64:

timestamp + method.toUpperCase() + requestPath + "?" + queryString + body

Quando queryString è vuota, ometti il punto interrogativo: timestamp + method + requestPath + body.

Query sulla profondità di BTCUSDT:

String to sign: 1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20
Signature = base64.encode(hmac_sha256(secretKey, message))

Tre dettagli causano la maggior parte delle integrazioni fallite:

1. Il timestamp è in millisecondi e deve essere entro 30 secondi dall'ora del server. WEEX confronta ACCESS-TIMESTAMP con il proprio orologio e rifiuta qualsiasi cosa fuori tempo. Le istanze cloud possono avere deriva; interroga l'endpoint dell'ora del server all'avvio e correggi rispetto ad esso invece di fidarti del Date.now() locale.
2. Il metodo deve essere in maiuscolo. Inviare get invece di GET rompe la firma, ma la risposta viene letta come un errore di autenticazione, il che spinge le persone a cercare una chiave errata.
3. I simboli sono case-sensitive e devono essere in maiuscolo. btcusdt non è normalizzato. Per gli endpoint degli ordini, prendi il valore del simbolo dalla risposta /products invece di costruirlo a mano.

L'esempio completo, inclusa la concatenazione del body per gli ordini POST, si trova nella documentazione di firma delle richieste di WEEX. Fai funzionare una GET prima di tentare una POST.

Limiti di velocità: cosa scatena un 429 e come gestire il back-off

Superare un limite restituisce HTTP 429 e comporta un ban di circa 10s. WEEX non esegue un contatore globale: i limiti sono definiti per dimensione:

Fonte: FAQ API spot e futures di WEEX, aggiornate al 2026-04-14.

Due meccaniche meritano di essere interiorizzate. Il piazzamento dell'ordine è misurato per account (userId) e non consuma peso IP: il contatore IP in quegli header di risposta legge 0. Tutto il resto è misurato per peso IP, con endpoint più pesanti che portano un peso maggiore. Quindi diverse macchine che condividono un IP in uscita competeranno per il budget dei dati di mercato ma non per il budget degli ordini.

Non stimare il tuo budget rimanente con un contatore locale. Ogni risposta porta X-USED-WEIGHT-1M e X-REMAINING-WEIGHT-1M; le richieste di ordine portano inoltre X-ORDER-COUNT-* e X-ORDER-REMAINING-*. Gestisci il back-off sugli header piuttosto che codificare "5 richieste al secondo" e nota che la documentazione inglese e cinese di WEEX attualmente non concorda sul limite degli ordini spot (quella inglese dice 100/min, quella cinese 100/10s). Gli header di risposta sono l'unica fonte di verità.

Un'API di un exchange crypto è sicura? Tre anelli della catena

La sicurezza qui è una proprietà della tua configurazione, non solo dell'exchange. L'exchange possiede un anello su tre.

Anello uno: archiviazione delle chiavi. La SecretKey viene mostrata una volta e mai più, quindi le fughe hanno origine dalla tua parte: commit su Git, incorporata in un bundle frontend, scritta nei log, incollata in una chat di lavoro. Variabili d'ambiente o un secrets manager, più una regola senza eccezioni: le chiavi non viaggiano mai attraverso strumenti di messaggistica.

Anello due: whitelisting IP. WEEX ti permette di associare indirizzi IP quando crei una chiave e raccomanda esplicitamente di abilitarlo. Una chiave non vincolata funziona da qualsiasi parte del mondo nel momento in cui viene compromessa; una vincolata costringe l'attaccante a compromettere prima il tuo server. Non impostare 0.0.0.0/0 in produzione: è come non impostarlo affatto.

Anello tre: privilegio minimo. Tornando alla tabella dei permessi: i processi di monitoraggio ottengono Readonly, per sempre. Una strategia spot non ha motivo di detenere Futures. Questa non è pignoleria, è controllo del raggio d'azione.

Due trappole operative sono documentate ma facili da perdere:

• Una chiave nuova o appena modificata impiega circa 15 minuti per propagarsi globalmente. Un errore di permesso subito dopo la configurazione è solitamente un ritardo di propagazione, non una configurazione errata.
• Attivare il controllo del rischio della piattaforma (login sospetti, inondazioni di richieste non valide) può disabilitare automaticamente i permessi API, e il ripristino passa attraverso il supporto. Non fare load-test con una chiave di produzione.

Un giudizio che non troverai nelle guide generiche: per la maggior parte degli utenti retail e dei piccoli fondi, la probabilità di furto della chiave è ben al di sotto della probabilità di perdere denaro a causa della propria gestione degli errori sotto pressione dei limiti di velocità. Configura la sicurezza correttamente, poi spendi la stessa energia su tentativi e piazzamento ordini idempotente. Il rendimento atteso è più alto.

Testa prima sul paper trading: cinque errori che colpiscono le nuove integrazioni

WEEX esegue endpoint di paper trading sul lato futures usando SUSDT simulati, sotto /capi/v3/sim/: sim/balance, sim/position/allPosition, sim/order, sim/order/history, con supporto per posizioni duali in hedge-mode. Eseguire una nuova strategia dall'inizio alla fine lì è il debug più economico che farai mai.

Prima che entri capitale reale, tieni questa tabella a portata di mano:

Altre due cose da sistemare in anticipo: WEEX attualmente non supporta il trading di segnali TradingView o FIX API, quindi le strategie che dipendono da entrambi necessitano di un'altra rotta; e gli endpoint V1/V2 vengono deprecati, quindi il nuovo lavoro dovrebbe puntare direttamente alla V3. Le domande e risposte complete su permessi e limiti di velocità si trovano nelle FAQ API spot di WEEX, e gli sviluppatori di futures dovrebbero iniziare dalla documentazione API futures.

L'ordine corretto per integrare un'API di un exchange crypto

Tornando alle quattro domande. Un API di un exchange crypto è il punto di ingresso programmatico a un exchange, diviso in endpoint pubblici che leggono ed endpoint privati che agiscono. Come lo usi dipende da quale permesso spunti: Readonly, Spot e Futures sono indipendenti, e WEEX non espone i prelievi tramite API. Come lo chiami si riduce alla firma: HMAC SHA256 più Base64, con una tolleranza di timestamp di 30 secondi. Se sia sicuro dipende da te; l'exchange fornisce il vincolo IP e i livelli di permesso, il resto è la tua disciplina operativa.

Se ricordi una cosa, ricorda la sequenza: chiave in sola lettura prima per testare dati di mercato e query, paper trading dopo per validare la strategia, e solo allora permessi di trading, vincolo IP e fondi reali. Invertire quell'ordine tende a essere costoso.

Pronto a costruire? Inizia dal centro sviluppatori WEEX, crea una chiave, configura i permessi e lavora sugli endpoint V3 uno alla volta.

FAQ

1. Un'API di un exchange crypto costa denaro o richiede una richiesta?

Su WEEX, nessun processo di qualificazione: accedi alla piattaforma web e fai da te, fino a 10 gruppi di chiavi API per account. Questo differisce dalle API di brokeraggio azionario, che comunemente limitano l'accesso in base a capitale, volume o requisiti di background professionale.

2. Se la mia API key viene compromessa, qualcuno può prelevare i miei fondi?

Non tramite l'API WEEX: il set di permessi è solo Readonly, Spot e Futures, senza ambito di prelievo. Una chiave con permesso di trading può ancora essere abusata per fare trading contro di te su coppie illiquide, spostando valore come perdite realizzate. Elimina immediatamente il gruppo di chiavi se sospetti un'esposizione.

3. Ho bisogno di un'API key solo per i dati di mercato?

No. Candele, profondità, ticker e liste di simboli sono endpoint pubblici, non autenticati e limitati per IP. Solo gli endpoint di account e ordini richiedono una firma.

4. Perché una nuova API key restituisce un errore di permessi insufficienti?

Le chiavi nuove o appena modificate impiegano circa 15 minuti per propagarsi nel sistema. Se -1052 persiste dopo quella finestra, controlla se Spot o Futures sono stati effettivamente spuntati.

5. Cosa succede se dimentico la passphrase dell'API?

Non può essere recuperata o cambiata. Elimina il gruppo di chiavi, creane uno nuovo e aggiorna ogni consumer di quella credenziale.

6. WEEX supporta TradingView o FIX API?

Nessuno dei due è supportato ad agosto 2026. I team che necessitano di accesso istituzionale a bassa latenza dovrebbero valutare se REST e WebSocket soddisfano i loro requisiti prima di impegnarsi.

Avviso sui rischi

Gli asset crypto sono altamente volatili e il trading programmatico tramite un API di un exchange crypto può comportare una perdita parziale o totale del capitale. I rischi specifici delle API includono attività non autorizzate sull'account a seguito dell'esposizione della chiave, ordini errati a cascata causati da bug della strategia o una debole gestione degli errori, ordini lasciati senza gestione dopo un ban per limite di velocità e un rischio di liquidazione amplificato quando si fa trading di futures con leva. Implementa una gestione approfondita delle eccezioni e una logica di retry, associa whitelist IP a ogni chiave, applica permessi di privilegio minimo e investi solo il capitale che puoi permetterti di perdere. I parametri degli endpoint e i limiti di velocità descritti qui sono stati verificati nell'agosto 2026 e potrebbero cambiare con gli aggiornamenti della piattaforma: fai sempre riferimento alla documentazione API ufficiale WEEX corrente. Questo articolo non è un consiglio di investimento.