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.
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:
If you are subscribing to the Book channel you should familiarize yourself with the Book Mechanics in the BTP Pricefeed Docs.
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 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.
Clients will receive a disconnect message when they are disconnected for any reason.
{
"type": "disconnect",
"reason": "Client requested logout"
}
There are currently 4 channels available on the Bitnomial WebSocket feed: trade
, book
, block
, and status
. They
are defined in more detail below.
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"
}
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.
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"
}
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"
}