# OpenApi Basic Information

## API Basic Information

* baseurl `https://openapi.darkex.com`
* All endpoints return either a JSON object or array.
* Data is returned in **Reverse** order. newest first, oldest last.
* All time and timestamp related fields are in milliseconds.

## HTTP Error Codes

* HTTP `4XX` return codes are used for malformed requests; the issue is on the sender's side.
* HTTP 410 return code is used when breaking a request rate limit.
* HTTP 418 means that if you continue to access after receiving 429, you will be blocked from IP, and the blocking time will be gradually extended from a minimum of 2 minutes to a maximum of 3 days for frequent violations of the restrictions.
* HTTP `5XX` return codes are used for internal errors
* HTTP `504` return code is used when the API successfully sent the message but not get a response within the timeout period. It is important to **NOT** treat this as a failure operation; the execution status is **UNKNOWN** and could have been a success.
* All endpoints can possibly return an ERROR, the error payload is as follows:

{% code overflow="wrap" %}

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

{% endcode %}

## General Information

* All requests are based on the Https protocol, and the `Content-Type` in the request header information needs to be uniformly set to:`'application/json'`
* For the interface of the `GET` method, the parameters must be sent in the `query string`
* The interface of the `POST` method, the parameters must be sent in the `request body`
* Parameters may be sent in any order.

## LIMITS <a href="#limits" id="limits"></a>

* 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.
* A 429 will be returned when either rate limit is violated.

## Endpoint Security Type <a href="#endpoint-security-type" id="endpoint-security-type"></a>

* Each endpoint has a security type that determines the how you will interact with it.
* API-keys are passed into the Rest API via the `X-CH-APIKEY` header.
* API-keys and secret-keys **are case sensitive**.

| 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.               |

<br>

## SIGNED (TRADE 与 USER\_DATA) endpoint security <a href="#signed-trade-yu-userdata-endpoint-security" id="signed-trade-yu-userdata-endpoint-security"></a>

* When calling the `TRADE` or `USER_DATA` interface, the signature parameter should be passed in the `X-CH-SIGN` field in the HTTP header.
* The signature uses the `HMAC SHA256` algorithm. The `API-Secret` corresponding to the API-KEY is used as the `HMAC SHA256` key.
* The request header of `X-CH-SIGN` is based on `timestamp` + `method` + `requestPath` + `body string` (+ means string connection) as the operation object
* The value of `timestamp` is the same as the `X-CH-TS` request header, `method` is the request method, and the letters are all uppercase: `GET/POST`
* `requestPath` is the request interface path For example: `/sapi/v1/order`
* `body` is the string of the request body (post only)
* The signature is not case sensitive.

## Timing Security <a href="#timing-security" id="timing-security"></a>

* 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 <a href="#signed-endpoint-examples-for-post-sapi-v1-order" id="signed-endpoint-examples-for-post-sapi-v1-order"></a>

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 <a href="#signature-example" id="signature-example"></a>

* **body:**

Copy

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

* **HMAC SHA256 Signature:**

Copy

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

Copy

```
  (HMAC SHA256)
  [linux]$ curl -H "X-CH-APIKEY: c3b165fd5218cdd2c2874c65da468b1e" -H "X-CH-SIGN: c50d0a74bb9427a9a0
```