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

  • Futures API URL: 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:

{
  "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:

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

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

Terminal

[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
SDK