Websocket Documentation

This document provides instructions on how to connect to and interact with the WebSocket service for real-time price updates.

Supported asset types

WebSocket delivers real-time updates for all supported asset types that your API key is authorized to access, including Crypto, Equity, Forex, Commodity, and others. Use GET /v1/pairs to discover the pair codes available to your API key, and see Supported Data Pairs for pair-code formats.

Authentication

All WebSocket requests must be authenticated using an API key.

• Header: X-API-Key

To authenticate your request, include your API key in the X-API-KEY header. Authentication failures before a Socket.IO connection is established are returned during the HTTP handshake; see HTTP Handshake Before Upgrade.

Message Formats

All requests and server responses use JSON.

Subscribe

Method: "subscribe" — request real-time updates for one or more pairs.

Request Parameters

Parameter	Type	Required	Description
id	string	No	Client-provided identifier.
method	string	Yes	The request action method.
params	object	Yes	Contains subscription parameters like "pairs".
params.pairs	arraystring	Yes	Array of authorized pair codes.

Response Parameters

Notice Response

Parameter	Type	Required	Description
method	string	Yes	The request action method.
message	string	Yes	Success / Error message.
code	string	Yes	Domain status code for the Socket.IO control or error frame.
id	string	No	Client-provided identifier.
data	object	No	Response data from server

Push Data Response

Parameter	Type	Required	Description
code	string	Yes	The code representing the pair.
ask	string	Yes	Ask price reported for the pair in its quote currency.
bid	string	Yes	Bid price reported for the pair in its quote currency.
price	string	Yes	NOBI mid-price for the pair.

All price values are JSON strings. Parse them with a decimal-capable type to avoid floating-point precision loss. The pair code identifies the instrument and quote currency; use GET /v1/pairs to discover the pairs available to your API key.

Request

{
  "id": "ca3569cb-97ff-439a-8088-0f252c28b452",
  "method": "subscribe",
  "params": {
    "pairs": [
      "Crypto:ALL:BTC/USDT",
      "Equity:US:NVDA/USD",
      "Forex:ALL:USD/JPY",
      "Commodity:ALL:USOILSPOT/USD"
    ]
  }
}

Notice: Successful Response

{
    "id": "61b0d7ba-568c-418f-91d3-a291673001ca",
    "method": "subscribe",
    "message": "Success",
    "code": "200",
    "data": null
}

Push Data Response: Crypto Example

{
    "code": "Crypto:ALL:BTC/USDT",
    "ask": "109999.6793997101",
    "bid": "109779.8998204899",
    "price": "109889.7896101",
    "last_updated": 1788394473795,
    "sent_at": 1788394474460
}

Notice: Error Response Pair Not Found

{
    "method": "error",
    "message": "pair not found: Equity:US:XXX/USD",
    "code": "50104",
    "id": "a9611418-a501-4138-a2da-5bdb9fde235a",
    "data": null
}

Unsubscribe

Method: "unsubscribe" — stop receiving updates for given pairs.

Request Parameters

Parameter	Type	Required	Description
id	string	No	Client-provided identifier.
method	string	Yes	The request action method.
params	object	Yes	Contains unsubscription parameters like "pairs".
params.pairs	arraystring	Yes	Array of authorized pair codes.

Response Parameters

Notice Response

Parameter	Type	Required	Description
method	string	Yes	Method from request
message	string	Yes	Success / Error Message
code	string	Yes	Status request code

Request

{
  "id": "ca3569cb-97ff-439a-8088-0f252c28b452",
  "method": "unsubscribe",
  "params": {
    "pairs": [
      "Equity:US:NVDA/USD"
    ]
  }
}

Notice: Successful Response

{
    "method": "unsubscribe",
    "message": "success",
    "code": "200"
}

Heartbeat

Use "ping" to keep the connection alive.

Request Parameters

Parameter	Type	Required	Description
id	string	No	Client-provided identifier.
method	string	Yes	The request action method
params	object	No	Specifies the parameter requested.

Request

{
  "method": "ping"
}

Response

Pong!

Important

Important: If the server does not receive a ping within 30 seconds, the websocket connection will be closed.

Limitations

Connection Limitations

WebSocket connection limits are based on the allowed connections per API key, not on IP address restrictions.

For example, one API key allows only one WebSocket connection. If an IP address (A) has already initiated a WebSocket connection, attempting a second connection from the same IP address (A) will be rejected. Similarly, attempting a second connection from a different IP address (B) will also be rejected because the API key permits only one WebSocket connection.

For example user have a limit of three connections, one API key allows up to three WebSocket connections. You can have three WebSocket connections simultaneously from IP address (A), or one each from IP address (A), IP address (B), and IP address (C), as long as the total connections do not exceed three.

Subscription Limitations

Each WebSocket connection allows one active subscription at a time. Sending a new subscription request overwrites the previous one. Example: If you initially subscribe to A, B, C and want to add E, F, G, you must resend A, B, C, E, F, G in a single request. Once subscribed, real-time data will be pushed automatically.

Max subscription pairs per connection is 100 pairs.

Status Codes

Socket.IO Frames After Connection

The code field in Socket.IO control and error frames is a string containing a domain status code. It is not an HTTP status code. Successful subscription and unsubscription frames continue to use "200".

code	Meaning	Example conditions
200	Success	Subscription or unsubscription accepted.
50000	Internal server error	An unclassified server or connection-manager error.
50004	Invalid request	Malformed message, unknown method, missing or invalid pairs, or pair-limit violation.
50005	Invalid API key	API-key data is absent or invalid after connection.
50010	Access denied	The key lacks V1/source-stream access or pair-whitelist access.
50104	Pair not found	A requested pair does not exist, is inactive, or is suspended.
50109	Asset type access denied	The key cannot access the requested pair's asset type.

HTTP Handshake Before Upgrade

The request that starts the WebSocket upgrade is a separate HTTP phase. Its JSON error body uses status_number, not the Socket.IO frame field code. For example, a connection-limit failure before the upgrade is:

{
  "status_number": "50009",
  "message": "You have reached the maximum number of connections."
}

V1 access denial during the handshake uses status_number: "50010". Do not expect status_number in post-connect Socket.IO frames.