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.

Domain	WebSocket API	Recommended to use
Websocket Domain	wss://ws.cointr.com/v2/ws/public	Main Domain, Public channel
Websocket Domain	wss://ws.cointr.com/v2/ws/private	Main 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.

5. 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;
6. A single connection can subscribe up to 1000 Streams;
7. 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 timestamp, method, requestPath, 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

• RSA sample code

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

Parameter	Type	Required	Description
op	String	Yes	Operation, subscribe
args	Array	Yes	List of subscribe channels
> instType	String	No	Instrument Type
> channel	String	Yes	Channel name
> instId	String	No	Instrument ID

Example Response

{
 "event": "subscribe",
  "arg": {
   "instType":"SPOT",
   "channel":"ticker", 
   "instId":"BTCUSDT" 
 }
}

Return Parameters

Parameter	Type	Required	Description
event	String	Yes	Event, subscribe error
arg	Object	No	Subscribed channel
> instType	String	No	Instrument Type MC：Perpetual contract public channel
> channel	String	Yes	Channel name
> instId	String	No	Instrument ID
code	String	No	Error code
msg	String	No	Error 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

Parameter	Type	Required	Description
op	String	Yes	Operation, unsubscribe
args	Array	Yes	List of channels to unsubscribe from
> instType	String	Yes	Instrument Type MC：Perpetual contract public channel
> channel	String	Yes	Channel name
> instId	String	Yes	Instrument ID

Example Response

{
  "op":"unsubscribe",
  "args":[
    {
      "instType":"SPOT",
      "channel":"ticker",
      "instId":"BTCUSDT"
    },
    {
      "instType":"SPOT",
      "channel":"candle1m",
      "instId":"BTCUSDT"
    }
  ]
}

Return Parameters

Parameter	Type	Required	Description
event	String	Yes	Event, unsubscribe error
arg	Object	Yes	Unsubscribed channel
> instType	String	Yes	Instrument Type
> channel	String	Yes	Channel name
> instId	String	Yes	Instrument ID
code	String	No	Error Code
msg	String	No	Error Message