Overview

Exchange WebSocket Overview #

The WebSocket feed is publicly available and provides real-time market data updates for orders and trades. Two endpoints are supported in both production and sandbox:

• HootDex Market Data is our traditional feed which is available without authentication.
• HootDex Direct Market Data has direct access to the HootDex Exchange and requires Authentication.

NOTE

You can subscribe to both endpoints, but if ws-direct is your primary connection, we recommend using ws-feed as a failover.

Protocol #

The WebSocket feed uses a bidirectional protocol that encodes all messages as JSON objects. All messages have a type attribute that can be used to handle the message appropriately.

NOTE

New message types can be added at any time. Clients are expected to ignore messages they do not support.

Subscribe #

To begin receiving feed messages, you must send a subscribe message to the server indicating which channels and products to receive. This message is mandatory—you are disconnected if no subscribe has been received within 5 seconds.

CAUTION

To receive feed messages, you must send a subscribe message or you are disconnected in 5 seconds.

// Request
// Subscribe to hETH-USD and hETH-GBP with the level2, heartbeat and ticker channels,
// plus receive the ticker entries for hETH-hBTC and hETH-GBP
{
    "type": "subscribe",
    "product_ids": [
        "hETH-USD",
        "hETH-GBP"
    ],
    "channels": [
        "level2",
        "heartbeat",
        {
            "name": "ticker",
            "product_ids": [
                "hETH-hBTC",
                "hETH-GBP"
            ]
        }
    ]
}

Unsubscribe​ #

To unsubscribe from channel/product pairs, send an unsubscribe message. The structure is equivalent to subscribe messages.

// Request
{
    "type": "unsubscribe",
    "channels": [
        "heartbeat"
    ]
}

You receive a subscriptions message as a response to an unsubscribe message.

Specifying Product IDs​ #

There are two ways to specify the product IDs to listen for within each channel:

• You can define product IDs for an individual channel.
• You can define product IDs at the root of the object—this adds them to all the channels you subscribe to.

// Request
{
    "type": "unsubscribe",
    "product_ids": [
        "hETH-USD",
        "hETH-GBP"
    ],
    "channels": [
        "ticker"
    ]
}

Once a subscribe message is received, the server responds with a subscriptions message that lists all channels you are subscribed to. Subsequent subscribe messages add to the list of subscriptions. If you already subscribed to a channel without being authenticated, you will remain in the unauthenticated channel.

// Response
{
    "type": "subscriptions",
    "channels": [
        {
            "name": "level2",
            "product_ids": [
                "hETH-USD",
                "hETH-GBP"
            ],
        },
        {
            "name": "heartbeat",
            "product_ids": [
                "hETH-USD",
                "hETH-GBP"
            ],
        },
        {
            "name": "ticker",
            "product_ids": [
                "hETH-USD",
                "hETH-GBP",
                "hETH-hBTC"
            ]
        }
    ]
}

Websocket Compression Extension​ #

Websocket compression, defined in RFC7692, compresses the payload of WebSocket messages which can increase total throughput and potentially reduce message delivery latency. The permessage-deflate extension can be enabled by adding the extension header. Currently, it is not possible to specify the compression level.

From RFC7692:

The simplest “Sec-WebSocket-Extensions” header in a client (or server’s) opening handshake to offer (or accept) use of the “permessage-deflate” extension looks like this:

    GET wss://
       Sec-WebSocket-Extensions: permessage-deflate

Sequence Numbers​ #

Most feed messages contain a sequence number. Sequence numbers are increasing integer values for each product, with each new message being exactly one sequence number greater than the one before it.

Sequence numbers that are greater than one integer value from the previous number indicate that a message has been dropped. Sequence numbers that are less than the previous number can be ignored or represent a message that has arrived out of order.

In either situation you may need to perform logic to make sure your system is in the correct state.