Flux WebSocket en temps réel pour développeurs

Les canaux et l’offre

Chaque canal appartient à une famille de données de marché, la même que par REST et MCP : trades.futures, trades.spot, orderbook.spot et orderbook.futures relèvent de la microstructure, liquidations des dérivés. Une famille absente de votre offre l’est sur tous les canaux, flux compris. Concrètement : Free n’a pas du tout le flux (403 à la poignée de main), et tout le flux est ouvert à partir de Traders. Le temps réel n’est pas la famille des ticks bruts, ouverte à partir de l’offre Financial, qui désigne l’historique tick par tick servi par REST.

Un canal hors offre reçoit {"op": "error", "server_time": "…", "error": {"code": "plan_family", "message": "Channel 'orderbook.futures.BTCUSDT' is not in your plan: the 'microstructure' data family is not included in your subscription.", "param": "channels"}} et, comme pour tout abonnement, aucun canal de la trame n’est appliqué. Le nombre de connexions simultanées par compte dépend aussi de l’offre : 3 en Traders, 10 en Financial, 20 en Startup. Voir les tarifs.

Transactions

{
  "channel": "trades.futures.BTCUSDT",
  "server_time": "2026-10-14T09:25:26.408Z",
  "data": [
    { "time": "2026-10-14T09:25:26.176Z", "id": "3cf0988ca613980c", "side": "buy", "price": 83283.9, "quantity": 0.24, "value_usd": 19988.136 },
    { "time": "2026-10-14T09:25:26.184Z", "id": "4b408a64af719aa6", "side": "sell", "price": 83268.6, "quantity": 0.002, "value_usd": 166.5372 }
  ],
  "seq": 443379
}

side est le côté du preneur : buy signifie qu’un acheteur a consommé l’offre. Une ligne est une exécution : un ordre preneur qui balaie plusieurs ordres de même taille au même prix produit plusieurs lignes identiques, et c’est normal. Les transactions sont regroupées par tick, mais aucune n’est perdue : chacune garde son horodatage d’origine dans data[].time, distinct du server_time du message, et les transactions d’un message sont triées selon cet horodatage, de la plus ancienne à la plus récente. Cet ordre ne vaut qu’à l’intérieur d’un message : un message suivant peut porter une transaction plus ancienne que la plus récente déjà reçue (une place qui la rapporte en retard, en général de moins d’une seconde, parfois jusqu’à 1,5 s environ). Pour construire des bougies, rangez sur data[].time et clôturez une période environ deux secondes après sa fin.

Chaque transaction porte id, le même identifiant que le tick de /v1/trades/futures ou /v1/trades/spot pour cette transaction (une empreinte opaque : elle ne dit ni la place ni son identifiant natif), et value_usd = price × quantity. Servez-vous d’id pour dédoublonner le flux en direct contre l’historique REST.

Liquidations

{
  "channel": "liquidations.BTCUSDT",
  "server_time": "2026-10-10T09:11:51.652Z",
  "data": [
    { "time": "2026-10-10T09:11:51.576Z", "price": 83168.0, "quantity": 0.081, "side": "short", "value_usd": 6736.608 }
  ],
  "seq": 7
}

side est ici le côté de la position liquidée : long signifie qu’une position acheteuse a été liquidée. Toutes les places n’ont pas cette convention ; la normalisation est faite pour vous. Comme pour les transactions, les liquidations d’un message sont triées par time. Une place peut rapporter une liquidation avec quelques secondes de retard : filtrez et fenêtrez sur time, jamais sur l’instant de réception. Une liquidation ancienne qu’une place republie plus de 60 s après son time n’est pas relayée (/v1/liquidations/events garde tous les événements).

Carnet d’ordres

{
  "channel": "orderbook.futures.BTCUSDT",
  "server_time": "2026-10-14T09:25:26.304Z",
  "data": {
    "bids": [[83271.0, 67.65684], [83270.0, 4.85424], [83269.0, 15.31266]],
    "asks": [[83272.0, 17.0135], [83273.0, 11.33315], [83274.0, 5.34624]],
    "avg_mid_price": 83271.75,
    "avg_spread_bps": 0.036
  },
  "seq": 627302
}

Chaque ligne est [prix, quantité], la quantité étant la somme des places à ce niveau de prix. Les bids sont décroissants, les asks croissants. Les prix sont ramenés à une grille commune par actif, sans quoi chaque place tomberait dans ses propres paliers et le carnet consolidé aurait plus de lignes, chacune plus mince.

