Books

The Order Books channel allows you to keep track of the state of the Bitfinex order book.
It is provided on a price aggregated basis with customizable precision.
Upon connecting, you will receive a snapshot of the book
followed by updates for any changes to the state of the book.

const ws = require('ws')
const w = new ws('wss://api-pub.bitfinex.com/ws/2')

w.on('message', (msg) => console.log(msg))

let msg = JSON.stringify({ 
  event: 'subscribe', 
  channel: 'book', 
  symbol: 'tBTCUSD' 
})

w.on('open', () => w.send(msg))
wscat -c wss://api-pub.bitfinex.com/ws/2
{ "event": "subscribe", "channel": "book", "symbol": "tBTCUSD" }
ws = websocket.WebSocketApp('wss://api-pub.bitfinex.com/ws/2')

ws.on_open = lambda self: self.send('{ "event": "subscribe", "channel": "book", "symbol": "tBTCUSD"}')

ws.on_message = lambda self, evt:  print (evt)
// request
{
	event: 'subscribe',
	channel: 'book',
	symbol: SYMBOL,
	prec: PRECISION,
	freq: FREQUENCY,
	len: LENGTH,
	subId: SUBID
}

{"event":"subscribe","channel":"book","symbol":"tBTCUSD","prec":"P0","freq":"F0","len":"25","subId": 123}

// response
{
	event: 'subscribed',
	channel: 'book',
	chanId: CHANNEL_ID,
	symbol: SYMBOL,
	prec: PRECISION,
	freq: FREQUENCY,
	len: LENGTH,
	subId: SUBID,
	pair: PAIR 
}

{"event":"subscribed","channel":"book","chanId":10092,"symbol":"tETHUSD","prec":"P0","freq":"F0","len":"25","subId":123,"pair":"ETHUSD"}
// on trading pairs (ex. tBTCUSD)

[
  17082, //CHANNEL_ID
  [
    [
      7254.7, //PRICE
      3, //COUNT
      3.3 //AMOUNT
    ], //BOOK_ENTRY
    ...
  ] //BOOK_ENTRIES
]
  
// on funding currencies (ex. fUSD)

[
  431549, //CHANNEL_ID
  [
    [
      0.00023112, //RATE
      30, //PERIOD
      1, //COUNT
      -15190.7005375 //AMOUNT
    ], //BOOK_ENTRY
    ...
  ] //BOOK_ENTRIES
]
// on trading pairs (ex. tBTCUSD)

[
  17082, //CHANNEL_ID
  [
    7254.5, //PRICE
    0, //COUNT
    1 //AMOUNT
  ] //BOOK_ENTRY
]
  
// on funding currencies (ex. fUSD)

[
  348748, //CHANNEL_ID
  [
    0.00023157, //RATE
    2, //PERIOD
    1, //COUNT
    66.35007188 //AMOUNT
  ] //BOOK_ENTRY
]
//Bulk updates can be enabled using a conf event flag of 536870912

// on trading pairs (ex. tBTCUSD)

[
  17082, //CHANNEL_ID
  [
    [
      7254.5, //PRICE
      0, //COUNT
      1 //AMOUNT
    ], //BOOK_ENTRY
  	...
  ] //BOOK_ENTRIES
]
  
// on funding currencies (ex. fUSD)

[
  348748, //CHANNEL_ID
  [
    [
      0.00023157, //RATE
      2, //PERIOD
      1, //COUNT
      66.35007188 //AMOUNT
    ], //BOOK_ENTRY
    ...
  ]//BOOK_ENTRIES
]

Request fields

FieldsTypeDescription
SYMBOLStringTrading pair or funding currency
PRECISIONstringLevel of price aggregation (P0, P1, P2, P3, P4).
The default is P0
FREQUENCYstringFrequency of updates (F0, F1).
F0=realtime / F1=2sec.
The default is F0.
LENGTHstringNumber of price points ("1", "25", "100", "250") [default="25"]
SUBIDstringOptional user-defined ID for the subscription

Book snapshot data

IndexFieldTypeDescription
[0]CHANNEL_IDIntIdentification number assigned to the channel for the duration of this connection.
[1]BOOK_ENTRIESArrayArray with an array of currently active book entries (Indices [0...n] will be book entries)
[1][0...n]BOOK_ENTRYArrayBook entry or funding book entry

Book update data

IndexFieldTypeDescription
[0]CHANNEL_IDIntIdentification number assigned to the channel for the duration of this connection.
[1]BOOK_ENTRYTradeBook entry or funding book entry

Bulk update date

IndexFieldTypeDescription
[0]CHANNEL_IDIntIdentification number assigned to the channel for the duration of this connection.
[1]BOOK_ENTRIESArrayArray with an array of currently active book entries (Indices [0...n] will be book entries)
[1][0...n]BOOK_ENTRYArrayBook entry or funding book entry

Book entry

IndexFieldTypeDescription
[0]PRICEFloatPrice level
[1]COUNTIntNumber of orders at that price level (delete price level if count = 0)
[2]AMOUNTFloatTotal amount available at that price level. Trading: if AMOUNT > 0 then bid else ask; Funding: if AMOUNT < 0 then bid else ask;

Funding book entry

IndexFieldTypeDescription
[0]RATEFloatPrice level
[1]PERIODIntPeriod level
[2]COUNTIntNumber of orders at that price level (delete price level if count = 0)
[3]AMOUNTFloatTotal amount available at that price level. Trading: if AMOUNT > 0 then bid else ask; Funding: if AMOUNT < 0 then bid else ask;

Algorithm to create and keep a trading book instance updated

  1. subscribe to channel
  2. receive the book snapshot and create your in-memory book structure
  3. when count > 0 then you have to add or update the price level
    3.1 if amount > 0 then add/update bids
    3.2 if amount < 0 then add/update asks
  4. when count = 0 then you have to delete the price level.
    4.1 if amount = 1 then remove from bids
    4.2 if amount = -1 then remove from asks

Algorithm to create and keep a funding book instance updated

  1. subscribe to channel
  2. receive the book snapshot and create your in-memory book structure
  3. when count > 0 then you have to add or update the price level
    3.1 if amount > 0 then add/update asks (offers)
    3.2 if amount < 0 then add/update bids
  4. when count = 0 then you have to delete the price level.
    4.1 if amount = 1 then remove from asks (offers)
    4.2 if amount = -1 then remove from bids

Node.JS example gists:

Precision Levels

Precision LevelNumber of significant figures
P05
P14
P23
P32
P41

Checksum
An Order Book Checksum can be requested through the Websocket configuration. You can find out more on the WebSocket Checksum page.

Bulk Updates
Bulk updates can be enabled by sending a conf event with a flag value of 536870912. With bulk updates enabled, updates will arrive as an array of arrays.

🚧

Error Codes

10011 : Unknown Book precision
10012 : Unknown Book length