Guide de l'API WEEX : de la clé API à votre premier ordre signé

La plupart des intégrations de l'API WEEX ne rencontrent pas de problèmes de logique de stratégie. Elles échouent dès la première heure sur quatre points qui ne sont pas évidents avant d'y être confronté : la clé que vous venez de créer n'est pas encore active, la paire que vous souhaitez trader n'est pas sur la liste blanche de l'API, votre connexion WebSocket est refusée car vous n'avez pas envoyé d'en-tête User-Agent, et votre signature est erronée d'un octet car vous avez signé un corps re-sérialisé au lieu de la chaîne exacte que vous avez envoyée.

Ce guide parcourt l'API WEEX de bout en bout : création de clé, permissions, règle de signature, limites de débit, codes d'erreur qui bloquent réellement les builds, et les points de terminaison de trading sur papier qui vous permettent de tout tester sans capital à risque. Tout ce qui suit a été vérifié par rapport à la documentation V3 en direct au 21 août 2026.

Ce que couvre l'API WEEX : spot, futures et WebSocket

L'API WEEX est divisée en deux produits indépendants avec deux domaines REST distincts. Le Spot se trouve sur api-spot.weex.com sous le chemin /api/v3. Les Futures se trouvent sur api-contract.weex.com sous le chemin /capi/v3. Ils partagent un schéma de signature et un ensemble d'en-têtes, mais rien d'autre : drapeaux de permission séparés, hôtes WebSocket séparés, paramètres d'ordre séparés.

Les points de terminaison se répartissent en deux classes d'accès. Les points de terminaison publics (heure du serveur, profondeur du carnet d'ordres, klines, taux de financement, tickers 24h) ne nécessitent aucune authentification, ce qui en fait le moyen le plus rapide de confirmer que votre chemin réseau fonctionne avant de toucher à la signature. Les points de terminaison privés (soldes, positions, ordres) nécessitent la signature complète à quatre en-têtes sur chaque requête.

Pour tout ce qui concerne le niveau tick, WEEX vous oriente vers WebSocket plutôt que vers le polling REST, et c'est le bon choix : les canaux publics transportent les flux de ticker, de profondeur et de trade, et un canal privé transporte les mises à jour de compte, de position et d'ordre. Poller la profondeur via REST pour construire un carnet d'ordres épuisera votre budget de poids IP sans aucun avantage.

Un point de référence daté pour l'échelle : au 21 août 2026, le contrat perpétuel BTC/USDT cotait un dernier prix de 65 088,8 USDT sur le carnet futures de WEEX — le même tick que votre appel /capi/v3/market/ticker24h renvoie.

Comment créer une clé API WEEX et définir les permissions

Les clés sont créées depuis Compte → Gestion API sur la plateforme web. Chaque compte peut contenir jusqu'à 10 groupes de clés API.

La création renvoie trois valeurs, et la troisième est celle que les gens perdent :

• APIKey — identifiant public, envoyé dans l'en-tête ACCESS-KEY.
• SecretKey — le secret de signature HMAC. Affiché une seule fois.
• Passphrase — définie par l'utilisateur, envoyée dans ACCESS-PASSPHRASE. Elle ne peut pas être modifiée ni récupérée. Si vous la perdez, vous recréez la clé.

Trois détails de configuration causent plus de tickets de support que tout le reste combiné :

1. Les nouvelles clés sont par défaut en lecture seule. La permission de trading est une case à cocher séparée, et elle est spécifique au produit : Spot pour le trading spot, Futures pour les contrats. Cocher l'une n'active pas l'autre. Passer un ordre sur une clé en lecture seule renvoie -1052.
2. Les clés mettent environ 15 minutes à se propager mondialement. Une clé qui s'authentifie correctement puis échoue sur un point de terminaison différent n'est généralement pas encore totalement active. Attendez avant de commencer à déboguer votre signature.
3. Gardez la passphrase alphanumérique. WEEX recommande explicitement de ne pas utiliser de caractères spéciaux. Les erreurs d'encodage dans les caractères spéciaux sont une classe de bugs vraiment pénible à traquer.

