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:
- Set a timer of 30 seconds.
- If the timer is triggered, send a String 'ping'.
- Expect a 'pong' as a response. If the response message is not received within 30 seconds, please raise an error and/or reconnect.
- 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.
- 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;
- A single connection can subscribe up to 1000 Streams;
- 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
const timestamp ='' + Date.now() / 1000
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
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
{
"op":"login",
"args":[
{
"apiKey":"<api_key>",
"passphrase":"<passphrase>",
"timestamp":"<timestamp>",
"sign":"<sign>"
}
]
}
{
"op":"login",
"args":[
{
"apiKey":"xx_xxx",
"passphrase":"xxx",
"timestamp":"1538054050",
"sign":"8RCOqCJAhhEh4PWcZB/96QojLDqMAg4qNynIixFzS3E="
}
]
}
{
"event":"login",
"code":"0",
"msg":""
}
{
"event":"error",
"code":"30005",
"msg":"error"
}
Subscribe
Subscription Instructions
{
"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.
{
"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 |
{
"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.
{
"op": "unsubscribe",
"args": ["< SubscriptionTopic>"]
}
{
"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 |
{
"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 |