Guide d'intégration de l'API WEEX : Authentification, limites et le piège du 403

La plupart des guides sur l'API d'une plateforme d'échange crypto s'arrêtent à "créez une clé et connectez votre bot". Cela vous mènera à votre première erreur -1052, pas à une intégration fonctionnelle. L'API WEEX est un système à deux piles — le spot et les futures fonctionnent sur des domaines différents avec des schémas d'ordres distincts — et les échecs qui coûtent le plus de temps aux développeurs ne sont pas conceptuels. Il s'agit d'un en-tête User-Agent manquant, d'une horloge décalée de 31 secondes, ou d'une paire de trading qui existe sur la plateforme mais n'est pas activée pour un accès programmatique.

Ce guide parcourt l'intégration de l'API WEEX de bout en bout : ce que l'API couvre, comment provisionner une clé sans vous bloquer, comment la signature est réellement construite, les limites de taux que vous rencontrerez en production, et les erreurs spécifiques qui font échouer la plupart des premières tentatives. Chaque chiffre ici provient de la documentation WEEX V3 en date d'août 2026.

Ce que couvre l'API WEEX — et ce qu'elle ne couvre toujours pas

L'API WEEX expose deux surfaces REST indépendantes ainsi qu'une couche WebSocket. Elles ne sont pas interchangeables, et c'est la première décision structurelle qu'une intégration doit réussir.

La couverture est réelle mais limitée. L' annonce de la bêta de l'OpenAPI WEEX liste plus de 140 paires — mais la répartition est inégale : la table des futures compte environ 130 contrats perpétuels, tandis que la liste spot est d'environ 25 paires. Si votre stratégie trade une paire spot à moyenne capitalisation, vérifiez cette liste avant d'écrire une ligne de code, car le fait qu'une paire soit en ligne sur l'interface web ne signifie pas qu'elle accepte les ordres API.

Deux absences comptent pour quiconque migre depuis une autre plateforme. La FAQ de l'API spot de WEEX, mise à jour le 14 avril 2026, indique clairement que ni l'API FIX ni l'intégration TradingView ne sont actuellement prises en charge. Si votre pile d'exécution suppose une session FIX ou des alertes webhook routées depuis TradingView, vous devrez reconstruire cette couche avec REST et WebSocket.

À noter également : les endpoints V1 et V2 sont en cours de dépréciation, et WEEX recommande la V3 pour les nouvelles constructions. Les exemples de code trouvés sur des plateformes de bots tierces peuvent encore cibler les chemins V2.

Comment créer une clé API WEEX sans vous bloquer

La création de clé se fait sur la page de gestion des API WEEX sous Compte. La mécanique prend deux minutes. Les décisions de configuration prennent plus de temps, et trois d'entre elles sont irréversibles.

1. Créez la clé. Chaque compte prend en charge jusqu'à 10 groupes de clés API. Les nouvelles clés sont par défaut en Read Only.
2. Sélectionnez explicitement les permissions. Readonly, Spot, et Futures/Contract sont indépendants. Cocher Spot ne donne pas accès aux futures, et un ordre futures envoyé avec une clé spot uniquement renvoie -1052 INSUFFICIENT_PERMISSIONS plutôt qu'une erreur plus descriptive.
3. Définissez la passphrase avec soin. Les conseils de sécurité de WEEX recommandent d'utiliser uniquement des caractères alphanumériques — les caractères spéciaux dans la passphrase sont une source documentée d'échecs d'authentification. La passphrase ne peut être ni modifiée ni récupérée. Si vous la perdez, créez une nouvelle clé.
4. Liez une liste blanche IP. Jusqu'à 10 IP, séparées par des virgules. Les clés sans restriction constituent le plus grand risque de garde dans une configuration API, et WEEX les signale comme telles.
5. Attendez. Les clés nouvellement créées ou modifiées prennent environ 15 minutes pour se propager sur les systèmes de WEEX. Les développeurs interprètent souvent cette fenêtre comme une signature cassée et commencent à réécrire du code fonctionnel.

Stockez l' APIKey, la SecretKey, et la Passphrase lors de la création. Seule l'APIKey est récupérable par la suite.

Une habitude à adopter dès le premier jour : n'activez jamais de permissions liées aux retraits sur une clé qui vit dans un processus de trading. Séparez les clés en lecture seule pour la surveillance des clés avec permissions de trading pour l'exécution, et donnez à chacune sa propre liaison IP. Le coût opérationnel est de dix minutes ; le mode de défaillance qu'il prévient est total.

Signer une requête API WEEX : La fenêtre de 30 secondes

Chaque appel API WEEX privé comporte quatre en-têtes plus un type de contenu :

Le message que vous signez est une concaténation, et la règle de concaténation change selon qu'une chaîne de requête existe :

# queryString présent
timestamp + METHOD + requestPath + "?" + queryString + body

# queryString absent
timestamp + METHOD + requestPath + body

METHOD est en majuscules. body est la chaîne JSON brute, identique octet par octet à ce que vous transmettez — sérialisez une fois, signez cette chaîne, envoyez cette chaîne. La re-sérialisation entre la signature et l'envoi est l'échec de signature auto-infligé le plus courant, car l'ordre des clés ou les espaces changent et le hash ne correspond plus.

