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)
[
  CHANNEL_ID,
  [
    [
      PRICE,
      COUNT,
      AMOUNT
    ],
    ...
  ]
]
  
[17082,[[7254.7,3,3.3]]]
  
// on funding currencies (ex. fUSD)
[
  CHANNEL_ID,
  [
    [
      RATE,
      PERIOD,
      COUNT,
      AMOUNT
    ],
    ...
  ]
]

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

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

[348748,[0.00023157,2,1,66.35007188]]
//Bulk updates can be enabled using a conf event flag of 536870912

// on trading pairs (ex. tBTCUSD)
[
  CHANNEL_ID,
  [
    [
      PRICE,
      COUNT,
      AMOUNT
    ],
    [
      PRICE,
      COUNT,
      AMOUNT
    ],
    ...
  ]
]

[17082,[[7254.5,0,1],[7252.3,1,0.123]]]
  
// on funding currencies (ex. fUSD)
[
  CHANNEL_ID,
  [
    [
      RATE,
      PERIOD,
      COUNT,
      AMOUNT
    ],
    [
      RATE,
      PERIOD,
      COUNT,
      AMOUNT
    ],
    ...
  ]
]

[348748,[[0.00023157,2,1,66.35007188],[0.00023147,10,2,250.58]]]

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

Stream Fields

FieldsTypeDescription
CHANNEL_IDintIdentification number assigned to the channel for the duration of this connection.
PRICEfloatPrice level
RATEfloatRate level
PERIODintPeriod level
COUNTintNumber of orders at that price level (delete price level if count = 0)
±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