General Info

Access Guide

ApiKey

After registering an account, users can view their API Key and Signature in the API management section. Keep these two values safe, as they will be needed for subsequent public parameter verification.

Header Keys

All interfaces requiring signature verification (spot account and trading part interfaces) must include the following HTTP header keys:

1. JAYX-ACCESS-KEY: The API Key from the API Key application

2. JAYX-ACCESS-SIGN: The signature of the request parameters

3. JAYX-ACCESS-TIMESTAMP: UTC millisecond timestamp

Signature (JAYX-ACCESS-SIGN)

The JAYX-ACCESS-SIGN request header is the HMAC SHA256 encryption of the string composed of timestamp + method + requestPath + body (+ indicates string concatenation), along with the signature, encoded in Base-64.

stsign = CryptoJS.enc.Base64.stringify(
    CryptoJS.HmacSHA256(timestamp + 'POST' + '/api/v1/trader/order' + 
            {"market":"BTCUSDT","type":"1","lots":"2","side":"BUY"}, 
    sgnature)        )

Example：

1. timestamp has the same value as the JAYX-ACCESS-TIMESTAMP request header, which is the UTC millisecond timestamp.

2. method is the request method, in uppercase letters: GET/POST.

3. requestPath is the request interface path, e.g., /api/v1/trader/order.

4. body refers to the string of the request body. If there is no body in the request (usually for GET requests), the body can be omitted, e.g., {"market":"BTCUSDT","type":"1","lots":"2","side":"BUY"}.

5. signature is the signature obtained from the API Key application.

Generating Signature with JavaScript Example：

  static async sign(method, requestPath, header, postBody) {
    console.log('header: ' + JSON.stringify(header));
    let signature = 'signature from apiKey'
    let sign = await TraderService.hmacSHA256(header['jayx-access-timestamp'], method, requestPath, JSON.stringify(postBody), signature);
    return sign;
  }

Common Structure for Response

{
    "data": {}, // data
    "code": 0, // 0 means success, otherwise fail
    "msg": "" // error information when code is not 0
}

Limits

If usage exists rate limit, users receives 429 . Repeating violation of 429 will result in an automatic ban with error code 418 with a Retry-After header giving the duration that the IP or user is banned in seconds. Detail info of rate limits can be found by querying the exchange info /api/v1/public/exchangeInfo

Headers

API Responses will carry the following header to give clients information on number of orders, requests and weights used so they can make sure they do not exceed the limits.

X-ORDER-COUNT-(intervalNum)(intervalLetter) - order count in this interval

X-USED-WEIGHT-(intervalNum)(intervalLetter) - weights used in this interval

X-REQUEST-COUNT-(intervalNum)(intervalLetter) - request counts in this interval

Rate Limiters

There are three types of rate limits:

1. RAW_REQUEST - the total number of requests made within the time frame defined

2. REQUEST_WEIGHT - the total weight of the requests made within the time frame defined

3. ORDER - the number of order related requests within the time frame defined

// Weighted requests
{
  "rateLimitType": "REQUEST_WEIGHT",
  "interval": "MINUTE",
  "intervalNum": 1,
  "limit": 6000
}
// Order related requests
{
  "rateLimitType": "ORDERS",
  "interval": "SECOND",
  "intervalNum": 10,
  "limit": 100
},
{
  "rateLimitType": "ORDERS",
  "interval": "DAY",
  "intervalNum": 1,
  "limit": 200000
}
// Raw request counts
{
  "rateLimitType": "RAW_REQUESTS",
  "interval": "MINUTE",
  "intervalNum": 5,
  "limit": 5000
}

Public Endpoints

• IP limits are applied to all public endpoints in addition to the API Gateway level limits per endpoint

• Endpoint weights are as follow:

  • /v1/ping - 1

  • /v1/exchangeInfo - 1

  • /v1/contracts - 2

  • /v1/markets - 2

  • /v1/pub/ticker - 5 *

  • /v1/pub/depth - 5 *

  • /v1/pub/fulldepth - 5 *

  • /v1/pub/trades - 5

  • /v1/pub/candlestick - 5

* In the future these endpoints will have adjusted increases based on limit. First 100 requests, weight = 5. Then up to 500, weight = 25. Up to 1000, weight increases to 50 and finally above 1000 to the 5000 raw request limit cap, the weight becomes 250.

Authenticated Endpoints

• User account limits are applied to all authenticated endpoints

• Endpoint weights are as follow:

  • /v1/trader/info - 2

  • /v1/trader/balances - 2

  • /v1/order/new - 500

  • /v1/order/status - 20

  • /v1/order/cancel - 200

  • /v1/order/cancel/all - 400