Une API key d’exchange est une paire composée d’une API Key et d’un API Secret. Avec cette key, les programmes et services travaillent avec un compte via l’API : ils lisent le solde, ouvrent et ferment des trades et exécutent d’autres opérations autorisées pour cette key sans connexion au tableau de bord web.
Objectif du matériel : décrire les restrictions qu’un exchange applique aux requêtes API : vérification de signature via API Secret, droits de la key (permissions), liaison de la source de la requête à une IP whitelist, restrictions de retrait via une whitelist d’adresses de retrait et isolation du solde via des sub-accounts. Ces restrictions réduisent le risque qu’un leak de la paire API Key + API Secret entraîne un retrait d’actifs ou des trades déficitaires.
🧭 Comment les exchanges crypto contrôlent l’accès API
Les API keys sont utilisées par les trading bots, terminaux, services de reporting et intégrations internes. Un exchange n’exécute une requête API qu’après avoir vérifié la signature (API Secret), les droits d’opération (permissions), l’adresse IP source (IP whitelist) et l’heure de la requête (timestamp et recvWindow). La vérification temporelle bloque une répétition ultérieure de la requête, même si la requête a été interceptée.
Le risque API est réduit par les paramètres de la key. IP whitelist accepte les requêtes uniquement depuis des adresses IP spécifiées. Permissions limite l’ensemble des opérations que l’exchange exécutera avec la key. Une whitelist d’adresses de retrait limite la liste des destinataires. Sub-accounts sépare les soldes et les keys entre sub-accounts, afin qu’une seule key n’ait pas accès à tous les actifs du compte.
🔍 Comment un exchange vérifie une requête API : signature, droits, IP et temps
Une API key se compose d’une API Key (l’identifiant de la key) et d’un API Secret (le secret utilisé pour la signature). La signature confirme à l’exchange que la requête a été créée avec l’API Secret et n’a pas été modifiée en transit.
- Formation des paramètres de requête vers l’API endpoint de l’exchange (l’adresse API qui accepte une opération précise)
- La requête définit l’opération : ouvrir ou annuler un ordre, obtenir un solde, effectuer un transfert ou lancer un retrait.
- La requête contient un timestamp et parfois une fenêtre temporelle autorisée (recvWindow). L’exchange compare ces valeurs à sa propre heure et rejette la requête si elle sort de l’intervalle autorisé.
- Signature des paramètres de requête via HMAC
- HMAC est une signature par hash générée avec une clé secrète. La chaîne de paramètres est signée avec l’API Secret.
- L’exchange recalcule le HMAC avec les mêmes paramètres et compare la signature. Une non-correspondance signifie que l’expéditeur ne possède pas l’API Secret ou que les paramètres ont été modifiés.
- Vérification des restrictions de la key et décision d’exécution
- Permissions définit quelles opérations sont autorisées pour la key (read/trade/transfer/withdraw sur la plupart des exchanges centralisés, CEX).
- IP whitelist limite les sources de requêtes. L’exchange rejette une requête si l’IP de l’expéditeur ne figure pas dans la whitelist de la key.
- Exécution de l’opération et retour du résultat
- Si les droits sont insuffisants, l’exchange renvoie un refus et n’exécute pas l’opération, même avec une signature correcte.
- Si l’IP ne correspond pas, l’exchange renvoie un refus à l’étape d’autorisation et ne passe pas à une opération de trading ou de retrait.
Composants d’accès API contrôlés par l’exchange
L’exchange réduit le risque API grâce à trois vérifications dans chaque requête : signature via API Secret, permissions pour les opérations et IP whitelist pour la source de la requête.
- API Secret est stocké uniquement dans un coffre de secrets et dans la mémoire du processus qui signe les requêtes.
- Permissions est activé selon la tâche de la key : lecture pour le reporting, trading pour un bot, retrait uniquement pour les paiements opérationnels.
- IP whitelist contient uniquement les adresses IP des serveurs qui envoient réellement des requêtes, afin que la liste n’élargisse pas la surface d’attaque.
Si un attaquant obtient une API Key sans API Secret, l’exchange rejette la requête à cause d’une signature invalide. Si un attaquant obtient à la fois API Key et API Secret, l’exchange rejette la requête lorsque permissions n’autorise pas l’opération ou que l’IP ne figure pas dans la whitelist.
🎯 Quelles pertes sont possibles via API : retraits, transferts et pertes de trading
Les dommages via API dépendent des permissions activées et du solde accessible à cette key. Une trade-only key présente un risque plus faible sur un sub-account avec un petit solde opérationnel et un risque plus élevé sur un sub-account contenant le capital principal.
Trois scénarios exécutés par un exchange via API
Les pertes via API surviennent par retrait, transfert interne ou trades qui créent une perte au prix d’exécution.
- Retrait direct : une key avec withdraw permission lance un retrait vers une adresse que l’exchange autorise après ses vérifications et ses règles de whitelist.
- Transfert interne : une key avec transfer permission déplace des actifs entre wallets de produit ou entre sub-accounts si l’exchange autorise ces opérations via l’API.
- Perte de trading sans retrait : une key avec trade permission place des ordres sur une paire peu liquide et exécute des trades à un prix moins favorable, créant une perte due au slippage, au spread et aux frais.
Une withdraw permission désactivée supprime le retrait direct. Trade permission reste une source de pertes si un solde important est conservé dans le trading wallet et si la key n’est pas limitée par IP et par instruments.
Signaux après lesquels une vérification API devient nécessaire
- Des ordres sont apparus alors qu’ils ne correspondent pas à la logique du trading system ni au calendrier de lancement.
- Des transferts sont apparus entre wallets ou sub-accounts sans raison opérationnelle.
- De nouvelles permissions sont apparues dans les paramètres de la key ou IP whitelist a été supprimée.
- Des erreurs de signature sont apparues dans les logs du trading system et la fréquence des requêtes a augmenté alors que le code est resté inchangé.
🌐 IP whitelist : liaison d’une key au serveur source des requêtes
IP whitelist oblige l’exchange à accepter les requêtes uniquement depuis des adresses IP prédéfinies. Si l’API Secret se retrouve dans le code, les logs, les sauvegardes ou un service tiers, un attaquant ne pourra pas envoyer de requête depuis une IP absente de la whitelist.
Choix d’une source stable pour les requêtes API
- Un VPS (serveur privé virtuel) avec une IP publique statique convient à IP whitelist et au fonctionnement continu d’un trading system.
- Une connexion domestique avec IP dynamique ne convient pas, car un changement d’IP provoque des refus de requêtes API jusqu’à la mise à jour de la whitelist.
Configuration d’IP whitelist pour une API key
- IP whitelist inclut l’IP du serveur du trading system et du serveur de secours si le serveur de secours est réellement utilisé.
- Si l’exchange prend en charge CIDR (notation de sous-réseau, par exemple 203.0.113.10/32), la plage minimale est définie afin de ne pas élargir la liste des sources.
Vérification de la résilience de l’accès API
- Une API key de secours sur une IP distincte est utilisée lors d’une migration d’infrastructure et d’un changement d’adresse serveur.
- La procédure de mise à jour d’IP whitelist est documentée à l’avance afin qu’un changement d’IP ne coïncide pas avec une perte de contrôle des ordres.
Dans l’infrastructure cloud, les requêtes peuvent sortir vers Internet via NAT (traduction d’adresses en bordure de réseau). Dans ce cas, l’IP externe visible par l’exchange peut différer de l’IP du conteneur ou de la machine virtuelle. IP whitelist doit contenir l’egress IP (l’IP externe du trafic sortant), sinon l’exchange rejettera les requêtes.
IP whitelist ne protège pas contre la compromission du VPS. Si le serveur est pris en contrôle, un attaquant enverra des requêtes depuis la même IP, donc la protection de l’accès au VPS et le contrôle des mises à jour restent une partie de la protection API.
IP whitelist bloque les requêtes provenant de serveurs non autorisés, car l’exchange compare l’IP source à la whitelist et rejette la requête avant l’exécution d’une opération de trading ou de retrait.
🔑 Permissions : quels droits sont attribués à une key pour une tâche précise
Permissions détermine quels API endpoints l’exchange autorisera à appeler avec cette key. Les noms des droits dépendent de l’exchange, mais le schéma est généralement le même : read pour la lecture, trade pour les ordres, transfer pour les transferts internes et withdraw pour les retraits vers la blockchain.
| Tâche | Autoriser | Interdire | Opération bloquée |
|---|---|---|---|
| Screener/analytics | Read | Trade; Transfer; Withdraw | Placement d’ordres et déplacement d’actifs |
| Trading bot | Read; Trade | Withdraw | Retrait direct de fonds via API |
| Reporting | Read | Trade; Transfer; Withdraw | Opérations en cas de compromission du service de reporting |
| Transferts opérationnels | Read; Transfer | Trade; Withdraw | Opérations de trading et retraits vers la blockchain |
Read-only key pour monitoring et reporting
Une read-only key est utilisée lorsqu’un système doit lire les soldes, l’historique des trades et les statuts des positions, mais ne doit pas modifier l’état du compte.
- Une read-only key bloque le placement et l’annulation d’ordres, car l’exchange rejette les trading endpoints pour cette key.
- IP whitelist limite l’accès aux données à un serveur précis et bloque les requêtes provenant d’IP non autorisées en cas de leak de l’API Secret.
- Une read-only key distincte pour le reporting sépare le risque du service de reporting du risque de la trading key.
Une read-only key expose les soldes et l’historique, mais ne permet ni retraits ni trades, car l’exchange rejette les endpoints trade/transfer/withdraw.
Trade key pour un trading system sans retrait
Une trade key est utilisée pour placer et annuler des ordres. Withdraw permission n’est pas nécessaire pour les opérations de trading.
- Trade permission donne accès à la gestion des ordres et des positions dans les marchés du compte.
- Une withdraw permission désactivée bloque les retraits, car l’exchange rejette les withdrawal endpoints pour cette key.
- IP whitelist lie la key au serveur du trading system et bloque les requêtes venant de machines non autorisées en cas de leak de l’API Secret.
Une trade-only key crée un risque pour les fonds du trading wallet, donc le trading sub-account conserve généralement un solde opérationnel, et non le capital principal.
Transfer key pour les mouvements internes
Une transfer key est utilisée pour les transferts à l’intérieur de l’exchange : entre wallets de produit ou entre sub-accounts, si l’exchange autorise ces opérations via l’API.
- Transfer permission permet des transferts internes qui ne vont pas sur la blockchain.
- Une trade permission désactivée exclut les trades, car la transfer key ne peut pas créer d’ordres.
- Une withdraw permission désactivée exclut les retraits vers la blockchain en cas de compromission de la transfer key.
La séparation de transfer et trade sur des keys différentes réduit les dommages en cas de leak, car une seule key ne donne pas simultanément accès aux trades et au déplacement des actifs.
Permissions définit quelle opération l’exchange autorisera pour cette key. Les permissions superflues élargissent l’ensemble des actions que l’exchange exécutera avec une key compromise, donc les droits sont activés uniquement pour un processus précis.
🏷️ Protection des retraits : whitelist d’adresses, confirmations et limites
Withdraw permission permet à une API key d’initier le retrait de fonds depuis le solde d’un exchange vers une blockchain. La protection des retraits repose sur une whitelist d’adresses destinataires, le contrôle des changements de whitelist et des limites de retrait.
Dans les intégrations de trading, withdraw permission est généralement désactivée. Les ordres, annulations et lectures de solde s’exécutent à l’intérieur de l’exchange et ne nécessitent pas de retrait vers le réseau. Read permission suffit pour le monitoring et le reporting. Trade permission suffit pour le trading algorithmique.
Exemple : un trading bot fonctionne avec une key ayant trade permission et sans withdraw permission. Si la key est compromise, un attaquant pourra ouvrir et fermer des trades via les trading endpoints. L’exchange rejettera une requête de retrait, car la key n’a pas withdraw permission.
La whitelist d’adresses limite le destinataire du retrait : l’exchange envoie les fonds uniquement vers des adresses ajoutées à l’avance. Sur de nombreux exchanges, l’ajout d’une adresse à la whitelist nécessite une 2FA (authentification à deux facteurs) et une confirmation via un canal séparé, par exemple email, application ou hardware key. Dans ce cas, le retrait vers une nouvelle adresse dépend non seulement de l’API key, mais aussi du contrôle de ces canaux de confirmation.
Le délai de modification de whitelist (security lock, hold) n’active pas immédiatement l’adresse ajoutée. Lorsque le délai est activé, le retrait vers une nouvelle adresse est bloqué pendant la période de hold, ce qui permet de remarquer l’adresse ajoutée avant le premier retrait.
La connexion API des trading bots, les trade-only keys et IP whitelist sont présentés dans le matériel « Gagner avec les bots de trading crypto ».
Les limites de retrait limitent le montant des pertes si un attaquant obtient une key qui passe les vérifications de whitelist et de confirmation. La limite quotidienne est définie pour les montants de paiements opérationnels réguliers, et non pour le solde total du compte, afin qu’un seul cycle de retrait ne puisse pas vider tout le dépôt.
La compromission de l’email augmente le risque, car de nombreux exchanges utilisent l’email pour confirmer l’ajout d’adresses et les réinitialisations de sécurité, y compris les liens de confirmation et les notifications de changement de whitelist.
Withdraw permission sans whitelist d’adresses fait d’un leak d’API key un canal direct de retrait vers la blockchain. Withdraw permission avec whitelist d’adresses et délai de modification de whitelist déplace le risque critique vers la compromission des canaux de confirmation. Les limites de retrait limitent le montant des pertes si les autres restrictions sont contournées.
🛡️ Sub-accounts : isolation du solde, des keys et des processus
Sub-accounts sépare les soldes et les API keys à l’intérieur d’un même exchange. En cas de leak d’une key, les opérations sont limitées aux actifs du sub-account concerné.
- Séparation du storage et du trading entre différents sub-accounts
- Le sub-account de storage conserve le capital principal et n’utilise pas de trading API keys permanentes.
- Les trading sub-accounts conservent les soldes opérationnels destinés à des bots et stratégies précis.
- Contrôle des transferts internes via API
- La désactivation de transfer permission sur les trading keys réduit la possibilité de déplacer des actifs en cas de leak d’une trading key.
- Une transfer key dédiée est utilisée lorsque les transferts internes font partie du processus opérationnel.
- Limitation des instruments de la key lorsque la whitelist de paires de trading est prise en charge
- La whitelist de paires de trading bloque les trades sur des instruments qui n’appartiennent pas au trading system.
- La limitation des paires réduit le risque de pertes sur les marchés peu liquides.
Schéma d’isolation pour plusieurs trading systems
Le schéma d’isolation sépare le solde via des sub-accounts et sépare l’accès via API keys, permissions et IP whitelist.
- Un trading system sur un exchange fonctionne via un sub-account séparé et une trade-only key liée à l’IP du VPS.
- Le reporting est connecté avec une read-only key sur un serveur distinct, afin qu’un leak du reporting n’expose pas la trading key.
- Les transferts opérationnels sont effectués avec une transfer key sans trade ni withdraw permissions.
En cas de leak de la key d’un trading system, l’exchange exécute les opérations uniquement dans le cadre du solde de son sub-account, ce qui limite les pertes au solde opérationnel.
🗄️ Stockage des secrets et rotation : comment API Secret fuit depuis l’infrastructure
API Secret fuit plus souvent non pas via l’exchange, mais depuis l’infrastructure du trading system : dépôts de code, pipelines CI/CD (processus automatisés de build et de déploiement), logs d’applications, dumps de bases de données, captures d’écran et sauvegardes. La gestion des secrets définit les emplacements de stockage de l’API Secret et les rôles pouvant y accéder.
API Secret n’est pas stocké dans le code de l’application. La valeur du secret est injectée au démarrage du service depuis un stockage protégé et n’est pas enregistrée dans les fichiers du projet ni dans le dépôt. Le code et la configuration conservent une référence au secret, et non sa valeur.
Exemple : un trading bot est déployé via CI/CD. Dans le dépôt, seul le nom du secret est stocké, et la valeur de l’API Secret est injectée à l’étape de déploiement depuis un stockage protégé. En cas de leak du code et de l’historique des commits, l’API Secret n’y figure pas.
En production, API Secret est stocké dans un secret manager — un service qui conserve les secrets sous forme chiffrée et les fournit uniquement aux processus autorisés via IAM (gestion des accès par rôles). Ce schéma sépare les secrets de production des environnements de développement et des services de test.
Les causes comportementales des erreurs dans la gestion du risque et le plan de trading sont présentées dans le matériel « Psychologie du trading ».
La rotation des API keys réduit le risque d’un leak longue durée. La rotation comprend la création d’une nouvelle key sur l’exchange, le basculement du système vers le nouvel API Secret et la révocation de l’ancienne key afin que l’exchange cesse d’accepter les signatures avec l’ancien secret.
Le basculement est planifié sur une période sans positions ouvertes ni ordres limite actifs, afin que le changement d’API Secret n’interrompe pas la gestion des ordres et du risque.
Règles minimales de stockage d’API Secret
- API Secret est stocké dans un secret manager ou dans un stockage chiffré avec contrôle d’accès.
- API Secret n’entre pas dans Git, Docker image, CI artifacts ni dans les sauvegardes en clair.
- Le secret de production n’est pas accessible depuis l’environnement de développement et n’est pas accessible aux rôles qui ne lancent pas le trading system.
- La rotation inclut la révocation de l’ancienne key après le basculement, afin que l’ancien secret cesse de fonctionner côté exchange.
Permissions, IP whitelist et whitelist d’adresses protègent côté exchange, tandis que secret management réduit le risque de leak d’API Secret depuis le code et les logs côté infrastructure.
🧩 Terminaux et bots tiers : comment la connexion influence le risque
Un service tiers reçoit l’API Key et l’API Secret afin de signer des requêtes au nom du compte. Si le service accepte la key dans un tableau de bord web, l’API Secret est stocké dans l’infrastructure du fournisseur. Lors d’un incident chez le fournisseur, un attaquant pourra signer des requêtes et réussir la vérification de signature côté exchange.
✅ Signes d’un risque contrôlé
- Le service fonctionne avec des read-only et trade-only keys et n’exige pas withdraw permission pour le trading et le reporting.
- Le service affiche un journal d’actions API : ordres créés et endpoints appelés.
- Le service prend en charge une connexion via un sub-account distinct avec un solde opérationnel limité.
❌ Signes d’un risque accru
- Le service exige withdraw permission pour des fonctions qui ne sont pas liées aux paiements opérationnels.
- Le service exige la désactivation d’IP whitelist et ne propose pas de modèle avec un agent côté utilisateur et une IP fixe.
- Le service ne fournit pas d’historique des actions API, donc l’enquête repose sur des signaux indirects.
Exemple de configuration : les signaux et le reporting utilisent une read-only key, les opérations de trading utilisent une trade-only key sur un sub-account avec solde opérationnel, et les retraits via API sont désactivés.
Un service tiers n’annule pas les restrictions de l’exchange. Un sub-account, IP whitelist, des permissions minimales et withdraw permission désactivée limitent le risque au solde opérationnel.
🧯 Réaction à un leak de key : arrêt de l’exécution et conservation des traces
En cas de suspicion de leak de la paire API Key + API Secret, le risque évolue rapidement, car l’exchange exécute les opérations dès que la signature, les droits, l’IP et l’heure de la requête sont vérifiés. La réaction commence par l’arrêt de l’autorisation de la key et la conservation des traces d’opérations.
- Révocation de la key côté exchange
- La désactivation ou la suppression de la key arrête l’acceptation des requêtes signées avec cette API Key.
- La désactivation de toutes les keys du sub-account est utilisée si la source du leak n’est pas identifiée.
- Conservation des traces d’opérations
- La liste des ordres ouverts et l’historique des trades sur la période d’anomalie montrent quelles opérations ont été exécutées.
- L’historique des retraits et les changements de whitelist d’adresses montrent les tentatives de retrait et la préparation des adresses.
- Fermeture des canaux d’accès supplémentaires au compte
- Le changement de mot de passe et la vérification 2FA réduisent le risque d’accès à l’interface web.
- La vérification de la sécurité de l’email est nécessaire, car les confirmations de retrait et les changements de whitelist sont souvent liés à l’email.
- Restauration de l’accès opérationnel
- Une nouvelle key est créée avec des permissions minimales et IP whitelist sur le serveur actuel.
- L’API Secret est mis à jour dans le secret manager afin que l’ancien secret cesse d’être utilisé.
La révocation de la key arrête l’exécution des actions, car l’exchange cesse d’accepter les signatures pour cette API Key, même si les requêtes continuent d’arriver.
✅ Configuration qui réduit le risque de retrait après un leak de key
Le risque de retrait après un leak de la paire API Key + API Secret est réduit lorsque la trade key n’a pas withdraw permission, que les requêtes sont limitées par IP whitelist et que le capital principal est séparé du trading sub-account.
Ensemble minimal de paramètres pour la trade key d’un trading system
- Le trading system fonctionne sur un VPS avec IP fixe, et cette IP est ajoutée à l’IP whitelist de la key.
- La key possède read + trade permissions et n’a pas withdraw permission.
- Le trading sub-account contient le solde opérationnel, tandis que le capital principal est stocké séparément sans trading keys permanentes.
- API Secret est stocké dans un secret manager ou dans un stockage chiffré et n’entre pas dans les dépôts ni les logs.
IP whitelist, permissions minimales, whitelist d’adresses pour les retraits rares et isolation via sub-accounts limitent les dommages au solde opérationnel et réduisent le risque de retrait vers la blockchain via une key compromise.
❓ FAQ sur la sécurité des API keys
Pourquoi IP whitelist protège-t-elle même en cas de leak d’API Secret ?
L’exchange compare l’IP source de la requête à l’IP whitelist de la key et rejette la requête si l’IP ne correspond pas. La signature HMAC peut être correcte, mais l’opération ne sera pas exécutée, car la vérification IP s’effectue côté exchange.
Quand withdraw permission est-elle réellement nécessaire ?
Withdraw permission est nécessaire pour les paiements opérationnels automatisés vers la blockchain. Pour le trading, le monitoring et le reporting, withdraw permission n’est pas nécessaire, car ces processus utilisent des endpoints de trading et de lecture à l’intérieur de l’exchange.
Pourquoi une trade-only key peut-elle provoquer des pertes sans retrait ?
Une trade-only key permet de placer des ordres. Avec accès à une trade-only key, un attaquant peut exécuter des trades à un prix moins favorable sur une paire peu liquide et créer une perte due au slippage, au spread et aux frais si un solde important se trouve dans le trading wallet.
Pourquoi utiliser un sub-account séparé pour chaque trading system ?
Un sub-account limite le solde accessible à la key. En cas de leak de la key d’un trading system, les dommages sont limités aux actifs de ce sub-account, car l’exchange exécute les opérations dans le solde du sub-account concerné.
Comment effectuer une rotation des keys sans perdre le contrôle des ordres ?
La rotation comprend la création d’une nouvelle key, le basculement du trading system vers le nouvel API Secret et la révocation de l’ancienne key. Le basculement est planifié sur une période sans positions ouvertes ni ordres limite actifs, afin que le changement de key n’interrompe pas la gestion des ordres.
Comment limiter le risque lié à la connexion d’un terminal tiers ?
Le risque est limité par une trade-only key sur un sub-account avec solde opérationnel, IP whitelist (si les requêtes passent par un agent côté utilisateur) et withdraw permission désactivée lorsque le terminal ne participe pas aux retraits opérationnels.
🧷 Comment les restrictions API réduisent le risque de retrait et de dommages de trading
Le risque API dépend des opérations autorisées et des vérifications que l’exchange applique à chaque requête : signature (API Secret), permissions, IP whitelist et paramètres de temps de requête.
- Withdraw permission désactivée bloque les retraits vers la blockchain via API, car l’exchange rejette les withdrawal endpoints pour une key sans ce droit.
- Une whitelist d’adresses de retrait limite le destinataire, car l’exchange envoie les fonds uniquement vers des adresses ajoutées à l’avance.
- IP whitelist limite la source des requêtes, car l’exchange rejette les requêtes provenant d’IP qui ne figurent pas dans la liste de la key, même avec une signature correcte.
- Sub-accounts limite le volume des pertes, car la key obtient accès au solde d’un sub-account précis, et non à tous les actifs du compte.