Comment utiliser l'API Coinbase : un guide étape par étape

Coinbase, un leader mondial dans le paysage des échanges d'actifs numériques, propose une suite robuste d'Interfaces de Programmation d'Applications (API). Ces API sont l'épine dorsale des développeurs, des traders algorithmiques et des institutions financières qui cherchent à s'intégrer de manière programmatique aux services de trading et de données de Coinbase. Ce guide fournit une exploration technique détaillée de l'API Coinbase Exchange, en se concentrant sur la mise en œuvre pratique, les fonctionnalités de base et les meilleures pratiques opérationnelles.

💡

Vous voulez un excellent outil de test d'API qui génère une belle documentation API ?

Vous voulez une plateforme intégrée et tout-en-un pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos demandes et remplace Postman à un prix beaucoup plus abordable !

button

Configuration initiale et authentification

Une interaction réussie avec l'API Coinbase Exchange commence par la préparation du compte, la gestion sécurisée des clés API et une compréhension précise du protocole d'authentification.

Conditions préalables du compte et génération de clés API

Un compte Coinbase vérifié, généralement un compte Coinbase Advanced Trade ou institutionnel, est requis. Les clés API sont générées dans les paramètres de votre compte. Ce processus génère trois informations essentielles :

Clé API : Une chaîne alphanumérique publique (par exemple, k7b9f2d7e8h1g3j4) identifiant votre application.
Secret API : Une chaîne alphanumérique privée (par exemple, S9vP3rK2sLqR7xW1yZ0aB5cD6fE8gH9i). Ce secret n'est affiché qu'une seule fois lors de la génération et doit être stocké en toute sécurité.
Phrase secrète : Une autre information d'identification de sécurité (par exemple, mySecureP@$$phr@se2024!) créée par vous lors de la génération de la clé.

Les autorisations de clé API sont granulaires, ce qui vous permet de restreindre les actions (par exemple, affichage seul, exécution de transactions, capacités de retrait). Respectez toujours le principe du moindre privilège.

Authentification des requêtes API

L'API Coinbase Exchange utilise un mécanisme d'authentification basé sur la signature (HMAC-SHA256) pour tous les points de terminaison privés et authentifiés. Chaque requête nécessite plusieurs en-têtes HTTP personnalisés :

CB-ACCESS-KEY : Votre clé API.
CB-ACCESS-SIGN : La signature HMAC-SHA256 encodée en base64.
CB-ACCESS-TIMESTAMP : Un horodatage Unix epoch actuel (secondes).
CB-ACCESS-PASSPHRASE : Votre phrase secrète de clé API.

La signature (CB-ACCESS-SIGN) est générée en créant un hachage HMAC-SHA256 d'une chaîne de pré-hachage. La chaîne de pré-hachage est une concaténation de :

L'horodatage (sous forme de chaîne).
La méthode HTTP en majuscules (par exemple, GET, POST).
Le chemin de la requête (par exemple, /orders, /products/BTC-USD/book).
Le corps de la requête (pour les requêtes POST ; une chaîne vide si aucun corps).

Exemple de construction de chaîne de pré-hachage (pour une requête POST) :

timestamp = str(time.time())
method = "POST"
request_path = "/orders"
body_json_string = '{"product_id": "BTC-USD", "side": "buy", "type": "limit", "price": "50000.00", "size": "0.1"}' // JSON string, not Python dict
prehash_string = timestamp + method + request_path + body_json_string

// The API Secret needs to be base64-decoded before being used as the HMAC key.
// secret_decoded = base64.b64decode(api_secret)
// signature = hmac.new(secret_decoded, prehash_string.encode('utf-8'), hashlib.sha256).digest()
// CB_ACCESS_SIGN = base64.b64encode(signature)

Les chaînes de pré-hachage mal construites ou les écarts d'horodatage (assurez-vous que l'horloge de votre serveur est synchronisée via NTP) sont des sources courantes d'erreurs d'authentification (HTTP 401).

Bibliothèques clientes et environnement de développement

Les bibliothèques clientes officielles et développées par la communauté pour des langages comme Python (cbpro), Node.js (coinbase-pro-node), Java et Go abstraient ces complexités d'authentification. Alternativement, des requêtes HTTP directes peuvent être effectuées à l'aide d'outils comme curl ou de modules clients HTTP standard, ce qui nécessite une implémentation manuelle du processus de signature.

L'environnement Sandbox pour les tests

Coinbase fournit un environnement Sandbox pour le développement et les tests, essentiel avant d'interagir avec les marchés en direct.

Objectif et fonctionnalité

