Documentation Description

​

Example of Interface

​

Check Server Time

{
    "timezone": "Coordinated Universal Time",
    "serverTime": 1785841675564
}

​

Document parameters specifications

​

Whether the interface requires signature verification?

• The interfaces under the “Public” and “Market” categories can be accessed without API-Key or signature.
• “Trade” and “Account” security require API-Key and signature verification before access
• The signature content is related to the parameters. If the parameters are entered incorrectly, the parameter error or null value will be returned.
• For interfaces that require signature verification, X-CH-SIGN, X-CH-APIKEY, and X-CH-TS must be added to the header for signature verification. For signature rules and examples, please refer to : Signature (apiKey and secretKey in this document are virtual values. The real content needs to be obtained by the user in the API management of the front page)

​

Return code type

​

API Basic Information

• baseurl https://openapi.oceanxz-au.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 429 return code is used when breaking a request rate limit.
• HTTP 418 return code is used when an IP has been auto-banned for continuing to send requests after receiving 429 codes.
• 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": -1121,
  "msg": "Invalid symbol."
}

​

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

• 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

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

​

SIGNED (TRADE and USER_DATA) endpoint security

• 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

• 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
}

​

SIGNED Endpoint Examples for POST /sapi/v1/order

​

Signature example

• body:

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

• HMAC SHA256 Signature:

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

  (HMAC SHA256)
  [linux]$ curl -H "X-CH-APIKEY: <your-api-key>" -H "X-CH-SIGN: <your-signature>"