Liez une liste blanche IP pendant que vous êtes sur l'écran de création. Une clé non liée est une information d'identification au porteur qui fonctionne depuis n'importe où sur Internet, et si une machine la détenant est compromise, la liste blanche est la seule chose qui sépare un attaquant de vos positions.

API spot WEEX vs API futures : les différences qui comptent

C'est le tableau à garder ouvert pendant que vous construisez. Les deux produits semblent symétriques mais ne le sont pas.

Deux de ces points sont les plus critiques. Les Futures exigent newClientOrderId sur chaque ordre, donc une base de code conçue pour le spot qui l'omet sera rejetée dès que vous la pointerez vers les contrats. Et POST_ONLY n'existe que sur les futures : une stratégie maker-only écrite pour l'API spot n'a aucun moyen natif de garantir qu'elle ne franchira pas le spread.

Les paramètres TP/SL des futures méritent plus d'attention qu'ils n'en reçoivent habituellement. Attacher tpTriggerPrice et slTriggerPrice à l'ordre d'entrée signifie que votre stop existe sur l'échange dès l'ouverture de la position, plutôt que d'être placé par un appel ultérieur qui pourrait ne pas survivre à un crash de processus ou à une partition réseau. Vous pouvez également choisir la source de déclenchement par étape via TpWorkingType et SlWorkingType — MARK_PRICE pour le stop est le défaut le plus sûr, car CONTRACT_PRICE peut être manipulé par un dernier trade sur une paire peu liquide.

Comment signer correctement une requête API WEEX

Chaque appel privé comporte quatre en-têtes : ACCESS-KEY, ACCESS-SIGN, ACCESS-PASSPHRASE, ACCESS-TIMESTAMP, plus Content-Type: application/json.

La règle de signature est identique sur les deux domaines. Construisez cette chaîne :

timestamp + METHOD + requestPath + "?" + queryString + body

Supprimez ? et queryString lorsqu'il n'y a pas de paramètres de requête ; supprimez body lorsqu'il n'y en a pas. Appliquez HMAC-SHA256 avec votre SecretKey, puis encodez le résultat en Base64.

import base64, hashlib, hmac, json, time, requests

API_KEY, SECRET, PASSPHRASE = "...", "...", "..."
BASE = "https://api-contract.weex.com"
path = "/capi/v3/order"
body = json.dumps({
    "symbol": "BTCUSDT", "side": "BUY", "positionSide": "LONG",
    "type": "LIMIT", "timeInForce": "GTC", "quantity": "0.01",
    "price": "60000", "newClientOrderId": "my-order-0001",
}, separators=(",", ":"))

ts = str(int(time.time() * 1000))
message = ts + "POST" + path + body
sign = base64.b64encode(
    hmac.new(SECRET.encode(), message.encode(), hashlib.sha256).digest()
).decode()

r = requests.post(BASE + path, data=body, headers={
    "ACCESS-KEY": API_KEY, "ACCESS-SIGN": sign,
    "ACCESS-PASSPHRASE": PASSPHRASE, "ACCESS-TIMESTAMP": ts,
    "Content-Type": "application/json",
})

Notez data=body, pas json=payload. Signez les octets exacts que vous transmettez. Si votre client HTTP re-sérialise le dictionnaire — réordonnant les clés ou insérant des espaces après les séparateurs — le serveur calcule un condensé différent et vous obtenez -1047, sans aucune indication que la cause était un espace blanc.

La fenêtre de temps est de 30 secondes par rapport à l'heure du serveur WEEX. Si l'horloge de votre hôte dérive, les requêtes commencent à échouer par intermittence d'une manière qui ressemble à un bug de signature. Appelez GET /capi/v3/market/time et suivez le décalage plutôt que de faire confiance à l'heure locale.

Les canaux privés WebSocket se signent différemment et cela piège les gens : le message est seulement timestamp + requestPath, où requestPath est /v3/ws/private. Pas de méthode, pas de corps.

