Change Log (2023-03-17)

2023-03-17

OpenApi V2.0

• Added a v2 program interface, and adjusted access parameters
• The V1 interface remains unchanged. For details about how to use the V1 interface, see the documentation: https://github.com/Bitrue-exchange/USDT-M-Future-open-api-docs

General Info

SDK and Code Demonstration

Disclaimer:

• The following SDKs are provided by partners and users, and are not officially produced. They are only used to help users become familiar with the API endpoint. Please use it with caution and expand R&D according to your own situation.
• Bitrue does not make any commitment to the safety and performance of the SDKs, nor will be liable for the risks or even losses caused by using the SDKs.

Java

To get the provided SDK for Bitrue Futures,

• please visit https://github.com/Bitrue-exchange/Bitrue-future-SDK
• or use the command below: git clone https://github.com/Bitrue-exchange/Bitrue-future-SDK.git

python

To get the provided SDK for Bitrue Futures,

• please visit https://github.com/Bitrue-exchange/Bitrue-future-SDK
• or use the command below: git clone https://github.com/Bitrue-exchange/Bitrue-future-SDK.git

General API Information

• Some endpoints will require an API Key. Please refer to this page
• The base endpoint is: https://fapi.bitrue.com
• All endpoints return either a JSON object or array.
• Data is returned in ascending order. Oldest first, newest last.
• All time and timestamp related fields are in milliseconds.
• All data types adopt definition in JAVA.

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:

Error Codes and Messages

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

• Any endpoint can return an ERROR
• Specific error codes and messages defined in Error Codes.

General Information on Endpoints

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

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
}

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

SIGNED Endpoint Examples for POST /fapi/v1/order - HMAC Keys

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 :

  [linux]$ curl -H "X-CH-APIKEY: c3b165fd5218cdd2c2874c65da468b1e" -H "X-CH-SIGN: c50d0a74bb9427a9a03933d0eded03af9bf50115dc5b706882a4fcf07a26b761" -H "X-CH-TS: 1588591856950" -H "Content-Type:application/json" -X POST 'http://localhost:30000/sapi/v1/order/test' -d '{"symbol":"BTCUSDT","price":"9300","quantity":"1","side":"BUY","type":"LIMIT"}'