Fetch Orderbook Data

Use the orderbook namespace to fetch historical futures orderbook depth for one exchange product or a Velo-aggregated coin.

List of symbols that support orderbooks

   // Supported products for orderbooks

┌────┬─────────────────┬──────────┬───────────────┐
│    │ exchange        │ coin     │ product       │
├────┼─────────────────┼──────────┼───────────────┤
│  0 │ hyperliquid     │ BRENTOIL │ xyz:BRENTOIL  │
│  1 │ binance-futures │ BTC      │ BTCUSDT       │
│  2 │ hyperliquid     │ BTC      │ BTC-USD       │
│  3 │ bybit           │ BTC      │ BTCUSDT       │
│  4 │ okex-swap       │ BTC      │ BTC-USDT-SWAP │
│  5 │ binance-futures │ CL       │ CLUSDT        │
│  6 │ hyperliquid     │ CL       │ xyz:CL        │
│  7 │ bybit           │ CL       │ CLUSDT        │
│  8 │ hyperliquid     │ ETH      │ ETH-USD       │
│  9 │ bybit           │ ETH      │ ETHUSDT       │
│ 10 │ okex-swap       │ ETH      │ ETH-USDT-SWAP │
│ 11 │ binance-futures │ ETH      │ ETHUSDT       │
│ 12 │ hyperliquid     │ HYPE     │ HYPE-USD      │
│ 13 │ bybit           │ HYPE     │ HYPEUSDT      │
│ 14 │ binance-futures │ HYPE     │ HYPEUSDT      │
│ 15 │ okex-swap       │ SOL      │ SOL-USDT-SWAP │
│ 16 │ binance-futures │ SOL      │ SOLUSDT       │
│ 17 │ hyperliquid     │ SOL      │ SOL-USD       │
│ 18 │ bybit           │ SOL      │ SOLUSDT       │
│ 19 │ hyperliquid     │ SP500    │ xyz:SP500     │
│ 20 │ hyperliquid     │ SPCX     │ xyz:SPCX      │
│ 21 │ bybit           │ XAG      │ XAGUSDT       │
│ 22 │ hyperliquid     │ XAG      │ xyz:SILVER    │
│ 23 │ binance-futures │ XAG      │ XAGUSDT       │
│ 24 │ hyperliquid     │ XAU      │ xyz:GOLD      │
│ 25 │ bybit           │ XAU      │ XAUUSDT       │
│ 26 │ binance-futures │ XAU      │ XAUUSDT       │
│ 27 │ hyperliquid     │ XRP      │ XRP-USD       │
│ 28 │ binance-futures │ XRP      │ XRPUSDT       │
│ 29 │ bybit           │ XRP      │ XRPUSDT       │
│ 30 │ okex-swap       │ XRP      │ XRP-USDT-SWAP │
│ 31 │ hyperliquid     │ XYZ100   │ xyz:XYZ100    │
└────┴─────────────────┴──────────┴───────────────┘

Fetch historical orderbook data

Pass either exchange and product together, or coin on its own. A coin query aggregates depth across every tracked futures exchange.

Use catalog.futures() to find products with depth: true.

const velo = new Velo({ apiKey: process.env.VELO_API_KEY! });
const data = await velo.query(
  orderbook.levels({
    exchange: 'binance-futures',
    product: 'BTCUSDT',
    last: '1h',
    resolution: '1m',
  }),
);
 
const latest = data.snapshotAt(-1);
if (latest) {
  console.log('Best bid:', latest.bids[0]);
  console.log('Best ask:', latest.asks[0]);
}

const velo = new Velo({ apiKey: process.env.VELO_API_KEY! });
 
const data = await velo.query(
  orderbook.levels({
    coin: 'BTC',
    last: '1h',
    resolution: '1m',
  }),
);
 
const latest = data.snapshotAt(-1);
 
if (latest) {
  console.log('Best bid:', latest.bids[0]);
  console.log('Best ask:', latest.asks[0]);
}

Result types

velo.query() resolves to OrderbookData. Call snapshots() or snapshotAt(index) to view the data as two-sided orderbooks with the best levels first.

The depth column ranks price levels within each side of the book. Depth 1 is the best bid or ask, while depth 216 is the deepest level shown in this snapshot.

  // Example snapshot for coin `BTC`

  asks                          bids
┌───────┬───────┬────────────┐┌───────┬───────┬────────────┐
│ depth │ price │ size       ││ depth │ price │ size       │
├───────┼───────┼────────────┤├───────┼───────┼────────────┤
│     1 │ 64710 │ 5771.51513 ││     1 │ 64695 │ 4523.11767 │
│     2 │ 64725 │ 5275.07568 ││     2 │ 64680 │ 6011.80615 │
│     3 │ 64740 │ 5563.13037 ││     3 │ 64665 │ 4952.93603 │
│     4 │ 64755 │ 447.168518 ││     4 │ 64650 │ 4475.40917 │
│     5 │ 64770 │ 195.603027 ││     5 │ 64635 │ 2156.96655 │
│     6 │ 64785 │ 208.961578 ││     6 │ 64620 │ 197.118194 │
│   ... │   ... │        ... ││   ... │   ... │        ... │
│   214 │ 67905 │ 5.78559017 ││   214 │ 61500 │ 595.669799 │
│   215 │ 67920 │ 7.74172019 ││   215 │ 61485 │ 2.72295999 │
│   216 │ 67935 │ 59.1259193 ││   216 │ 61470 │ 2.05807995 │
└───────┴───────┴────────────┘└───────┴───────┴────────────┘

interface OrderbookSnapshot {
  time: number;
  mid: number;
  bids: readonly OrderbookLevel[];
  asks: readonly OrderbookLevel[];
}
 
interface OrderbookLevel {
  price: number;
  size: number;
}

interface OrderbookRow {
  time: number;
  mid: number;
  step: number;
  prices: Float64Array;
  sizes: Float64Array;
}

Field	Description
`time`	Bucket timestamp in Unix milliseconds
`mid`	Mid price for the bucket
`bids`	Levels below `mid`, ordered from highest to lowest price
`asks`	Levels at or above `mid`, ordered from lowest to highest price
`price`	Level price
`size`	Resting base-asset size at the level