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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.zke.com/api_en/openapi-basic-information.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.