Skip to main content

Websocket API

Overview

WebSocket is a new HTML5 protocol that achieves full-duplex data transmission between the client and server, allowing data to be transferred effectively in both directions. A connection between the client and server can be established with just one handshake. The server will then be able to push data to the client according to preset rules. Its advantages include:

  • The WebSocket request header size for data transmission between client and server is only 2 bytes.
  • Either the client or server can initiate data transmission.
  • There's no need to repeatedly create and delete TCP connections, saving resources on bandwidth and server.

It is strongly recommended that developers use WebSocket API to obtain market information and transaction depth.

DomainWebSocket APIRecommended to use
Websocket Domainwss://ws.cointr.com/v2/ws/publicMain Domain, Public channel
Websocket Domainwss://ws.cointr.com/v2/ws/privateMain Domain, Private channel

Connect

Connection instructions:

Connection limit: 100 connections per IP

Subscription limit: 240 times per hour

If there’s a network problem, the system will automatically disconnect the connection.

The connection will break automatically if the subscription is not established or data has not been pushed for more than 30 seconds.

To keep the connection stable:

  1. Set a timer of 30 seconds.
  2. If the timer is triggered, send a String 'ping'.
  3. Expect a 'pong' as a response. If the response message is not received within 30 seconds, please raise an error and/or reconnect.
  4. The Websocket server accepts up to 10 messages per second. The message includes:
  • PING frame (Not tcp ping)
  • Messages in JSON format, such as subscribe, unsubscribe.
  1. If the user sends more messages than the limit, the connection will be disconnected. IPs that are repeatedly disconnected may be blocked by the server;
  2. A single connection can subscribe up to 1000 Streams;
  3. A single IP can create up to 100 connections.

Login

apiKey: Unique identification for invoking API. Requires user to apply one manually.

passphrase: APIKey password

timestamp: the Unix Epoch time, the unit is seconds(--different from the signature timestamp of restAPI--)

secretKey: The security key generated when the user applies for APIKey, e.g. : 22582BD0CFF14C41EDBF1AB98506286D

Example of timestamp
const timestamp ='' + Date.now() / 1000
"Sign
sign=CryptoJS.enc.Base64.Stringify(CryptoJS.HmacSHA256(timestamp +'GET'+'/user/verify', secretKey))

method: always 'GET'.

requestPath : always '/user/verify'

sign: signature string, the signature algorithm is as follows:

First concatenate timestampmethodrequestPath, then use HMAC SHA256 method to encrypt the concatenated string with SecretKey, and then perform Base64 encoding.

The request will expire 30 seconds after the timestamp. If your server time differs from the API server time, we recommended using the REST API to query the API server time and then compare the timestamp.

Steps to generate the final signature

HMAC

Step 1. concat the content

Long timestamp = System.currentTimeMillis() / 1000;
String content = timestamp +"GET"+"/user/verify";

Step 1. Use the private key secretkey to encrypt the string to be signed with hmac sha256

String hash = hmac_sha256(content, secretkey);

The final step is to base64 encode the hash

String sign = base64.encode(hash);

RSA

Step 1. Use the RSA privateKey privateKey to encrypt the string to be signed with SHA-256

Step 2. Base64 encoding for Signature.

If login fails, it will automatically disconnect

Request Format Description
{
"op":"login",
"args":[
{
"apiKey":"<api_key>",
"passphrase":"<passphrase>",
"timestamp":"<timestamp>",
"sign":"<sign>"
}
]
}
Request Example
{
"op":"login",
"args":[
{
"apiKey":"xx_xxx",
"passphrase":"xxx",
"timestamp":"1538054050",
"sign":"8RCOqCJAhhEh4PWcZB/96QojLDqMAg4qNynIixFzS3E="
}
]
}
Successful Response Example
{
"event":"login",
"code":"0",
"msg":""
}
Failure Response Example
{
"event":"error",
"code":"30005",
"msg":"error"
}

Subscribe

Subscription Instructions

Request Format Description
{
"op": "subscribe",
"args": ["<SubscriptionTopic>"]
}

instId: should be either symbol or default

Users can choose to subscribe to one or more channels, and the total length of multiple channels cannot exceed 4096 bytes at a time.

Request Example
{
"op":"subscribe",
"args":[
{
"instType":"SPOT",
"channel":"ticker",
"instId":"BTCUSDT"
},
{
"instType":"SPOT",
"channel":"candle5m",
"instId":"BTCUSDT"
}
]
}

Request Parameters

ParameterTypeRequiredDescription
opStringYesOperation, subscribe
argsArrayYesList of subscribe channels
> instTypeStringNoInstrument Type
> channelStringYesChannel name
> instIdStringNoInstrument ID
Example Response
{
"event": "subscribe",
"arg": {
"instType":"SPOT",
"channel":"ticker",
"instId":"BTCUSDT"
}
}

Return Parameters

ParameterTypeRequiredDescription
eventStringYesEvent, subscribe error
argObjectNoSubscribed channel
> instTypeStringNoInstrument Type MC:Perpetual contract public channel
> channelStringYesChannel name
> instIdStringNoInstrument ID
codeStringNoError code
msgStringNoError message

Unsubscribe

Unsubscribe from one or more channels.

Request Format Description
{
"op": "unsubscribe",
"args": ["< SubscriptionTopic>"]
}
Request Example
{
"op":"unsubscribe",
"args":[
{
"instType":"SPOT",
"channel":"ticker",
"instId":"BTCUSDT"
},
{
"instType":"SPOT",
"channel":"candle1m",
"instId":"BTCUSDT"
}
]
}

Request Parameters

ParameterTypeRequiredDescription
opStringYesOperation, unsubscribe
argsArrayYesList of channels to unsubscribe from
> instTypeStringYesInstrument Type MC:Perpetual contract public channel
> channelStringYesChannel name
> instIdStringYesInstrument ID
Example Response
{
"op":"unsubscribe",
"args":[
{
"instType":"SPOT",
"channel":"ticker",
"instId":"BTCUSDT"
},
{
"instType":"SPOT",
"channel":"candle1m",
"instId":"BTCUSDT"
}
]
}

Return Parameters

ParameterTypeRequiredDescription
eventStringYesEvent, unsubscribe error
argObjectYesUnsubscribed channel
> instTypeStringYesInstrument Type
> channelStringYesChannel name
> instIdStringYesInstrument ID
codeStringNoError Code
msgStringNoError Message