Introduction

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 https://github.com/bitfinexcom/api_docs

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

URL

wss://api.bitfinex.com/ws/2

Message encoding

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

Supported Pairs

All pairs available in the platform are supported

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://api.bitfinex.com/ws/2')
wss.onmessage = (msg) => console.log(msg.data)
wss.onopen = () => {
  // API keys setup here (See "Authenticated Channels")
}
import (
	"code.google.com/p/go.net/websocket"
)

ws, err := websocket.Dial("wss://api.bitfinex.com/ws/2", "", "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.

NOTE

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

{
   "event":"info",
   "code": CODE,
   "msg": MSG
}

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

Info Codes

  • 20051 : Stop/Restart Websocket Server (please reconnect)
  • 20060 : Entering in Maintenance mode. Please pause any activity and resume after receiving the info message 20061 (it should take 120 seconds at most).
  • 20061 : Maintenance ended. You can resume normal activity. It is advised to unsubscribe/subscribe again all channels.

Important

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.

Ping/Pong

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

// request
{
   "event":"ping"
}

// response
{
   "event":"pong"
}

Configuration

{ 
  event: "conf", 
  flags: 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

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

Available Options

Name
Value
Description

DEC_S

8

Enable all decimal as strings.

TIME_S

32

Enable all times as date strings.

SEQ_ALL

65536

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.

Heartbeating

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" ]

Snapshot

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.

[ 
  CHANNEL_ID,
  CHANNEL_NAME,
  [
    [ UPDATE_MESSAGE ],
    ...
  ]
]

Update

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_ID,
  CHANNEL_NAME,
  [ UPDATE_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

General