@xapy/orderbook

Lightweight multi-exchange orderbook SDK — REST snapshot + WebSocket maintained stream.

Install

npm i @xapy/orderbook
# Optional, only needed on Node < 22:
npm i ws

Usage

import { BybitClient } from "@xapy/orderbook/bybit";

const bybit = new BybitClient({ market: "perpetual" });

// One-shot REST snapshot
const snapshot = await bybit.fetchOrderbook("BTC/USDT", { depth: 50 });
console.log(snapshot.bids[0], snapshot.asks[0]);

// Maintained live stream (snapshot + deltas → always the latest book)
const stream = bybit.streamOrderbook("BTC/USDT", { depth: 50 });
stream.on("update", (book) => {
  console.log(book.exchange, book.symbol, book.bids[0], book.asks[0]);
});
stream.on("reconnecting", (attempt, waitMs) => {
  console.log(`reconnect attempt ${attempt} in ${waitMs}ms`);
});

// Or async-iterator
for await (const book of stream.iter()) {
  console.log(book.sequence, book.bids[0]);
}

stream.close();

Browser + CORS

Several exchanges block direct browser requests. Use transformUrl to route through your proxy:

const bybit = new BybitClient({
  market: "perpetual",
  transformUrl: (url) =>
    `https://my-proxy.example/${url.replace(/^https?:\/\//, "")}`,
});

WebSocket connections are not subject to CORS and work directly in the browser.

What you get

• Maintained orderbook — the lib applies WS deltas internally; consumers always see a sorted, latest snapshot.
• Gap recovery — sequence numbers are verified; on a gap the lib re-fetches a REST snapshot and resumes without you noticing.
• Auto-reconnect — exponential backoff with jitter; the subscription replays on each reconnect.
• Cross-runtime — Node ≥ 18 (with ws peer for < 22) and modern browsers.
• Tree-shakeable — import "@xapy/orderbook/bybit" doesn't pull in other adapters.

Supported exchanges

| Exchange | Spot | Perpetual | Status | | --- | --- | --- | --- | | Bybit | ✅ | ✅ | available (0.1) | | OKX | | | planned (0.2) | | Bitget | | | planned (0.2) | | Gate | | | planned (0.3) | | CoinEx | | | planned (0.3) | | BingX | | | planned (0.4) | | Huobi | | | planned (0.4) | | KuCoin | | | planned (0.5) |

API

new BybitClient(options)

interface ClientOptions {
  market: "spot" | "perpetual";
  transformUrl?: (url: string) => string;
  timeoutMs?: number; // default 10_000
}

client.fetchOrderbook(symbol, opts?)

REST snapshot. Returns a Promise<Orderbook>.

client.streamOrderbook(symbol, opts?)

WebSocket stream. Returns an OrderbookStream exposing:

stream.on("update",       (book: Orderbook) => {});
stream.on("connected",    () => {});
stream.on("disconnected", (reason?: string) => {});
stream.on("reconnecting", (attempt: number, waitMs: number) => {});
stream.on("error",        (err: Error) => {});

for await (const book of stream.iter()) { /* … */ }

stream.close();

Orderbook shape

interface Orderbook {
  exchange: ExchangeName;
  symbol: string;          // "BTC/USDT"
  market: "spot" | "perpetual";
  bids: { price: number; size: number }[]; // descending
  asks: { price: number; size: number }[]; // ascending
  timestamp: number;       // ms epoch
  sequence: number;        // last applied seq
}

Sizes are in base coin (e.g. BTC). Conversion to quote (USDT) is left to the caller.

Development

npm install
npm run build
npm test

License

MIT