Le Sandbox reflète les fonctionnalités de l'API de production, mais utilise des fonds de test et des données de marché simulées. Il permet de :

Tester sans risque les algorithmes de trading.
Vérifier la logique d'intégration de l'API et la gestion des erreurs.
Se familiariser avec les structures de requêtes/réponses de l'API.

Principales différences par rapport à la production

Points de terminaison API : Sandbox utilise des URL de base distinctes.
Production : https://api.exchange.coinbase.com
Sandbox : https://api-public.sandbox.exchange.coinbase.com (Remarque : les URL exactes du Sandbox doivent toujours être confirmées à partir de la documentation officielle).
Clés API : Des clés API distinctes doivent être générées pour et utilisées exclusivement avec le Sandbox.
Données de marché et liquidité : La profondeur du carnet d'ordres, le volume des transactions et les mouvements de prix sont simulés. La simulation de remplissage des ordres peut être plus simpliste et peut ne pas refléter parfaitement le glissement ou les scénarios de remplissage partiel du monde réel.
Pas de fonds réels : Tous les actifs et transactions sont virtuels. Des soldes de test sont généralement fournis ou peuvent être réinitialisés.

Passage à la production

Une stratégie de déploiement robuste comprend des configurations distinctes pour Sandbox et Production, qui diffèrent principalement en termes d'informations d'identification API et d'URL de base. Des tests approfondis dans le Sandbox sont primordiaux pour éviter les erreurs avec des fonds réels.

Fonctionnalités de base de l'API : points de terminaison et structures de données

L'API est largement classée en gestion de compte, récupération de données de marché et opérations de trading.

Gestion de compte

Points de terminaison pour interroger les états et l'historique des comptes.

Récupération des soldes de compte (GET /accounts)
Récupère une liste de tous les comptes utilisateur (fiat et crypto) avec leurs soldes.
Extrait d'exemple de réponse pour un compte BTC :

{
  "id": "7532b1f0-20f4-4ba7-96f0-303b592d130f",
  "currency": "BTC",
  "balance": "0.50123456",
  "available": "0.49123456",
  "hold": "0.01000000",
  "profile_id": "your-profile-id-string"
}

balance est le montant total, available est ce qui peut être utilisé pour le trading et hold est les fonds réservés aux ordres ouverts.

Historique du compte / Grand livre (GET /accounts/{account_id}/ledger)
Fournit une liste paginée des transactions (transactions, frais, transferts) pour un compte spécifique.
Paramètres de requête typiques : before (curseur pour la pagination), after (curseur), limit (max 100, défaut 100), start_date, end_date.
Extrait d'exemple d'entrée de grand livre :

{
  "id": "1001874",
  "created_at": "2023-10-26T10:00:00.000Z",
  "amount": "-0.00005000",
  "balance": "0.50118456",
  "type": "fee",
  "details": {
    "order_id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
    "product_id": "BTC-USD",
    "trade_id": "7423736"
  }
}

Points de terminaison des données de marché

Accès aux informations de marché en temps réel et historiques.

Produits / Paires de trading (GET /products)
Répertorie toutes les paires de trading disponibles et leurs propriétés.
Extrait d'exemple de produit (BTC-USD) :

{
  "id": "BTC-USD",
  "base_currency": "BTC",
  "quote_currency": "USD",
  "base_min_size": "0.0001", // Minimum order size in base currency
  "base_max_size": "200.0",  // Maximum order size in base currency
  "quote_increment": "0.01", // Smallest price change unit for quote currency
  "base_increment": "0.00000001", // Smallest size change unit for base currency
  "display_name": "BTC/USD",
  "min_market_funds": "1",    // Minimum funds for a market order in quote currency
  "max_market_funds": "1000000", // Maximum funds for a market order
  "status": "online",
  "status_message": "",
  "cancel_only": false,
  "limit_only": false,
  "post_only": false,
  "trading_disabled": false
}

Carnets d'ordres (GET /products/{product_id}/book)
Récupère le carnet d'ordres actuel d'un produit.
Paramètres de requête : level (1, 2 ou 3).
* Niveau 1 : uniquement le meilleur prix acheteur et vendeur.
* Niveau 2 : liste agrégée des offres et des demandes à chaque niveau de prix. (Max 50 entrées par côté).
* Niveau 3 : carnet d'ordres complet avec des ordres individuels non agrégés (nécessite une authentification et peut avoir des limites de débit plus strictes).
Extrait d'exemple de carnet d'ordres de niveau 2 (BTC-USD) :

