The Bitfinex API’s are designed to allow access to all of the features of the Bitfinex platform. The end goal is to allow people to potentially recreate the entire platform on their own.

If you would like to suggest changes to the documentation, please see the github at

Open Source Libraries

The following open source projects are works in progress. We will be continually improving them, but we want to release them early so that the community can take a look, make use of them, and offer pull requests. Nothing in the Bitcoin world exists in isolation.

Get Started    

Current Version

Bitfinex Websocket API version is 2.0



Message encoding

Each message sent and received via the Bitfinex's websocket channel is encoded in JSON format

Supported Pairs


A symbol can be a trading pair or a margin currency.

Trading pairs symbols are formed prepending a "t" before the pair (i.e tBTCUSD, tETHUSD).
Margin currencies symbols are formed prepending a "f" before the currency (i.e fUSD, fBTC, ...)

How to Connect

Open up a websocket connection to the websocket URI.

const WebSocket = require('ws')

const wss = new WebSocket('wss://')
wss.onmessage = (msg) => console.log(
wss.onopen = () => {
  // API keys setup here (See "Authenticated Channels")
import (

ws, err := websocket.Dial("wss://", "", "http://localhost/")
if err != nil {
    return err

Error Codes

In case of error, you receive a message containing the proper error code (code JSON field).

Generic Error Codes

  • 10000 : Unknown event
  • 10001 : Unknown pair

Info Messages

   "event": "info",
   "version":  VERSION

Info messages are sent from the websocket server to notify the state of your connection.
Right after connecting you receive an info message that contains the actual version of the websocket stream.


If you are developing/using a trading bot, please make sure to handle version number changes.

   "code": CODE,
   "msg": MSG

Websocket server sends other info messages to inform regarding relevant events.

Info Codes

  • 20051 : Stop/Restart Websocket Server (please try to reconnect)
  • 20060 : Refreshing data from the Trading Engine. Please pause any activity and resume after receiving the info message 20061 (it should take 10 seconds at most).
  • 20061 : Done Refreshing data from the Trading Engine. You can resume normal activity. It is advised to unsubscribe/subscribe again all channels.


Rely on CODE only to handle info events.
We wish to emphasize to only rely on the event message codes rather than the text descriptions of the event messages. The descriptions may change over time and are not part of the protocol.

  • All times are UTC timestamps expressed as milliseconds (eg 1477409622229)

Array Length

Message (JSON array) lengths should never be hardcoded. New fields may be appended at the end of a message without changing version.


Use ping message to test your connection to the websocket server.

// request

// response


  event: "conf", 
  flags: FLAGS


In order to change the configuration, there is a new event able to be requested conf, and this will have a parameter flags which is the bitwise XOR of the different options listed below

To enable all decimals as strings and all times as date strings, you would set the value of flags to 40

Available Options




Enable all decimal as strings.



Enable all times as date strings.



Enable sequencing BETA FEATURE

Subscribe to Channels

// request
   "event": "subscribe",
   "channel": CHANNEL_NAME

// response
   "event": "subscribed",
   "channel": CHANNEL_NAME,
   "chanId": CHANNEL_ID

// response-failure
   "event": "error",
   "msg": ERROR_MSG,
   "code": ERROR_CODE

To receive data from a channel you have to send a "subscribe" message first.


If there is no activity in the channel for 5 second, Websocket server will send you an heartbeat message in this format.

[ CHANNEL_ID, "hb" ]


Upon subscribing to a channel an initial snapshot is sent. Typically, the snapshot will have as its first item, the CHANNEL_ID, its second item will be the CHANNEL_NAME and the third item will be an array of UPDATE_MESSAGEs (each of which is itself an array).

So The array would have 3 levels.



After receiving the snapshot, you will receive updates upon any change.

CHANNEL_ID's allow you to keep track of the messages, they are static per session, you will receive both the CHANNEL_NAME and the CHANNEL_ID in the response to a subscription message.

  • CHANNEL_NAME: (string) channel name (book, trades, ticker)
  • CHANNEL_ID: (int) channel identifier. CHANNEL_ID is a numeric channel identifier that the developer can use to distinguish between updates for each subscribed channel.

Error Codes

  • 10300 : Subscription failed (generic)
  • 10301 : Already subscribed
  • 10302 : Unknown channel

Unsubscribe to Channels

To stop receiving data from a channel you have to send a "unsubscribe" message.

// request
   "event": "unsubscribe",
   "chanId": CHANNEL_ID

// response
   "event": "unsubscribed",
   "status": "OK",
   "chanId": CHANNEL_ID

// response-failure
   "event": "error",
   "msg": ERROR_MSG,
   "code": ERROR_CODE

Error Codes

10400 : Subscription failed (generic)
10401 : Not subscribed

Abbreviated Terms Glossary

Below you can find all the message types that the API will send

Term Definition
bu balance update
ps position snapshot
pn new position
pu position update
pc position close
ws wallet snapshot
wu wallet update
os order snapshot
on new order
ou order update
oc order cancel
oc-req order cancel
te trade executed
tu trade execution update
fte funding trade execution
ftu funding trade update
hos historical order snapshot
mis margin information snapshot
miu margin information update
n notification
fos funding offer snapshot
fon funding offer new
fou funding offer update
foc funding offer cancel
hfos historical funding offer snapshot
fcs funding credits snapshot
fcn funding credits new
fcu funding credits update
fcc funding credits close
hfcs historical funding credits snapshot
fls funding loan snapshot
fln funding loan new
flu funding loan update
flc funding loan close
hfls historical funding loan snapshot
hfts historical funding trade snapshot
fte funding trade execution
ftu funding trade update
uac user custom price alert