@blackcube/bybit-sdk

TypeScript SDK pour Bybit v5 — 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/bybit-sdk

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

Tout passe par la classe Bybit

import { Bybit } from '@blackcube/bybit-sdk';

const by = new Bybit();

const pairs = await by.perp().getPairs();                       // 797 marchés linear
const candles = await by.perp().getCandles({ name: 'BTCUSDT', interval: '1h', limit: 100 });
const prices = await by.perp().getPrices();                     // 801 cotations, UN seul appel

Un hôte REST, deux marchés

perp() interroge le linear (perpétuels et futures datés en USDT/USDC), spot() le comptant. Le marché se choisit par un paramètre category — c'est l'inverse de Binance qui sépare ses marchés sur deux domaines. Le WebSocket, lui, sépare bien par l'URL.

| | linear | spot | |---|---|---| | Marchés | 797 | 557 | | Pagination | obligatoire (cursor) | aucune | | Levier max | leverageFilter.maxLeverage | non publié | | Date de lancement | launchTime (ms en chaîne) | non publiée | | Pas de quantité | lotSizeFilter.qtyStep | lotSizeFilter.basePrecision | | Notionnel minimum | minNotionalValue | minOrderAmt | | mark, oracle, funding, OI | oui | non — hors dérivés ces notions n'existent pas | | Args par subscribe (WS) | sans limite | 10 maximum |

Cinq particularités que le SDK absorbe

retCode fait foi, pas le statut HTTP. Bybit répond 200 même quand il refuse : le verdict est dans le corps. Sans ce test, un refus deviendrait « ce marché n'a pas de données ».

La pagination du linear est obligatoire. L'endpoint rend 500 entrées par défaut et la venue en porte près de 800. Sans boucle de cursor, le catalogue serait tronqué — et tout ce qui manque paraîtrait délisté au tour suivant, en silence.

Les bougies arrivent du plus récent au plus ancien. Le SDK les retourne, pour que l'appelant reçoive partout le même ordre chronologique.

Aucune heure de clôture n'est publiée : elle se calcule depuis l'ouverture et l'intervalle.

Le client doit envoyer le ping. Contrairement à Binance où le serveur pingue, ici c'est à nous — toutes les 20 s, faute de quoi la venue coupe après 10 minutes d'inactivité.

Ce que le SDK garantit

Une bougie va de 10:00:00.000 à 10:59:59.999.

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

La grille bybit est traduite : l'appelant écrit 1h, la venue reçoit 60. Sept intervalles — 1m, 5m, 15m, 1h, 4h, 1d, 1w. Le mensuel existe chez bybit (M) mais n'est pas repris : sans heure de clôture publiée, il faudrait un calendrier pour fermer la bougie.

Un null veut dire « la venue ne le publie pas », jamais zéro :

• takerBuyBaseVolume / takerBuyQuoteVolume — bybit ne publie aucun volume par côté, le CVD y est hors d'atteinte ;
• trades vaut 0 — la venue ne compte pas les transactions d'une bougie ;
• mid n'est pas coté.

delisted vaut presque toujours false : sans filtre, instruments-info ne rend que les Trading. Ce n'est pas une venue sans marchés morts, c'est une venue qui ne les publie pas.

40 LinearFutures (contrats datés) cohabitent avec 757 perpétuels : leur prix s'écarte du comptant à l'approche de l'échéance. contractType survit dans xtras pour permettre de filtrer.

Temps réel

const off = by.ws('perp').subscribeCandles({ name: 'BTCUSDT', interval: '1m' }, (candle) => {
  if (candle.xtras?.closed === true) {
    // bougie définitive (`confirm` natif) ; sinon c'est l'état courant
  }
});
off();

Le topic s'écrit kline.{interval}.{symbol} — l'intervalle avant le symbole, et le symbole ne figure que là. Une socket par marché, souscription par message, reconnexion à recul exponentiel (1 s → 60 s) avec rejeu des abonnements, ping applicatif toutes les 20 s.

Tests

pnpm test

11 tests, tous en réel contre l'API publique : aucun mock.

Licence

BSD-3-Clause — Blackcube.