{
  "sequence": 1234567890,
  "bids": [
    ["49999.99", "0.75", 3], // [price, size, num-orders-at-this-price]
    ["49999.98", "1.20", 5]
  ],
  "asks": [
    ["50000.01", "0.50", 2],
    ["50000.02", "1.00", 4]
  ],
  "time": "2023-10-26T10:05:00.123Z"
}

Ticker du produit (GET /products/{product_id}/ticker)
Informations instantanées sur la dernière transaction (tick), le meilleur prix acheteur/vendeur et le volume sur 24 heures.
Extrait d'exemple de ticker (BTC-USD) :

{
  "trade_id": 7423739,
  "price": "50001.50", // Last trade price
  "size": "0.005",    // Last trade size
  "bid": "50001.49",
  "ask": "50001.51",
  "volume": "1250.75", // 24-hour trading volume in base currency
  "time": "2023-10-26T10:06:15.234Z"
}

Taux historiques / Chandeliers (GET /products/{product_id}/candles)
Récupère les données de prix historiques (OHLCV).
Paramètres de requête : start (horodatage ISO 8601), end (ISO 8601), granularity (en secondes : 60, 300, 900, 3600, 21600, 86400). Max 300 chandeliers par requête.
Exemple de données de chandelier (granularité d'une heure) :

[
  // [time, low, high, open, close, volume]
  [1666771200, 49850.25, 50050.75, 49900.00, 50025.10, 15.2345], // time is Unix epoch
  [1666767600, 49700.00, 49950.50, 49750.20, 49850.25, 22.6789]
]

Opérations de trading

Points de terminaison pour passer, gérer et interroger les ordres.

Passer des ordres (POST /orders)
Soumet de nouveaux ordres au moteur de correspondance.
Paramètres courants du corps de la requête :

{
  "client_oid": "my-unique-client-order-id-001", // Optional: UUID for idempotency
  "product_id": "BTC-USD",
  "side": "buy", // "buy" or "sell"
  "type": "limit", // "limit", "market", or "stop" (stop orders are more complex)
  "price": "49500.00", // Required for limit orders
  "size": "0.0125", // Amount of base currency to buy/sell
  // "funds": "500.00", // For market buy orders: amount of quote currency to spend
  "time_in_force": "GTC", // GTC (Good 'Til Canceled), GTT (Good 'Til Time), IOC (Immediate Or Cancel), FOK (Fill Or Kill)
  // "cancel_after": "min" / "hour" / "day" (used with GTT)
  "post_only": false, // If true, order is rejected if it would immediately match (ensures maker)
  "stp": "dc" // Self-trade prevention: "dc" (Decrease and Cancel), "co" (Cancel Oldest), "cn" (Cancel Newest), "cb" (Cancel Both)
}

Une passation d'ordre réussie renvoie les détails de l'ordre, y compris l'id attribué par le serveur.

Gestion des ordres

Obtenir l'état de l'ordre (GET /orders/{order_id_or_client_oid}) : Récupère un seul ordre par son ID de serveur ou votre client_oid (préfixe avec client: pour client_oid, par exemple, GET /orders/client:my-unique-client-order-id-001).
Lister les ordres ouverts (GET /orders) : Renvoie une liste paginée de vos ordres actifs. Des paramètres tels que status (open, pending, active) et product_id peuvent être utilisés pour le filtrage.
Annuler l'ordre (DELETE /orders/{order_id_or_client_oid}) : Annule un ordre ouvert spécifique. Renvoie l'ID de l'ordre lors d'une demande d'annulation réussie.
Annuler tous les ordres (DELETE /orders) : Annule tous les ordres ouverts, éventuellement pour un product_id spécifique.

Remplissages (GET /fills)
Récupère une liste paginée de vos transactions exécutées (remplissages).
Paramètres de requête : order_id, product_id, before, after, limit.
Extrait d'exemple de remplissage :

{
  "trade_id": 7423800,
  "product_id": "BTC-USD",
  "price": "49500.00",
  "size": "0.00500000",
  "order_id": "e4f2c1a0-f3d8-4b9b-8b7e-1f2a3c4d5e6f",
  "created_at": "2023-10-26T10:15:30.123Z",
  "liquidity": "T", // "M" for Maker, "T" for Taker
  "fee": "0.00000250", // Fee in quote currency (USD for BTC-USD) or base currency depending on API.
  "settled": true,
  "side": "buy"
}

Le moteur de correspondance

Le moteur de correspondance associe les ordres d'achat et de vente en fonction d'un algorithme de priorité Prix-Temps :

Priorité des prix : Les ordres avec des prix plus favorables sont prioritaires (prix plus élevé pour les offres, prix plus bas pour les demandes).
Priorité temporelle : Parmi les ordres au même prix, l'ordre soumis le plus tôt est prioritaire.

Ordres Maker vs. Taker :
Maker : Un ordre qui ajoute de la liquidité au carnet d'ordres (par exemple, un ordre limite qui ne se remplit pas immédiatement). Bénéficie généralement de frais de trading moins élevés (par exemple, 0,00 % - 0,40 %). L'indicateur post_only permet de s'assurer qu'un ordre est un maker.
Taker : Un ordre qui supprime de la liquidité (par exemple, un ordre au marché ou un ordre limite qui se remplit immédiatement). Engendre des frais légèrement plus élevés (par exemple, 0,05 % - 0,60 %). Les niveaux de frais sont souvent basés sur le volume sur 30 jours glissants.

Comprendre cette logique est essentiel pour les stratégies de passation d'ordres, la gestion du glissement et l'optimisation des frais.

Limites de débit et limitation

L'accès à l'API est soumis à des limites de débit pour garantir la stabilité de la plateforme et une utilisation équitable.

Types et identification

Les limites sont généralement appliquées par clé API, par adresse IP et peuvent varier par point de terminaison (par exemple, points de terminaison privés signés par rapport aux points de terminaison publics non signés). Les points de terminaison publics peuvent avoir des limites comme 3 à 10 requêtes/seconde par IP. Les points de terminaison privés (signés) ont souvent des limites plus élevées, également par clé API.

Les réponses de l'API incluent des en-têtes indiquant l'état actuel de la limite de débit :

CB-RATELIMIT-LIMIT : La limite de requêtes totale pour la fenêtre actuelle.
CB-RATELIMIT-REMAINING : Requêtes restantes dans la fenêtre.
CB-RATELIMIT-RESET : Horodatage Unix pour la réinitialisation de la fenêtre de limite.

Le dépassement des limites entraîne une erreur HTTP 429 Too Many Requests.

Stratégies de gestion

Surveillance proactive : Vérifiez CB-RATELIMIT-REMAINING avant de faire des requêtes.
Utilisation efficace de l'API :

Récupérez uniquement les données nécessaires.
Utilisez les flux WebSocket pour les données en temps réel au lieu d'interroger les points de terminaison REST.
Mettez en cache les données statiques ou rarement modifiées (par exemple, les détails du produit à partir de /products).

Backoff exponentiel : Après avoir reçu une erreur 429, attendez avant de réessayer. Mettez en œuvre un backoff exponentiel (par exemple, attendez 1 s, puis 2 s, 4 s, 8 s, etc., avec une gigue) pour éviter de submerger le serveur.
WebSockets pour les données en temps réel : Pour les mises à jour du carnet d'ordres, les transactions en direct et les tickers, les connexions WebSocket sont beaucoup plus efficaces que l'interrogation REST.

Excellence opérationnelle : principes du Runbook

Des pratiques opérationnelles robustes sont essentielles pour toute intégration d'API de trading.

Surveillance et alerte

Connectivité et latence de l'API : Surveillez les temps de ping et les taux de réussite vers les points de terminaison de l'API.
Consommation de la limite de débit : Suivez CB-RATELIMIT-REMAINING et alertez lorsque vous approchez de zéro.
Exécution des ordres : Alerte sur les passations d'ordres ayant échoué, les ordres bloqués dans l'état pending au-delà des durées prévues ou les écarts de remplissage importants.
Écarts de solde : Surveillez les soldes de compte clés pour les écarts inattendus.
Taux d'erreur : Suivez les pourcentages d'erreur HTTP 4xx et 5xx ; examinez les pics. Des outils comme Prometheus/Grafana ou Datadog sont couramment utilisés.
État du système Coinbase : Abonnez-vous ou vérifiez régulièrement la page d'état officielle de Coinbase (par exemple, status.coinbase.com) pour les incidents ou la maintenance à l'échelle de la plateforme.

Journalisation

Enregistrez les informations essentielles pour le débogage et l'audit :

Horodatage (UTC).
Requête : méthode, chemin, en-têtes (clé API masquée), corps (données sensibles masquées).
Réponse : code d'état, en-têtes (en particulier la limite de débit et l'ID de requête comme CB-TRACE-ID), corps.
ID de corrélation : si votre système les utilise, ou utilisez CB-TRACE-ID à partir des en-têtes de réponse.

