# OpenAPI Introduction

### Fokawa Open API Basic Information

Welcome to the Fokawa Open API. Below you will find essential information to help you interact with our API efficiently.

#### API Basic Information

* **Base URL:** `https://openapi.fokawa.com`

All endpoints return either a JSON object or array. Data is returned in reverse order, with the newest entries first and the oldest last. All time and timestamp-related fields are in milliseconds.

#### HTTP Error Codes

* **HTTP 4XX:** Malformed requests; the issue is on the sender's side.
* **HTTP 410:** Breaking a request rate limit.
* **HTTP 418:** If you continue to access after receiving a 429 error, your IP will be blocked, and the blocking time will gradually extend from 2 minutes to 3 days for frequent violations.
* **HTTP 5XX:** Internal errors.
* **HTTP 504:** The API sent the message but did not receive a response within the timeout period. This should not be treated as a failure; the execution status is unknown and could have been successful.

#### Error Payload Example

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

#### General Information

* All requests are based on the HTTPS protocol.
* The `Content-Type` in the request header must be set to `'application/json'`.
* For GET requests, parameters must be sent in the query string.
* For POST requests, parameters must be sent in the request body.
* Parameters may be sent in any order.

#### Limits

* Access restrictions are based on IP or UID, not API Key.
* 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.
* A 429 error will be returned when either rate limit is violated.

#### Endpoint Security Type

* **API-keys:** Passed into the Rest API via the `X-CH-APIKEY` header.
* **API-keys and secret-keys:** Case sensitive.

**Security Types:**

* **NONE:** Endpoint can be accessed freely.
* **TRADE:** Requires a valid API-Key and signature.
* **USER\_DATA:** Requires a valid API-Key and signature.
* **USER\_STREAM:** Requires a valid API-Key.
* **MARKET\_DATA:** Requires a valid API-Key.

#### Signed (TRADE and USER\_DATA) Endpoint Security

When calling TRADE or USER\_DATA interfaces, the signature parameter should be passed in the `X-CH-SIGN` field in the HTTP header.

**Signature Details:**

* Algorithm: HMAC SHA256
* Key: API-Secret corresponding to the API-KEY
* Request Header: `X-CH-SIGN`
* Concatenation: `timestamp + method + requestPath + body` (as string)
* `timestamp`: Same as `X-CH-TS` request header
* `method`: Uppercase (GET/POST)
* `requestPath`: Example: `/sapi/v1/order`
* `body`: Request body string (POST only)
* The signature is not case-sensitive.

#### Timing Security

* Pass the timestamp in the `X-CH-TS` field in the HTTP header.
* Value should be the Unix timestamp of the request sending time (e.g., 1528394129373).
* An additional parameter, `recvWindow`, may specify the number of milliseconds after the timestamp the request is valid. Defaults to 5000 if not sent.
* If the client's timestamp is more than one second in the future compared to the server’s time, the request will be rejected.

**Example Logic:**

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

#### Example of Signed Endpoint for POST /sapi/v1/order

**Step-by-Step Example**

**Key Values:**

* **apiKey:** `vmPUZE6mv9SD5V5e14y7Ju91duEh8A`
* **secretKey:** `902ae3cb34ecee2779aa4d3e1d226686`
* **symbol:** `BTCUSDT`
* **side:** `BUY`
* **type:** `LIMIT`
* **volume:** `1`
* **price:** `9300`

**Signature Example:**

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

**HMAC SHA256 Signature:**

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

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