Current Version
Bitfinex Websocket API version is 2.0
URL
Channels that require authentication should use the domain:
wss://api.bitfinex.com/
Public channels should use the domain:
wss://api-pub.bitfinex.com/
// For public channels:
wss://api-pub.bitfinex.com/ws/2
// For authenticated channels:
wss://api.bitfinex.com/ws/2Message 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, and must always be uppercase (i.e. btcusd is invalid, BTCUSD is valid)
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, ...)
The pair list is continuously growing, to get the an up to date list you can query the symbols this endpoint: https://api-pub.bitfinex.com/v1/symbols
How to Connect
Open up a websocket connection to the websocket URI.
const WebSocket = require('ws')
const wss = new WebSocket('wss://api-pub.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
- 10305 : Reached limit of open channels
Info Messages
{
"event": "info",
"version": VERSION,
"platform": {
"status": 1
}
}
Info messages are sent from the websocket server to notify the state of your connection.
Right after connecting you will receive an info message that contains the actual version of the websocket stream, along with a platform status flag (1 for operative, 0 for maintenance).
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
infomessage20061(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",
"cid": 1234
}
// response
{
"event":"pong",
"ts": 1511545528111,
"cid": 1234
}
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, set the value of flags to 8.
If you wish to enable more than one flag, sum up their values. Enabling both DEC_S and TIME_S can be done by setting the value of flags to 40.
DEC_S
8
Enable all decimals as strings
TIME_S
32
Enable all timestamps as strings
TIMESTAMP
32768
Timestamp in milliseconds.
SEQ_ALL
65536
Enable sequencing BETA FEATURE
OB_CHECKSUM
131072
Enable checksum for every book iteration. Checks the top 25 entries for each side of book. Checksum is a signed int.
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.
Subscription Limit
Starting June 22nd, 2019 All websocket connections will have a limit of 30 subscriptions to public market data feed channels (tickers, book, candles, trades, …). We kindly ask all users to adapt their application setup accordingly to split subscriptions to channels using multiple WebSocket connections.
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,
[
[ 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,
[ 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
Updated about a month ago