@blackcube/binance-sdk

TypeScript SDK pour Binance — lecture publique uniquement. Même surface que @blackcube/hyperliquid-sdk et @blackcube/pacifica-sdk, réduite au catalogue, aux bougies et aux prix.

Ce SDK ne trade pas et ne lit aucun compte. account() et trade() existent et lèvent, en nommant la limite : une méthode absente laisserait croire à un oubli, une méthode qui rendrait un tableau vide ferait croire à un compte vide.

Installation

pnpm add @blackcube/binance-sdk

Node.js ≥ 22. Aucun credential, aucune configuration : ce sont des données publiques.

Tout passe par la classe Binance

import { Binance } from '@blackcube/binance-sdk';

const bn = new Binance();

const pairs = await bn.perp().getPairs();                       // 854 marchés
const candles = await bn.perp().getCandles({ name: 'BTCUSDT', interval: '1h', limit: 100 });
const prices = await bn.spot().getPrices();                     // 3 683 cotations

Deux marchés, deux APIs

perp() sert les futures USDT-M (fapi.binance.com/fapi/v1), spot() le comptant (api.binance.com/api/v3). Ce ne sont pas deux vues d'une même source : les hôtes, les chemins et jusqu'aux noms des filtres diffèrent.

| | perp | spot | |---|---|---| | Marchés | 854 | 3 680 | | Date de listing | onboardDate | non publiée → listedAt absent | | Notionnel minimum | filtre MIN_NOTIONAL / notional | filtre NOTIONAL / minNotional | | mark, oracle, funding | oui | non — ces notions n'existent pas hors dérivés | | WebSocket | fstream.binance.com/market/stream | stream.binance.com:9443/stream |

Le chemin du WebSocket diffère, et se tromper ne lève rien

Le spot écoute sur /stream, les futures sur /market/stream. Un /stream nu sur fstream se connecte, accepte la souscription ({"result":null,"id":1}) et ne délivre jamais de bougie — alors que @bookTicker y répond quand même. Le SDK choisit le bon chemin selon le marché ; c'est noté ici parce que le symptôme est parfaitement trompeur.

Ce que le SDK garantit

Une bougie va de 10:00:00.000 à 10:59:59.999. La fermeture est calculée depuis l'intervalle, jamais recopiée du wire : deux bougies consécutives ne se recouvrent pas, et le cœur ne dépend pas de la convention de la venue.

candle.closedAt.getTime() - candle.openedAt.getTime() === 3_600_000 - 1;
candles[1].openedAt.getTime() === candles[0].closedAt.getTime() + 1;

Les intervalles s'arrêtent à la semaine : 1m, 5m, 15m, 1h, 4h, 1d, 1w. Le mensuel n'est pas supporté — un mois ne dure pas un nombre fixe de millisecondes. La casse compte : 1M n'est pas 1m, et un intervalle inconnu lève au lieu de rendre une bougie fausse.

Un null veut dire « la venue ne le publie pas », jamais zéro. mid et openInterest restent null : le premier n'est pas coté, le second exigerait un appel par marché (plus de 800 requêtes pour un champ).

Rien n'est jeté : ce qui ne rentre pas dans le cœur unifié part dans xtras — contractType, deliveryDate, underlyingType côté catalogue, firstTradeId/lastTradeId côté flux.

Trois pièges du catalogue perp

Mesurés le 2026-08-06 sur les 854 symboles :

• 153 TRADIFI_PERPETUAL — actions et indices tokenisés au milieu de 697 perpétuels crypto ;
• 4 futures datés (CURRENT_QUARTER, NEXT_QUARTER) dont le prix s'écarte du comptant à l'approche de l'échéance ;
• SETTLING (123) et PENDING_TRADING ne sont pas vivants — seul TRADING l'est.

Tout reste au catalogue (la venue les cote), mais contractType survit dans xtras : un consommateur qui ne veut que du crypto perpétuel doit pouvoir filtrer.

Temps réel

const off = bn.ws('perp').subscribeCandles({ name: 'BTCUSDT', interval: '1m' }, (candle) => {
  if (candle.xtras?.closed === true) {
    // bougie définitive ; sinon c'est l'état courant, réémis toutes les 250 ms
  }
});
off();

Une socket par marché, partagée et comptée par référence. Souscription par message (SUBSCRIBE), donc ajout et retrait à chaud sans rouvrir la connexion. Reconnexion à recul exponentiel (1 s → 60 s) avec rejeu des abonnements, et renouvellement à 23 h — la venue documente une durée de vie de 24 h.

Tests

pnpm test

15 tests, tous en réel contre l'API publique : aucun mock. Ils vérifient des invariants (durée de bougie, enchaînement, champs servis), pas des valeurs qui bougent.

Licence

BSD-3-Clause — Blackcube.