Une particularité de la documentation à connaître avant de copier-coller : la page Signature des futures illustre la règle en utilisant des chemins spot (/api/v3/order). La règle est correcte ; les chemins d'exemple ne sont pas ceux des futures. Utilisez /capi/v3/... lorsque vous êtes sur le domaine des contrats.

Limites de débit de l'API WEEX : deux seaux, pas un

WEEX gère deux compteurs de limites de débit indépendants, et les confondre est la raison pour laquelle les bots obtiennent des 429 inattendus.

Le détail important : le placement d'ordre consomme zéro poids IP, et les annulations et requêtes consomment zéro compte d'ordre. Ce sont des registres vraiment séparés. Une boucle de market-making qui place et annule agressivement épuisera le seau ORDRES lors du placement tandis que son trafic d'annulation drainera silencieusement le poids IP — et aucun compteur ne vous avertit de l'autre.

Lisez les en-têtes plutôt que de compter les requêtes côté client. X-REMAINING-WEIGHT-1M et X-ORDER-REMAINING-1M reviennent à chaque appel et reflètent la vue du serveur, qui est la seule qui compte. Dépasser une limite renvoie HTTP 429 et déclenche un bannissement de 10 secondes, et continuer à marteler malgré une 429 est le moyen le plus rapide de voir votre accès API désactivé par le contrôle des risques.

Si vous exécutez plusieurs stratégies depuis une seule machine, rappelez-vous que le seau IP est partagé. Deux bots sur un serveur se disputent les mêmes 500 poids par 10 secondes.

Les erreurs de l'API WEEX qui bloquent la plupart des intégrations

Les réponses d'erreur sont une paire code et message. Ce sont celles qui apparaissent pendant l'intégration plutôt qu'en production :

-1058 mérite un flux de travail spécifique. Tous les contrats WEEX ne sont pas activés pour le trading API, et il n'y a aucun moyen de le déduire de l'interface utilisateur. Appelez GET /capi/v3/market/apiTradingSymbols au démarrage, mettez le tableau en cache, et validez les symboles avant que votre stratégie ne construise un ordre. Cette vérification élimine une classe entière d'échecs à l'exécution.

Deux autres qui ressemblent à des bugs et n'en sont pas. Un handshake WebSocket renvoyant 403 signifie presque toujours que vous avez omis l'en-tête User-Agent — le contenu est arbitraire, mais le pare-feu rejette les connexions sans lui. Et la documentation est actuellement en désaccord sur les échecs d'annulation : la référence des codes d'erreur mappe -1054 à une erreur système générique et -3200 à "l'ordre n'existe pas", tandis que la FAQ des futures attribue "l'ordre n'existe pas" à -1054. Gérez les deux codes sur les chemins d'annulation plutôt que de bifurquer sur un seul.

Testez d'abord sur les points de terminaison de trading sur papier WEEX

WEEX a ajouté des points de terminaison de trading simulé sur le domaine des futures, et ils reflètent la surface réelle assez étroitement pour être un vrai test à sec plutôt qu'un jouet :

• GET /capi/v3/sim/balance — soldes simulés, libellés en SUSDT
• GET /capi/v3/sim/position/allPosition — positions, incluant les paires long/short en mode couverture
• POST /capi/v3/sim/order — placement d'ordre via les types habituels
• GET /capi/v3/sim/order/history — exécutions simulées historiques

Même domaine, mêmes en-têtes, même règle de signature. Remplacer /capi/v3/order par /capi/v3/sim/order est souvent le seul changement nécessaire pour exécuter un test d'intégration complet.

Utilisez-les pour valider les parties de votre système qui ne cassent que dans des conditions réelles : logique de reconnexion après un WebSocket perdu, si votre machine à états d'ordre récupère lorsqu'une exécution arrive avant l'accusé de réception REST, si votre dimensionnement de position fait la bonne chose au plafond de levier. Ce sont ces échecs qui coûtent de l'argent en production, et aucun d'entre eux ne nécessite de capital réel pour apparaître.

À savoir avant d'architecturer autour : WEEX ne supporte actuellement ni l'exécution de webhook TradingView ni une passerelle FIX. Si votre stratégie supposait l'un ou l'autre, prévoyez plutôt REST et WebSocket.

