> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.odyssey.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Welcome to Odyssey Exchange API documentation

Using the exchange API, you can do the following: get a list of all coins on the exchange, get the exchange rate of coins, create orders, close orders, get account balance and much more.

## Basic information

* Spot API URL: [https://openapi.odyssey.trade](https://openapi.odyssey.trade)

* Futures API URL: [https://futuresopenapi.odyssey.trade](https://futuresopenapi.odyssey.trade)

* WebSocket API URL: **wss\://ws.odyssey.trade/kline-api/ws**

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

* All requests are based on the `HTTPS` protocol, and the `Content-Type` should be `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.

## HTTP Error Codes

HTTP `4XX` return codes are used for malformed requests; the issue is on the sender's side.

HTTP `418` return code is used when an IP has been auto-banned for continuing to send requests after receiving `429` codes.

HTTP `429` return code is used when breaking a request rate limit.

HTTP `5XX` return codes are used for internal errors

HTTP `504` return code is used when the API successfully sent the message but did 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:

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

## Endpoint Security Type

Each endpoint has a security type that determines the how you will interact with it.

API key are passed into the Rest API via the `X-CH-APIKEY` header.

API keys and secret keys are case sensitive.

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

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

```js
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!

## Signature

Requests with the `Trade` and `USER_DATA` level must be signed. The signature is not case-sensitive and generated as follows:

`{timestamp}{method}{path}{data}`

* timestamp – current timestamp in milliseconds
* method – `GET` or `POST`
* path – request path, example: /ping
* data – `query string` if method is GET else `body data`

Then you have to hash this string using SHA512 secret key as a salt.

### Signature Example

Body

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

Terminal

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