WebSocket Interface

Overview

WebSocket is a new protocol (Protocol) in HTML5. It realizes full-duplex communication between the client and the server, allowing data to be quickly transmitted in both directions. A simple handshake can establish a connection between the client and the server, and the server can actively push information to the client according to business rules. Its advantages are as follows:

• When the client and server transmit data, the request header information is relatively small, about 2 bytes.
• Both the client and server can actively send data to each other.
• There is no need to create and destroy TCP requests multiple times, saving bandwidth and server resources.
• It is strongly recommended that developers use the WebSocket API to obtain market quotes, order book depth, and other information.

Domain	WebSocket API	Recommended Use
Spot Channel	wss://open-ws.j2coin.com/ws	Main domain, spot public channel
Futures Channel	wss://open-fws.j2coin.com/ws	Main domain, futures channel

Connection

Connection Instructions:

Connection Limit: 300 connection requests/IP/5 minutes, a single IP can create up to 100 connections

Subscription Limit: 240 times/hour/connection, a single connection can subscribe to up to 1000 channels

To keep the connection valid and stable, it is recommended that you perform the following operations:

1. The user sets a timer to send the string "ping" every 30 seconds and expects a string "pong" as a response. If the string "pong" response is not received, please reconnect
2. If the server does not receive "ping" within 2 minutes, it will automatically disconnect
3. The Websocket server accepts up to 10 messages per second per connection. Messages include:

• String "ping"
• JSON format messages, such as subscribe, unsubscribe

4. If the user sends messages exceeding the limit, the connection will be disconnected. IPs that are repeatedly disconnected may be blocked by the server
5. To maintain the stability of the connection, it is strongly recommended that a single connection should not subscribe to more than 50 channels. The fewer channels a connection subscribes to, the higher the stability.

Login

Private channels (orders, balance, positions, etc.) require login authentication before subscription.

Request Format:

{
  "op": "auth",
  "args": [
    {
      "validate-algorithms": "HmacSHA256",
      "validate-appkey": "ak_95e7762883a06dfc93ea479c08018afd",
      "validate-recvwindow": "5000",
      "validate-timestamp": "1641446237201",
      "validate-signature": "a0695576d86546a00c8e95422c868e82a78f7f76aa995cfda9cc454b77204295"
    }
  ]
}

Parameter Description:

Field	Description
validate-algorithms	Signature algorithm, fixed as HmacSHA256
validate-appkey	User's appkey
validate-recvwindow	Request validity time (milliseconds), recommended 5000
validate-timestamp	Current timestamp (milliseconds)
validate-signature	Signature value (see below for generation method)

Signature Generation Method (Same as REST API):

1. Concatenate request header part (in dictionary order of keys, connected by &), recorded as X:

   validate-algorithms=HmacSHA256&validate-appkey=<appkey>&validate-recvwindow=<recvwindow>&validate-timestamp=<timestamp>

2. Concatenate data part, method fixed as GET, path fixed as /ws/auth, no query, no body, recorded as Y:

   #GET#/ws/auth

3. Final string to be signed original = X + Y, use secretKey for HmacSHA256 encryption (hex output):

   signature = hmacSha256Hex(secretKey, original)

Success Response:

{ "op": "auth", "success": true }

Failure Response:

{ "op": "auth", "success": false, "msg": "invalid signature" }

Error Code	Description
invalid signature	Signature error
invalid appkey	Invalid appkey
timestamp expired	Timestamp outside recvwindow range
ip not allowed	IP not in whitelist

After successful authentication, it will automatically subscribe to order, balance (futures will also automatically subscribe to position).

Subscribe

Request Format:

{
  "op": "subscribe",
  "args": [
    "ticker@BTC_USDT",
    "depth@BTC_USDT,20",
    "kline@BTC_USDT,1m"
  ]
}

Success Response:

{
  "op": "subscribe",
  "success": true,
  "args": ["ticker@BTC_USDT"]
}

Failure Response:

{
  "op": "subscribe",
  "success": false,
  "msg": "invalid channel format"
}

Push Message Format:

{
  "ch": "ticker@BTC_USDT",
  "d": { ... }
}

Field	Description
ch	Channel name
d	Data content

Unsubscribe

Request Format:

{
  "op": "unsubscribe",
  "args": ["ticker@BTC_USDT"]
}

Success Response:

{
  "op": "unsubscribe",
  "success": true,
  "args": ["ticker@BTC_USDT"]
}