WebSocket

The WebSocket API allows clients to subscribe to various topics via topics query parameter. Clients can receive updates for multiple topics in a single connection or establish separate connections for each topic. We advise to subscribe only to necessary topics, to lower the risk of disconnection due to message processing delays. 

Supported topics:

  • orders: Updates on the client’s own orders.
  • orderbook: Snapshot and live updates of the orderbook.
  • hubtohub: Updates on available transfer capacities.
  • marketstatus: Updates on market trading status.

The orderbookfrequency query parameter lets clients control the frequency of orderbook updates to manage processing load or reduce update intervals when real-time changes are not required. Parameter specifies the minimum interval between orderbook updates. However, the actual time between messages may vary based on market events and system configuration.

Message Format

Each message follows a standardized JSON structure with root-level properties:

  • type: Specifies the type of message (e.g., order-change, orderbook-snapshot-request).
  • payload: Contains the data relevant to the message type.

Rate Limiting

Rate limiting is applied to prevent excessive requests. If a client exceeds the limit, the server may reject the request with a message of type ratelimit-error. This message includes:

  • Policy Information: For example, 50;w=10 (50 requests allowed per 10 seconds).
  • Reset Time: Time until the request counter resets, in seconds.

Disconnection Reasons

The server may disconnect the client for the following reasons:

  1. Message Processing Delays: The client fails to process messages in a timely manner.
  2. Invalid Message Type: The client sends an unrecognized or incorrect message type.
  3. Planned Maintenance: A scheduled service downtime.

In all cases, the WebSocket protocol's close message will include the reason for disconnection.

Connection Health (Ping/Pong)

The server and client can verify connection health using ping and pong messages.

  • Either side can send a ping message at any time. 
  • The client is not required to send ping messages.
  • The recipient must respond with a pong message to confirm the connection is still active. If no response is received within 5 seconds, the WebSocket connection will be terminated by the server.
  • Message format: { "type": "ping" }

This mechanism ensures the stability of the WebSocket connection.


WS wss://isot.okte.sk/api/v1/idm/ws

Parameters

:topics
Enum (orders | orderbook | hubtohub | marketstatus)
A comma-delimited list of topics to receive updates for. Default: "all" (receive updates for all topics).
:orderbookfrequency
Integer
The minimum interval between orderbook updates, in milliseconds. Default: 0 ms (no delay).

Example

WS wss://isot.okte.sk/api/v1/idm/ws?topics=orders,orderbook,hubtohub,marketstatus&orderbookfrequency=500{
  "type": "orderbook-snapshot",
  "payload": {
    "seqNo": 6351,
    "timeDelta": 0,
    "data": [
      {
        "period": {
          "start": "2024-11-22T09:00:00Z",
          "end": "2024-11-22T10:00:00Z",
          "isBlock": false,
          "tradingEnd": "2024-11-22T08:30:00Z"
        },
        "statistics": {
          "lastTradeTime": "2024-11-22T07:35:29Z",
          "lastPrice": 179.9,
          "highPrice": 179.9,
          "lowPrice": 24,
          "totalQuantity": 87764,
          "lastQuantity": 46,
          "priceDirection": 1
        },
        "ownStatistics": {
          "buy": {
            "quantity": 20.1,
            "remainingQuantity": 0,
            "weigtedAveragePrice": 6.1
          },
          "sell": {}
        },
        "buyList": [
          {
            "price": 62,
            "quantity": 6,
            "ownQuantity": 0
          },
          {
            "price": 34,
            "quantity": 31,
            "ownQuantity": 0
          },
          {
            "price": 33,
            "quantity": 47,
            "ownQuantity": 0
          },
          {
            "price": 32,
            "quantity": 89,
            "ownQuantity": 0
          },
          {
            "price": 31,
            "quantity": 89,
            "ownQuantity": 0
          },
          {
            "price": 30,
            "quantity": 49,
            "ownQuantity": 0
          },
          {
            "price": 29,
            "quantity": 72,
            "ownQuantity": 0
          },
          {
            "price": 28,
            "quantity": 81,
            "ownQuantity": 0
          },
          {
            "price": 27,
            "quantity": 104,
            "ownQuantity": 0
          },
          {
            "price": 26,
            "quantity": 126,
            "ownQuantity": 0
          },
          {
            "price": 25,
            "quantity": 82,
            "ownQuantity": 0
          },
          {
            "price": 24,
            "quantity": 166,
            "ownQuantity": 0
          },
          {
            "price": 23,
            "quantity": 272,
            "ownQuantity": 0
          },
          {
            "price": 22,
            "quantity": 201,
            "ownQuantity": 0
          },
          {
            "price": 21,
            "quantity": 238,
            "ownQuantity": 0
          },
          {
            "price": 20,
            "quantity": 341,
            "ownQuantity": 0
          }
        ],
        "sellList": [],
        "blockOrders": []
      },
      {
        "period": {
          "start": "2024-11-22T17:00:00Z",
          "end": "2024-11-22T19:00:00Z",
          "isBlock": true,
          "tradingEnd": "2024-11-22T16:30:00Z"
        },
        "buyList": [],
        "sellList": [],
        "blockOrders": [
          {
            "price": 37.6,
            "quantity": 23.1,
            "direction": "buy"
          }
        ]
      }
    ]
  }
}

The previous example shows a message of type orderbook-snapshot, which is sent to the client after the connection is initiated with the orderbook topic or without any topic specified. This message represents the state of the orderbook at that moment. Subsequent messages of type orderbook-change are sent with the seqNo property incremented by one, reflecting changes to the orderbook.

Every message sent via WebSocket has a structure with type and an optional payload property at the root of the JSON object.