Un exemple tiré de la spécification de signature WEEX, pour récupérer la profondeur :

1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20

Et un ordre :

1561022985382POST/api/v3/order{"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"1","price":"68900","newClientOrderId":"my-order-001"}

Puis HMAC-SHA256 avec votre clé secrète, puis Base64.

La contrainte qui piège les gens en production est l'horloge. Les requêtes sont rejetées si ACCESS-TIMESTAMP dévie de plus de 30 secondes par rapport à l'heure du serveur WEEX, renvoyant -1046 ACCESS_TIMESTAMP_EXPIRED. Les conteneurs avec des horloges qui dérivent, les démarrages à froid serverless, et les VM sans NTP échouent tous de manière intermittente — ce qui est pire qu'un échec constant, car cela ressemble à un problème réseau. Interrogez l'endpoint d'heure du serveur au démarrage, stockez le décalage, et appliquez-le à chaque timestamp.

Les canaux privés WebSocket utilisent un message plus court : timestamp + "/v3/ws/private", signé de la même manière — mêmes en-têtes, mêmes étapes HMAC-SHA256 et Base64, juste une chaîne différente.

Limites de taux de l'API WEEX que vous atteindrez réellement

Dépasser une limite renvoie une erreur HTTP 429 et un bannissement de 10 secondes. WEEX divise la limitation en deux budgets indépendants, ce que la plupart des intégrations modélisent incorrectement.

Limites de taux provenant de la documentation de l'API spot WEEX et de la FAQ, au 14 avril 2026.

La distinction qui compte : le placement d'ordre est limité par compte, tout le reste par IP. Les endpoints de placement consomment zéro poids IP — le compteur IP dans leurs en-têtes de réponse indique 0. Donc, exécuter trois stratégies derrière une IP ne triple pas votre budget d'ordres (c'est par compte), mais cela triple votre consommation du pool IP de 500 poids pour les données de marché et les requêtes.

Lisez les en-têtes plutôt que de deviner. Chaque réponse contient X-USED-WEIGHT-1M et X-REMAINING-WEIGHT-1M ; les endpoints d'ordres contiennent X-ORDER-COUNT-10S et X-ORDER-REMAINING-10S. Un back-off piloté par l'en-tête de poids restant surpassera tout intervalle de sommeil fixe que vous codez en dur.

Les ordres Spot et Futures ne partagent pas de schéma

C'est la divergence qui brise les couches d'abstraction partagées, et elle n'est pas mise en évidence de manière proéminente dans les docs — vous la trouvez en comparant les deux pages d'ordres.

Cette dernière ligne mérite d'être soulignée. L'endpoint futures peut renvoyer HTTP 200 avec {"success": false, "errorCode": "...", "errorMessage": "..."}. Le code qui vérifie uniquement le statut HTTP enregistrera un ordre rejeté comme exécuté et procédera joyeusement à construire une position qu'il n'a pas. Vérifiez success explicitement sur chaque réponse d'ordre futures.

Il existe également une incohérence en direct dans la documentation elle-même. La page Paramètres publics de l'API spot liste toujours des enums en minuscules (buy, sell, limit, market) à côté d'un champ force, tandis que les endpoints d'ordres V3 sous Trade utilisent des majuscules BUY, SELL, LIMIT et timeInForce. Les pages d'endpoints reflètent la V3 ; la page des paramètres porte des valeurs de l'ère V2. En cas de désaccord, faites confiance à la page d'endpoint — et envoyez -1116 INVALID_ORDER_TYPE à vos logs comme signal que vous avez copié depuis la mauvaise.

Les symboles sont sensibles à la casse et doivent être en majuscules. btcusdt renvoie -1121.

Cinq erreurs qui brisent la plupart des intégrations API WEEX

Le 403 WebSocket est celui qui vaut la peine d'être internalisé. Cela n'a rien à voir avec vos identifiants — la bordure de WEEX rejette purement et simplement les handshakes sans en-tête, donc une souscription privée parfaitement signée échoue de la même manière qu'une non signée. Les développeurs déboguent leur signature pendant une heure avant de trouver. WEEX documente cela dans la FAQ de l'API spot, et le correctif est d'une ligne.

Maintenez également les connexions en vie correctement. Le serveur envoie des pings périodiques — {"event":"ping","time":"..."} sur les canaux publics, {"type":"ping","time":"..."} sur les privés — et attend {"method":"PONG","id":1} en retour. Manquez-en plus de 10 et le serveur ferme la connexion. Une déconnexion silencieuse pendant une session volatile est la façon dont un bot finit par trader sur un carnet obsolète.

La taxonomie complète des erreurs se trouve dans la FAQ de l'API spot WEEX et référence des codes d'erreur.

Testez en mode démo avant de risquer une marge réelle

WEEX propose un environnement futures simulé accessible via le même modèle authentifié, sous /capi/v3/sim/. L' endpoint de solde démo renvoie des positions libellées en SUSDT — USDT simulé — à côté de availableBalance, frozen, et unrealizePnl. PlaceOrder, GetAllPositions, et GetOrderHistory en démo sont tous exposés.

Utilisez-le pour ce à quoi il est réellement bon : valider la construction de votre signature, votre gestion des erreurs, et votre logique de reconnexion. Ne l'utilisez pas pour valider l'économie de la stratégie. Un lieu simulé n'a pas de position dans la file d'attente, pas de comportement d'exécution partielle sous stress, et pas de slippage — les trois choses qui séparent un backtest d'un P&L.

Pour le calibrage côté réel : WEEX a coté les perpétuels BTC à 65 088,80 USDT sur son marché futures BTC/USDT au 21 août 2026, avec un levier disponible jusqu'à 400×. Ce plafond de levier est une raison d'être conservateur avec un système automatisé, pas une fonctionnalité sur laquelle s'appuyer. Un bug de signature qui déclenche des ordres en double est survivable à 3×. Il ne l'est pas à 400×.

La version courte

L'API WEEX est simple une fois que trois choses sont vraies : votre horloge est synchronisée dans la fenêtre de 30 secondes, votre WebSocket envoie un User-Agent, et votre code futures vérifie le champ success plutôt que le statut HTTP. Tout le reste — permissions, listes blanches IP, back-off de limite de taux — est un travail d'intégration d'échange standard.

La seule chose qui n'est pas standard, et celle pour laquelle il vaut la peine de prévoir du temps, est la divergence de schéma spot/futures. Une abstraction d'ordre partagée sur les deux surfaces semblera correcte en revue et échouera en production. Construisez-les comme deux adaptateurs.

Prêt à commencer ? Créez une clé sous Compte → Gestion API sur WEEX, pointez-la d'abord sur le mode démo, et n'élargissez les permissions qu'une fois vos chemins de reconnexion et d'erreur prouvés.

FAQ

1. L'API WEEX est-elle gratuite ?

Oui. Il n'y a pas de frais distincts pour l'accès à l'API. Vous payez les frais de trading spot ou futures standard sur les ordres exécutés, comme pour le trading manuel.

2. Combien de clés API puis-je créer sur WEEX ?

Jusqu'à 10 groupes de clés API par compte. Chaque clé peut être configurée indépendamment avec des permissions Readonly, Spot, ou Futures/Contract et sa propre liste blanche IP allant jusqu'à 10 adresses.

3. Pourquoi ma clé API WEEX fonctionne-t-elle dans Postman mais pas depuis mon serveur ?

Presque toujours la liste blanche IP (-1056) ou la dérive d'horloge (-1046). Les environnements cloud sortent fréquemment d'une IP NAT tournante qui n'est pas sur votre liste blanche, et les conteneurs sans NTP dérivent au-delà de la fenêtre de signature de 30 secondes.

4. L'API WEEX prend-elle en charge les webhooks FIX ou TradingView ?

Non. Au 14 avril 2026, ni l'API FIX ni l'intégration TradingView ne sont prises en charge. REST et WebSocket sont les transports disponibles.

5. Combien de temps avant qu'une nouvelle clé API WEEX ne commence à fonctionner ?

Environ 15 minutes pour qu'une clé nouvelle ou modifiée se propage. Les échecs d'authentification dans cette fenêtre sont attendus et ne sont pas un problème de signature.

6. Puis-je tester des stratégies API WEEX sans fonds réels ?

Oui, pour les futures. Les endpoints démo sous /capi/v3/sim/ acceptent les mêmes requêtes authentifiées et renvoient des soldes libellés en SUSDT. Traitez-les comme un banc d'essai d'intégration, pas comme un backtest de stratégie.

Avertissement sur les risques

Les actifs crypto sont volatils, et les trader peut entraîner une perte partielle ou totale de capital. Le trading par API concentre ce risque plutôt que de le réduire : une erreur de logique, un rejet non géré, ou un flux WebSocket obsolète peut exécuter des dizaines d'ordres involontaires avant qu'un humain ne s'en aperçoive. WEEX offre un levier jusqu'à 400× sur certains contrats perpétuels, ce qui magnifie les signaux corrects et incorrects — un système automatisé fonctionnant à fort levier peut être liquidé en un seul mouvement défavorable.

Risques spécifiques à prendre en compte dans un déploiement API : risque de garde lié aux clés non restreintes ou divulguées, qui accordent un contrôle total de trading sur le compte ; risque opérationnel lié à la dérive d'horloge, aux limites de débit de l'API WEEX et aux connexions interrompues qui laissent les positions non gérées ; risque de liquidité sur les paires peu tradées où un ordre au marché déplace le carnet contre vous ; et risque de contrepartie et réglementaire, car la disponibilité du trading API et de paires spécifiques peut changer sans préavis. Liez une liste blanche IP, gardez les permissions de retrait désactivées sur les clés de trading, plafonnez la taille de position dans le code plutôt que dans l'intention, et testez les chemins d'erreur en mode démo avant de déployer du capital. Rien de tout cela n'est un conseil en investissement.