Conclusion

L'API WEEX est simple une fois que vous avez internalisé que le spot et les futures sont deux produits partageant un schéma de signature et presque rien d'autre. Obtenez les quatre en-têtes corrects, signez les octets exacts que vous envoyez, mettez en cache la liste blanche des symboles de trading API, lisez les en-têtes de limite de débit au lieu de compter les requêtes, et gérez -1047, -1052 et -1058 explicitement — cela couvre la grande majorité de ce qui peut mal tourner.

La séquence qui gaspille le moins de temps : créez une clé avec permission Lecture seule, confirmez qu'un point de terminaison public répond, faites fonctionner une lecture privée signée, exécutez votre stratégie complète contre les points de terminaison de trading sur papier, et seulement ensuite activez la permission de trade et liez une liste blanche IP. Les références complètes des points de terminaison se trouvent dans la documentation de l'API futures WEEX et la documentation de l'API spot WEEX, avec les spécificités de permission et de limite de débit collectées dans la FAQ de l'API futures.

FAQ

1. Ai-je besoin de clés API WEEX séparées pour le spot et les futures ?

Non — une clé peut porter les deux permissions. Mais ce sont des cases à cocher séparées, et chacune est désactivée par défaut. Une clé avec seulement Spot coché renverra -1052 sur chaque ordre futures, et vice versa.

2. Quelles sont les limites de débit de l'API WEEX ?

Deux seaux indépendants : 500 poids par 10 secondes par IP pour les points de terminaison REST généraux, et 300 placements d'ordres par minute par compte pour les futures. WebSocket est plafonné à 20 connexions simultanées par IP, 100 canaux par connexion. Dépasser l'une d'elles renvoie HTTP 429 et un bannissement de 10 secondes.

3. Pourquoi ma clé API WEEX renvoie-t-elle -1049 juste après sa création ?

Les clés nouvelles et modifiées mettent environ 15 minutes à se propager à travers les systèmes de WEEX. Si la clé est fraîche, attendez avant de déboguer davantage. Si cela persiste, vérifiez si la passphrase contient des caractères spéciaux — WEEX recommande uniquement l'alphanumérique.

4. Puis-je trader chaque paire WEEX via l'API ?

Non. Seules les paires sur la liste blanche de trading API sont disponibles par programmation. Appelez GET /capi/v3/market/apiTradingSymbols pour la liste actuelle ; tout ce qui est en dehors renvoie -1058.

5. WEEX supporte-t-il les alertes TradingView ou FIX ?

Aucun n'est supporté à la mise à jour de la documentation d'avril 2026. L'automatisation s'exécute via les API REST et WebSocket.

6. Comment tester une stratégie API WEEX sans risquer de fonds ?

Utilisez les points de terminaison de trading sur papier futures sous /capi/v3/sim/. Ils acceptent la même authentification et signature que les points de terminaison réels et se règlent en SUSDT simulé.

Avertissement sur les risques

Les actifs crypto sont volatils et peuvent perdre de la valeur rapidement ; les trader peut entraîner une perte partielle ou totale de capital. Le trading API concentre ce risque plutôt que de le réduire. Les systèmes automatisés peuvent placer des centaines d'ordres avant qu'un humain ne remarque une erreur, et une erreur de signature, un flux de prix obsolète ou une reconnexion non gérée peuvent ouvrir des positions que personne n'avait l'intention de prendre. Le trading de futures ajoute un risque de levier : avec un levier disponible jusqu'à 400× sur certains contrats WEEX, des mouvements défavorables peuvent liquider une position en quelques secondes, et utiliser CONTRACT_PRICE comme déclencheur de stop sur un marché peu profond vous expose à des stop-outs provoqués par des mèches. Les clés API sont également un risque de garde — une clé non liée avec permission de trade est une information d'identification active qui fonctionne depuis n'importe quelle IP sur Internet. Liez une liste blanche IP, gardez la permission de trade désactivée jusqu'à ce que votre intégration soit testée contre les points de terminaison de trading sur papier, et dimensionnez les positions en supposant que votre propre code finira par mal se comporter.