Le pas de cette grille, dans la monnaie de cotation : BTC 1; ETH, BNB, TAO, ZEC, BCH 0.1; SOL, HYPE, XMR, LTC, QNT, AAVE, ETC, VVV, DASH, BSV 0.01; LINK, UNI, GRAM, AVAX, NEAR, DOT, MORPHO, ICP, RENDER, ATOM, FIL, INJ, LIT, ZRO, CAKE, TRUMP, PENDLE, LDO 0.001; XRP, TRX, SUI, XLM, ADA, USDCUSDT, USDTUSDC, ENA, ONDO, WLD, ASTER, WLFI, ARB, ALGO, POL, JUP, AERO, APT, STX, TIA, CRV, FET, VIRTUAL, GRASS, XPL, SPX, XTZ 0.0001; DOGE, HBAR, CC, SKY, JST, KAS, STABLE, AKE, NIGHT, PYTH, STRK, SEI, FF 0.00001; PUMP, VET, PENGU 0.000001.

Il y a un carnet par marché : orderbook.spot ne fusionne que les carnets spot, orderbook.futures que les carnets perpétuels. Les deux ne sont jamais mélangés, car leurs prix diffèrent de la base. Au sein d’un marché, une place dont le prix médian s’écarte de plus de 5 points de base de la médiane des autres (dès que trois places au moins sont présentes) est écartée de la fusion jusqu’à ce qu’elle revienne dans la norme : une place isolée ne peut pas déformer le carnet consolidé.

Le carnet consolidé est une profondeur, pas le carnet d’une place

Entre plusieurs places d’un même marché, il n’y a pas de moteur d’appariement commun : leurs prix médians diffèrent de quelques points de base, alors que l’écart achat/vente d’une place sur BTC est d’environ 0,1 point de base. Additionnés à leur prix brut, leurs niveaux croisaient le carnet consolidé dans la quasi-totalité des messages.

Depuis le 08/10/2026, chaque place est recentrée sur avg_mid_price avant la fusion : tous ses niveaux sont décalés de avg_mid_price moins son propre prix médian. Les quantités sont intactes, la distance de chaque niveau au prix médian de sa place est conservée, et le carnet consolidé n’est jamais croisé : bids[0][0] est toujours sous asks[0][0]. Une place qui n’a, à cet instant, qu’un côté de carnet n’y contribue pas.

Le nombre de transactions ne mesure pas l’activité

Certaines places fractionnent leurs exécutions à l’extrême, jusqu’à des ordres d’un satoshi, une fraction de centime. Dans le flux consolidé, le nombre de transactions est donc dominé par de minuscules exécutions. Pour mesurer l’activité, additionnez quantity ou quantity × price, ne comptez jamais les lignes.

Un saut de seq signifie que vous avez perdu des messages

La file d’envoi de chaque client est bornée à 512 trames, environ huit ticks à pleine charge (800 ms d’à-coup absorbable). Un client qui ne consomme pas assez vite voit ses messages les plus anciens abandonnés ; il se dégrade seul, sans affecter les autres.

Sur les canaux d’événements, un message abandonné est définitivement perdu ; c’est le saut de seq qui vous le dit. Sur le carnet d’ordres, seul le dernier état est gardé : un saut n’y a aucune conséquence, l’état suivant remplace entièrement le précédent.

L’identifiant est vérifié à la poignée de main, pas dans une trame

La clé (ou le jeton) est vérifiée à la poignée de main, avant que la connexion ne s’ouvre : une offre qui n’inclut pas le flux reçoit un 403 et rien n’est établi. Depuis un serveur, elle voyage dans l’en-tête X-API-KEY ; un navigateur, qui ne peut pas poser d’en-tête sur un WebSocket, utilise un jeton éphémère dans l’URL (?token=), pour que la clé elle-même ne quitte jamais votre serveur.

La trame {"op": "auth"} est toujours acceptée et répond authenticated, mais elle n’est plus nécessaire : la session s’ouvre déjà authentifiée. ?token= et ?api_key= ne sont acceptés que sur la poignée de main WebSocket, jamais sur les routes REST, et la ligne de requête de /ws n’est pas journalisée par la passerelle.

Le nombre de connexions simultanées dépend de l’offre

Chaque offre borne le nombre de connexions ouvertes en même temps, pour tout le compte, toutes clés confondues. La connexion de trop est fermée aussitôt avec le code 4003 et le plafond dans la raison. Ne la confondez pas avec un 503 à la poignée de main, qui dit que le service lui-même est plein, quelle que soit l’offre.

Une déconnexion libère immédiatement sa place : il n’y a rien à attendre ni rien à réinitialiser.

Le flux ne nomme jamais une place

Aucun message ne dit de quelle place vient une transaction, une liquidation ou un niveau du carnet, ni combien de places l’ont alimenté : le flux sert le marché consolidé. Une place muette depuis plus de dix secondes sort automatiquement du carnet, et une place au carnet vide n’y est jamais fusionnée.