Pour l'utilisateur ordinaire, le site officiel de Binance se résume à www.binance.com. Pour un développeur, la réalité est beaucoup plus complexe : ce à quoi votre code doit réellement se connecter, ce n'est pas la page vitrine, mais la série de noms d'hôtes api.binance.com, stream.binance.com, fapi.binance.com, etc. De nombreux programmeurs se font piéger par des documentations d'hameçonnage ou des SDK clones : la cause principale est de ne pas distinguer le « site officiel destiné aux utilisateurs » du « site officiel destiné aux développeurs ». Commencez par le Site Officiel de Binance pour préparer votre compte et vos clés API, puis installez l'Application Officielle Binance pour recevoir les notifications de double authentification. Sur iPhone, la configuration est décrite dans le Guide d'installation iOS.
La suite de cet article détaille, strictement du point de vue développeur, la structure des portails officiels de Binance : identification des entrées de documentation, distinction entre production et Testnet, vérification des sources de téléchargement des SDK, liste des hôtes WebSocket et moyens de suivre les changelogs.
Les bonnes portes d'entrée du portail développeur Binance
La documentation destinée aux développeurs n'est pas accrochée à la navigation de premier niveau de www.binance.com : elle est répartie sur plusieurs sous-domaines indépendants et sur une organisation GitHub. En ne reconnaissant que ces entrées, vous ne vous tromperez pas.
Le portail principal developers.binance.com
developers.binance.com est l'entrée unifiée du portail développeur de Binance. Il agrège les manuels de référence des interfaces Spot, Futures, Margin, Wallet et Staking. En haut à droite, vous pouvez basculer sur le Change Log, où chaque mise à jour d'API est horodatée à la minute près.
Le sujet du certificat TLS de ce domaine est Binance Holdings Ltd, et il partage la même chaîne de certificats que le site principal binance.com. Si le sujet ne correspond pas, vous êtes très probablement victime d'un détournement.
L'organisation GitHub binance
Les dépôts de code officiels sont centralisés sous l'organisation github.com/binance. C'est la source d'autorité la plus haute pour vérifier l'authenticité des SDK et des exemples de code. Quelques dépôts fréquemment utilisés :
- binance-spot-api-docs : spécification REST/WebSocket du spot
- binance-futures-connector-python : connecteur Python pour les contrats U-based
- binance-connector-node : SDK officiel Node.js
- binance-api-postman : collection Postman de débogage
La page de l'organisation GitHub affiche un badge Verified. Ce badge exige une liaison par enregistrement DNS TXT avec binance.com et ne peut donc pas être imité par une organisation clone.
L'entrée des articles techniques de Binance Academy
academy.binance.com est un site de contenus, pas un site d'interfaces, mais son onglet « Developer » publie des décryptages de design de protocole, des changements de structure de frais et des explications du comportement du moteur d'appariement. C'est très utile pour comprendre la logique métier derrière les interfaces.
Distinguer les hôtes de production et de Testnet
Binance fournit aux développeurs un environnement Testnet complet, mais les noms d'hôtes du Testnet et de la production sont très faciles à confondre. Se tromper d'hôte conduit à deux conséquences catastrophiques : tester avec de l'argent réel, ou placer un ordre réel avec une clé de test.
Liste des hôtes des interfaces spot
| Usage | Production | Testnet |
|---|---|---|
| API REST | api.binance.com | testnet.binance.vision |
| WebSocket Stream | stream.binance.com:9443 | stream.testnet.binance.vision:9443 |
| WebSocket API | ws-api.binance.com:443 | ws-api.testnet.binance.vision:443 |
À noter en particulier : le Testnet utilise le domaine indépendant binance.vision, et non un sous-domaine de binance.com. C'est voulu par Binance pour éviter qu'une ressemblance de noms ne provoque une confusion entre clé de production et clé de test.
Liste des hôtes des interfaces futures
| Usage | Production | Testnet |
|---|---|---|
| REST U-based | fapi.binance.com | testnet.binancefuture.com |
| WS U-based | fstream.binance.com | stream.binancefuture.com |
| REST Coin-based | dapi.binance.com | testnet.binancefuture.com |
| WS Coin-based | dstream.binance.com | dstream.binancefuture.com |
Le Testnet futures passe par binancefuture.com, encore un domaine indépendant. Si vous voyez dans votre code un hôte binance.com avec un path /fapi, c'est probablement un ancien SDK qui passait par un domaine unique redirigé ; les versions récentes séparent tout.
Les clés API ne sont pas interchangeables entre les deux environnements
Une clé API de production ne fonctionne pas sur le Testnet, et réciproquement. La clé de Testnet se génère sur la page testnet.binance.vision, en s'y connectant via un compte GitHub ; la clé de production se crée dans la page de sécurité du compte sur le Site Officiel de Binance. Les deux systèmes sont totalement isolés : la fuite d'une clé Testnet n'affecte pas vos fonds réels.
Vérifier l'authenticité des sources de téléchargement des SDK
Dans l'écosystème développeur, les attaques les plus fréquentes sont les paquets clones sur pip et npm, dont les noms sont particulièrement trompeurs. Pour télécharger un SDK, utilisez obligatoirement les sources légitimes ci-dessous.
Le bon nom de paquet Python
Binance ne publie pas de paquet Python officiel nommé « binance ». Pour se connecter aux interfaces, utilisez l'un des deux suivants :
- binance-connector : maintenu officiellement, l'éditeur sur PyPI est Binance
- python-binance : bibliothèque communautaire historique, écrite par Sam McHardy, citée officiellement
Les noms suivants sont des imitations : binance-api, binancepy, pybinance, binance-sdk (ancienne version déguisée avec tiret). Sur PyPI, vous pouvez consulter le domaine e-mail de l'éditeur : celui du paquet officiel est impérativement en @binance.com.
Vérification d'intégrité des paquets
Depuis 2023, pip prend en charge la vérification par hash ; verrouiller le hash dans requirements.txt empêche un remplacement par un attaquant intermédiaire :
binance-connector==3.7.0 \
--hash=sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
La valeur du hash se trouve sur la page PyPI, dans la section « Download files » : comparez avant d'installer.
Le bon nom de paquet Node.js
Sur npm, le scope du paquet officiel est @binance/connector. Le scope @binance fait l'objet d'une vérification d'organisation au niveau npm ; les imitateurs ne peuvent pas s'y enregistrer. Le paquet sans scope node-binance-api est une bibliothèque communautaire historique, relativement fiable, mais non officielle.
Le cas de Go et de Rust
Binance n'a pas publié de SDK officiel pour Go. Le paquet communautaire dominant est adshao/go-binance ; l'auteur adshao est un développeur partenaire historique de Binance et la qualité du code est bonne. Côté Rust, rien non plus d'officiel ; ccxt-rust et binance-rs sont deux implémentations communautaires, à auditer avant utilisation.
Détails d'exploitation des connexions WebSocket longues
Une requête REST est éphémère ; une connexion WebSocket reste ouverte longtemps, et comporte donc beaucoup plus de subtilités d'exploitation.
Déconnexion forcée au bout de 24 heures
Le WebSocket spot de Binance impose une règle stricte : une connexion ne peut être maintenue plus de 24 heures ; passé ce délai, le serveur la ferme activement. Les développeurs doivent implémenter une logique de reconnexion ; l'idéal est de se reconnecter proactivement autour de 23 heures plutôt que d'attendre d'être coupé.
Heartbeat PING/PONG
Le serveur envoie une trame PING toutes les 3 minutes ; le client doit répondre par un PONG dans les 10 minutes, faute de quoi la connexion sera coupée. La plupart des bibliothèques WebSocket s'en occupent automatiquement, mais certaines implémentations bas niveau ne le font pas : il faut alors intercepter manuellement la trame de heartbeat.
Plafond du nombre de souscriptions
Une connexion unique peut souscrire au maximum à 1024 flux, au-delà vous obtenez le code d'erreur -1013. Pour surveiller un grand nombre de paires simultanément, organisez plusieurs connexions côté client.
Écriture des flux combinés
Le format de l'URL d'un flux combiné est stream.binance.com:9443/stream?streams=btcusdt@trade/ethusdt@kline_1m, les flux étant séparés par une barre oblique. Pour un flux unique, c'est stream.binance.com:9443/ws/btcusdt@trade, avec un path différent.
Comment suivre les changements d'API
Binance modifie ses API plus souvent que la plupart des plateformes ; sans abonnement au journal des changements, vous tomberez facilement sur une interface retirée ou sur un champ dont la signification a changé.
Emplacement du Change Log officiel
Le Change Log est publié en parallèle sur binance-docs.github.io et developers.binance.com ; l'historique remonte jusqu'en 2017. Chaque entrée porte l'une des étiquettes UPDATE, NEW ou DEPRECATED.
Abonnement aux Releases GitHub
Sur le dépôt github.com/binance/binance-spot-api-docs, utilisez Watch → Releases only. Chaque commit de documentation de protocole déclenche une notification e-mail : plus fiable qu'un polling web.
Liste de diffusion d'alerte
Les changements majeurs d'API font l'objet d'une notification envoyée à l'adresse de votre compte, 2 semaines à 2 mois à l'avance. Associez donc vos clés API à une adresse e-mail que vous consultez régulièrement, pas à une adresse jetable.
Ajustements de rate limit
Les limites de fréquence sont la partie la plus susceptible d'évoluer silencieusement. Binance renvoie en temps réel l'en-tête HTTP X-MBX-USED-WEIGHT-1M ; surveiller son évolution permet de détecter un ajustement de politique plus rapidement qu'en lisant la documentation.
Check-list de connexion sécurisée
Ces points, vérifiés avant tout déploiement, évitent 95 % des pièges de sécurité :
- Activation obligatoire de la liste blanche d'IP : dans la page de gestion des API, cochez « Restrict access to trusted IPs only » ; sans cela, vous êtes nu sur l'Internet public.
- Principe du moindre privilège : créez des clés en lecture seule et des clés de trading séparées ; ne cochez jamais le droit de retrait par défaut.
- Pas de clés dans le dépôt de code : utilisez des variables d'environnement ou un Vault ; passez gitleaks en CI pour éviter tout commit accidentel.
- Forcez HTTPS : rejetez tout appel API en HTTP pour empêcher les attaques de type homme du milieu.
- Signatures en HMAC-SHA256 : concaténez les paramètres par ordre alphabétique, et n'inversez pas l'ordre entre timestamp et signature.
- recvWindow inférieur à 5 secondes : la valeur par défaut est 5000 ms ; un seuil trop élevé offre à un attaquant une fenêtre de rejeu plus large.
FAQ
Q1 : Les pages de documentation du site officiel et binance-docs.github.io sont-elles identiques ?
Elles peuvent être désynchronisées pendant un court intervalle. binance-docs.github.io est une GitHub Pages mise à jour par commit ; developers.binance.com est diffusé en statique via le CDN officiel ; un décalage de quelques minutes à quelques heures est habituel. Pour la dernière version du protocole, GitHub Pages est la source la plus fiable.
Q2 : Les ordres passés sur le Testnet peuvent-ils affecter mon compte réel ?
Absolument pas. Le Testnet est un système d'appariement indépendant, les fonds sont des jetons de test que l'on réclame, et le carnet d'ordres est isolé du réseau principal. Le seul lien est que les données de marché proviennent d'un snapshot du mainnet, ce qui fait que les courbes ressemblent à celles du vrai marché.
Q3 : Entre python-binance et binance-connector, que choisir ?
Cela dépend du besoin. binance-connector est maintenu officiellement et couvre les interfaces les plus récentes, mais son style d'API est plutôt fonctionnel ; python-binance propose une encapsulation plus abstraite, synchrone et asynchrone, avec une documentation d'exemples plus riche. En production, préférez connector ; en prototypage rapide, python-binance.
Q4 : Faut-il appliquer un backoff exponentiel à la reconnexion WebSocket ?
Oui. En cas de pic de trafic anormal, Binance bloque temporairement l'IP ; sans backoff, vous déclenchez un blocage en boucle. Stratégie recommandée : première tentative à 1 seconde, multiplication par 2 à chaque essai, plafond à 60 secondes, réinitialisation du compteur après succès.
Q5 : Binance dispose-t-il d'un Demo Trading comme OKX ?
Oui, mais sous un autre nom. Pour le spot, c'est le Testnet (testnet.binance.vision) ; pour les futures, c'est Binance Futures Testnet (testnet.binancefuture.com). Les deux portails et systèmes de clés API sont indépendants, contrairement à OKX qui permet une bascule depuis un même compte.