Language

OpenAPI Basic Information

API Basic Information

  • REST API Baseurl ： https://openapi.zke.com

  • All interfaces return a JSON object or array.

  • If there are arrays in the response, the elements are arranged in reverse chronological order, with earlier data appearing first.

  • All times and timestamps are in UNIX format, with the unit being milliseconds.

​

HTTP Error Codes

  • HTTP 4XX error codes are used to indicate incorrect request content, behavior, or format.

  • HTTP 410 error code indicates a warning that the access frequency limit is exceeded, and the IP is about to be blocked.

  • HTTP 418 indicates that continuing to access after receiving a 429 will result in IP ban. Frequent violations of the limit will gradually extend the ban duration, from a minimum of 2 minutes to a maximum of 3 days.

  • HTTP 5XX return codes signify internal system errors; this indicates that the problem is on the server side. When dealing with this error, do not treat it as a failed task, as the execution status is unknown; it could be successful or could have failed.

  • HTTP 504 means that the API server has submitted a request to the business core but failed to get a response. It is important to note that a 504 code does not mean the request failed but is unknown. It might have been executed successfully, or it might have failed, and further confirmation is needed.

  • Any interface may return an ERROR; the error return payload is as follows:

{
  "code": -1121,
  "msg": "Invalid symbol."
}

General Information

  • All requests are based on the HTTPS protocol, and the Content-Type in the request header needs to be uniformly set to 'application/json'.

  • For interfaces using the GET method, parameters must be sent in the query string.

  • For interfaces using the POST method, parameters must be sent in the request body.

  • There is no requirement for the order of parameters.

LIMITS

  • Access restrictions are based on IP or UID, not API Key.

  • The statistics by IP and by UID (account) are independent of each other.

  • The total weight of single interface weight according to IP statistics is 12,000 per minute

  • The total amount of interface weights by UID is 60,000 per minute

  • Each interface will indicate whether the statistics are by IP or by UID, and the weight value of the corresponding request once

  • There will be a limited frequency description below each interface.

  • A 429 will be returned when either rate limit is violated.

​

Endpoint Security Type

  • Each interface has its own authentication type, which determines the kind of authentication required during access.

  • If an API-key is needed, it should be transmitted in the HTTP header using the X-CH-APIKEY field.

  • Both API-key and API-secret are case sensitive.

  • You can modify the permissions associated with the API-key in the web user center, such as reading account information, sending trade orders, or sending withdrawal instructions.

Security Type

description

NONE

Endpoint can be accessed freely.

TRADE

Endpoint requires sending a valid API-Key and signature.

USER_DATA

Endpoint requires sending a valid API-Key and signature.

USER_STREAM

Endpoint requires sending a valid API-Key.

MARKET_DATA

Endpoint requires sending a valid API-Key.

SIGNED (TRADE 与 USER_DATA) endpoint security

  • When calling the TRADE or USER_DATA interfaces, the signature parameter should be transmitted in the HTTP header using the X-CH-SIGN field.

  • The signature uses the HMAC SHA256 algorithm. The API-Secret corresponding to the API-KEY is used as the key for HMAC SHA256.

  • The X-CH-SIGN request header is formed by concatenating the timestamp + method + requestPath + body string (where '+' denotes string concatenation).

  • The value of the timestamp is the same as in the X-CH-TS request header. The method is the request method, in all uppercase letters: GET/POST.

  • requestPath is the request interface path, for example: /sapi/v1/order?orderId=211222334&symbol=BTCUSDT.

  • body is the string of the request body (post only). If it is a GET request, then the body can be omitted.

  • The signature is not case sensitive.

Timing Security

  • The signature interface needs to pass the timestamp in the X-CH-TS field in the HTTP header, and its value should be the unix timestamp of the request sending time e.g. 1528394129373

  • An additional parameter, recvWindow, may be sent to specify the number of milliseconds after timestamp the request is valid for. If recvWindow is not sent, it defaults to 5000.

  • In addition, if the server calculates that the client's timestamp is more than one second ‘in the future’ of the server’s time, it will also reject the request.

  • The logic is as follows:

if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
  // process request
} else {
  // reject request
}

Serious trading is about timing. Networks can be unstable and unreliable, which can lead to requests taking varying amounts of time to reach the servers. With recvWindow, you can specify that the request must be processed within a certain number of milliseconds or be rejected by the server.

It recommended to use a small recvWindow of 5000 or less!

SIGNED Endpoint Examples for POST /sapi/v1/order

Here is a step-by-step example of how to send a vaild signed payload from the Linux command line using echo, openssl, and curl.

Key

Value

apiKey

vmPUZE6mv9SD5V5e14y7Ju91duEh8A

secretKey

902ae3cb34ecee2779aa4d3e1d226686

Parameter

Value

symbol

BTCUSDT

side

BUY

type

LIMIT

volume

1

price

9300

Signature example

  • body:

{"symbol":"BTCUSDT","price":"9300","volume":"1","side":"BUY","type":"LIMIT"}

  • HMAC SHA256 Signature:

[linux]$ echo -n "1588591856950POST/sapi/v1/order/test{\"symbol\":\"BTCUSDT\",\"price\":\"9300\",\"volume\":\"1\",\"side\":\"BUY\",\"type\":\"LIMIT\"}" | openssl dgst -sha256 -hmac "902ae3cb34ecee2779aa4d3e1d226686"
(stdin)= c50d0a74bb9427a9a03933d0eded03af9bf50115dc5b706882a4fcf07a26b761

  • Curl command :

  (HMAC SHA256)
  [linux]$ curl -H "X-CH-APIKEY: c3b165fd5218cdd2c2874c65da468b1e" -H "X-CH-SIGN: c50d0a74bb9427a9a03933d0eded03af9bf50115dc5b706882a4fcf07a26b761" -H "X-CH-TS: 1588591856950" -H "Content-Type:application/json" -X POST 'http://localhost:30000/sapi/v1/order/test' -d '{"symbol":"BTCUSDT","price":"9300","quantity":"1","side":"BUY","type":"LIMIT"}'

Last updated