Overview

Suggest Edits

Current Version

The current Eosfinex Websocket API version is 1.0

Public URL

Private URL

Eosfinex is passing the torch, open-source access to its core IP will put the platform’s industry leading exchange technology in the hands of the developer community.

Rate limits

eosfinex API access is rate limited. The rate limit applies if an IP address exceeds a certain number of requests per minute. The current limit is between 10 and 45 to a specific REST API endpoint (ie. /ticker). In case a client reaches the limit, we block the requesting IP address for 10-60 seconds on that endpoint. The API will return the JSON response {"error": "ERR_RATE_LIMIT"}. These DDoS defenses may change over time to further improve reliability.

Multiple clients

Your security is key to us. For every authenticated action taken via the eosfinex API, a nonce is required. Nonces are used to guard against replay attacks. If multiple requests arrive at the API with the wrong nonce (e.g. due to an async timing issue) the API will reject the request.

Data format

General notes

Two domains are utilised for REST endpoints and WebSocket channels, the difference between the two being if the request is public, or requires authentication.

Endpoints that require authentication should use the domain:
(https | wss)://api.eosfinex.com/

Public endpoints should use the domain:
(https | wss)://api-pub.bitfinex.com/

Do not parse text descriptions - use only codes. Text descriptions are subject to changes and adjustments without any warning.

Messages may contain null placeholders in the payload for future additional fields
All times are UTC timestamps expressed as milliseconds (eg 1477409622229)

Protocol extension / change of message format

New fields may be appended at the end of an Array or inserted in an Object without changing the API version. When we change existing positional elements in an Array or existing fields in an Object, it will trigger a version change of the API.

Price Precision

The precision level of all trading prices is calculated based on significant figures.

For all pairs on eosfinex we use 5 significant digits. Examples of five significant digits would be 12.123, 1.1234, 123.43, and 1234.5.

This mimics how traditional global markets handle the precision of small, medium and large values. The reason is that the higher the amounts, the less relevant the number of decimals become. The corollary is true for very small amounts, where more precision is more useful.

If you submit prices with a precision large a precision of 5, the API will cut them.

Message encoding

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

ws.send(JSON.stringify({
  ...payload,
});

ws.on('message', (message) {
  const data = JSON.parse(message));
  
  // ...
});

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

Refer to our error codes page, to view more error codes.

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 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",
   "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 and all times as date strings, you would set the value of flags to 40

Available Options

NameValueDescription
TIMESTAMP32768Timestamp in milliseconds.
SEQ_ALL65536Enable sequencing BETA FEATURE
CHECKSUM131072Enable 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
}

[block:callout]
{
  "type": "info",
  "body": "- CHANNEL_NAME: (string) channel name (book, trades, ticker)\n- 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."
}
[/block]

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

❗️

Error Codes

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

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 public channel an initial snapshot is sent. Typically, the snapshot will have as its first item, the CHANNEL_ID, its second item 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 public channel subscription message.

[ 
  CHANNEL_ID,
  [ UPDATE_MESSAGE ],
]

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 3 years ago