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


---

# 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://apidocs.fokawa.com/openapi-basic-information/openapi-introduction.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.