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 1.1

SSL Websocket Connection

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

Message encoding

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

Supported Pairs

BTCUSD, LTCUSD, LTCBTC, ETHUSD, ETHBTC, ETCUSD, ETCBTC, BFXUSD, BFXBTC, RRTUSD, RRTBTC, ZECUSD, ZECBTC

Public Channels

  • Book: order book feed
  • Ticker: ticker feed
  • Trades: trades feed

Authenticated Channels

  • Account Information: account specific private data (positions, orders, executed trades, balances)

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/')
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", "", "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": 1
}

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 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.

NOTE

Rely on CODE only to handle info events.

Ping/Pong

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

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

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

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

["<Chan Id>", "hb"]

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

Snapshot

["<Chan Id>",
  ["<Group of Update Messages>",
    ["<Update Message>"]
  ]
]

Upon subscribing to a channel an initial snapshot is sent. Typically, the snapshot will have as its first item, the chanId, its second item will be an array of update messages (each of which is itself an array).
So The array would have 3 levels.

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_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

// request
{
   "event":"unsubscribe",
   "chanId":"<CHANNEL_ID>"
}

// response
{
   "event":"unsubscribed",
   "status":"OK",
   "chanId":"<CHANNEL_ID>"
}

// response-failure
{
   "event":"error",
   "msg":"<ERROR_MSG>",
   "code":"<ERROR_CODE>"
}

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

Error Codes

10400 : Unsubscription failed (generic)
10401 : Not subscribed

General