# OpenAPI Basic Information

### API Basic Information     <a href="#api-ji-ben-xin-xi" id="api-ji-ben-xin-xi"></a>

* ## <mark style="color:blue;">**REST API Baseurl ：**</mark><mark style="color:blue;">**&#x20;&#x20;**</mark><mark style="color:blue;">**`https://openapi.zke.com`**</mark>
* 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:

```javascript
{
  "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:

```javascript
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.&#x20;

**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:**

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

* **HMAC SHA256 Signature:**

```bash
[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 :**

```bash
  (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"}'
```