Meilleures pratiques de sécurité

Sécurité des clés API : Stockez les clés dans des coffres-forts sécurisés (par exemple, HashiCorp Vault, AWS Secrets Manager) ou des variables d'environnement. Ne les codez jamais en dur et ne les validez jamais dans le contrôle de version.
Liste blanche IP : Si disponible, limitez l'accès aux clés API à des adresses IP spécifiques.
Principe du moindre privilège : Accordez aux clés API uniquement les autorisations dont elles ont absolument besoin.
Audits réguliers : Examinez périodiquement l'utilisation et les autorisations des clés API.
Gestion des versions de l'API : Tenez compte des modifications de version de l'API (par exemple, /v2/products, /v3/products). Surveillez les annonces des développeurs pour les calendriers de dépréciation et les chemins de migration.

Rubriques et techniques avancées

Flux WebSocket pour les données en temps réel

Coinbase Exchange fournit des flux WebSocket pour les données en temps réel à faible latence.

Point de terminaison : Généralement une seule URL WebSocket (par exemple, wss://ws-feed.exchange.coinbase.com).
Abonnement : Après la connexion, envoyez un message JSON pour vous abonner aux canaux et aux ID de produit.
Exemple de message d'abonnement :

{
    "type": "subscribe",
    "product_ids": ["ETH-USD", "BTC-USD"],
    "channels": [
        "level2", // For Level 2 order book updates
        "heartbeat", // To keep connection alive and monitor status
        {
            "name": "ticker", // Ticker channel for specific products
            "product_ids": ["ETH-USD", "BTC-USD"]
        },
        "status" // For updates on product trading statuses
    ],
    // For user-specific updates (orders, balances), authentication is required within the WebSocket handshake or initial messages.
    // "signature": "...", "key": "...", "passphrase": "...", "timestamp": "..." (if auth needed for certain channels)
}

Types de messages :

heartbeat : Message périodique pour confirmer l'intégrité de la connexion et fournir les états actuels des produits.
snapshot : État initial des données abonnées (par exemple, instantané complet du carnet d'ordres pour level2).
l2update : Modifications incrémentielles du carnet d'ordres de niveau 2 (offres/demandes ajoutées, modifiées ou supprimées).
ticker : Prix en temps réel, volume et mises à jour des offres/demandes.
matches (ou trade) : Transactions exécutées en temps réel pour les produits abonnés.
error : Indique un problème avec l'abonnement ou la connexion.
La gestion des connexions WebSocket implique la gestion de la logique de reconnexion, le séquencement des messages (le cas échéant, via les numéros de séquence dans les messages) et la maintenance de l'état local (par exemple, la reconstruction d'un carnet d'ordres à partir des messages snapshot et l2update).

Idempotence et `client_oid`

Pour éviter les soumissions d'ordres en double en raison de problèmes de réseau ou de nouvelles tentatives, les requêtes POST /orders peuvent inclure un champ client_oid. Il doit s'agir d'un identifiant unique (par exemple, UUID v4) généré par votre client.

Si un ordre avec un client_oid donné est reçu et traité, les requêtes identiques ultérieures avec le même client_oid dans un certain délai (par exemple, 24 heures) ne créeront pas un nouvel ordre, mais renverront plutôt l'état de l'ordre d'origine.
Cela garantit que la nouvelle tentative d'une requête « passer un ordre » est sûre.

Prévention des transactions automatiques (STP)

Le paramètre stp dans la passation d'ordres (POST /orders) permet d'empêcher les ordres d'un compte de correspondre les uns aux autres. Les options incluent généralement :

dc (Diminuer et annuler) : L'ordre agressif (taker) est annulé et la taille de l'ordre en attente (maker) est diminuée de la taille de l'ordre agressif.
co (Annuler le plus ancien) : L'ordre le plus ancien est annulé.
cn (Annuler le plus récent) : L'ordre le plus récent (agressif) est annulé.
cb (Annuler les deux) : Les deux ordres sont annulés.

Conclusion

L'API Coinbase Exchange fournit une boîte à outils complète permettant aux développeurs de créer des applications et des intégrations de trading sophistiquées. Maîtriser son authentification, comprendre ses structures de données, respecter les limites de débit et mettre en œuvre des pratiques opérationnelles robustes sont essentiels pour exploiter tout son potentiel. Le passage aux flux WebSocket pour les données en temps réel et les fonctionnalités comme client_oid pour l'idempotence permettent en outre aux développeurs de créer des systèmes résilients et efficaces dans le monde en évolution rapide du trading de crypto-monnaies. Une attention continue à la documentation officielle des développeurs de Coinbase est cruciale pour rester informé des nouvelles fonctionnalités, des modifications des points de terminaison et des meilleures pratiques.