WebSocket Protocol

The websocket server can be found at wss://bitnomial.com/exchange/ws. The sandbox websocket server can be found at wss://bitnomial.com/exchange/sandbox/ws. It uses a bidirectional feed with all messages encoded as JSON objects. Each message has a type field which allows the consumer to handle it appropriately.

Product Codes

A few messages in the WebSocket protocol use product codes. The product codes are designed to be flexible so that clients don’t necessarily have to spell out 10s or 100s of product symbols if they don’t want to. To that end, there are a few different ways each product code can be interpreted:

  1. Symbol: If the product code exactly matches a product symbol it will apply only to that product.
  2. Futures: If the product code exactly matches a future base symbol (eg. “BUS”), then that will apply to all futures that share the same base symbol.
  3. Options: If the product code exactly matches a base symbol with an “O” appeneded to it (eg. “BUSO”), then that will apply to all options with an underlying future having that base symbol.

A note about Book Mechanics

If you are subscribing to the Book channel you should familiarize yourself with the Book Mechanics in the BTP Pricefeed Docs.

Subscribe

Websocket clients must send a subscribe message within 10 seconds of connecting or they will be disconnected. An example subscribe message can be seen below.

{
  "type": "subscribe",
  "product_codes": ["BUSZ22", "BUSO"],
  "channels": [
    {
      "name": "trade",
      "product_codes": ["BUIZ22"]
    },
    {
      "name": "book",
      "product_codes": ["BUIH23"]
    }
  ]
}

This message will subscribe the client to all channels for BUSZ22 as well as all options with a BUS underlying future. See Product Codes for additional details on what strings are allowed in the product_codes field. Additionally, this message will subscribe the client to only trade updates for BUIZ22 and only book updates for BUIH23.

Unsubscribe

Unsubscribe messages have the same structure as subscribe messages, except for the type field is "unsubscribe".

{
  "type": "unsubscribe"
  "product_codes": [
    "BUIH23"
  ],
  "channels": [
    {
      "name": "trade",
      "product_codes": [
        "BUSO"
      ]
    }
  ]
}

This unsubscribe message will unsubscribe the client from all updates to BUIH23 as well as trade updates from BUSO meaning all options with a BUS underlying. Note that even if you originally subscribe to all updates for a product code you can still unsubscribe to specific channels after the fact.

Disconnect

Clients will receive a disconnect message when they are disconnected for any reason.

{
  "type": "disconnect",
  "reason": "Client requested logout"
}

Channels

There are currently 4 channels available on the Bitnomial WebSocket feed: trade, book, block, and status. They are defined in more detail below.

Trade

If you subscribe to the trade channel, you will only receive trades for the specific product codes you requested. Below is an example of the messages that are sent on the trade channel.

{
  "type": "trade",
  "ack_id": "7148460953766461527",
  "price": 19000,
  "quantity": 10,
  "symbol": "BUSZ22",
  "taker_side": "Bid",
  "timestamp": "2022-09-28T16:06:39.022836179Z"
}

Book

The book channel provides level and book updates for the product codes you requested. Upon subscribing, you will receive a book snapshot for each product matching the product code with which you subscribed. After you receive a book snapshot you can begin applying level updates after that. You can determine whether a level update can be applied to your book snapshot if level.ack_id > book.ack_id. A level update with a quantity of 0 means that price level has been cleared out, either from a match or a cancel.

Note: It is possible for the book snapshot to not arrive immediately upon subscribing to a book channel. This is only possible when the WebSocket is recovering from an error and is reconciling the pricefeed to make sure it has an accurate book snapshot to send. In this case it will send the book snapshot as soon as it has confirmed it’s correct. This also means that clients will not receive any book snapshots until it has been reconciled even though they are indeed subscribed.

Level Updates:

{
  "type": "level",
  "ack_id": "7148460953766461522",
  "price": 20000,
  "quantity": 10,
  "side": "Bid",
  "symbol": "BUSZ22",
  "timestamp": "2022-09-28T16:04:32.357586392Z"
}
{
  "type": "level",
  "ack_id": "7148460953766461524",
  "price": 20000,
  "quantity": 0,
  "side": "Bid",
  "symbol": "BUSZ22",
  "timestamp": "2022-09-28T16:04:37.003590493Z"
}

Book Update:

{
  "type": "book",
  "ack_id": "7148460953766461532",
  "asks": [
    [21000, 10],
    [22000, 10]
  ],
  "bids": [
    [19000, 15],
    [18000, 10]
  ],
  "symbol": "BUSZ22",
  "timestamp": "2022-09-28T16:07:36.93709645Z"
}

Each book update contains an array of asks and bids, which are aggregated per price level and represented as a tuple of (price, quantity). They are ordered such that the first element is the best ask or best bid, respectively. Note that the ack_id of a book update will be 0 when the market is closed.

Block Trade

The block channel only provides updates when Block Trade has occurred.

{
  "type": "block",
  "ack_id": "7148466850756558935",
  "leader_side": "Bid",
  "price": 19500,
  "quantity": 10,
  "symbol": "BUSZ22",
  "timestamp": "2022-09-28T16:26:01.440681563Z"
}

Status

The status channel provides updates on Market State events.

{
  "type": "status",
  "ack_id": "7148460953766461485",
  "state": "Open",
  "symbol": "BUSZ22",
  "timestamp": "2022-09-28T16:03:38.37944775Z"
}