Navbar
现货 交割合约 币本位永续合约 USDT永续合约 期权合约
简体中文
shell

Introduction

Documentation Summary

Welcome to the Huobi Future API! You can use our API to access all market data, trading, and account management endpoints.

We have code example in Shell! You can view code examples in the dark area to the right.

You can use the drop down list above to change the API version. You can also use the language option at the top right to switch documentation language.

Market Maker Program

Market maker program gives clients with good market making strategy an opportunity to access customized trading fee structure.

Eligibility Criteria as a Market Maker on Huobi Future

Welcome users, who are dedicated to maker strategy and have created large trading volume, to participate in Huobi Futures long-term Market Maker project.If you have more than 3 BTC in your Huobi future account, or more than 3 BTC in your Huobi coin margined swap account, or you have more than 3 BTC in your Huobi option account,or more than 30000 USDT in your Huobi USDT Margined swap account, please send the following information to dm_mm@huobi.com:

  1. Huobi UIDs (not linked to any rebate program in any accounts)
  2. Provide screenshot of trading volume for the past 30 days or VIP/corporate status with other Exchanges

Changelog

1.2.1 2020-12-02 【 Modified “Order details acquisition” interface (When querying cancelation data of orders that have not been partially filled, if “created_at” and “order_type” parameters are not uploaded, the data that can be queried reduced from last 12 hours to last 2 hours.); modified “Query history orders” interface (When querying cancelation data of orders that have not been partially filled, the data that can be retained reduced from last 24 hours to last 2 hours.); modified “Query history orders via multiple fields” interface (When querying cancelation data of orders that have not been partially filled, the data that can be retained reduced from last 24 hours to last 2 hours.)】

1、Modified “Order details acquisition” interface (When querying cancelation data of orders that have not been partially filled, if “created_at” and “order_type” parameters are not uploaded, the data that can be queried reduced from last 12 hours to last 2 hours.)

2、modified “Query history orders” interface (When querying cancelation data of orders that have not been partially filled, the data that can be retained reduced from last 24 hours to last 2 hours.)

3、modified “Query history orders via multiple fields” interface (When querying cancelation data of orders that have not been partially filled, the data that can be retained reduced from last 24 hours to last 2 hours.)

1.2.0 2020-11-24 【 Added: Query historical settlement records of the platform interface. Modified: Added fields of return parameter for "Query Liquidation Orders" interface and "Subscribe Liquidation Order Data" interface】

1、Added “Query historical settlement records of the platform” interface

2、Added fields of return parameter for "Query Liquidation Orders" interface（“amount” are added for return parameter “data". "amount" represents the liquidation amount (token);）

3、Added fields of return parameter for "Subscribe Liquidation Order Data" interface（“amount” are added for return parameter “data". "amount" represents the liquidation amount (token);）

1.1.9 2020-10-28 【Newly added：Query financial records via multiple fields, Query history orders via multiple fields, Query history transactions via multiple fields.】

1、Query history transactions via multiple fields

2、Query history orders via multiple fields

3、Query financial records via multiple fields

1.1.8 2020-10-15 【Newly added：Added switch leverage interface; Updated: websocket messages of account topic will be pushed when leverage switch succeeds; websocket messages of position topic will be pushed when leverage switch succeeds; new response fields are added on websocket topic of match orders; the interface(contract_order_info) supports query of 4-hour order cancellation data (previously only support to query 24-hour data).】

1、Added switch leverage interface

2、Subscribe Account Equity Updates Data（Return parameters added “switch_lever_rate” event type to represent switching leverages. When the leverage is successfully switched, a latest information on assets will be pushed with event“switch_lever_rate".）

3、Subscribe Position Updates（Return parameters added “switch_lever_rate” event type to represent switching leverages. When the leverage is successfully switched, a latest information on positions will be pushed with event“switch_lever_rate" (the information will not be pushed when the user's position is 0).）

4、Subscribe Match Order Data（Added the following fields in return parameters: direction (buy/sell direction), offset (open/close direction), lever_rate (leverages), price (order price), created_at (creation time), order_source (order source), order_price_type (order quotation type).）

5、The interface(contract_order_info) supports query of 4-hour order cancellation data (previously only support to query 24-hour data).

1.1.7 2020-10-10 【Newly added：Added WS interface for subscribing system status updates push】

1. Added WS interface for subscribing system status updates push

1.1.6 2020-09-22 【Updated: Future Market Data Interfaces (including rest and ws interfaces) already support calls according to the contract code. Modified “symbol” field in request parameter: added contract code type, the format of which is fixed at “symbol-year-month-date”, for example, BTC200925. Only listing contracts can be queried currently if query according to the contract code. 】

1、Get Market Depth

2、Get Kline Data

3、Get Market Data Overview

4、Query The Last Trade of a Contract

5、Query a Batch of Trade Records of a Contract

6、Subscribe Kline data

7、Request Kline data

8、Subscribe Market Depth Data

9、Subscribe Market Detail Data

10、Subscribe Trade Detail Data

11、Request Trade Detail Data

12、Subscribe Incremental Market Depth Data

13、Subscribe Market BBO Data

1.1.5 2020-08-06 【Added interfaces：Query user’s settlement records；Subscribe trigger orders updates】

1、Query user’s settlement records

2、Subscribe trigger orders updates

1.1.4 2020-06-19 【Updated: added the return field "client_order_id" of websocket subscription of Match Order】

1、Modified futures subscribe match order data interface: added client_order_id in outer return parameter.

1、Added websocket subscription of contract info

2、Added websocket subscription of Market BBO

3、Added four depth level of websocket subscription of market depth: step12、step13、step14、step15

4、Added the interface of querying available leverage rate

5、Added periodical push of websocket subscription of account: push every 5 seconds

6、Added periodical push of websocket subscription of position: push every 5 seconds

7、Added high leverage support of placing orders

7.1

7.2

7.3

8、Added 9 fields of querying order detail interface: fee、order_id、order_id_str、client_order_id、order_type、status、trade_avg_price、trade_turnover、trade_volume.

9、Added 2 fields of querying order info interface: liquidation_type、canceled_at.

10、Added 2 fields of websocket subscription of orders: canceled_at、fee_asset.

11、Added uid field of websocket subscription of private events.

11.1

11.2

11.3

11.4

12、Added 2 fields of websocket subscription of match orders: trade_volume(total filled volume of the order)、volume(total volume of the order)

13、Added next quarter contract type,such as BTC_NQ

1.1.2 2020-04-09【Add an interface: Futures liquidation order WS push without authentication】

1.1.1 2020-03-12 【upgrade：added websocket subscription of index kline data；added websocket subscription of basis data; added restful interface of querying index kline data; added restful interface of querying basis data】

1、Added websocket subscription of index kline data

2、Added websocket subscription of basis data

3、Added restful interface of querying index kline data

4、Added restful interface of querying basis data

1.1.0 2020-03-05【upgrade：add transfer between master account and sub-account; add more order types; add websocket subscription of match orders】

1、Added asset transfer function between master account and sub-account on Web and API. When using Web, only master account has transfer authority, including transfer master account assets to sub-account and vice versa, but transfers between sub-accounts are not supported; When using API, only API Key of master account has authority for the transfer operations between master and sub account.

1.1、Added an interface: transfer between master account and sub-accounts, the rate limit between the master account and each subaccount is 10 times/ minute.Interface name: Transfer between master account and sub-accounts.

1.2、Added a parameter: transfer permission between master account and sub-accounts. Added strings: "master_transfer_sub" and "sub_transfer_master" in returning parameter data array.

1.3、Added an interface: query transfer records of master account and sub-accounts.

1.4、Added 4 kinds transfer statements of master account and sub-accounts in query contract financial record interface.

2、Modifications details of contract asset interface and contract trade interface are laid out as following：

2.1、Modified query contract information on order limit: added 10 order price types including opponent_ioc, lightning_ioc, optimal_5_ioc, optimal_10_ioc，optimal_20_ioc，opponent_fok，lightning_fok，optimal_5_fok，optimal_10_fok，optimal_20_fok

2.2、Modified place an order interface: added 8 order price types, including opponent_ioc, optimal_5_ioc, optimal_10_ioc, optimal_20_ioc, opponent_fok,optimal_5_fok, optimal_10_fok, optimal_20_fok.

2.3、Modified place a batch of orders interface: added 8 order price types, including opponent_ioc, optimal_5_ioc, optimal_10_ioc, optimal_20_ioc, opponent_fok, optimal_5_fok, optimal_10_fok, optimal_20_fok。

2.4、Modified get trade details of an order interface: added string "liquidation_type".

2.5、Modified "trade_type" and "orders" in query history orders interface. Added "reduce positions to close long" and "reduce positions to close short" types in request parameter "trade_type"; Added string "liquidation_type" in orders array of returning parameter.

2.6、Modified place flash close order interface: added string "order_price_type", including values: lightning_ioc, lightning_fok, lightning

2.7、Added string "liquidation_type" in order transaction push in WebSocket Subscription.

2.8、Added matching order transaction push interface in WebSocket Subscription.

2.10、Added API interface of getting user's API indicator disable information

Interface name: Query user's API indicator disable information

1.0.11 2020-02-21 API Uprade

1、 Interface URL: api/v1/contract_batchorder

the maximum number of batch order cancellation each time in request parameter “orders_data” will be changed from 20 to 10.

2、Interface URL: api/v1/contract_cancel

the maximum number of order cancellation each time in request parameter “order_id” and “client_order_id” will be changed from 20 to 10. Multiple order IDs are separated by “,”.

1.0.10 2020-01-15 API Upgrade

1、modify get Kline data interface:Added two request parameters “from” and “to”. Request parameter “from” stands for starting time and request parameter “to” stands for ending time. Data can be obtained for up to two consecutive years. Request parameter “size” was changed to non-mandatory.

2、When getting information on order cancellation via get contracts Information interface, users can only query last 24-hour data.

3、When getting information on order cancellation via query history orders interface, users can only query last 24-hour data.

4、When getting information on order cancellation via query order detail interface, users who type in parameters “created_at” and “order_type” can query last 90-day data, while users who don’t type in parameters “created_at” and “order_type” can only query last 24-hour data.

1.0.9 2019-12-02 API Upgrade: Added API interface with trigger order function

1、Added API interface with query assets and positions function.

2、Added API interface with trigger order function.

3、Updated API interfaces with fee coin type field added corresponding to the given fee.

Interfaces are as follows:

4、Updated API interfaces with the 'create_date' field to support any positive interger

Please note that the system will return with the last 90-day data by default if the 'create_date' field exceed 90.

1.0.8 2019-10-17 API Upgrade: Added the order_id_str field

api/v1/contract_order

api/v1/contract_batchorder

api/v1/contract_matchresults

api/v1/contract_hisorders

api/v1/contract_openorders

api/v1/lightning_close_position

api/v1/contract_order_info

1.0.7 2019-10-15

1、 Modified rest interface: User’s Account Information

Added return string “margin_static”in rest interface User’s Account Information (URL: api/v1/contract_account_info). The newly added return string “margin_static” in data array means account static equity.

2、 Added string “ID “in three interfaces;

Added string“ID”in rest interface Order details acquisition (URL: api/v1/contract_order_detail) , rest interface Get History Match Results (URL: api/v1/contract_matchresults) as well as the match result on Order Push in WebSocket Subscription.

3、Added “IOC”and “FOK order types for order placement

Added order_price_type “ioc”(ioc:Immediate Or Cancel) and “fok”(fok:Fill Or Kill)under Request Parameter in rest interface Place an Order(URL: api/v1/contract_order) and rest interface Place a Batch of Orders(URL: api/v1/contract_batchorder)

4、Modified interface: Query contract information on order limit

Added “fok”:FOK Order(fok:Fill Or Kill),“ioc”:IOC Order(ioc:Immediate Or Cancel) into string of“ order_price_type” in Returning Parameter under rest interface Query contract information on order limit (URL: api/v1/contract_order_limit)

The“ order_price_type” means Order Type here.

5、Added rest API interface: Query information on system status

Interface URL: api/v1/contract_api_state

6、 Added rest interface: Top Trader Sentiment Index Function-Account

Interface URL: api/v1/contract_elite_account_ratio

7、Added rest interface: Top Trader Sentiment Index Function-Position

Interface URL: api/v1/contract_elite_position_ratio

8、Added Liquidation order query function in API and WS subscription.

Added rest interface: Request Liquidation Order Information

Interface URL: rest interface api/v1/contract_liquidation_orders

Liquidation order push is added also into WebSocket Subscription.

1.0.6 2019-08-08 API Upgrade: Added rest interface

Added rest interface

Request access to address: https://api.hbdm.com/heartbeat/

Note: To query whether the system is available or not, request https://api.hbdm.com/heartbeat/. When Heartbeat is 1, system is available; when Heartbeat is 0, system is unavailable.

1.0.5 2019-07-10 API Upgrade: New Features of Query and Order Placing

Newly Added API Restful Interface

Newly added Interface: query user’s order limit information

Newly added Interface: query user’s trading fee information

Newly added Interface: query user’s transfer limit information

Newly added Interface: query users’ position limit information

Newly added Interface: query platform information on insurance fund and estimated clawback rate

Newly added Interface: query platform information on open interest information

Newly added Interface: query history records information on insurance fund

Newly added Interface: query platform information on Tiered Adjustment Factor

Newly added Interface: place Flash Close order

Modified API Interface

Restful interface: add “return to users’ adjustment factor” on Query Users’ Account Information Interface;

Restful interface: add “return to users’ adjustment factor” on Query a Single Sub-Account’s Assets Information Interface.

WebSocket Interface: add “return to users’ adjustment factor” on WebSocket Portfolio Push Interface;

Restful Interface: add Optimal price set with optimal top 5, optimal 10 and optimal top 20 on Order Place Interface and Place a Batch of Orders Interface

Restful Interface: add “query according contract code” on Acquire History of Match Results Interface.

1.0.4 2019-06-06 API Upgrade:Restful interface

Query assets information of all sub-accounts under the master account

URL：api/v1/contract_sub_account_list

Notice: Only return data for activated contract sub-account (i.e. sub-accounts that have gained contract trading permission).

Query a single sub-account's assets information

URL：api/v1/contract_sub_account_info

Notice: Only query account information for activated contract sub-account (i.e. sub-accounts that have gained contract trading permission); No data return for sub-accounts which has logged in hbdm but have not gained trading permission/activated.

Query a single sub-account's position information

URL：api/v1/contract_sub_position_info

Query account financial records

URL：api/v1/contract_financial_record

1.0.3 2019-05-28 API Upgrade: WebSocket Portfolio Push

WebSocket balance push is available:

users could subscribe the interface to get information of their balances automatically.

WebSocket position push is available:

users could subscribe the interface to get information of their positions automatically.

Acuqire positions information via Restful interface:

api/v1/contract_position_info.

The string of “latest price”is added into response

1.0.2 2019-05-14 API Upgrade: Transfer margin between Spot account and Future account

URL /v1/futures/transfer

This interface is used to transfer assets between Spot account and Future account.

The type is “pro-to-futures” when transferring assets from Spot account to Future; “futures-to-pro” when transferring from Future account to Spot account.

API rate limit for this interface is up to 10 times per minute.

API rate limit

Private interface rate limit has been increased from 10 times/second to 30 times every 3 seconds, which means users could send up to 30 requests within 3 seconds.

The rate limit of other non-market public interface has been increased from 20 times/second to 60 times every 3 seconds, which means users could send up to 60 requests within 3 seconds.

1.0.1 2019-05-09 API Upgrade: Post_only and more

Cancel all interface: URL api/v1/contract_cancelall

Send symbol to cancel all the contracts of that kind of symbol, e.g. send “BTC” to cancel all BTC weekly, biweekly and quarterly contracts.

Send contract_code to cancel the contracts of that code.

Send symbol+contract_type to cancel the certain contracts under the symbol of that contract_type, e.g. send “BTC” and “this week”, then the BTC weekly contracts will be cancelled.

Order place interface: URL api/v1/contract_order

Post_only is added into the string of order_price_type.

Description of post_only: assure that the maker order remains as maker order, it will not be filled immediately with the use of post_only, for the match system will automatically check whether the price of the maker order is higher/lower than the opponent first price, i.e. higher than bid price 1 or lower than the ask price 1. If yes, the maker order will placed on the orderbook, if not, the maker order will be cancelled.

Position limit will be applied to post_only while order limit will not.

Place a batch of orders: URL /v1/contract_batchorder

Post_only is added into the string of order_price_type.

Description of post_only: assure that the maker order remains as maker order, it will not be filled immediately with the use of post_only, for the match system will automatically check whether the price of the maker order is higher/lower than the opponent first price, i.e. higher than bid price 1 or lower than the ask price 1. If yes, the maker order will placed on the orderbook, if not, the maker order will be cancelled.

Position limit will be applied to post_only while order limit will not.

Will response following string for "header" via api

ratelimit-limit: the upper limit of requests per time, unit: time

ratelimit-interval: reset interval (reset the number of request), unit: ms

ratelimit-remaining: the left available request number for this round, unit: time

ratelimit-reset: upper limit of reset time used to reset request number, unit: ms

Order details acquisition: URL api/v1/contract_order_detail

The string of “role” (i.e. taker or maker) is added into “trades”

Acquire history of match results: URL api/v1/contract_matchresults

The string of “role” (i.e. taker or maker) is added into “trades

WebSocket, the private order push interface, requires API KEY Verification

Each UID can build at most create 30 WS connections for private order push at the same time. For each account, contracts of the same underlying coin only need to subscribe one WS order push, e.g. users only need to create one WS order push connection for BTC Contract which will automatically push orders of BTC weekly, BTC biweekly and BTC quarterly contracts.

Please note that the rate limit of WS order push and RESTFUL private interface are separated from each other, with no relations.

1.0.0 has launched on December 10, 2018

Future API Access Illustration

API List

permission type Content Type Context Request Type Desc Signature Required
Read Market Data api/v1/contract_contract_info GET Get Contracts Information No
Read Market Data api/v1/contract_index GET Get contract Index Price Information No
Read Market Data api/v1/contract_price_limit GET Get Contract Price Limitation No
Read Market Data api/v1/contract_open_interest GET Get Contract Open Interest Information No
Read Market Data api/v1/contract_delivery_price GET Get the estimated delivery price No
Read Market Data api/v1/contract_api_state GET Query information on system status No
Read Market Data /market/depth GET Get Market Depth No
Read Market Data /market/history/kline GET Get Kline Data No
Read Market Data /market/detail/merged GET Get Market Data Overview No
Read Market Data /market/trade GET Query The Last Trade of a Contract No
Read Market Data /market/history/trade GET Query a Batch of Trade Records of a Contract No
Read Market Data api/v1/contract_risk_info GET Query information on contract insurance fund balance and estimated clawback rate No
Read Market Data api/v1/contract_insurance_fund GET Query history records of insurance fund balance No
Read Market Data api/v1/contract_adjustfactor GET Query information on Tiered Adjustment Factor No
Read Market Data api/v1/contract_his_open_interest GET Query information on open interest No
Read Market Data api/v1/contract_elite_account_ratio GET Query Top Trader Sentiment Index Function-Account No
Read Market Data api/v1/contract_elite_position_ratio GET Query Top Trader Sentiment Index Function-Position No
Read Market Data api/v1/contract_liquidation_orders GET Query Liquidation Order Information No
Read Market Data api/v1/contract_settlement_records GET Query historical settlement records of the platform interface No
Read Market Data api/v1/index/market/history/index GET Query Index Kline Data No
Read Market Data api/v1/index/market/history/basis GET Query Basis Data No
Read Account api/v1/contract_account_info POST Query User’s Account Information Yes
Read Account api/v1/contract_position_info POST Query User’s Position Information Yes
Read Account api/v1/contract_sub_account_list POST Query assets information of all sub-accounts under the master account (Query by coins) Yes
Read Account api/v1/contract_sub_account_info POST Query a single sub-account's assets information Yes
Read Account api/v1/contract_sub_position_info POST Query a single sub-account's position information Yes
Read Account api/v1/contract_financial_record POST Query account financial records Yes
Read Account api/v1/contract_financial_record_exact POST Query financial records via multiple fields Yes
Read Account api/v1/contract_user_settlement_records POST Query user’s settlement records Yes
Read User Account api/v1/contract_order_limit POST Query contract information on order limit Yes
Read User Account api/v1/contract_available_level_rate POST Query contract available level rate Yes
Read User Account api/v1/contract_fee POST Query information on contract trading fee Yes
Read User Account api/v1/contract_transfer_limit POST Query information on Transfer Limit Yes
Read User Account api/v1/contract_position_limit POST Query information on position limit Yes
Trade User Account api/v1/contract_master_sub_transfer POST Transfer between master and sub account Yes
Read User Account api/v1/contract_account_position_info POST User’s position Information And User’s position Information Yes
Read Trade api/v1/contract_trigger_openorders POST Query Trigger Order Open Orders Yes
Read Trade api/v1/contract_trigger_hisorders POST Query Trigger Order History Yes
Trade Trade api/v1/contract_order POST Place an Order Yes
Trade Trade api/v1/contract_batchorder POST Place a Batch of Orders Yes
Trade Trade api/v1/contract_cancel POST Cancel an Order Yes
Trade Trade api/v1/contract_cancelall POST Cancel All Orders Yes
Trade Trade api/v1/contract_switch_lever_rate POST Switch Leverage Yes
Trade Trade api/v1/lightning_close_position POST Place Flash Close Order Yes
Read User Order Info api/v1/contract_order_info POST Get Information of an Order Yes
Read User Order Info api/v1/contract_order_detail POST Get Trade Details of an Order Yes
Read User Order Info api/v1/contract_openorders POST Get Current Orders Yes
Read User Order Info api/v1/contract_hisorders POST Get History Orders Yes
Read User Order Info api/v1/contract_hisorders_exact POST Query history orders via multiple fields Yes
Read User Order Info api/v1/contract_matchresults POST Get History Match Results Yes
Read User Order Info api/v1/contract_matchresults_exact POST Query history transactions via multiple fields Yes
Trade Trade v1/futures/transfer POST Transfer margin between Spot account and Future account Yes
Trade Trade api/v1/contract_trigger_order POST Place Trigger Order Yes
Trade Trade api/v1/contract_trigger_cancel POST Cancel Trigger Order Yes
Trade Trade api/v1/contract_trigger_cancelall POST Cancel All Trigger Orders Yes

Address

Address Applicable sites Applicable functions Applicable trading pairs
https://api.hbdm.com Huobi Future Market Trading pairs provided by Huobi Future

Notice

If you can't connect "https://api.hbdm.com", please use "https://api.btcgateway.pro" for debug purpose. If your server is deployed in AWS, we recommend using "https://api.hbdm.vn".

Signature Authentication & Verification

Signature Illustration

Considering that API requests may get tampered in the process of transmission, to keep the transmission secure, you have to use your API Key to do Signature Authentication for all private interface except for public interface (used for acuqiring basic information and market data), in this way to verify whether the parameters/ parameter value get tampered or not in the process of transmission

A legitimate request consists of following parts：

Create API Key

You could create API Key at

API Key consists of the following two parts.

Steps for Signature

Normative request for Signature calculation Different contents will get totally different results when use HMAC to calculate Signature, therefore, please normalize the requests before doing Signature calculation. Take the request of inquering order details as an example:

query details of one order

https://api.hbdm.com/api/v1/contract_order?

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

&SignatureMethod=HmacSHA256

&SignatureVersion=2

&Timestamp=2017-05-11T15:19:30

1. Request methods (GET/POST): add line breaker "\n".

POST\n

2. Text the visit address in lowercase, adding line breake "\n"

api.hbdm.com\n

3. Visit the path of methods, adding line breaker "\n"

/api/v1/contract_order\n

4. Rank the parameter names according to the sequence of ASCII codes, for example, below is the parameters in original sequence and the new sequence:

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

SignatureMethod=HmacSHA256

SignatureVersion=2

Timestamp=2017-05-11T15%3A19%3A30

5. After ranking

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

SignatureMethod=HmacSHA256

SignatureVersion=2

Timestamp=2017-05-11T15%3A19%3A30

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30

7. Form the final character strings that need to do Signature calculation as following:

POST\n

api.hbdm.com\n

/api/v1/contract_order\n

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30

8. Use the "request character strings" formed in the last step and your Secret Key to create a digital Signature.

4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=

  1. Take the request character string formed in the last step and API Secret Key as two parameters, encoding them with the Hash Function HmacSHA256 to get corresponding Hash value.

  2. Encoding the Hash value with base-64 code, the result will be the digital Signature of this request.

9. Add the digital Signature into the parameters of request path.

The final request sent to Server via API should be like:

https://api.hbdm.com/api/v1/contract_order?AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&order-id=1234567890&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30&Signature=4F65x5A2bLyMWVQj3Aqp%2BB4w%2BivaA7n5Oi2SuYtCJ9o%3D

  1. Add all the must authentication parameters into the parameters of request path;

  2. Add the digital Signature encoded with URL code into the path parameters with the parameter name of "Signature".

API Rate Limit Illustration

Future, Coin Margined Swap,Option Swap and USDT Margined Swap are using separate API rate limits.

Please note that, for both public interface and private interface, there are rate limits, more details are as below:

API Limitation on Order Cancellation Ratio

Get system status

This endpoint allows users to get system status, Incidents and planned maintenance.

The system status can also be obtained through email, SMS, webhook, RSS/Atom feed. Users can You can click here to subscribe. The subscription function depends on Google services. Before you subscribe, please ensure that you can access Google services normally. 

curl "https://status-dm.huobigroup.com/api/v2/summary.json"

HTTP Request

Request Parameters

No parameter is available for this endpoint.

Response:

{
  "page": {  // Basic information of status page
    "id": "p0qjfl24znv5",  // page id
    "name": "Huobi",  // page name
    "url": "https://status-dm.huobigroup.com/", // page url
    "time_zone": "Etc/UTC", // time zone
    "updated_at": "2020-02-07T10:25:14.717Z" // page update time
  },
  "components": [  // System components and their status
    {
      "id": "h028tnzw1n5l",  // component id
      "name": "Deposit", // component name
      "status": "operational", // component status
      "created_at": "2019-12-05T02:07:12.372Z",  // component create time
      "updated_at": "2020-02-07T09:27:15.563Z", // component update time
      "position": 1,
      "description": null,
      "showcase": true,
      "group_id": "gtd0nyr3pf0k",  
      "page_id": "p0qjfl24znv5", 
      "group": false,
      "only_show_if_degraded": false
    }
  ],
  "incidents": [ // System fault incidents and their status
        {
            "id": "rclfxz2g21ly",  // incident id
            "name": "Market data is delayed",  // incident name
            "status": "investigating",  // incident stutus
            "created_at": "2020-02-11T03:15:01.913Z",  // incident create time
            "updated_at": "2020-02-11T03:15:02.003Z",   // incident update time
            "monitoring_at": null,
            "resolved_at": null,
            "impact": "minor",  // incident impact
            "shortlink": "http://stspg.io/pkvbwp8jppf9",
            "started_at": "2020-02-11T03:15:01.906Z",
            "page_id": "p0qjfl24znv5",
            "incident_updates": [ 
                {
                    "id": "dwfsk5ttyvtb",   
                    "status": "investigating",   
                    "body": "Market data is delayed", 
                    "incident_id": "rclfxz2g21ly",   
                    "created_at": "2020-02-11T03:15:02.000Z",    
                    "updated_at": "2020-02-11T03:15:02.000Z",  
                    "display_at": "2020-02-11T03:15:02.000Z",   
                    "affected_components": [  
                        {
                            "code": "nctwm9tghxh6",  
                            "name": "Market data",  
                            "old_status": "operational",  
                            "new_status": "degraded_performance"  
                        }
                    ],
                    "deliver_notifications": true,
                    "custom_tweet": null,
                    "tweet_id": null
                }
            ],
            "components": [  
                {
                    "id": "nctwm9tghxh6",   
                    "name": "Market data",  
                    "status": "degraded_performance", 
                    "created_at": "2020-01-13T09:34:48.284Z", 
                    "updated_at": "2020-02-11T03:15:01.951Z", 
                    "position": 8,
                    "description": null,
                    "showcase": false,
                    "group_id": null,
                    "page_id": "p0qjfl24znv5",
                    "group": false,
                    "only_show_if_degraded": false
                }
            ]
        }
    ],
      "scheduled_maintenances": [  // System scheduled maintenance events and their status
        {
            "id": "k7g299zl765l", // incident id
            "name": "Schedule maintenance", // incident name
            "status": "scheduled", // incident status
            "created_at": "2020-02-11T03:16:31.481Z",  // incident create time
            "updated_at": "2020-02-11T03:16:31.530Z",  // incident update time
            "monitoring_at": null,
            "resolved_at": null,
            "impact": "maintenance",  // incident impact
            "shortlink": "http://stspg.io/md4t4ym7nytd",
            "started_at": "2020-02-11T03:16:31.474Z",
            "page_id": "p0qjfl24znv5",
            "incident_updates": [  
                {
                    "id": "8whgr3rlbld8",  
                    "status": "scheduled", 
                    "body": "We will be undergoing scheduled maintenance during this time.", 
                    "incident_id": "k7g299zl765l",  
                    "created_at": "2020-02-11T03:16:31.527Z",  
                    "updated_at": "2020-02-11T03:16:31.527Z",  
                    "display_at": "2020-02-11T03:16:31.527Z",  
                    "affected_components": [  
                        {
                            "code": "h028tnzw1n5l",  
                            "name": "Deposit And Withdraw - Deposit",  
                            "old_status": "operational",  
                            "new_status": "operational" 
                        }
                    ],
                    "deliver_notifications": true,
                    "custom_tweet": null,
                    "tweet_id": null
                }
            ],
            "components": [  
                {
                    "id": "h028tnzw1n5l",  
                    "name": "Deposit", 
                    "status": "operational", 
                    "created_at": "2019-12-05T02:07:12.372Z",  
                    "updated_at": "2020-02-10T12:34:52.970Z",  
                    "position": 1,
                    "description": null,
                    "showcase": false,
                    "group_id": "gtd0nyr3pf0k",
                    "page_id": "p0qjfl24znv5",
                    "group": false,
                    "only_show_if_degraded": false
                }
            ],
            "scheduled_for": "2020-02-15T00:00:00.000Z",  // scheduled maintenance start time
            "scheduled_until": "2020-02-15T01:00:00.000Z"  // scheduled maintenance end time
        }
    ],
    "status": {  // The overall current status of the system
        "indicator": "minor",   // system indicator
        "description": "Partially Degraded Service"  // system description
    }
}

Response Content

Field Data Type Description
page basic information of status page
{id string page id
name string page name
url string page url
time_zone string time zone
updated_at} string page update time
components System components and their status
[{id string component id
name string component name, including Order submission, Order cancellation, Deposit etc.
status string component status, value range: operational, degraded_performance, partial_outage, major_outage, under maintenance
created_at string component create time
updated_at string component update time
.......}] for details of other fields, please refer to the return example
incidents System fault incident and their status. If there is no fault at present, it will return to null
[{id string incident id
name string incident name
status string incident staus, value range: investigating, identified, monitoring, resolved
created_at string incident creat time
updated_at string incident update time
.......}] for details of other fields, please refer to the return example
scheduled_maintenances System scheduled maintenance incident and status. If there is no scheduled maintenance at present, it will return to null
[{id string incident id
name string incident name
status string incident staus, value range: scheduled, in progress, verifying, completed
created_at string incident creat time
updated_at string incident update time
scheduled_for string scheduled maintenance start time
scheduled_until string scheduled maintenance end time
.......}] for details of other fields, please refer to the return example
status The overall current status of the system
{indicator string system indicator, value range: none, minor, major, critical, maintenance
description} string system description, value range: All Systems Operational, Minor Service Outager, Partial System Outage, Partially Degraded Service, Service Under Maintenance

Query whether the system is available

Returning Parameter

Parameter Name Parameter Type Desc
status string "ok" or "error"...
<data> dict object
heartbeat int future 1: avaiable 0: not available
swap_heartbeat int coin margined swap 1: avaiable 0: not available
estimated_recovery_time long null: normal. estimated recovery time :millionseconds.
swap_estimated_recovery_time long null: normal. coin margined swap estimated recovery time millionseconds.
option_heartbeat int option 1: avaiable 0: not available
option_estimated_recovery_time long null: normal. option estimated recovery time :millionseconds.
linear_swap_heartbeat long USDT margined swap 1: avaiable 0: not available
linear_swap_estimated_recovery_time long null: normal. USDT margined swap estimated recovery time millionseconds.
</data>

Response:


{
    "status":"ok",
    "data":{
        "heartbeat":1,
        "estimated_recovery_time":null,
        "swap_heartbeat":1,
        "swap_estimated_recovery_time":null,
        "option_heartbeat":1,
        "option_estimated_recovery_time":null,
        "linear_swap_heartbeat":1,
        "linear_swap_estimated_recovery_time":null
    },
    "ts":1557714418033
}

Get current system timestamp

get https://api.hbdm.com/api/v1/timestamp

request

null

response


{
    "status": "ok",
    "ts": 1578124684692
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result
ts true long current system timestamp

Note:

Details of Each Error Code

Error Code Error Details Description
403 invalid ID
1000 System error.
1001 System is unprepared.
1002 Query error.
1003 Abnormal redis operation.
1004 System busy. Please try again later.
1010 Account doesn't exist.
1011 The user's session doesn't exist.
1012 The user's account doesn't exist.
1013 This contract type doesn't exist.
1014 This contract doesn't exist.
1015 The index price does not exist.
1016 The bid offer does not exist. Please input the price.
1017 Order doesn't exist.
1018 Main account doesn't exist.
1019 Main account doesn't exist in the sub-account white list.
1020 The number of your sub-account exceeds the maximum. Please contact customer service.
1021 Account open failed. Main account hasn’t opened contract trading account yet.
1030 Input error.
1031 Incorrect form source.
1032 The number of access exceeded the limit.
1033 Incorrect field of contract period.
1034 Incorrect field of contract period.
1035 Incorrect field of form direction.
1036 Incorrect field of open long form.
1037 The leverage is invalid. Please contact the customer service.
1038 The order price exceeds the precision limit, please modify and order again.
1039 Buy price must be lower than {0} USD. Sell price must exceed {1} USD.
1040 Invalid amount, please modify and order again.
1041 The order amount exceeds the limit ({0}Cont), please modify and order again.
1042 Current positions have triggered position limits ({0}Cont). Please order after changing the amount.
1043 Current positions have triggered position limits ({0}Cont). Please order after changing the amount.
1044 Current positions have triggered position limits of our platform. Please order after changing the amount.
1045 Unable to switch leverage due to current holdings or open orders.
1046 Abnormal service. Please try again later.
1047 Insufficient margin available.
1048 Insufficient close amount available.
1049 Open a position with market price is not available.contracts.
1050 Customer's order number is repeated. Please try again later.
1051 No orders to cancel.
1052 The number exceeds the batch limit.
1053 Unable to get the latest price range.
1054 Unable to get the latest price.
1055 The price is not reasonable, and the account equity will be less than 0 after placing this order. Please modify the price and place the order.
1056 In settlement. Your order can’t be placed/withdrew currently.
1057 Your order can’t be placed due to trading halt.
1058 Your order can’t be placed due to trade suspension.
1059 In delivery. Your order can’t be placed/withdrew currently.
1060 Your order can’t be placed currently due to abnormal contracts status.
1061 This order doesn't exist.
1062 Cancelling. Please be patient.
1063 The order has been executed.
1064 The main key of order conflicts.
1065 The form number of client isn't an integer.
1066 {0} cannot be empty.
1067 Illegal parameter {0}.
1068 Export error.
1069 The price is not reasonable.
1070 Empty data, cannot be exported.
1071 Repeated cancellation. Your order has been canceled.
1072 Sell price must be lower than {0} USD.
1073 Position abnormal. Please contact the customer service.
1074 Unable to order currently. Please contact the customer service.
1075 The price is not reasonable, and the margin rate will be less than 0 after placing this order. Please modify the price and place the order.
1076 No orders, please try again later.
1077 In settlement or delivery. Unable to get assets.
1078 In settlement or delivery. Unable to get assets.
1079 In settlement or delivery. Unable to get positions.
1080 In settlement or delivery. Unable to get positions of some contracts.
1081 The number of unfilled trigger order exceeds the limit.
1082 Trigger type parameter error.
1083 Your position is in the process of forced liquidation. Unable to place order temporarily.
1084 Your contract API is disabled, please try again after {0} (GMT+8).
1085 Trigger order failed, please modify the price and place the order again or contact the customer service.
1086 {0} contract is restricted of opening positions on {1}. Please contact customer service.
1087 {0} contract is restricted of closing positions on {1}. Please contact customer service.
1088 {0} contract is restricted of withdraw order on {1}. Please contact customer service.
1089 {0} contract is restricted of transfer. Please contact customer service.
1090 Margin rate is lower than 0. Order can’t be placed.
1091 Equity is less than 0. Order can’t be placed.
1092 The Flash Closing Order takes the {0}th price at the order book. After placing an order, the account equity will be less than 0. Please manually enter the price or place an order with the counterparty price.
1093 The Flash Closing Order takes the {0}th price at the order book. The margin rate will be less than 0 after placing an order. Please manually enter the price or place an order with the counterparty price.
1094 The leverage cannot be empty, please switch the leverage or contact customer service.
1095 Non-trading state, unable to switch the leverage temporarily.
1100 Unable to open a position currently. Please contact the customer service.
1101 Unable to close a position currently. Please contact the customer service.
1102 Unable to transfer in currently. Please contact customer service.
1103 Unable to transfer out currently. Please contact customer service.
1104 Trading is prohibited due to contracts trading constraints.
1105 Only Close is available due to contracts trading constraints.
1106 Abnormal contracts status. Can’t transfer.
1108 Abnormal service. Please try again later.
1109 Sub-account doesn't own the permissions to open positions. Please contact customer service.
1110 Sub-account doesn't own the permissions to close positions. Please contact customer service.
1111 Sub-account doesn't own the permissions to transfer in. Please contact customer service.
1112 Sub-account doesn't own the permissions to transfer out. Please contact customer service.
1113 The sub-account does not have transaction permissions. Please login main account to authorize.
1114 The sub-account does not have transfer permissions. Please login main account to authorize.
1115 You have no access permissions of this sub-account.
1200 Login error. Please try again.
1220 You don’t have access permission as you have not opened contracts trading.
1221 The total balances of Exchange Account can't meet the requirements for opening contracts.
1222 The days of opening account can't meet the requirements for opening contracts.
1223 The VIP level can't meet the requirements for opening contracts.
1224 Your country/region can't meet the requirements for opening contracts.
1225 Failed to open contracts.
1226 Repeated account.
1227 Huobi Contract does not support sub-accounts. Please log out sub-account and log in again with primary account.
1228 Account has not opened, cannot agree to agreement.
1229 Cannot agree twice.
1230 You haven't finished the risk verification.
1231 You haven't finished the ID Verification.
1232 The format/size of the image you uploaded does not meet the requirements. Please re-upload.
1233 High leverage is not enabled (Please sign in the APP or web with your main account to agree to the High-Leverage Agreement).
1234 {0} contract opening orders cannot exceed {1} .
1235 {0} contract closing orders cannot exceed {1}.
1250 Unable to get the HT_token.
1251 Unable to get BTC assets. Please try again later.
1252 Unable to get currency account assets. Please try again later.
1253 Error in signature verification.
1254 The sub-account has no permission to open futures, please go to the web side to log in the main account and open.
1300 Transfer failed.
1301 Insufficient amount available.
1302 Transfer failed.
1303 The single transfer-out amount must be no less than {0}{1}.
1304 The single transfer-out amount must be no more than {0}{1}.
1305 The single transfer-in amount must be no less than {0}{1}.
1306 The single transfer-in amount must be no more than {0}{1}.
1307 Your accumulative transfer-out amount is over the daily maximum, {0}{1}. You can't transfer out for the time being.
1308 Your accumulative transfer-in amount is over the daily maximum, {0}{1}. You can't transfer in for the time being.
1309 Your accumulative net transfer-out amount is over the daily maximum, {0}{1}. You can't transfer out for the time being.
1310 Your accumulative net transfer-in amount is over the daily maximum, {0}{1}. You can't transfer in for the time being.
1311 The platform's accumulative transfer-out amount is over the daily maximum. You can't transfer out for the time being.
1312 The platform's accumulative transfer-in amount is over the daily maximum. You can't transfer in for the time being.
1313 The platform's accumulative net transfer-out amount is over the daily maximum. You can't transfer out for the time being.
1314 The platform's accumulative net transfer-in amount is over the daily maximum. You can't transfer in for the time being.
1315 Wrong transfer type.
1316 Failed to freeze the transfer.
1317 Failed to unfreeze the transfer.
1318 Failed to confirm the transfer.
1319 Failed to acquire the available transfer amount.
1320 The contract status is abnormal. Transfer is unavailable temporarily.
1321 Transfer failed. Please try again later or contact customer service.
1322 Invalid amount. Must be more than 0.
1323 Abnormal service, transfer failed. Please try again later.
1325 Failed to set trading unit.
1326 Failed to obtain trading units.
1327 No transfer permission, transfer failed, please contact customer service.
1328 No transfer permission, transfer failed, please contact customer service.
1329 No transfer permission, transfer failed, please contact customer service.
1330 No transfer permission, transfer failed, please contact customer service.
1331 Exceeds limit of transfer accuracy (8 digits). Please modify it.
1332 The contract doesn't exist.
1333 Failed to open the Maker&Taker agreement.
1334 Failed to check the Maker&Taker agreement.
1335 Failed to check the second confirmation setting of Maker&Taker.
1336 Failed to update the second confirmation setting of Maker&Taker.
1337 Failed to check the settings of Maker&Taker.
1338 Failed to update the settings of Maker&Taker.
1339 Nickname contains illegal words, please modify it.
1340 Nickname has been used, please modify it.
1341 The enrollment has ended.
1342 You cannot set nickname for sub-account.
12001 Invalid submission time.
12002 Incorrect signature version.
12003 Incorrect signature method.
12004 Private key is expired.
12005 Incorrect IP address.
12006 The submission time can't be empty.
12007 Incorrect public key.
12008 Verification failed.
12009 The user is locked or doesn't exist.

API Best Practice

1. Query contract history orders interface: /api/v1/contract_hisorders

2. Query contract match results interface: /api/v1/contract_matchresults

3. Query contract financial record interface: /api/v1/contract_financial_record

4. Query contract order detail interface: api/v1/contract_order_detail

5. Query contract trigger order history orders interface:

6. WebSocket subscription to Market Depth data:

{

"sub": "market.BTC_CQ.depth.step6",

"id": "id5"

}

{

"sub": "market.BTC_CQ.depth.size_20.high_freq",

"data_type":"incremental",

"id": "id1"

}

7. Place order interface (URL: api/v1/contract_order) and place a batch of orders interface (URL:api/v1/contract_batchorder):

Code Demo

REST

Websocket

Contract sdk

Asynchronous Library

Future API FAQ

Access and Authentication

Q1: Is the API Key for future and spot the same ?

Yes. The future API key and spot API key are same. You can create API using the following link. click here

Q2: Why are APIs disconnected or timeout?

  1. The network connection is unstable if the server locates in China mainland,it is suggested to invoke APIS from a server located in 1c area of AWS Tokyo.

  2. You can use api.btcgateway.pro to debug for domestic network.

Q3: Why is the websocket often disconnected?

It seems that most of the abnormal websocket issues (such as disconnect, websocket close )(websocket: close 1006 (abnormal closure))are caused by different network environment. The following measures can effectively reduce websocket issues.

It would be better if the server is located in 1c area of AWS Tokyo with url api.hbdm.vn and implement websocket re-connection mechanism. Both market heartbeat and order heartbeat should response with Pong with different format, following Websocket market heartbeat and account heartbeat requirement.here

Q4: What is the difference between api.hbdm.com and api.hbdm.vn?

The api.hbdm.vn uses AWS's CDN service. it should be more stable and faster for AWS users. The api.hbdm.com uses Cloudflare's CDN service.

Q5: What is the colocation service ? which attention points should we know ?

Actually ,colo corresponds to a vpc node, which directly connects to private network of huobi's future, so it will reduce the latency between the client and the Huobi future server (bypassing the CDN)

huobi future and huobi swap have the same colo, so the domain name connecting the swap api and the future api are the same.

Note : Colo needs to use api.hbdm.com for signature(authentication) to avoid getting 403 error: Verification failure.

Q6: Why does signature verification return failure (403: Verification failure) ?

The signature process of future is similar to huobi Spot . In addition to the following precautions,please refer to the swap or spot demo to verify whether the signature is successful. Please check your own signature code after demo verification is successful. The coin margined swap code demo is here. The future code demo is here.The option code demo is here. The USDT Margined Swap code demo is here.

  1. Check if the API key is valid and copied correctly.
  2. Check if the IP is in whitelist
  3. Check if th timestamp is UTC time
  4. Check if parameters are sorted alphabetically
  5. Check if the encoding is UTF-8
  6. Check if the signature has base64 encoding
  7. Any method with parameters for GET requests should be signed.
  8. Any method with parameters for POST requests don't need to be signed.
  9. Check if whether the signature is URI encoded and Hexadecimal characters must be capitalized, such as ":" should be encoded as "%3A", and the space should be encoded as "%20"
  10. The authorization of websocket is similar to the authorization of restful interface.Pls note that the json body of the websocket authorization shouldn't be URL encoded.

Q7: Is the ratelimit of public market based on IP ? Is the ratelimit of interface with private key based on UID?

Yes. The ratelimit of interface with private key is based on the UID, not the API key. The master and sub accounts are separately ratelimited and don't affect each other.

Q8: Is there any recommendation for third-party framework which integrates Huobi future?

There is an open source asynchronous quantization framework which integrates Huobi future and Huobi swap: here. If you have any quetsions, please open a ticket in github issues.

Market and Websocket

Q1: How often are the snapshot orderbook subscription and incremental orderbook subscription pushed?

The snapshot orderbook subscription(market.$symbol.depth.$type) is checked once every 100MS.If there is an update,it will be pushed. It will be pushed at least 1 second.The incremental orderbook subscription is checked once every 30MS.If there is an update,it will be pushed.If there is no update, it will not be pushed.

Q2: How often is the market trade subscription pushed?

The market trade subscription will be pushed when there is a transaction.

Q3: Are there historical Kline data or historical market trade data?

Historical Kline data can be obtained through the API interface:/market/history/kline.Only the from and to parameters need to be filled in, and the size parameter is not needed.At most, only two consecutive years of data can be obtained.

The historical market trade data is currently not available, you can store it locally by subscribing to market trade: market.$symbol.trade.detail.

Q4: How to get MACD and other technical indicators on Kline?

The API does not have interfaces to get technical indicators such as MACD. You can refer to TradingView and other websites to calculate them.

Q5: What is the definition of timestamp in the document?

The timestamp in the document refers to the total number of seconds or total milliseconds from Greenwich Mean Time, January 1, 1970, 00:00:00 (Beijing Time, January 1, 1970, 08:00:00) to the present.

Q6: What is the definition of the 150 level and 20 level of MBP?

The Subscription of MBP data: market.$symbol.depth.$type.150 price level means the current bids and asks splited into 150 level by price.20 price level means the current bids and asks splited into 20 level by price.

Q7: What is the meaning of merged depth when subscribing MBP data?

The subscrpition of MBP data:market.$symbol.depth.$type：

step1 and step7 are merged by 5 decimal places.bids down,asks up. step2 and step8 are merged by 4 decimal places.bids down,asks up. step3 and step9 are merged by 3 decimal places.bids down,asks up. step4 and step10 are merged by 2 decimal places.bids down,asks up. step5 and step11 are merged by 1 decimal places.bids down,asks up. step12 and step14 are combined by single digit.bids down,asks up. step13 and step15 are combined by tens.bids down,asks up.

Example:

step4(0.01):

bids price: 100.123, 100.245. The merged bids price are 100.12, 100.24.

asks price: 100.123, 100.245 The merged asks price are 100.13, 100.25.

("Down" and "Up" are rounded up or down, if the price is down, the asks price is not rounded down, and the bids price is rounded up.)

150 price level: step0 to step5, step14, step15；

20 price level: step6 to step13;

More examples：

step1(0.00001):

price: 1.123456 The merged bid price is 1.12345. The merged ask price is 1.12346.

step7(0.00001):

price: 1.123456 The merged bid price is 1.12345. The merged ask price is 1.12346.

step6(0.000001)

price: 1.123456 The merged bid price is 1.123456. The merged ask price is 1.123456.

step11(0.1):

price: 1.123456 The merged bid price is 1.1. The merged ask price is 1.1.

Q8:Does websocket's position channel push full data or incrementall data each time?

Subscription of position event: "positions.btc".The latest position is pushed,including the volumes, available volumes, frozen volumes.If there is no update,it will not be pushed.

Q9: Does websocket's position channel push data when the unrealized profit is updated?

Subscription of position event: "positions.btc".It will not be pushed if only unrealized profit is updated. It will be pushed only when position event is updated.

Q10: What is the difference between market detail and trade detail in WS?

Market Detail(market.$symbol.detail) is the merged market data. It will be checked every 0.5s, pushed once trade event udpates,including the OHLCV data,etc.Trade Detail(market.$symbol.trade.detail) is pushed once trade event updates,including trade price, trade volume, trade direction,etc.

Q11: What is the meaning of the two ts pushed by subscription of incremental MBP ?

Subscription of incremental MBP：market.$symbol.depth.size_${size}.high_freq，The outer ts is the timestamp when the market server sends the data.The inner ts is the timestamp when the orderbook is checked.

Q12: What is the difference between websocket subscription of MBP and incremental MBP? How often is the incremental MBP pushed?

market.$symbol.depth.$type is snapshot MBP data，market.$symbol.depth.size_${size}.high_freq is incremental MBP data.Snapshot MBP data is checked every 100ms,pushed at least every 1s.Incremental MBP data is checked every 30ms.It will not be pushed,if MBP has no update.

Q13: How to maintain local MBP data subscribing incremental MBP:market.$symbol.depth.size_${size}.high_freq?

Snapshot MBP data will be pushed for the first time, and the incremental MBP data will be pushed afterwards.

(1) Compare the incremental price with the previous full MBP data, and replace the order amount with the same price;

(2) If the price is not in the local MBP data,add the price to the local MBP data;

(3) If a price level is gone, data such as [8100, 0] will be pushed.You have to remove the same price of local MBP data;

(4) For the same websocket connection, the incremental data version is incremented; if the version is not incremented, you need to re-subscribe and re-maintain the local full MBP data;

Q14: Will the quarter contract of the delivery contract be converted to the next week contract, will it be notified or changged by WS?

If a quarterly contract such as BTC_CQ is converted to the next week contract BTC_NW, WS will not automatically notify you, you need to change the subscription to BTC_NW.

Order and Trade

Q1: What is the future settlement cycle? Which interface can be used to check the status when the future is settled?

一、Orders can't be placed or cancelled during settlement period, error code "1056" will be returned if users place or cancel orders. You are recommended to request contract information every few seconds during settlement period: api/v1/contract_contract_info. It's in settlement time if there is any number of 5, 6, 7, 8 included in the returned status code of contract_status, while it indicates that settlement completed and users could place and cancel orders as usual if the returned status code is 1.

二、 We warmly remind you that Huobi Futures is settled at 16:00 on each Friday (GMT+8). When querying fund or position information during the settlement period, error codes will be returned.

Error codes and their meaning are as following:

Error code "1077" indicates that "the fund query of current perpetual swap trading pair failed during the settlement"; Error code "1078" indicates that "the fund query of part of perpetual swap trading pairs failed during the settlement"; Error code "1079" indicates that "the position query of current perpetual swap trading pair failed during the settlement"; Error code "1080" indicates that "the position query of part of perpetual swap trading pairs failed during the settlement"; You are recommended to read the status code from the returned message. If the above four types of status code appear, the returned data is not accurate and couldn't be used as reference.

Q2: What's the reason for 1004 error code?

We notice that the system is sometimes overloaded when the market suddenly turns to be highly volatile. If the system is busy recently or the following prompts appear:

{“status”: “error”, “err_code”: 1004, “err_msg”: “System busy. Please try again later.”, “ts”:}

please be patient, and do not place or cancel order repeatedly during the process to avoid repeated orders and additional pressure on system performance. In the meanwhile, it is recommended to place and cancel orders through Web and APP.

Q3: The same order ID and match ID can have multiple trades. for example: if a user take a large amount of maker orders, there will be multiple corresponding trades . How to identify these different trades ?

The field ID returned by the information interface api/v1/contract_order_detail is a globally unique transaction identifier. if a maker order is matched multiple times, a trade will be pushed once there is a transaction matched.

Q4: What is the delay for the round trip of huobi future?

At present,it normally takes about 30-50ms from placing the order to getting the status of the order.

Q5: Why does the API return connection reset or Max retris or Timeout error?

Most of the network connectivity problems ,(such as Connection reset or network timeout ) are caused by network instability , you can use the server in AWS Tokyo C area with api.hbdm.vn , which can effectively reduce network timeout errors.

Q6: How to check the order status without order_id not returned?

If the order_id couldn't be returned due to network problems, you can query the status of the order by adding the custom order number(client_order_id ).

Q7: What to do if it's diconnected after the websocket subscription of account, order and positions for a while?

When subscribing private accounts, orders and positions, the heartbeat should also be maintained regularly ,which is different from the market heartbeat format . Please refer to the "websocket Heartbeat and Authentication Interface" . if the it is disconnected ,please try to reconnect.

Q8. What is the difference between order status 1 and 2 ? what is the status 3 ?

Status 1 is the preparation for submission. status 2 is the sequential submission of internal process, which can be considered that it has been accepted by the system. Status 3 indicated that the order has been already submitted to market.

Q9. Is there an interface to get the total assets in BTC of my account ?

No.

Q10. Why is the order filled after the order is withdrawed successfully by placing API cancellation ?

The success return of order cancellation or placement only represents that the command is excuted successfully and doesn't mean that the order has been cancelled . You can check the order status through the interface api/v1/contract_order_info.

Q11. How long does it generally take for an API from withdrawing to cancelling successfully ?

The order cancellation command generally takes several tens of ms. The actual status of order cancellation can be obtained by invoking the interface: api/v1/contract_order_info.

Error Codes

Q1: What is the reason for 1030 error code?

If you encounter errors such as {"status":"error","err_code":1030,"err_msg":"Abnormal service. Please try again later.","ts":1588093883199},indicating that your input request parameter is not correct, please print your request body and complete URL parameters, and please check the corresponding API document interface one by one.The common example is that the volume must be an integer, and the client_order_id must be of type uint32 rather than type uint64.

Q2: What is the reason for 1048 error code?

If you encounter errors such as {'index': 1, 'err_code': 1048, 'err_msg': 'Insufficient close amount available.'}, indicating that your available position is not enough.You need to query the api api/v1/contract_position_info to get your available position.

Q3: What is the reason for 1032 error code?

1032 means that your request exceeds the ratelimit. The coin margined swap, future, option swap and USDT margined swap limit the rate separately. Please check the ratelimit in the api ratelimit instructions, and you can print the current ratelimit in the header of the API response to check whether the ratelimit is exceeded. It is recommended to increase the request interval delay to avoid exceeding the ratelimit.

How to solve problems more effectively?

When you report an API error, you need to attach your request URL, the original complete body of the request and the complete request URL parameters, and the original complete log of the server's response. If it is a websocket subscription, you need to provide the address of the subscription, the topic of the subscription, and the original complete log pushed by the server.

If it is an order-related issue, use the API order query interface api/v1/contract_order_info to keep the complete log returned and provide your UID and order number.

Future Market Data interface

Get Contract Info

Example

curl "https://api.hbdm.com/api/v1/contract_contract_info"

Request Parameter

Parameter Name Type Mandatory Description
symbol string false Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC","ETH"...
contract_type string false "this_week","next_week", "quarter" "next_quarter"
contract_code string false BTC180914

Note：

Note：If there is a number in the Contract Code row，inquiry with Contract_Code. If there is no number，inquiry by Symbol + Contract Type. One of the query conditions must be chosen.

Response


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC201225",
            "contract_type": "quarter",
            "contract_size": 100,
            "price_tick": 0.01,
            "delivery_date": "20201225",
            "create_date": "20200605",
            "contract_status": 1
        }
    ],
    "ts": 1604296501822
}

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" , "error"
<list>(Attribute Name: data)
symbol true string Product Code "BTC","ETH"...
contract_code true string Contract Code "BTC180914" ...
contract_type true string Contract Type "this_week","next_week", "quarter" ,"next_quarter"
contract_size true decimal Contract Value (USD of one contract) 10, 100...
price_tick true decimal Minimum Variation of Contract Price 0.001, 0.01...
delivery_date true string Contract Delivery Date eg "20180720"
create_date true string Contract Listing Date eg "20180706"
contract_status true int Contract Status 0: Delisting,1: Listing,2: Pending Listing,3: Suspension,4: Suspending of Listing,5: In Settlement,6: Delivering,7: Settlement Completed,8: Delivered,9: Suspended Listing
</list>
ts true long Time of Respond Generation，Unit：Millisecond

Get Contract Index Price Information

Example

curl "https://api.hbdm.com/api/v1/contract_index?symbol=BTC"

Request Parameter

Parameter Name Parameter Type Mandatory Desc
symbol string false Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC","ETH"...

Response


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "index_price": 13707.26,
            "index_ts": 1604296614010
        }
    ],
    "ts": 1604296620746
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<list>(Attribute Name: data)
symbol true string symbol "BTC","ETH"...
index_price true decimal Index Price
index_ts true long Response generation time point, unit: millisecond
</list>
ts true long Time of Respond Generation，Unit：Millisecond

Get Contract Price Limitation

Example

curl "https://api.hbdm.com/api/v1/contract_price_limit?symbol=BTC&contract_type=this_week"

Request Parameter

Parameter Name Parameter Type Mandatory Desc
symbol string false Case-Insenstive.Both uppercase and lowercase are supported.e.g."BTC","ETH"...
contract_type string false Contract Type ("this_week","next_week","quarter", "next_quarter")
contract_code string false BTC180914 ...

Note ：

If there is a number in the Contract Code row，inquiry with Contract_Code. If there is no number，inquiry by Symbol + Contract Type. One of the query conditions must be chosen.

Response


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC201225",
            "contract_type": "quarter",
            "high_limit": 14724.88,
            "low_limit": 13057.92
        }
    ],
    "ts": 1604296680648
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" ,"error"
<list>(Attribute Name: data)
symbol true string Variety code "BTC","ETH" ...
high_limit true decimal Highest Buying Price
low_limit true decimal Lowest Selling Price
contract_code true string Contract Code eg "BTC180914" ...
contract_type true string Contract Type "this_week","next_week","quarter" ,"next_quarter"
<list>
ts true long Time of Respond Generation, Unit: Millisecond

Get Contract Open Interest Information

Example

curl "https://api.hbdm.com/api/v1/contract_open_interest?symbol=BTC&contract_type=this_week"

Request Parameter

Parameter Name Parameter Type Mandatory Desc
symbol string false Case-Insenstive.Both uppercase and lowercase are supported.e.g."BTC","ETH"...
contract_type string false Contract Type ("this_week","next_week","quarter")
contract_code string false BTC180914

Response:


{
    "status": "ok",
    "data": [
        {
            "volume": 3057834,
            "amount": 22013.565930537597871378,
            "symbol": "BTC",
            "contract_type": "quarter",
            "contract_code": "BTC201225"
        }
    ],
    "ts": 1604296751272
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<list>(Attribute Name: data)
symbol true string Variety code "BTC", "ETH" ...
contract_type true string Contract Type "this_week","next_week","quarter", "next_quarter"
volume true decimal Position quantity(volume)
amount true decimal Position quantity(Currency)
contract_code true string Contract Code eg "BTC180914" ...
</list>
ts true long Time of Respond Generation, Unit: Millisecond

Get the estimated delivery price

Example

curl "https://api.hbdm.com/api/v1/contract_delivery_price?symbol=BTC"

Request Parameter

Parameter Name Parameter Type Mandatory Desc
symbol string true Case-Insenstive.Both uppercase and lowercase are supported.e.g."BTC","ETH"...

Response:


{
    "status": "ok",
    "data": {
        "delivery_price": 13212.3643864774624373956594
    },
    "ts": 1604296995036
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<list>(Attribute Name: data)
delivery_price true decimal estimated delivery price
</list>
ts true long Time of Respond Generation, Unit: Millisecond

Get Market Depth

Example

curl "https://api.hbdm.com/market/depth?symbol=BTC_CQ&type=step5"

Request Parameter

Parameter Name Parameter Type Mandatory Desc
symbol string true Case-Insenstive.Both uppercase and lowercase are supported..e.g. "BTC_CW" represents BTC “This Week”，"BTC_NW" represents BTC “Next Week”，"BTC_CQ" represents BTC “Quarter”."BTC_NQ" represents BTC “Next Quarter”. Contract code is supported to query data. e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)
type string true Get depth data within step 150, use step0, step1, step2, step3, step4, step5, step14, step15（merged depth data 0-5,14-15）；when step is 0，depth data will not be merged; Get depth data within step 20, use step6, step7, step8, step9, step10, step11, step12, step13(merged depth data 7-13); when step is 6, depth data will not be merged.

tick illustration:

"tick": {
    "id": Message id,
    "ts": Time of Message Generation, unit: millisecond,
    "bids": Buying, [price(hanging unit price), vol(this price represent single contract)], According to the descending order of Price,
    "asks": Selling, [price(hanging unit Price), vol(this price represent single contract)], According to the ascending order of Price,
    "ch": Data channel,
    "mrid": Order ID,
    "ts": Time of Respond Generation,
    "version": version ID 
}

Response:


{
    "ch":"market.BTC_NQ.depth.step6",
    "status":"ok",
    "tick":{
        "asks":[
            [
                14100.87,
                163
            ],
            [
                14100.88,
                20
            ]
        ],
        "bids":[
            [
                14098.09,
                53
            ],
            [
                14098.08,
                75
            ]
        ],
        "ch":"market.BTC_NQ.depth.step6",
        "id":1604297395,
        "mrid":113765352864,
        "ts":1604297395012,
        "version":1604297395
    },
    "ts":1604297395085
}

Returning Parameter

Parameter Name Mandatory Data Type Desc Value Range
ch true string Data belonged channel，Format： market.period
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation，Unit：Millisecond
<tick>
mrid true long Order ID
id true long tick ID
asks true array Sell,[price(Ask price), vol(Ask orders (cont.) )], price in ascending sequence
bids true array Buy,[price(Bid price), vol(Bid orders(Cont.))], Price in descending sequence
ts true long Time of Respond Generation, Unit: Millisecond
version true long version ID
ch true string Data channel, Format： market.period
</tick>

Get Kline Data

Example

curl "https://api.hbdm.com/market/history/kline?period=1min&size=200&symbol=BTC_CQ"

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
symbol true string Contract Name Case-Insenstive.Both uppercase and lowercase are supported..e.g. "BTC_CW" represents BTC “This Week”，"BTC_NW" represents BTC “Next Week”，"BTC_CQ" represents BTC “Quarter”."BTC_NQ" represents BTC “Next Quarter”. Contract code is supported to query data. e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)
period true string Kline Type 1min, 5min, 15min, 30min, 60min, 1hour,4hour,1day, 1mon
size false int Acquisition Quantity 150 [1,2000]
from false long start timestamp seconds.
to false long end timestamp seconds

Note

Data Illustration：

"data": [
  {
        "id": Kline id,
        "vol": Transaction Volume(amount),
        "count": transaction count
        "open": opening Price
        "close": Closing Price, when the Kline is the latest one，it means the latest price
        "low": Lowest price
        "high": highest price
        "amount": transaction volume(currency), sum(every transaction volume(amount)*every contract value/transaction price for this contract)
   }
]

Response:


{
    "ch": "market.BTC_NQ.kline.5min",
    "data": [
        {
            "amount": 4.30994018951037,
            "close": 14103.1,
            "count": 39,
            "high": 14110,
            "id": 1604297400,
            "low": 14098.29,
            "open": 14098.75,
            "vol": 608
        },
        {
            "amount": 0.19851299586596685,
            "close": 14104.87,
            "count": 1,
            "high": 14104.87,
            "id": 1604297700,
            "low": 14104.87,
            "open": 14104.87,
            "vol": 28
        }
    ],
    "status": "ok",
    "ts": 1604297729928
}

Returning Parameter

Parameter Name Mandatory Data Type Desc Value Range
ch true string Data belonged channel，Format： market.period
data true object Kline Data
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond

data parameters

parameter name type desc
id int kline id,the same as kline timestamp, kline start timestamp
vol decimal volume.
count decimal count.
open decimal open price
close decimal close price
low decimal lowest price
high decimal highest price
amount decimal amount based on coins.

Get Market Data Overview

Example

curl "https://api.hbdm.com/market/detail/merged?symbol=BTC_CQ"

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
symbol true string Contract Name Case-Insenstive.Both uppercase and lowercase are supported..e.g. "BTC_CW" represents BTC “This Week”，"BTC_NW" represents BTC “Next Week”，"BTC_CQ" represents BTC “Quarter”."BTC_NQ" represents BTC “Next Quarter”. Contract code is supported to query data. e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)

tick Illustration:

"tick": {
    "id": Kline id,
    "vol": transaction volume（contract）,
    "count": transaction count
    "open": opening price,
    "close": Closing Price, when the Kline is the latest one，it means the latest price
    "low": Lowest price
    "high": highest price
    "amount": transaction volume(currency), sum(every transaction volume(amount)*every contract value/transaction price for this contract)
    "bid": [price of buying one (amount)],
    "ask": [price of selling one (amount)]

  }

Response:


{
    "ch": "market.BTC_NQ.detail.merged",
    "status": "ok",
    "tick": {
        "amount": "4478.2911316482577028620799060719867257944",
        "ask": [
            14114.01,
            177
        ],
        "bid": [
            14112.71,
            28
        ],
        "close": "14114",
        "count": 18805,
        "high": "14299.99",
        "id": 1604298319,
        "low": "14028.78",
        "open": "14229.47",
        "ts": 1604298319019,
        "vol": "633708"
    },
    "ts": 1604298319019
}

Returning Parameter

Parameter Name Mandatory Data Type Desc Value Range
ch true string Data belonged channel，format： market.$contract_code.detail.merged
status true string Request Processing Result "ok" , "error"
tick true object Kline Data
ts true long Time of Respond Generation, Unit: Millisecond
<tick> kline data (Start at 00:00(UTC+8) of the day)
id true long kline id,the same as kline timestamp
vol true string Trade Volume(Cont.)
count true int Order Quantity
open true string Open Price
close true string Clos Price, the price in the last kline is the latest order price
low true string Low Price
high true string High Price
amount true string Trade Amount(Coin), trade amount(coin)=sum(order quantity of a single order * face value of the coin/order price)
ask true object Sell,[price(Ask price), vol(Ask orders (cont.) )], price in ascending sequence
bid true object Buy,[price(Bid price), vol(Bid orders(Cont.))], Price in descending sequence
</tick>

Query The Last Trade of a Contract

Example

curl "https://api.hbdm.com/market/trade?symbol=BTC_CQ"

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
symbol true string Contract Name Case-Insenstive.Both uppercase and lowercase are supported.. e.g. "BTC_CW" represents BTC “This Week”，"BTC_NW" represents BTC “Next Week”，"BTC_CQ" represents BTC “Quarter”."BTC_NQ" represents BTC “Next Quarter”. Contract code is supported to query data. e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)

Tick Illustration：

"tick": {
  "id": Unique Order Id(symbol level),
  "ts": Latest Transaction time,
  "data": [
    {
      "id": Unique Transaction Id(symbol level),
      "price": Transaction price,
      "amount": transaction amount,
      "direction": Active transaction direction,
      "ts": transaction time

    }
  ]
}

Response:


{
    "ch": "market.BTC_NQ.trade.detail",
    "status": "ok",
    "tick": {
        "data": [
            {
                "amount": "4",
                "ts": 1604298443540,
                "id": 1137660004780000,
                "price": "14117.98",
                "direction": "sell"
            }
        ],
        "id": 1604298454352,
        "ts": 1604298454352
    },
    "ts": 1604298454352
}

Returning Parameter

Parameter Name Mandatory Type Desc Default Value Range
ch true string Data belonged channel，Format： market.$contract_code.trade.detail
status true string "ok","error"
ts true long Sending time
<dict> (attrs: tick)
id true long Unique Order Id(symbol level)
ts true long Latest Creation Time
<list> (attrs: data)
id true long Unique Transaction Id(symbol level)
price true decimal Price
amount true decimal Quantity(Cont.)
direction true string Order Direction
ts true long Order Creation Time
</list>
</dict>

Query a Batch of Trade Records of a Contract

Example

curl "https://api.hbdm.com/market/history/trade?symbol=BTC_CQ&size=100"

Request Parameter

Parameter Name Mandatory Data Type Desc Default Value Range
symbol true string Contract Name Case-Insenstive.Both uppercase and lowercase are supported.. e.g. "BTC_CW" represents BTC “This Week”，"BTC_NW" represents BTC “Next Week”，"BTC_CQ" represents BTC “Quarter”."BTC_NQ" represents BTC “Next Quarter”. Contract code is supported to query data. e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)
size true int Number of Trading Records Acquisition 1 [1, 2000]

data Illustration：

"data": {
  "id": Unique Order Id(symbol level),
  "ts": Latest transaction time,
  "data": [
    {
      "id": Unique Transaction Id(symbol level),
      "price": transaction price,
      "amount": transaction (amount),
      "direction": active transaction direction
      "ts": transaction time
      }
}

Response:


{
    "ch": "market.BTC_NQ.trade.detail",
    "data": [
        {
            "data": [
                {
                    "amount": 12,
                    "direction": "buy",
                    "id": 1137660361550000,
                    "price": 14119.84,
                    "ts": 1604298530920
                }
            ],
            "id": 113766036155,
            "ts": 1604298530920
        },
        {
            "data": [
                {
                    "amount": 4,
                    "direction": "sell",
                    "id": 1137660376740000,
                    "price": 14123.14,
                    "ts": 1604298531331
                }
            ],
            "id": 113766037674,
            "ts": 1604298531331
        }
    ],
    "status": "ok",
    "ts": 1604298553734
}

Returning Parameter

Parameter Name Mandatory Type Desc Default Value Range
ch true string Data belonged channel，Format： market.$contract_code.trade.detail
status true string "ok","error"
ts true long Sending time
<dict> (attrs: tick)
id true long Unique Order Id(symbol level)
ts true long Latest Creation Time
<list> (attrs: data)
id true long Unique Transaction Id(symbol level)
price true decimal Price
amount true decimal Quantity(Cont.)
direction true string Order Direction
ts true long Order Creation Time
</list>
</dict>

Query information on contract insurance fund balance and estimated clawback rate

curl "https://api.hbdm.com/api/v1/contract_risk_info"

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol false string Contract Type Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"...，If no data detected, system will return to all contracts by default.

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "insurance_fund": 1909.852579486750035041,
            "estimated_clawback": 0
        }
    ],
    "ts": 1604298633195
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: milesecond
<data>
symbol true string Contract Code "BTC","ETH"...
insurance_fund true decimal Insurance Fund Balance
estimated_clawback true decimal Estimated Clawback Rate
</data>

Query history records of insurance fund balance

curl "https://api.hbdm.com/api/v1/contract_insurance_fund?symbol=BTC"

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol true string Contract Code Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...

Response:


{
    "status":"ok",
    "data":{
        "symbol":"BTC",
        "tick":[
            {
                "insurance_fund":1909.852579486750035041,
                "ts":1604217600000
            },
            {
                "insurance_fund":1907.646552903264189201,
                "ts":1604131200000
            }
        ]
    },
    "ts":1604298695848
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Milesecond
<data> Dictionary Data
symbol true string Contract Code "BTC","ETH"...
<tick>
insurance_fund true decimal Insurance Fund Balance
ts true long Timestamp, Unit: Milesecond
</tick>
</data>

Query information on Tiered Adjustment Factor

curl "https://api.hbdm.com/api/v1/contract_adjustfactor"

Request Parameter

Parameter Name Mandatory Type Desc Data Value
symbol false string Contract Code Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...，If no data detected, system will return to all contracts by default.

Response:


{
    "status":"ok",
    "data":[
        {
            "symbol":"BTC",
            "list":[
                {
                    "lever_rate":125,
                    "ladders":[
                        {
                            "ladder":0,
                            "min_size":0,
                            "max_size":1999,
                            "adjust_factor":0.65
                        },
                        {
                            "ladder":1,
                            "min_size":2000,
                            "max_size":14999,
                            "adjust_factor":0.8
                        },
                        {
                            "ladder":2,
                            "min_size":15000,
                            "max_size":null,
                            "adjust_factor":0.85
                        }
                    ]
                }
            ]
        }
    ],
    "ts":1604298785020
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Milesecond
<data>
symbol true string Contract Code "BTC","ETH"...
<list>
lever_rate true decimal Leverage
<ladderDetail>
min_size true decimal Min net position limit
max_size true decimal Max net position limit
ladder true int Tier
adjust_factor true decimal Adjustment Factor
</ladderDetail>
</list>
</data>

Query information on open interest

curl "https://api.hbdm.com/api/v1/contract_his_open_interest?symbol=BTC&contract_type=this_week&period=60min&amount_type=1"

Request Parameter

Parameter Name Mandatory Type Desc Data Range
symbol true string Contract Code Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
contract_type true string Contract Type Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter" Next Quarterly Contract: "next_quarter"
period true string Period Type 1 hour:"60min"，4 hours:"4hour"，12 hours:"12hour"，1 day:"1day"
size false int Request Amount Default：48，Data Range [1,200]
amount_type true int Open interest unit 1:-cont，2:-cryptocurrenty

Response:


{
    "status": "ok",
    "data": {
        "symbol": "BTC",
        "contract_type": "quarter",
        "tick": [
            {
                "volume": "3058980.0000000000000000",
                "amount_type": 1,
                "ts": 1604296800000
            },
            {
                "volume": "3049899.0000000000000000",
                "amount_type": 1,
                "ts": 1604293200000
            }
        ]
    },
    "ts": 1604298943494
}

Returning Parameter

Parameter Name Mandatory Type Desc Data Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Milesecond
<data> Dictionary Data
symbol true string Contract Code "BTC","ETH"...
contract_type true string Contract Type Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter" Next Quarterly Contract: "next_quarter"
<tick>
volume true string Open Interest
amount_type true int Open Interest Unit 1:-cont，2:- cryptocurrency
ts true long Recording Time
</tick>
</data>

Notice

Query information on system status

curl "https://api.hbdm.com/api/v1/contract_api_state"

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol false string symbol Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"... If no data detected, system will return to all symbols by default

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "open": 1,
            "close": 1,
            "cancel": 1,
            "transfer_in": 1,
            "transfer_out": 1,
            "master_transfer_sub": 1,
            "sub_transfer_master": 1
        }
    ],
    "ts": 1604297099976
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: milesecond
<data>
symbol true string symbol "BTC","ETH"...
open true int open order access：when “1”, then access available; when “0”, access unavailable"1"
close true int close order access：when “1”, then access available; when “0”, access unavailable "1"
cancel true int order cancellation access：when “1”, then access available; when “0”, access unavailable "1"
transfer_in true int deposit access：when “1”, then access available; when “0”, access unavailable "1"
transfer_out true int withdraw access： when “1”, then access available; when “0”, access unavailable "1"
master_transfer_sub true int transfer from master to sub account："1" is available，“0” is unavailable
sub_transfer_master true int transfer from sub to master account："1" is available，“0” is unavailable
</data>

Notice

Query Top Trader Sentiment Index Function-Account

curl "https://api.hbdm.com/api/v1/contract_elite_account_ratio?symbol=BTC&period=60min"

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol true string symbol Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
period true string period 5min, 15min, 30min, 60min,4hour,1day

Response:


{
    "status":"ok",
    "data":{
        "list":[
            {
                "buy_ratio":0.52,
                "sell_ratio":0.45,
                "locked_ratio":0.03,
                "ts":1604290200000
            }
        ],
        "symbol":"BTC"
    },
    "ts":1604299070097
}

Returning Parameter

Parameter Name Mandatory Type Desc Vaue Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Milesecond
<data>
symbol true string symbol "BTC","ETH"...
<list>
buy_ratio true decimal net long accounts ratio
sell_ratio true decimal net short accounts ratio
locked_ratio true decimal locked accounts ratio
ts true long Time of Respond Generation
</list>
</data>

Query Top Trader Sentiment Index Function-Position

curl "https://api.hbdm.com/api/v1/contract_elite_position_ratio?symbol=BTC&period=60min"

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol true string symbol Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
period true string period 5min, 15min, 30min, 60min,4hour,1day

Response:


{
    "status":"ok",
    "data":{
        "list":[
            {
                "buy_ratio":0.51,
                "sell_ratio":0.49,
                "ts":1604290500000
            },
            {
                "buy_ratio":0.508,
                "sell_ratio":0.492,
                "ts":1604290800000
            }
        ],
        "symbol":"BTC"
    },
    "ts":1604299402211
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Milesecond
<data>
symbol true string symbol "BTC","ETH"...
<list>
buy_ratio true decimal Net long position ratio
sell_ratio true decimal Net short position ratio
ts true long Time of Respond Generation
</list>
</data>

Query Liquidation Order Information

curl "https://api.hbdm.com/api/v1/contract_liquidation_orders?symbol=BTC&trade_type=0&create_date=7"

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
symbol true string symbol Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
trade_type true int trading types when “0”, request fully filled liquidated orders; when “5’, request liquidated close orders; when “6”, request liquidated open orders
create_date true int date 7，90（ 7 days or 90 days）
page_index false int page, system sets page 1 by default without further instruction
page_size false int system sets page 20 by default without further instruction. Max page size is 50.

Response:


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "contract_code": "BTC201225",
                "symbol": "BTC",
                "direction": "buy",
                "offset": "close",
                "volume": 26,
                "price": 19674.96,
                "created_at": 1606293144641,
                "amount": 0.132147663832607537
            }
        ],
        "total_page": 114,
        "current_page": 1,
        "total_size": 2264
    },
    "ts": 1604299610722
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result
<object>(object name: data)
<list>( object name: orders)
symbol true string symbol
contract_code true string contract code "BTC180914" ...
direction true string "buy":buy"sell": sell
offset true string "open":open "close": close
volume true decimal liquidated volume(cont)
amount true decimal liquidation amount (token)
price true decimal bankruptcy price
created_at true long liquidation time
</list>
total_page true int total page
current_page true int current page
total_size true int total size
</object>
ts true long timestamp

Query historical settlement records of the platform interface

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol true string Token Code "BTC","ETH"...
start_time false long Start time（timestamp，unit: millisecond） Value range: [(Current time minus 90 days), Current time] ，default current time minus 90 days
end_time false long End time（timestamp，unit: millisecond） Value range: (start_time, current time]，default current time
page_index false int Page, default page 1 if not filled
page_size false int Page items, default 20, shall not exceed 50 [1-50]

Response: 

{
    "status": "ok",
    "data": {
        "total_page": 13,
        "current_page": 1,
        "total_size": 13,
        "settlement_record": [
            {
                "symbol": "BTC",
                "settlement_time": 1605859200000,
                "clawback_ratio": 0,
                "list": [
                    {
                        "contract_code": "BTC201120",
                        "settlement_price": 18217.62,
                        "settlement_type": "delivery"
                    },
                    {
                        "contract_code": "BTC201127",
                        "settlement_price": 18292.24,
                        "settlement_type": "settlement"
                    },
                    {
                        "contract_code": "BTC201225",
                        "settlement_price": 18490.42,
                        "settlement_type": "settlement"
                    },
                    {
                        "contract_code": "BTC210326",
                        "settlement_price": 18788.7,
                        "settlement_type": "settlement"
                    }
                ]
            }
        ]
    },
    "ts": 1606295834648
}

Return Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
ts true long Response generation time point, unit: millisecond
<data> true object array
<settlement_record> true object array
symbol true string Token Code
settlement_time true long Settlement Time（timestamp，unit: millisecond）（when the settlement_type is delivery, the time is delivery time; when the settlement_type is settlement, the time is settlement time）
clawback_ratio true decimal Clawback Ratio
<list> true object array
contract_code true string Contract Code "BTC180914" ...
settlement_price true decimal Settlement Price（when the settlement_type is delivery, the price is delivery price; when the settlement_type is settlement, the price is settlement price；）
settlement_type true string Settlement Type “delivery”：Delivery，“settlement”：Settlement
</list>
</settlement_record>
total_page true int Total Pages
current_page true int Current Page
total_size true int Total page items
</data>

Query Index Kline Data

example

curl "https://api.hbdm.com/index/market/history/index?symbol=BTC-USD&period=1min&size=150"

request parameters

Parameter Name Mandatory Type Desc Default Value Range
symbol true string index symbol Case-Insenstive.Both uppercase and lowercase are supported..e.g."BTC-USD","ETH-USD"...
period true string kline type 1min, 5min, 15min, 30min, 60min,4hour,1day, 1mon
size true integer data size 150 [1,2000]

Response Example：


{
    "ch": "market.BTC-USD.index.60min",
    "data": [
        {
            "amount": 0,
            "close": 13703.4175,
            "count": 0,
            "high": 13720.84,
            "id": 1604293200,
            "low": 13658.245,
            "open": 13709.6175,
            "vol": 0
        },
        {
            "amount": 0,
            "close": 13751.6,
            "count": 0,
            "high": 13771.21,
            "id": 1604296800,
            "low": 13693.16,
            "open": 13703.365,
            "vol": 0
        }
    ],
    "status": "ok",
    "ts": 1604299755097
}

response parameters：

Parameter Name Mandatory Type Desc Default Value Range
ch true string data channel eg： market.period
<data> object
id true decimal index kline id,the same as kline timestamp, kline start timestamp
vol true decimal Trade Volume(Cont.) The value is 0
count true decimal Order Quantity The value is 0
open true decimal Opening Index Price
close true decimal Closing Index Price, the price in the last kline is the latest order price
low true decimal Lowest Index Price
high true decimal Highest Index Price
amount true decimal Trade Amount(Coin), The value is 0. )
</data>
status true string process status "ok" , "error"
ts true long timestamp of the response of the server unit：millionseconds

Query Basis Data

example

curl "https://api.hbdm.com/index/market/history/basis?symbol=BTC-USD&period=1min&size=150&basis_price_type=open"

request parameters

Parameter name Mandatory Type Desc Default Value Range
symbol true string symbol name Case-Insenstive.Both uppercase and lowercase are supported..e.g. "BTC_CW" represents BTC “This Week”，"BTC_NW" represents BTC “Next Week”，"BTC_CQ" represents BTC “Quarter”."BTC_NQ" represents BTC “Next Quarter”.
period true string kline period 1min,5min, 15min, 30min, 60min,4hour,1day,1mon
basis_price_type false string use basis price type to calculate the basis data Using open price default open price："open"，close price："close"，highest price："high"，lowest price："low"，avg=（high price +low price）/2："average"
size true integer data size 150 [1,2000]

Response example：


{
    "ch": "market.BTC-USD.basis.5min.open",
    "data": [
        {
            "basis": "-2.1850000000013097",
            "basis_rate": "-0.00015880531885174013",
            "contract_price": "13756.8",
            "id": 1604299500,
            "index_price": "13758.985"
        },
        {
            "basis": "-4.235000000000582",
            "basis_rate": "-0.00030799697602973224",
            "contract_price": "13745.9",
            "id": 1604299800,
            "index_price": "13750.135"
        }
    ],
    "status": "ok",
    "ts": 1604299816352
}

response parameters

parameter name Mandatory Type Desc Value Range
ch true string theme
status true string status
<data> true object
id true long unique id
contract_price true string contract last price
index_price true string index price
basis true string basis=contract_price - index_price
basis_rate true string basis_rate=basis/index_price
</data>
ts true long the timestamp of generation

2000 size at most per request ；

The basis data of Next Quarterly Contract is available after 2020/6/15 14:00:00.

Future Account Interface

Query User’s Account Information

Example

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
symbol false string Variety code Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...if default, return to all types defaulted

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "ADA",
            "margin_balance": 453.151955780787465997,
            "margin_position": 0,
            "margin_frozen": 0,
            "margin_available": 453.151955780787465997,
            "profit_real": 16.35635155751274032,
            "profit_unreal": 0,
            "risk_rate": null,
            "withdraw_available": 436.795604223274725677,
            "liquidation_price": null,
            "lever_rate": 10,
            "adjust_factor": 0.2,
            "margin_static": 453.151955780787465997,
            "is_debit": 0
        }
    ],
    "ts": 1604300060777
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<list>(Attribute Name: data)
symbol true string Variety code "BTC","ETH"...
margin_balance true decimal Account rights
margin_position true decimal Position Margin
margin_frozen true decimal Freeze margin
margin_available true decimal Available margin
profit_real true decimal Realized profit
profit_unreal true decimal Unrealized profit
risk_rate true decimal risk rate
liquidation_price true decimal Estimated liquidation price
withdraw_available true decimal Available withdrawal
lever_rate true decimal Leverage Rate
adjust_factor true decimal Adjustment Factor
margin_static true decimal Static Margin
</list>
ts long long Time of Respond Generation, Unit: Millisecond

Query User’s Position Information

Example

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
symbol false string Variety code Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"...if default, return to all types defaulted

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "ADA",
            "contract_code": "ADA201225",
            "contract_type": "quarter",
            "volume": 1,
            "available": 1,
            "frozen": 0,
            "cost_open": 0.0991,
            "cost_hold": 0.0991,
            "profit_unreal": 0,
            "profit_rate": 0,
            "lever_rate": 10,
            "position_margin": 10.090817356205852674,
            "direction": "sell",
            "profit": 0,
            "last_price": 0.0991
        }
    ],
    "ts": 1604301441639
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<list>(Attribute Name: data)
symbol true string Variety code "BTC","ETH"...
contract_code true string Contract Code "BTC180914" ...
contract_type true string Contract Type "this_week", "next_week", "quarter", "next_quarter"
volume true decimal Position quantity
available true decimal Available position can be closed
frozen true decimal frozen
cost_open true decimal Opening average price
cost_hold true decimal Average price of position
profit_unreal true decimal Unrealized profit and loss
profit_rate true decimal Profit rate
profit true decimal profit
position_margin true decimal Position margin
lever_rate true int Leverage rate
direction true string Transaction direction
last_price true decimal Latest price
</list>
ts true long Time of Respond Generation, Unit: Millisecond

Note

Query assets information of all sub-accounts under the master account

Request Parameters

Parameter name Must fill or not Type Description Default value Value range
symbol false string type code Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"... ,if blank, it will return all contract types by default

Response:


{
    "status": "ok",
    "data": [
        {
            "sub_uid": 123456789,
            "list": [
                {
                    "symbol": "ADA",
                    "margin_balance": 50,
                    "liquidation_price": null,
                    "risk_rate": null
                }
            ]
        }
    ],
    "ts": 1604301647427
}

Return parameters

Parameter name Must fill or not Type Description Value range
status true string the handling result of requests "ok" , "error"
ts true long the create time point of response, unit: ms
<data>
sub_uid true long sub-account UID
<list>
symbol true string type code "BTC","ETH"...
margin_balance true decimal account equity
liquidation_price true decimal estimated liquidation price
risk_rate true decimal margin rate
</list>
</data>

Only return data for activated contract sub-account (i.e. sub-accounts that have gained contract trading permission).

Query a single sub-account's assets information

Request Parameters

Parameter name Must fill or not Type Description Default value Value range
symbol false string type code Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"...，if blank, it will return all contract types by default
sub_uid true long sub-account UID

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "ADA",
            "margin_balance": 50,
            "margin_position": 0,
            "margin_frozen": 0,
            "margin_available": 50,
            "profit_real": 0,
            "profit_unreal": 0,
            "risk_rate": null,
            "withdraw_available": 50,
            "liquidation_price": null,
            "lever_rate": 5,
            "adjust_factor": 0.1,
            "margin_static": 50,
            "is_debit": 0
        }
    ],
    "ts": 1604301730723
}

Return parameters

Parameter name Must fill or not Type Description Value range
status true string the handling result of requests "ok" , "error"
ts true long the create time point of response, unit: ms
<data>
symbol true string type code "BTC","ETH"...when the$symbol value is "*", it will subscribe all contract types
margin_balance true decimal account equity
margin_position true decimal position margin (the margin used by current positions)
margin_frozen true decimal frozen margin
margin_available true decimal available margin
profit_real true decimal realized profits and losses
profit_unreal true decimal unrealized profits and losses
risk_rate true decimal margin rate
liquidation_price true decimal estimated liquidation price
withdraw_available true decimal available transfer amount
lever_rate true decimal leverage ratios
adjust_factor true decimal Adjustment Factor
margin_static true decimal Static Margin
</data>

Only query account information for activated contract sub-account (i.e. sub-accounts that have gained contract trading permission);

No data return for sub-accounts which has logged in hbdm but have not gained trading permission/activated.

Query a single sub-account's position information

Request Parameters

Parameter name Must fill or not Type Description Default value Value range
symbol false string type code Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"...，if blank, it will return all contract types by default
sub_uid true long sub-account UID

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "ADA",
            "contract_code": "ADA201225",
            "contract_type": "quarter",
            "volume": 1,
            "available": 1,
            "frozen": 0,
            "cost_open": 0.0991,
            "cost_hold": 0.0991,
            "profit_unreal": -0.04686106551835051,
            "profit_rate": -0.002321965796434265,
            "lever_rate": 5,
            "position_margin": 20.191006925515375451,
            "direction": "buy",
            "profit": -0.04686106551835051,
            "last_price": 0.099054
        }
    ],
    "ts": 1604302891178
}

Return parameters

Parameter name Must fill or not Type Description Value range
status true string the handling result of requests "ok" , "error"
ts true long the create time point of response, unit: ms
<data>
symbol true string type code "BTC","ETH"...
contract_code true string contract code "BTC180914" ...
contract_type true string contract type Weekly:"this_week", Biweekly:"next_week", Quarterly:"quarter", Next Quarterly Contract: "next_quarter"
volume true decimal open interest
available true decimal available positions to close
frozen true decimal amount of frozen positions
cost_open true decimal average price of open positions
cost_hold true decimal average price of positions
profit_unreal true decimal unrealized profits and losses
profit_rate true decimal profit rate
profit true decimal profits
position_margin true decimal position margin
lever_rate true int leverage ratios
direction true string transaction direction of positions "buy":long "sell":short
last_price true decimal Latest price
</data>

Query account financial records

Request Parameters

Parameter name Must fill or not Type Description Value range
symbol true string contract type code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC","ETH"...
type false string if not fill this parameter, it will query all types 【please use "," to seperate multiple types】 3:close long; 4:close short; 5:fees for open positions-taker; 6:fees for open positions-maker; 7:fees for close positions-taker; 8:fees for close positions-maker; 9:close long for delivery; 10:close short for delivery; 11:delivery fee; 12:close long for liquidation; 13:lose short for liquidation; 14:transfer from spot exchange to contract exchange; 15:tranfer from contract exchange to spot exchange; 16:settle unrealized PnL-long positions; 17:settle unrealized PnL-short positions; 19:clawback; 26:system; 28:activity prize rewards; 29:rebate; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master;
create_date false int any positive integer available. Requesting data beyond 90 will not be supported, otherwise, system will return trigger history data within the last 90 days by default.
page_index false int which page, default value is "1st page" when not fill this parameter
page_size false int the default value is "20" when not fill this parameter, should ≤50

Response:


{
    "status": "ok",
    "data": {
        "total_page": 15,
        "current_page": 1,
        "total_size": 15,
        "financial_record": [
            {
                "id": 3662498355,
                "symbol": "ADA",
                "type": 8,
                "amount": -0.074766355140186915,
                "ts": 1605014144415,
                "contract_code": "ADA201225"
            }
        ]
    },
    "ts": 1604306015124
}

Return parameters

Parameter name Must fill or not Type Description Value range
status true string processing result of requests "ok" , "error"
ts true long response create time point，unit：ms
<data> dicitionary type
<financial_record>
id true long
ts true long create time
symbol true string contract type code "BTC","ETH"...
type true int transaction type 3:close long; 4:close short; 5:fees for open positions-taker; 6:fees for open positions-maker; 7:fees for close positions-taker; 8:fees for close positions-maker; 9:close long for delivery; 10:close short for delivery; 11:delivery fee; 12:close long for liquidation; 13:lose short for liquidation; 14:transfer from spot exchange to contract exchange; 15:tranfer from contract exchange to spot exchange; 16:settle unrealized PnL-long positions; 17:settle unrealized PnL-short positions; 19:clawback; 26:system; 28:activity prize rewards; 29:rebate; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master;
amount true decimal amount
contract_code true string contract code
</financial_record>
total_page true int total page
current_page true int current page
total_size true int total size
</data>

Query financial records via multiple fields

Request Parameter

Parameter name Mandatory Type Description Value range
symbol true string contract symbol "BTC","ETH"...
type false string if not fill this parameter, it will query all types 【please use "," to seperate multiple types】 3:close long; 4:close short; 5:fees for open positions-taker; 6:fees for open positions-maker; 7:fees for close positions-taker; 8:fees for close positions-maker; 9:close long for delivery; 10:close short for delivery; 11:delivery fee; 12:close long for liquidation; 13:lose short for liquidation; 14:transfer from spot exchange to contract exchange; 15:tranfer from contract exchange to spot exchange; 16:settle unrealized PnL-long positions; 17:settle unrealized PnL-short positions; 19:clawback; 26:system; 28:activity prize rewards; 29:rebate; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master;
start_time false long Start Time（Timestamp，Unit: Millisecond） See Note
end_time false long End Time（Timestamp，Unit: Millisecond） See Note
from_id false long Query start id（uses id of returned data）
size false int number of data it will be the default value of 20; the number should ≤50
direct false string Query direction prev ；next ；default value:prev

Note:

Query cases are as below (special cases are not included)：

start_time end_time from_id size direct Query Result
Default 10 days before the current time Default current time Default 20 prev Query the data within the last 10 days; query 20 data from back to front from the current time. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 60 days before the current time 50 days before the current time Default 20 prev Query data between 60 days ago and 50 days ago; query 20 data from back to front from 50 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
5 days before the current time Default current time Default 20 prev Query the data within the last 5 days; query 20 data from back to front from the current time. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
20 days before the current time 10 days before the current time Default 20 prev Query data between 20 days ago and 10 days ago; query 20 data from back to front from 10 days ago.The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 10 days before the current time Default current time Default 20 next Query the data within the last 10 days; query 20 data from front to back from 10 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 60 days before the current time 50 days before the current time Default 20 next Query data between 60 days ago and 50 days ago, query 20 data from front to back from 60 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
5 days before the current time Default current time Default 20 next Query the data within the last 5 days; query 20 data from 5 days ago. query 20 data from front to back from 5 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
20 days before the current time 10 days before the current time Default 20 next Query data between 20 days ago and 10 days ago; query 20 data from front to back from 20 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 10 days before the current time Default current time 1000 20 prev Query the data within the last 10 days; query 20 data from back to front from the data with transaction id 1000 and the data with transaction id 1000 is in the first line. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
20 days before the current time 10 days before the current time 1000 20 next Query data between 20 days ago and 10 days ago, query 20 data from front to back from the data with transaction id 1000 and the data with transaction id 1000 is in the last line. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.

Response:


{
    "status": "ok",
    "data": {
        "financial_record": [
            {
                "id": 3657420903,
                "symbol": "ADA",
                "type": 34,
                "amount": -50,
                "ts": 1604301623306,
                "contract_code": "ADA"
            },
            {
                "id": 3657420101,
                "symbol": "ADA",
                "type": 6,
                "amount": -0.020181634712411705,
                "ts": 1604301416067,
                "contract_code": "ADA201225"
            }
        ],
        "remain_size": 22,
        "next_id": 3657309434
    },
    "ts": 1604305081144
}

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string request handling result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object dicitionary type
<financial_record> true object array
id true long
ts true long create time
symbol true string Type Code "BTC","ETH"...
contract_code true string Contract Code "BTC200919"...
type true int order type 3:close long; 4:close short; 5:fees for open positions-taker; 6:fees for open positions-maker; 7:fees for close positions-taker; 8:fees for close positions-maker; 9:close long for delivery; 10:close short for delivery; 11:delivery fee; 12:close long for liquidation; 13:lose short for liquidation; 14:transfer from spot exchange to contract exchange; 15:tranfer from contract exchange to spot exchange; 16:settle unrealized PnL-long positions; 17:settle unrealized PnL-short positions; 19:clawback; 26:system; 28:activity prize rewards; 29:rebate; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master;
amount true decimal amount
</financial_record>
remain_size true int Remaining data number（the number of data that has not been queried due to the limitation of data number in the time range）
next_id true long id for next data (only has value when query result exceeds data number limits）
</data>

Note:

Query user’s settlement records

Request Parameter

Parameter Name Mandatory Type Description Value Range
symbol true string contract symbol "BTC","ETH"...
start_time false long start time（Timestamp，Unit: Millisecond） Value Range: [(current time - 90 days), current time] ，default current day - 90 days
end_time false long end time（Timestamp，Unit: Millisecond） Value Range: (start_time, current time]，default current time
page_index false int Page 1st page by default without given instruction
page_size false int page size Page 20 by default without given instruction, ，no more than 50

Note:

Response: 


{
    "status": "ok",
    "data": {
        "total_page": 13,
        "current_page": 1,
        "total_size": 13,
        "settlement_records": [
            {
                "symbol": "ADA",
                "margin_balance_init": 436.415907066107795161,
                "margin_balance": 436.795604223274725677,
                "settlement_profit_real": 0.379697157166930517,
                "settlement_time": 1604044800130,
                "clawback": 0,
                "delivery_fee": 0,
                "offset_profitloss": 13.25977319159553892,
                "fee": -0.565357129977092573,
                "fee_asset": "ADA",
                "positions": [
                    {
                        "symbol": "ADA",
                        "contract_code": "ADA201225",
                        "direction": "buy",
                        "volume": 2,
                        "cost_open": 0.098,
                        "cost_hold_pre": 0.098,
                        "cost_hold": 0.092423,
                        "settlement_profit_unreal": -12.31471890445151583,
                        "settlement_price": 0.092423,
                        "settlement_type": "settlement"
                    }
                ]
            }
        ]
    },
    "ts": 1604305358564
}

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result
<data> true object
<settlement_records> true object array
symbol true string Contract Code "BTC","ETH"...
margin_balance_init true decimal Initial account equity for this term
margin_balance true decimal Account equity after settlement for this term
settlement_profit_real true decimal Realized PnL for this term
settlement_time true long Settlement time for this term; delivery time if at the delivery.
clawback true decimal Clawback for this term
delivery_fee true decimal Delivery fee for this term（total fee of long and short positions）, the field has value only when the positions are at the delivery
offset_profitloss true decimal Current term PnL of positions closed
fee true decimal Transaction fee for this term
fee_asset true string Transaction Fee Coin
<positions> true object array
symbol true string Coin Code "BTC","ETH"...
contract_code true string Contract Code "BTC200619" ...
direction true string Position Direction [buy : sell ]
volume true decimal Position volume before the settlement of this term（cont）
cost_open true decimal Open price
cost_hold_pre true decimal Average position price before the settlement of this term
cost_hold true decimal Average position price after the settlement of this term
settlement_profit_unreal true decimal Unrealized PnL for this term
settlement_price true decimal Settlement price for this term; delivery price if at the delivery.
settlement_type true string Settlement Type settlement: settlement；delivery: delivery；
</positions>
</settlement_records>
total_page true int Total Pages
current_page true int Current Page
total_size true int Total Size
</data>
ts true long Timestamp

Rule:

Query contract information on order limit

Request Parameter

Parameter Name Mandatory Type Description Value Range
symbol false string contract code Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"...，If no data detected, system will return to all contracts by default
order_price_type true string Order Type "limit": Limit Order，"opponent":BBO，"lightning": Flash Close，"optimal_5": Optimal top 5 price，"optimal_10":Optimal top 10 price，"optimal_20":Optimal top 20 price,"fok":FOK order,"ioc":ioc order,"opponent_ioc"：IOC order using the BBO price，"lightning_ioc"：lightning IOC，"optimal_5_ioc"：optimal_5 IOC，"optimal_10_ioc"：optimal_10 IOC， "optimal_20_ioc"：optimal_20 IOC, "opponent_fok"：FOK order using the BBO price，"lightning_fok"：lightning FOK，"optimal_5_fok"：optimal_5 FOK，"optimal_10_fok"：optimal_10 FOK，"optimal_20_fok"：optimal_20 FOK

Response:


{
    "status": "ok",
    "data": {
        "order_price_type": "limit",
        "list": [
            {
                "symbol": "ADA",
                "types": [
                    {
                        "contract_type": "this_week",
                        "open_limit": 6000,
                        "close_limit": 12000
                    },
                    {
                        "contract_type": "next_week",
                        "open_limit": 6000,
                        "close_limit": 12000
                    },
                    {
                        "contract_type": "quarter",
                        "open_limit": 6000,
                        "close_limit": 12000
                    },
                    {
                        "contract_type": "next_quarter",
                        "open_limit": 6000,
                        "close_limit": 12000
                    }
                ]
            }
        ]
    },
    "ts": 1604306946036
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range Í
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data>
order_price_type true string Order Type "limit": Limit Order，"opponent":BBO，"lightning": Flash Close，"optimal_5": Optimal top 5 price，"optimal_10":Optimal top 10 price，"optimal_20":Optimal top 20 price,"fok":FOK order,"ioc":ioc order
<list>
symbol true string Contract Code "BTC","ETH"...
<types>
contract_type true string Contract Type Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter". Next Quarterly Contract: "next_quarter"
open_limit true long Max open order limit
close_limit true long Max close order limit
</types>
</list>
</data>

Query information on contract trading fee

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol false string Contract Code Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"...，If no data detected, system will return to all contract by default

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "ADA",
            "open_maker_fee": "0.0002",
            "open_taker_fee": "0.0004",
            "close_maker_fee": "0.0002",
            "close_taker_fee": "0.0004",
            "delivery_fee": "0.0005",
            "fee_asset": "ADA"
        }
    ],
    "ts": 1604307012954
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data>
symbol true string Contract Code "BTC","ETH"...
open_maker_fee true string Open maker order fee, decimal
open_taker_fee true string Open taker order fee, decimal
close_maker_fee true string Close maker order fee, decimal
close_taker_fee true string Close taker order fee, decimal
delivery_fee true string delivery fee, decimal
fee_asset true string the corresponding cryptocurrency to the given fee "BTC","ETH"...
</data>

Query information on Transfer Limit

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol false string Contract Code Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"...，If no data detected, system will return to all contracts by default.

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "ADA",
            "transfer_in_max_each": 1500000000,
            "transfer_in_min_each": 16,
            "transfer_out_max_each": 150000000,
            "transfer_out_min_each": 0.000001,
            "transfer_in_max_daily": 15000000000,
            "transfer_out_max_daily": 3000000000,
            "net_transfer_in_max_daily": 7500000000,
            "net_transfer_out_max_daily": 1500000000
        }
    ],
    "ts": 1604307084954
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Milesecond
<data>
symbol true string Contract Code "BTC","ETH"...
transfer_in_max_each true decimal Max limit of a single deposit
transfer_in_min_each true decimal Min limit of a single deposit
transfer_out_max_each true decimal Max limit of a single withdrawal
transfer_out_min_each true decimal Min limit of a single withdrawal
transfer_in_max_daily true decimal Max daily limit of total deposits
transfer_out_max_daily true decimal Max daily limit of totally withdrawals
net_transfer_in_max_daily true decimal Max daily limit of net total deposits
net_transfer_out_max_daily true decimal Max daily limit of net total withdrawals
</data>

Query information on position limit

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol false string Contract Code Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"...，If no data detected, system will return to all contracts by default.

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "ADA",
            "list": [
                {
                    "contract_type": "this_week",
                    "buy_limit": 60000,
                    "sell_limit": 60000
                },
                {
                    "contract_type": "next_week",
                    "buy_limit": 60000,
                    "sell_limit": 60000
                },
                {
                    "contract_type": "quarter",
                    "buy_limit": 60000,
                    "sell_limit": 60000
                },
                {
                    "contract_type": "next_quarter",
                    "buy_limit": 60000,
                    "sell_limit": 60000
                },
                {
                    "contract_type": "all",
                    "buy_limit": 240000,
                    "sell_limit": 240000
                }
            ]
        }
    ],
    "ts": 1604307195501
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Responding Generation, Unit: milesecond
<data>
symbol true string Contract Code "BTC","ETH"...
<list>
contract_type true string Contract Type Weekly :"this_week", Bi-weekly:"next_week", Quarterly:"quarter"， Next Quarterly Contract: "next_quarter"
buy_limit true decimal Max long position limit, Unit: Cont
sell_limit true decimal Max short position limit, Unit: Cont
</list>
</data>

Query Assets And Positions

params

field Mandatory type desc range
symbol true string symbol Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"....

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "ADA",
            "margin_balance": 405.226124145843792312,
            "margin_position": 10.300252356182726476,
            "margin_frozen": 0,
            "margin_available": 394.925871789661065836,
            "profit_real": 16.336169922800328615,
            "profit_unreal": 2.09434999976873802,
            "risk_rate": 39.141378262699244579,
            "withdraw_available": 386.795604223274725677,
            "liquidation_price": null,
            "lever_rate": 10,
            "adjust_factor": 0.2,
            "margin_static": 403.131774146075054292,
            "positions": [
                {
                    "symbol": "ADA",
                    "contract_code": "ADA201225",
                    "contract_type": "quarter",
                    "volume": 1,
                    "available": 1,
                    "frozen": 0,
                    "cost_open": 0.0991,
                    "cost_hold": 0.0991,
                    "profit_unreal": 2.09434999976873802,
                    "profit_rate": 0.20755008497708193,
                    "lever_rate": 10,
                    "position_margin": 10.300252356182726476,
                    "direction": "sell",
                    "profit": 2.09434999976873802,
                    "last_price": 0.097085
                }
            ]
        }
    ],
    "ts": 1604307305267
}

response

attr type Mandatory desc
status string true Request Processing Result "ok" , "error"
ts long true Time of Respond Generation, Unit: Millisecond
<data> object array true
symbol string true contract type
margin_balance decimal true Balance Margin
margin_position decimal true Postion Margin
margin_frozen decimal true Frozen Margin
margin_available decimal true Available Margin
profit_real decimal true Realized Profit
profit_unreal decimal true Unreadlized Profit
risk_rate decimal true risk rate
withdraw_available decimal true Available Withdraw
liquidation_price decimal true Estimated Liquidation Price
lever_rate decimal true Leverage Rate
adjust_factor decimal true Adjustment Factor
margin_static decimal true Static Margin
<positions>
symbol string true Variety Code
contract_code string true Contract Code "BTC180914" ...
contract_type string true Contract Type "this_week", "next_week", "quarter" "next_quarter"
volume decimal true Position Quantity
available decimal true Available position quatity can be closed
frozen decimal true forzen postion Quantity
cost_open decimal true Opening Average Price
cost_hold decimal true Average position price
profit_unreal decimal true Unrealized profit
profit_rate decimal true Profit Rate
profit decimal true Profit
position_margin decimal true Position Margin
lever_rate int true Leverage Rate
direction string true "buy" "sell"
last_price decimal true Last Price
</positions>
</data>

Transfer between master and sub account

Request:

{
    "sub_uid": "123456789",
    "symbol": "BTC",
    "amount": "123",
    "type": "master_to_sub"
}

params

attr required type desc
sub_uid true long uid of sub account
symbol true string symbol Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
amount true decimal transfer amount
type true string transfer type "master_to_sub" or "sub_to_master"

Response:


{
    "status": "ok",
    "data": {
        "order_id": "772874532490125313"
    },
    "ts": 1604309247876
}

response

attr required type desc
status true string status "ok" , "error"
ts true long response timestamp，millionseconds
<data> true object
order_id true string order id
</data>

Get transfer records between master and sub account

request

attr required type desc
symbol true string symbol Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
transfer_type false string All by default【multiple types need to be joined with ';'】 34:transfer to sub account 35:transfer from sub account
create_date true int days days need to be less than or equal to 90
page_index false int 1 by default 1
page_size false int 20 by default.less than or equal to 50. 20

Response:


{
    "status": "ok",
    "data": {
        "total_page": 1,
        "current_page": 1,
        "total_size": 2,
        "transfer_record": [
            {
                "id": 3657499070,
                "symbol": "ADA",
                "transfer_type": 34,
                "amount": -1,
                "ts": 1604309247860,
                "sub_uid": "123456789",
                "sub_account_name": "tom"
            },
            {
                "id": 3657420904,
                "symbol": "ADA",
                "transfer_type": 34,
                "amount": -50,
                "ts": 1604301623314,
                "sub_uid": "123456789",
                "sub_account_name": "tom"
            }
        ]
    },
    "ts": 1604309883224
}

response

attr required type desc
status true string respone status "ok" , "error"
ts true long response millionseconds.
<data> true object
<transfer_record> true object array
id true long transfer id
ts true long create timestamp
symbol true string symbol "BTC","ETH"...
sub_uid true string subaccount uid
sub_account_name true string subaccount name
transfer_type true int transfer type transfer from subaccount：35，transfer to subaccount:34
amount true decimal amount
</transfer_record>
total_page true int total page
current_page true int current page
total_size true int total size
</data>

Query user's API indicator disable information

request body

null

eg：

  {
  "status": "ok",
  "data":
  [{
      "is_disable": 1,  
      "order_price_types": "limit,post_only,FOK,IOC", 
      "disable_reason":"COR", 
      "disable_interval": 5,
      "recovery_time": 1,
      "COR":
       {
           "orders_threshold": 150,
           "orders": 150,
           "invalid_cancel_orders": 150,
           "cancel_ratio_threshold": 0.98,
           "cancel_ratio": 0.98,
           "is_trigger": 1,
           "is_active": 1
      } ,
      "TDN":
       {
           "disables_threshold": 3,
           "disables": 3,
           "is_trigger": 1,
           "is_active": 1
      } 
   }],
 "ts": 158797866555
}

Response:

attr required type desc
status true string response status "ok" , "error"
ts true long response millionseconds
<data> true array object
is_disable true long 1：is disabled，0：isn't disabled
order_price_types true string order price types,such as：“limit,post_only,FOK,IOC”
disable_reason true string disable reason "COR":（Cancel Order Ratio），“TDN”：（Total Disable Number）
disable_interval true long disable millionseconds
recovery_time true long recovery millionseconds
<COR> true dict object （Cancel Order Ratio）
orders_threshold true long orders threshold
orders true long total pending orders
invalid_cancel_orders true long numbers of invalid cancel orders
cancel_ratio_threshold true decimal cancel ratio threshold
cancel_ratio true decimal cancel ratio
is_trigger true int 1: triggered，0: not triggered
is_active true int 1: active，0：not active
</COR> true dict object
<TDN> true dict object Total Disable Number
disables_threshold true long disable threshold
disables true long total disable number
is_trigger true long 1：triggered，0：not triggered
is_active true long
</TDN> true dict object
</data>

Query Available Leverage Rate

request body

attr required type desc
symbol false string case-insensitive "BTC" , "ETH"

eg:


{
    "status": "ok",
    "data": [
        {
            "symbol": "ADA",
            "available_level_rate": "1,2,3,5,10,20,30,50,75"
        }
    ],
    "ts": 1604312615051
}

Response:

attr required type desc
status true string response status "ok" , "error"
ts true long response millionseconds
<data> true array object
symbol false string case-insensitive "BTC" , "ETH"
available_level_rate true string available level rate,splited by ',' "1,5,10"
</data>

Future Trade Interface

Place an Order

Example

Request:

{
    "client_order_id":11223344556677,
    "contract_code":"btc200925",
    "contract_type":"quarter",
    "direction":"BUY",
    "lever_rate":75,
    "offset":"OPEN",
    "order_price_type":"post_only",
    "price":2.5,
    "symbol":"btc",
    "volume":1
}

Request Parameter

Parameter Name Parameter Type Mandatory Desc
symbol string false Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"...
contract_type string false Contract Type ("this_week": "next_week": "quarter": "next_quarter")
contract_code string false BTC180914
client_order_id long false Clients fill and maintain themselves.must be Less or Equal than 9223372036854775807
price decimal false Price
volume long true Numbers of orders (volume)
direction string true Transaction direction
offset string true "open", "close"
lever_rate int true Leverage rate [if“Open”is multiple orders in 10 rate, there will be not multiple orders in 20 rate. Using Leverage greater than 20 times requires prior approval of high-leverage agreement for the first time. ]
order_price_type string true "limit”: Limit Order "opponent":BBO "post_only": Post-Only Order, No order limit but position limit for post-only orders.,optimal_5： Optimal , optimal_10： Optimal 10, optimal_20：Optimal 20，ioc: IOC Order,，fok：FOK Order. "opponent_ioc"：IOC order using the BBO price，"optimal_5_ioc"：optimal_5 IOC，"optimal_10_ioc"：optimal_10 IOC，"optimal_20_ioc"：optimal_20 IOC, "opponent_fok"：FOK order using the BBO price，"optimal_5_fok"：optimal_5 FOK，"optimal_10_fok"：optimal_10 FOK，"optimal_20_fok"：optimal_20 FOK

Note ：

If there is a number in the Contract Code row，inquiry with Contract_Code.

If there is no number，inquiry by Symbol + Contract Type.

Post-Only orders are limit orders that will never take liquidity (also called maker-only order). There are order limit and position for post-only orders which the upper limit is 500,000 for open/close orders under weekly, bi-weekly and quarterly contract respectively.

If you’re holding a position currently, the leverage you choose when placing an order should be the same as the leverage of your current positions, otherwise, the order will fail to be placed. If you need a new leverage to place an order, you should switch the leverage of current positions first by using the Switch Leverage interface.

Description of post_only: assure that the maker order remains as maker order, it will not be filled immediately with the use of post_only, for the match system will automatically check whether the price of the maker order is higher/lower than the opponent first price, i.e. higher than bid price 1 or lower than the ask price 1. If yes, the maker order will placed on the orderbook, if not, the maker order will be cancelled.

open long: direction - buy、offset - open

close long: direction -sell、offset - close

open short: direction -sell、offset - open

close short: direction -buy、offset - close

No need to transfer BBO order price(ask 1and bid 1) parameter, optimal_5: top 5 optimal BBO price, optimal_10：top 10 optimal BBO price, optimal_20：top 20 optimal BBO price (No need to transfer price data) ，limit": limit order, "post_only": maker order only (price data transfer is needed),IOC :Immediate-Or-Cancel Order,FOK:Fill-Or-Kill Order.

Response:


{
    "status": "ok",
    "data": {
        "order_id": 773119326353580033,
        "order_id_str": "773119326353580033"
    },
    "ts": 1604367611267
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<data>
order_id true long Order ID
order_id_str true string Order ID
client_order_id true int the client ID that is filled in when the order is placed, if it’s not filled, it won’t be returned
</data>
ts true long Time of Respond Generation, Unit: Millisecond

Note

Place a Batch of Orders

Example

Request:

{
    "orders_data":[
        {
            "clientOrderId":11223344556688,
            "contract_code":"btc200925",
            "contract_type":"quarter",
            "direction":"BUY",
            "leverRate":75,
            "offset":"OPEN",
            "order_price_type":"post_only",
            "price":2.5,
            "symbol":"btc",
            "volume":1
        },
        {
            "clientOrderId":11223344556699,
            "contract_code":"btc200925",
            "contract_type":"quarter",
            "direction":"BUY",
            "leverRate":75,
            "offset":"OPEN",
            "order_price_type":"post_only",
            "price":2.5,
            "symbol":"btc",
            "volume":1
        }
    ]
}

Request Parameter

Parameter Name Parameter Type Mandatory Desc
orders_data List<Object> 10 orders most.
Parameter Name Parameter Type Mandatory Desc
symbol string false Case-Insenstive.Both uppercase and lowercase are supported. "BTC","ETH"...
contract_type string false Contract Type: "this_week": "next_week": "quarter": "next_quarter"
contract_code string false BTC180914
client_order_id long false Clients fill and maintain themselves.Must be Less or Equal than 9223372036854775807
price decimal false Price
volume long true Numbers of orders (volume)
direction string true Transaction direction
offset string true "open": "close"
leverRate int true Leverage rate [if “Open” is multiple orders in 10 rate, there will be not multiple orders in 20 rate.Using Leverage greater than 20 times requires prior approval of high-leverage agreement for the first time. ]
orderPriceType string true "limit”: Limit Order "opponent":BBO "post_only": Post-Only Order, No order limit but position limit for post-only orders.,optimal_5： Optimal , optimal_10： Optimal 10, optimal_20：Optimal 20 ,ioc: IOC Order,，fok：FOK Order ,"opponent_ioc"：IOC order using the BBO price，"optimal_5_ioc"：optimal_5 IOC，"optimal_10_ioc"：optimal_10 IOC，"optimal_20_ioc"：optimal_20 IOC, "opponent_fok"：FOK order using the BBO price，"optimal_5_fok"：optimal_5 FOK，"optimal_10_fok"：optimal_10 FOK，"optimal_20_fok"：optimal_20 FOK

Note ：

If there is a number in the Contract Code row,inquiry with Contract_Code.

If there is no number,inquiry by Symbol + Contract Type.

Description of post_only: assure that the maker order remains as maker order, it will not be filled immediately with the use of post_only, for the match system will automatically check whether the price of the maker order is higher/lower than the opponent first price, i.e. higher than bid price 1 or lower than the ask price 1. If yes, the maker order will placed on the orderbook, if not, the maker order will be cancelled.

If you’re holding a position currently, the leverage you choose when placing an order should be the same as the leverage of your current positions, otherwise, the order will fail to be placed. If you need a new leverage to place an order, you should switch the leverage of current positions first by using the Switch Leverage interface.

No need to transfer BBO order price(ask 1and bid 1) parameter, optimal_5: top 5 optimal BBO price, optimal_10：top 10 optimal BBO price, optimal_20：top 20 optimal BBO price (No need to transfer price data) ，limit": limit order, "post_only": maker order only (price data transfer is needed),IOC :Immediate-Or-Cancel Order,FOK:Fill-Or-Kill Order

Response:

{
    "status": "ok",
    "data": {
        "errors": [
            {
                "index": 1,
                "err_code": 1037,
                "err_msg": "The leverage is invalid. Please contact the customer service."
            }
        ],
        "success": [
            {
                "order_id": 773120304138219520,
                "index": 2,
                "order_id_str": "773120304138219520"
            }
        ]
    },
    "ts": 1604367844388
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<data>
<list>(Attribute Name: errors)
index true int order Index
err_code true int Error code
err_msg true string Error information
</list>
<list>(Attribute Name: success)
index true int order Index
order_id true long Order ID
order_id_str true string Order ID
client_order_id true long the client ID that is filled in when the order is placed, if it’s not filled, it won’t be returned
</list>
</data>
ts true long Time of Respond Generation, Unit: Millisecond

Note

The return order_id is 18 bits, it will make mistake when nodejs and JavaScript analysed 18 bits. Because the Json.parse in nodejs and JavaScript is int by default. so the number over 18 bits need be parsed by jaso-bigint package.

Cancel an Order

Example

Request Parameter

Parameter Name Mandatory Type Desc
order_id false string Order ID（different IDs are separated by ",", maximum 10 orders can be withdrew at one time）
client_order_id false string Client order ID (different IDs are separated by ",", maximum 10 orders can be withdrew at one time)
symbol true string Case-Insenstive.Both uppercase and lowercase are supported.."BTC","ETH"...

Note ：

Both order_id and client_order_id can be used for order withdrawl，one of them needed at one time，if both of them are set，the default will be order id。

The return data from Cancel An Order Interface only means that order cancelation designation is executed successfully. To check cancelation result, please check your order status at Get Information Of An Order interface.

Response: result of multiple order withdraws (successful withdrew order ID, failed withdrew order ID)


{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "769206471845261312",
                "err_code": 1061,
                "err_msg": "This order doesnt exist."
            }
        ],
        "successes": "773120304138219520"
    },
    "ts": 1604367997451
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<dict>(Key Name: data)
<list>(Attribute Name: errors)
order_id true string Order ID
err_code true int Error code
err_msg true string Error information
</list>
successes true string Successfully withdrew list of order_id or client_order_id
</dict>
ts true long Time of Respond Generation, Unit: Millisecond

Cancel All Orders

Example

Request:


{
    "symbol":"btc",
    "contract_code":"btc200925",
    "contract_type":"quarter"
}

Request Parameter

Parameter Name Mandatory Type Desc
symbol true string Case-Insenstive.Both uppercase and lowercase are supported..Variety code，eg "BTC","ETH"...
contract_code false string contract_code
contract_type false string contract_type

Note

  1. Send symbol to cancel all the contracts of that kind of symbol, e.g. send “BTC” to cancel all BTC weekly, biweekly and quarterly contracts.

  2. Send contract_code to cancel the contracts of that code.

  3. Send symbol+contract_type to cancel the certain contracts under the symbol of that contract_type, e.g. send “BTC” and “this week”, then the BTC weekly contracts will be cancelled.

Response:result of multiple order withdrawls (successful withdrew order ID, failed withdrew order ID)


{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "773120045672095744,773120045684678656"
    },
    "ts": 1604369127577
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<dict>(Key Name: data)
<list>(Attribute Name: errors)
order_id true string Order ID
err_code true int failed order error messageError code
err_msg true string failed order information
</list>
successes true string Successful order
</dict>
ts true long Time of Respond Generation, Unit: Millisecond

Switch Leverage

Note

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol true String Variety code "BTC","ETH"...
lever_rate true int Leverage to switch.[Using Leverage greater than 20 times requires prior approval of high-leverage agreement for the first time. ]

Response:


OK：

{
    "status": "ok",
    "data": {
        "symbol": "ada",
        "lever_rate": 20
    },
    "ts": 1604369902689
}
No：

{
    "status": "error",
    "err_code": 1037,
    "err_msg": "The leverage is invalid. Please contact the customer service.",
    "ts": 1604369954194
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string status: ok,error
<data> false object
symbol false string Variety code
lever_rate false int Switched leverage
</data>
err_code false int error code
err_msg false string error msg
ts true long Timestamp

Place Flash Close Order

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol false string Contract Code Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
contract_type false string Contract Type “this_week”:Weekly，“next_week”:Bi-weekly，“quarter”:Quarterly ,Next Quarterly Contract: "next_quarter"
contract_code false string Contract Code BTC190903
volume true long Order Quantity(volume)
direction true string “buy”:Open，“sell”:Close
client_order_id false long Client order ID.must be Less or Equal than 9223372036854775807
order_price_type false string "lightning" by default. "lightning_fok": lightning FOK type,"lightning_ioc": lightning IOC type

Response:


{
  "status": "ok",
  "data": {
    "order_id": 633766664829804544,
    "order_id_str": "633766664829804544",
    "client_order_id": 9086
  },
     "ts": 158797866555
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" :Order placed successfully, "error"：Order failed
ts true long Time of Respond Generation, Unit: Milesecond
<data> Dictionary
order_id true long Order ID [Different users may share the same order ID]
order_id_str true string Order ID
client_order_id false long user’s own order ID
</data>

Error：


{
    "status": "error",
    "err_code": 1048,
    "err_msg": "Insufficient close amount available.",
    "ts": 1604372431440
}

Get Information of an Order

Example

Request Parameter

Parameter Name Mandatory Type Desc
order_id false string Order ID（different IDs are separated by ",", maximum 50 orders can be withdrew at one time）
client_order_id false string Client order ID Order ID（different IDs are separated by ",", maximum 50 orders can be withdrew at one time)
symbol true string Case-Insenstive.Both uppercase and lowercase are supported.."BTC","ETH"...

Note ：

When getting information on order cancellation via get order information interface, users can only query last 4-hour data

Both order_id and client_order_id can be used for order withdrawl，one of them needed at one time，if both of them are set，the default will be order id. The order completed( 5.partially fulfilled but cancelled by client; 6. Fully fulfilled; 7. Cancelled; ) will be deleted after the settlement on Friday.

client_order_id，order status query is available for orders placed within 24 hours; Otherwise, clients cannot check orders placed beyond 24 hours.

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "ADA",
            "contract_code": "ADA201225",
            "contract_type": "quarter",
            "volume": 1,
            "price": 0.0933,
            "order_price_type": "post_only",
            "order_type": 1,
            "direction": "sell",
            "offset": "open",
            "lever_rate": 10,
            "order_id": 773119326353580033,
            "client_order_id": null,
            "created_at": 1604367611263,
            "trade_volume": 1,
            "trade_turnover": 10,
            "fee": -0.021436227224008574,
            "trade_avg_price": 0.0933,
            "margin_frozen": 0,
            "profit": 0,
            "status": 6,
            "order_source": "api",
            "order_id_str": "773119326353580033",
            "fee_asset": "ADA",
            "liquidation_type": "0",
            "canceled_at": 0
        }
    ],
    "ts": 1604370179844
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<list>(Attribute Name: data)
symbol true string Variety code
contract_type true string Contract Type "this_week", "next_week", "quarter","next_quarter"
contract_code true string Contract Code "BTC180914" ...
volume true decimal Numbers of order
price true decimal Price committed
order_price_type true string "limit", "opponent","post_only" Position limit will be applied to post_only while order limit will not.
direction true string Transaction direction
offset true string "open": "close"
lever_rate true int Leverage rate 1\5\10\20
order_id true long Order ID
order_id_str true string Order ID
order_type true int Order type: 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
client_order_id true long Client order ID
created_at true long Creation time
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction aggregate amount
fee true decimal Servicefee
trade_avg_price true decimal Transaction average price
margin_frozen true decimal Freeze margin
profit true decimal profit
status true int status: 1. Ready to submit the orders; 2. Ready to submit the orders; 3. Have sumbmitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled; 11. Orders cancelling.
order_source true string Order source（system、web、api、m、risk、settlement、ios、android、windows、mac、trigger）
fee_asset true string the corresponding cryptocurrency to the given fee "BTC","ETH"...
canceled_at true long Cancellation time
liquidation_type true string 0:Not Forced Liquidation Type，1：Netting Type， 2: Partial Takeover，3：All Takeover
</list>
ts true long Timestamp

Order details acquisition

Example

Request Parameter

Parameter Name Mandatory Type Desc
symbol true string Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
order_id true long Order ID
created_at true long Timestamp
order_type true int Order type: 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
page_index false int Page number, default 1st page
page_size false int Default 20，no more than 50

Note

When getting information on order cancellation via query order detail interface, users who type in parameters “created_at” and “order_type” can query last 24-hour data, while users who don’t type in parameters “created_at” and “order_type” can only query last 2-hour data.

The return order_id is 18 bits, it will make mistake when nodejs and JavaScript analysed 18 bits. Because the Json.parse in nodejs and JavaScript is int by default. so the number over 18 bits need be parsed by jason-bigint package.

created_at should use timestamp of long type as 13 bits (include Millisecond), if send the accurate timestamp for "created_at", query performance will be improved.

eg. the timestamp "2019/10/18 10:26:22" can be changed：1571365582123.It can also directly obtain the timestamp（ts) from the returned ordering interface(contract_order) to query the corresponding orders.

Please note that created_at can't send "0"

Response:


{
    "status": "ok",
    "data": {
        "symbol": "ADA",
        "contract_code": "ADA201225",
        "contract_type": "quarter",
        "instrument_price": 0,
        "final_interest": 0,
        "adjust_value": 0,
        "lever_rate": 10,
        "direction": "sell",
        "offset": "open",
        "volume": 1,
        "price": 0.0933,
        "created_at": 1604367611263,
        "canceled_at": 0,
        "order_source": "api",
        "order_price_type": "post_only",
        "margin_frozen": 0,
        "profit": 0,
        "trades": [
            {
                "trade_id": 113887800667,
                "trade_price": 0.0933,
                "trade_volume": 1,
                "trade_turnover": 10,
                "trade_fee": -0.021436227224008574,
                "created_at": 1604368087894,
                "role": "maker",
                "id": "113887800667-773119326353580033-1"
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1,
        "liquidation_type": "0",
        "fee_asset": "ADA",
        "order_id": 773119326353580033,
        "order_id_str": "773119326353580033",
        "client_order_id": null,
        "order_type": "1",
        "status": 6,
        "trade_avg_price": 0.0933,
        "trade_turnover": 10,
        "trade_volume": 1,
        "fee": -0.021436227224008574
    },
    "ts": 1604370259827
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<object> (Attribute Name: data)
symbol true string Variety code
contract_type true string Contract Type "this_week","next_week","quarter","next_quarter"
contract_code true string Contract Code "BTC180914" ...
lever_rate true int Leverage Rate 1\5\10\20
direction true string Transaction direction
offset true string "open": "close"
volume true decimal Number of Order
price true decimal Price committed
created_at true long Creation time
canceled_at true long Cancellation time
order_source true string Order Source
order_price_type true string "limit", "opponent","post_only" Position limit will be applied to post_only while order limit will not.
margin_frozen true decimal Freeze margin
profit true decimal profit
order_id true long Order ID
order_id_str true string Order ID
order_type true int Order type: 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
client_order_id true long Client order ID
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction aggregate amount
fee true decimal Servicefee
trade_avg_price true decimal Transaction average price
status true int status: 1. Ready to submit the orders; 2. Ready to submit the orders; 3. Have sumbmitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled; 11. Orders cancelling.
total_page true int Page in total
current_page true int Current Page
total_size true int Total Size
instrument_price true decimal Liquidation price
final_interest true decimal Account Balance After Liquidation
adjust_value true decimal Adjustment Factor of Liquidating Order
fee_asset true string the corresponding cryptocurrency to the given fee "BTC","ETH"...
liquidation_type true string 0:Not Forced Liquidation Type，1：Netting Type， 2: Partial Takeover，3：All Takeover
<list> (Attribute Name: trades)
id true string the global unique id of the trade.
trade_id true long In this interface, trade_id is the same with match_id of api/v1/contract_matchresults. trade_id is the result of sets of order execution and trade confirmation. NOTE: trade_id is not unique, which includes all trade records of a taker order and N maker orders. If the taker order matches with N maker orders, it will create N trades with same trade_id.
trade_price true decimal Match Price
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction price
trade_fee true decimal Transaction Service fee
role true string taker or maker
created_at true long Creation time
</list>
</object >
ts true long Timestamp

Query Open Orders

Example

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
symbol true string Variety code Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
page_index false int Page, default 1st page 1
page_size false int Default 20，no more than 50 20

Response:


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "ADA",
                "contract_code": "ADA201225",
                "contract_type": "quarter",
                "volume": 1,
                "price": 0.0925,
                "order_price_type": "post_only",
                "order_type": 1,
                "direction": "buy",
                "offset": "close",
                "lever_rate": 20,
                "order_id": 773131315209248768,
                "client_order_id": null,
                "created_at": 1604370469629,
                "trade_volume": 0,
                "trade_turnover": 0,
                "fee": 0,
                "trade_avg_price": null,
                "margin_frozen": 0,
                "profit": 0,
                "status": 3,
                "order_source": "web",
                "order_id_str": "773131315209248768",
                "fee_asset": "ADA",
                "liquidation_type": null,
                "canceled_at": null
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1604370488518
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result
<list>(Attribute Name: data)
<orders>
symbol true string Variety code
contract_type true string Contract Type "this_week","next_week","quarter","next_quarter"
contract_code true string Contract Code "BTC180914" ...
volume true decimal Number of Order
price true decimal Price committed
order_price_type true string "limit", "opponent","post_only" Position limit will be applied to post_only while order limit will not.
order_type true int Order type: 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
direction true string Transaction direction
offset true string "open": "close"
lever_rate true int Leverage Rate 1\5\10\20
order_id true long Order ID
order_id_str true string Order ID
client_order_id true long Client order ID
created_at true long Order Creation time
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction aggregate amount
fee true decimal Servicefee
trade_avg_price true decimal Transaction average price
margin_frozen true decimal Freeze margin
profit true decimal profit
status true int status: 1. Ready to submit the orders; 2. Ready to submit the orders; 3. Have sumbmitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled; 11. Orders cancelling.
order_source true string Order Source
fee_asset true string the corresponding cryptocurrency to the given fee "BTC","ETH"...
</orders>
total_page true int Total Pages
current_page true int Current Page
total_size true int Total Size
</list>
ts true long Timestamp

Get History Orders

Example

Request:

{
    "symbol": "BTC",
    "trade_type": 0,
    "type": 1,
    "status": "0,3,4,5",
    "create_date": 1,
    "page_index": 1,
    "page_size": 20,
    "contract_code": "BTC180914",
    "order_type": "limit"
}

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
symbol true string Variety code Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
trade_type true int Transaction type 0:all,1: buy long,2: sell short,3: buy short,4: sell long,5: sell liquidation,6: buy liquidation,7:Delivery long,8: Delivery short 11:reduce positions to close long，12:reduce positions to close short
type true int Type 1:All Orders,2:Order in Finished Status
status true string Order Status support multiple query seperated by ',',such as '3,4,5','0': all. 3. Have sumbmitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled;
create_date true int Date any positive integer available. Requesting data beyond 90 will not be supported, otherwise, system will return trigger history data within the last 90 days by default.
page_index false int Page, default 1st page 1
page_size false int Default 20，no more than 50 20
contract_code false string Contract Code "BTC180914" ...
order_type false string Order Type 1:"limit"，3:"opponent"，4:"lightning",5:"Trigger Order",6:"pst_only",7:"optimal_5"，8:"optimal_10"，9:"optimal_20",10:"fok":FOK order,11:"ioc":ioc order

Note

When getting information on order cancellation via query history orders interface, users can only query last 2-hour data.

Response:


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "order_id": 773131315209248768,
                "contract_code": "ADA201225",
                "symbol": "ADA",
                "lever_rate": 20,
                "direction": "buy",
                "offset": "close",
                "volume": 1,
                "price": 0.0925,
                "create_date": 1604370469629,
                "order_source": "web",
                "order_price_type": 6,
                "order_type": 1,
                "margin_frozen": 0,
                "profit": 0,
                "contract_type": "quarter",
                "trade_volume": 0,
                "trade_turnover": 0,
                "fee": 0,
                "trade_avg_price": 0,
                "status": 3,
                "order_id_str": "773131315209248768",
                "fee_asset": "ADA",
                "liquidation_type": "0"
            }
        ],
        "total_page": 19,
        "current_page": 1,
        "total_size": 19
    },
    "ts": 1604370617322
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result
<object>(Attribute Name: data)
<list>(Attribute Name: orders)
order_id true long Order ID
order_id_str true string Order ID
symbol true string Variety code
contract_type true string Contract Type "this_week","next_week","quarter","next_quarter"
contract_code true string Contract Code "BTC180914" ...
lever_rate true int Leverage Rate 1\5\10\20
direction true string Transaction direction
offset true string "open": "close"
volume true decimal Number of Order
price true decimal Price committed
create_date true long Creation time
order_source true string Order Source
order_price_type true int 1：limit，2：market，3：opponent，4：lightning，5：trigger，6：post_only ，7：optimal_5 ，8：optimal_10 ，9：optimal_20，10：FOK ，11：IOC ，12：opponent_ioc，13：lightning_ioc，14：optimal_5_ioc，15：optimal_10_ioc，16：optimal_20_ioc，17：opponent_fok，18：lightning_fok，19：optimal_5_fok，40：optimal_10_fok，41：optimal_20_fok .
margin_frozen true decimal Freeze margin
profit true decimal profit
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction aggregate amount
fee true decimal Servicefee
trade_avg_price true decimal Transaction average price
status true int status: 1. Ready to submit the orders; 2. Ready to submit the orders; 3. Have sumbmitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled; 11. Orders cancelling.
order_type true string Order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
fee_asset true string the corresponding cryptocurrency to the given fee "BTC","ETH"...
liquidation_type true string 0:Not Forced Liquidation Type，1：Netting Type， 2: Partial Takeover，3：All Takeover
</list>
total_page true int Total Pages
current_page true int Current Page
total_size true int Total Size
</object>
ts true long Timestamp

Note

The return order_id is 18 bits, it will make mistake when nodejs and JavaScript analysed 18 bits. Because the Json.parse in nodejs and JavaScript is int by default. so the number over 18 bits need be parsed by jaso-bigint package.

Query history orders via multiple fields

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol true string Contract Symbol "BTC","ETH"...
trade_type true int trading type 0:all,1: buy long,2: sell short,3: buy short,4: sell long,5: sell liquidation,6: buy liquidation,7:Delivery long,8: Delivery short 11:reduce positions to close long，12:reduce positions to close short
type true int Order Type 1:All Orders,2:Order in Finished Status
status true string Order Status support multiple query seperated by ',',such as '3,4,5','0': all. 3. Have sumbmitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled;
contract_code false string Contract Code
order_price_type false string order price types "limit”: Limit Order "opponent":BBO "post_only": Post-Only Order, No order limit but position limit for post-only orders.,optimal_5： Optimal , optimal_10： Optimal 10, optimal_20：Optimal 20，ioc: IOC Order,，fok：FOK Order. "opponent_ioc"：IOC order using the BBO price，"optimal_5_ioc"：optimal_5 IOC，"optimal_10_ioc"：optimal_10 IOC，"optimal_20_ioc"：optimal_20 IOC, "opponent_fok"：FOK order using the BBO price，"optimal_5_fok"：optimal_5 FOK，"optimal_10_fok"：optimal_10 FOK，"optimal_20_fok"：optimal_20 FOK
start_time false long start time（Timestamp，Unit: Millisecond） See Note
end_time false long end time（Timestamp，Unit: Millisecond） See Note
from_id false long Query start id（uses query_id of returned data）
size false int number of data it will be the default value of 20; the number should ≤50
direct false string Query direction prev ；next ；default value:prev

Note：

Query cases are as below (special cases are not included)：

start_time end_time from_id size direct Query Result
Default 10 days before the current time Default current time Default 20 prev Query the data within the last 10 days; query 20 data from back to front from the current time. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 60 days before the current time 50 days before the current time Default 20 prev Query data between 60 days ago and 50 days ago; query 20 data from back to front from 50 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
5 days before the current time Default current time Default 20 prev Query the data within the last 5 days; query 20 data from back to front from the current time. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
20 days before the current time 10 days before the current time Default 20 prev Query data between 20 days ago and 10 days ago; query 20 data from back to front from 10 days ago.The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 10 days before the current time Default current time Default 20 next Query the data within the last 10 days; query 20 data from front to back from 10 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 60 days before the current time 50 days before the current time Default 20 next Query data between 60 days ago and 50 days ago, query 20 data from front to back from 60 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
5 days before the current time Default current time Default 20 next Query the data within the last 5 days; query 20 data from 5 days ago. query 20 data from front to back from 5 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
20 days before the current time 10 days before the current time Default 20 next Query data between 20 days ago and 10 days ago; query 20 data from front to back from 20 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 10 days before the current time Default current time 1000 20 prev Query the data within the last 10 days; query 20 data from back to front from the data with transaction id 1000 and the data with transaction id 1000 is in the first line. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
20 days before the current time 10 days before the current time 1000 20 next Query data between 20 days ago and 10 days ago, query 20 data from front to back from the data with transaction id 1000 and the data with transaction id 1000 is in the last line. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.

Response:


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "query_id": 113957564277,
                "order_id": 773135295142658048,
                "contract_code": "ADA201225",
                "symbol": "ADA",
                "lever_rate": 20,
                "direction": "buy",
                "offset": "open",
                "volume": 1,
                "price": 0.092,
                "create_date": 1604371418518,
                "order_source": "web",
                "order_price_type": "post_only",
                "order_type": 1,
                "margin_frozen": 0,
                "profit": 0,
                "contract_type": "quarter",
                "trade_volume": 1,
                "trade_turnover": 10,
                "fee": -0.021739130434782608,
                "trade_avg_price": 0.092,
                "status": 6,
                "order_id_str": "773135295142658048",
                "fee_asset": "ADA",
                "liquidation_type": "0"
            }
        ],
        "remain_size": 19,
        "next_id": 113956362239
    },
    "ts": 1604371805794
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result
<data> true object
<orders> true object array
query_id true long Query id, which can be used as the from_id field for the next query request.
order_id true long Order ID
order_id_str true string Order ID
symbol true string Contract symbol
contract_type true string Contract Type “this_week”:Weekly，“next_week”:Bi-weekly，“quarter”:Quarterly ,Next Quarterly Contract: "next_quarter"
contract_code true string Contract Code "BTC180914" ...
lever_rate true int Leverage Rate
direction true string Transaction direction 【buy : sell】
offset true string offset direction 【open : close】
volume true decimal Number of Order
price true decimal Price committed
create_date true long Creation time
order_source true string Order Source
order_price_type true string order price types "limit”: Limit Order "opponent":BBO "post_only": Post-Only Order, No order limit but position limit for post-only orders.,optimal_5： Optimal , optimal_10： Optimal 10, optimal_20：Optimal 20，ioc: IOC Order,，fok：FOK Order. "opponent_ioc"：IOC order using the BBO price，"optimal_5_ioc"：optimal_5 IOC，"optimal_10_ioc"：optimal_10 IOC，"optimal_20_ioc"：optimal_20 IOC, "opponent_fok"：FOK order using the BBO price，"optimal_5_fok"：optimal_5 FOK，"optimal_10_fok"：optimal_10 FOK，"optimal_20_fok"：optimal_20 FOK
margin_frozen true decimal Freeze margin
profit true decimal profit
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction aggregate amount
fee true decimal Servicefee
trade_avg_price true decimal Transaction average price
status true int status 1. Ready to submit the orders; 2. Ready to submit the orders; 3. Have sumbmitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled; 11. Orders cancelling.
order_type true int Order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
fee_asset true string the corresponding cryptocurrency to the given fee （"BTC","ETH"...）
liquidation_type true string liquidation type 0:Not Forced Liquidation Type，1：Netting Type， 2: Partial Takeover，3：All Takeover
</orders>
remain_size true int Remaining data number（the number of data that has not been queried due to the limitation of data number in the time range）
next_id true long query_id for next data (only has value when query result exceeds data number limits）
</data>
ts true long Timestamp

Note:

Get History Match Results

Example

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
symbol true string symbol Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
trade_type true int trasanction types 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions
create_date true int date any positive integer available. Requesting data beyond 90 will not be supported, otherwise, system will return trigger history data within the last 90 days by default.
contract_code false string contract code
page_index false int page; if not enter, it will be the default value of the 1st page. 1
page_size false int if not enter, it will be the default value of 20; the number should ≤50 20

Response:


{
    "status": "ok",
    "data": {
        "trades": [
            {
                "match_id": 113891764710,
                "order_id": 773135295142658048,
                "symbol": "ADA",
                "contract_type": "quarter",
                "contract_code": "ADA201225",
                "direction": "buy",
                "offset": "open",
                "trade_volume": 1,
                "trade_price": 0.092,
                "trade_turnover": 10,
                "trade_fee": -0.021739130434782608,
                "offset_profitloss": 0,
                "create_date": 1604371703183,
                "role": "Maker",
                "order_source": "web",
                "order_id_str": "773135295142658048",
                "fee_asset": "ADA",
                "id": "113891764710-773135295142658048-1"
            }
        ],
        "total_page": 16,
        "current_page": 1,
        "total_size": 16
    },
    "ts": 1604371918571
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string request handling result
<object>(attribute name: data: data)
<list>(attribute name: data: trades)
id true string the global unique ID of the trade.
match_id true long match_id is the same with trade_id of the websocket subscriptions: orders.$symbol and matchOrders.$symbol.match_id is the result of sets of order execution and trade confirmation. NOTE: match_id is not unique, which includes all trade records of a taker order and N maker orders. If the taker order matches with N maker orders, it will create N trades with same match_id.
order_id true long order ID
order_id_str true string order ID
symbol true string contract type code
order_source true string Order Source
contract_type true string contract type deliver on this Friday then "this_week"; deliver on next Friday then "next_week"; for quarterly contract then "quarter", Next Quarterly Contract: "next_quarter"
contract_code true string contract code "BTC180914" ...
direction true string "buy": to bid/ go long; "sell": to ask/ go short.
offset true string "open": open positions; "close": close positions
trade_volume true decimal the number of traded contract with unit of lot
trade_price true decimal the price at which orders get filled
trade_turnover true decimal the number of total traded amout with number of USD
create_date true long the time when orders get filled
offset_profitloss true decimal profits and losses generated from closing positions
trade_fee true decimal fees charged by platform
role true string taker or maker
fee_asset true string the corresponding cryptocurrency to the given fee "BTC","ETH"...
</list>
total_page true int total pages
current_page true int current page
total_size true int total size of the list
</object>
ts true long timestamp

Notice

Query history transactions via multiple fields

Request Parameter

Parameter Name Mandatory Type Desc Value Range
symbol true string Variety code "BTC","ETH"...
trade_type true int Transaction type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions
contract_code false string Contract Code
start_time false long start time（Timestamp，Unit: Millisecond） See Note
end_time false long end time（Timestamp，Unit: Millisecond） See Note
from_id false long Query start id（uses query_id of returned data）
size false int number of data it will be the default value of 20; the number should ≤50
direct false string Query direction prev ；next ；Default value：prev

Note:

Query cases are as below (special cases are not included)：

start_time end_time from_id size direct Query Result
Default 10 days before the current time Default current time Default 20 prev Query the data within the last 10 days; query 20 data from back to front from the current time. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 60 days before the current time 50 days before the current time Default 20 prev Query data between 60 days ago and 50 days ago; query 20 data from back to front from 50 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
5 days before the current time Default current time Default 20 prev Query the data within the last 5 days; query 20 data from back to front from the current time. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
20 days before the current time 10 days before the current time Default 20 prev Query data between 20 days ago and 10 days ago; query 20 data from back to front from 10 days ago.The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 10 days before the current time Default current time Default 20 next Query the data within the last 10 days; query 20 data from front to back from 10 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 60 days before the current time 50 days before the current time Default 20 next Query data between 60 days ago and 50 days ago, query 20 data from front to back from 60 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
5 days before the current time Default current time Default 20 next Query the data within the last 5 days; query 20 data from 5 days ago. query 20 data from front to back from 5 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
20 days before the current time 10 days before the current time Default 20 next Query data between 20 days ago and 10 days ago; query 20 data from front to back from 20 days ago. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
Default 10 days before the current time Default current time 1000 20 prev Query the data within the last 10 days; query 20 data from back to front from the data with transaction id 1000 and the data with transaction id 1000 is in the first line. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.
20 days before the current time 10 days before the current time 1000 20 next Query data between 20 days ago and 10 days ago, query 20 data from front to back from the data with transaction id 1000 and the data with transaction id 1000 is in the last line. The data returned is in reverse order based on creation time. The newer the data, the closer to the front.

Response: 


{
    "status": "ok",
    "data": {
        "trades": [
            {
                "query_id": 2424420723,
                "match_id": 113891764710,
                "order_id": 773135295142658048,
                "symbol": "ADA",
                "contract_type": "quarter",
                "contract_code": "ADA201225",
                "direction": "buy",
                "offset": "open",
                "trade_volume": 1,
                "trade_price": 0.092,
                "trade_turnover": 10,
                "trade_fee": -0.021739130434782608,
                "offset_profitloss": 0,
                "create_date": 1604371703183,
                "role": "Maker",
                "order_source": "web",
                "order_id_str": "773135295142658048",
                "fee_asset": "ADA",
                "id": "113891764710-773135295142658048-1"
            }
        ],
        "remain_size": 15,
        "next_id": 2424413094
    },
    "ts": 1604372202243
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string request handling result
<data> true object
<trades> true object array
id true string the global unique ID of the trade.
query_id true long Query id, which can be used as the from_id field for the next query request.
match_id true long match_id is the same with trade_id of the websocket subscriptions: orders.$symbol and matchOrders.$symbol.match_id is the result of sets of order execution and trade confirmation. NOTE: match_id is not unique, which includes all trade records of a taker order and N maker orders. If the taker order matches with N maker orders, it will create N trades with same match_id.
order_id true long order ID
order_id_str true string order ID
symbol true string Variety code
contract_type true string contract type “this_week”:Weekly，“next_week”:Bi-weekly，“quarter”:Quarterly ,Next Quarterly Contract: "next_quarter"
contract_code true string Contract Code "BTC180914" ...
direction true string Transaction direction [Buy (buy), Sell(sell)]
offset true string "open": "close" [Open(open), Close(lose)]
trade_volume true decimal Transaction quantity
trade_price true decimal the price at which orders get filled
trade_turnover true decimal Transaction aggregate amount
create_date true long Creation time
offset_profitloss true decimal profits and losses generated from closing positions
traded_fee true decimal fees charged by platform
role true string taker or maker
fee_asset true string the corresponding cryptocurrency to the given fee （"BTC","ETH"...）
order_source true string Order Source
</trades>
remain_size true int Remaining data number（the number of data that has not been queried due to the limitation of data number in the time range）
next_id true long query_id for next data (only has value when query result exceeds data number limits）
</data>
ts true long timestamp

Note

Place Trigger Order

Request:

{
    "contract_code":"btc200925",
    "contract_type":"quarter",
    "direction":"BUY",
    "lever_rate":5,
    "offset":"OPEN",
    "order_price":10000,
    "order_price_type":"limit",
    "symbol":"btc",
    "trigger_price":10000,
    "trigger_type":"ge",
    "volume":1
}

body

Params Mandatory Type Desc Value Range
symbol false string symbol Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
contract_type false string contract type “this_week”，“next_week”，“quarter”,"next_quarter"
contract_code false string contract code BTC190903
trigger_type true string trigger： ge Equal to or Greater than；le Less than or Equal to
trigger_price true Decimal Trigger Price
order_price false Decimal Order Price
order_price_type false order price type： "limit" by default;"optimal_5", "optimal_10"，"optimal_20"
volume true long volume
direction true string buy sell
offset true string open close
lever_rate true int Long leverage shall be equal to short leverage.[Using Leverage greater than 20 times requires prior approval of high-leverage agreement for the first time. ]

Note

Response:


{
    "status": "ok",
    "data": {
        "order_id": 28312412,
        "order_id_str": "28312412"
    },
    "ts": 1604372634548
}

Response Desc

field type Mandatory Desc
status string true status: ok,error
err_code int false error code
err_msg string false error message
data List false list info
ts long true timestamp
field type Mandatory Desc
order_id long true order id. order id may be same among different users
order_id_str string true order id str

Cancel Trigger Order

request params

field type Mandatory desc
symbol string true Case-Insenstive.Both uppercase and lowercase are supported.BTC,LTC...
order_id string true order id. multiple orderids need to be joined by ",".Max number of order ids is 10 once.

Response:


{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "28312406",
                "err_code": 1061,
                "err_msg": "This order doesnt exist."
            }
        ],
        "successes": "28312412"
    },
    "ts": 1604372746401
}

response

field Required type desc value range
status true string response status "ok" , "error"
<data>
successes true string successful orders
<list>(field name: errors)
order_id true string order id
err_code true int error code
err_msg true string error messages
</list>
</data>
ts true long response timestamp millseconds

Cancel All Trigger Orders

Params

field type Mandatory desc
symbol string true Case-Insenstive.Both uppercase and lowercase are supported.BTC、LTC...
contract_code string false contract code,"BTC180914" ...
contract_type string false contract type "this_week" "next_week" "quarter" "next_quarter"

Note

Response:


{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "28312413,28312414"
    },
    "ts": 1604373863946
}

response params

field Mandatory type desc value range
status true string status "ok" , "error"
<data>
<list>(data name: errors)
order_id true string order id
err_code true int error code
err_msg true string error message
</list>
successes true string successful orders
</data>
ts true long response timestamp in millseconds

Query Trigger Order Open Orders

Request Parameter

Parameter Name Type Mandatory Description
symbol string true Case-Insenstive.Both uppercase and lowercase are supported.BTC,LTC...
contract_code string false Case-Insenstive.Both uppercase and lowercase are supported..contract code
page_index int false page number，default page 1 if no given instruction
page_size int false default 20 if no given instruction

Response:


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "ADA",
                "contract_code": "ADA201225",
                "contract_type": "quarter",
                "trigger_type": "le",
                "volume": 1,
                "order_type": 1,
                "direction": "buy",
                "offset": "open",
                "lever_rate": 20,
                "order_id": 28312415,
                "order_id_str": "28312415",
                "order_source": "api",
                "trigger_price": 0.0895,
                "order_price": 0.0895,
                "created_at": 1604374041289,
                "order_price_type": "limit",
                "status": 2
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1604374215911
}

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" , "error"
data true object Returned data
ts true long Time stamp of response, Unit: millisecond
Parameter Name Mandatory Type Description Value Range
total_page int true total page
current_page int true current page
total_size int true total size
<list> (Attribute Name: orders)
symbol string true Cryptocurrency
contract_code string true contract code
contract_type string true contract type
trigger_type string true trigger type： gegreat than or equal to；leless than or equal to
volume decimal true trigger order volume
order_type int true Transaction Type 1. Place orders 2. cancel orders
direction string true order direction [buy,sell]
offset string true offset direction [open,close]
lever_rate int true Leverage 1\5\10\20
order_id long true trigger order ID
order_id_str string true the order ID with string
order_source string true source
trigger_price decimal true trigger price
order_price decimal true the preset price by the client
created_at long true order creation time
order_price_type string true order price type "limit": limit order，"optimal_5":optimal 5，"optimal_10":optimal 10，"optimal_20":optimal 20
status int true order status：1:ready to submit、2:submited、3:order accepted、7:wrong order、8：canceled orders but not found、9：canceling order、10：failed'
</list>

Query Trigger Order History

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
symbol true string Cryptocurrency Case-Insenstive.Both uppercase and lowercase are supported."BTC","ETH"...
contract_code false string Contract Code EOS190118
trade_type true int Transaction type 0: All ,1: Open Long,2: Close Short,3: Open Short,4: Close Long；the system will transfer these parameters into offset and direction and query the requested data. Please note that no data can be requested with parameter out of this range.
status true string Order Status data divided with several commas, trigger orders ready to be submitted：0: All (All filled orders),4: Trigger orders successfully submitted,5: Trigger orders failed being submitted, 6: Trigger orders cancelled
create_date true int Date any positive integer available. Requesting data beyond 90 will not be supported, otherwise, system will return trigger history data within the last 90 days by default.
page_index false int Page, 1st page by default without given instruction 1 page，1st page by default without given instruction
page_size false int Page 20 by default without given instruction, ，no more than 50 20 Page 20 by default without given instruction, ，no more than 50

NOTE

Response:


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "ADA",
                "contract_code": "ADA201225",
                "contract_type": "quarter",
                "trigger_type": "le",
                "volume": 1,
                "order_type": 1,
                "direction": "buy",
                "offset": "open",
                "lever_rate": 20,
                "order_id": 28312415,
                "order_id_str": "28312415",
                "relation_order_id": "773147284987842560",
                "order_price_type": "limit",
                "status": 4,
                "order_source": "api",
                "trigger_price": 0.0895,
                "triggered_price": 0.089497,
                "order_price": 0.0895,
                "created_at": 1604374041289,
                "triggered_at": 1604374277082,
                "order_insert_at": 1604374277124,
                "canceled_at": 0,
                "fail_code": null,
                "fail_reason": null
            }
        ],
        "total_page": 4,
        "current_page": 1,
        "total_size": 4
    },
    "ts": 1604374349086
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Request Processing Result "ok" , "error"
data true object Return data
ts true long Time of Respond Generation, Unit: Millisecond
Parameter Name Mandatory Type Desc Value Range
total_page int true Total page
current_page int true Current page
total_size int true Total Size
<list>(Attribute Name: orders)
symbol string true Cryptocurrency
contract_code string true Contract Code
contract_type string true Contract Type
trigger_type string true trigger： ge Equal to or Greater than；le Less than or Equal to
volume decimal true Numbers of order placed
order_type int true Transaction type：1、Place orders 2、Cancel orders
direction string true order direction, [Buy (buy), Sell(sell)]
offset string true offset direction [Open(open), Close(lose)]
lever_rate int true leverage 1\5\10\20
order_id int true Trigger order ID
order_id_str string true the order ID with string
relation_order_id string true Relation order ID is the string related to the limit orders. The value is -1 before the trigger orders executed.
order_price_type string true order type "limit": Limit order price，"optimal_5": Optimal 5 price level，"optimal_10":Optimal 10 price level，"optimal_20": the Optimal 20 price level
status int true Order status (4:Orders accepted、5: Orders failing being placed、6: Orders canceled )
order_source string true Order source
trigger_price decimal true trigger price
triggered_price decimal true the price when trigger orders executed
order_price decimal true the order price preset by the client
created_at long true the order creation time
triggered_at long true the execution time when orders getting triggered.
order_insert_at long true the time when the triggered orders filled successfully.
canceled_at long true Order cancelation time
fail_code int true the error code when the triggered orders failed to be filled
fail_reason string true the error message with failure reason when triggered orders failed to filled.
</list>

Future Transferring Interface

Transfer margin between Spot account and Future account

Example

Notice

This interface is used to transfer assets between Spot account and Future account.

The type is “pro-to-futures” when transferring assets from Spot account to Future; “futures-to-pro” when transferring from Future account to Spot account.

API rate limit for this interface is 1 times/second.

Transferring margin between Spot account and Future account Interface, sets 8 decimal places for transferring amount of all coins.

Request Parameter

Parameter Name Mandatory Type Desc Default Value Range
currency true string currency. Case insensitive e.g. btc, BTC
amount true Decimal Transferring amount
type true string type of the transfer Transfer from Future account to Spot account: “futures-to-pro” Transfer from Spot account to Future account: "pro-to-futures"

Response:


{
    "status": "ok",
    "data": 179697972
}
Error response:
{
    "status": "error",
    "data": null,
    "err-code": "base-currency-error",
    "err-msg": "The current coin does not exist."
}

Returning Parameter

Parameter Name Mandatory Type Desc Value Range
status true string Response status ok, error
data true long Transfer ID If status="error", data will be null.
err-code true string Error code
err-msg true string Error code description

Error Code Table

err-code err-msg Comments
base-msg Other errors, please refer to err-msg list below for details。
base-currency-error The currency is invalid
frequent-invoke the operation is too frequent. Please try again later
banned-by-blacklist Blacklist restriction
dw-insufficient-balance Insufficient balance. You can only transfer {0} at most.
dw-account-transfer-unavailable account transfer unavailable
dw-account-transfer-error account transfer error
dw-account-transfer-failed Failed to transfer. Please try again later.
dw-account-transfer-failed-account-abnormality Account abnormality, failed to transfer。Please try again later.

Error message when err-code is ‘base-msg’.

err-msg Comments
Unable to transfer in currently. Please contact customer service.
Unable to transfer out currently. Please contact customer service.
Abnormal contracts status. Can’t transfer.
Sub-account doesn't own the permissions to transfer in. Please contact customer service.
Sub-account doesn't own the permissions to transfer out. Please contact customer service.
The sub-account does not have transfer permissions. Please login main account to authorize.
Insufficient amount available. Insufficient amount of Future Contract Account
The single transfer-out amount must be no less than {0}{1}.
The single transfer-out amount must be no more than {0}{1}.
The single transfer-in amount must be no less than {0}{1}.
The single transfer-in amount must be no more than {0}{1}.
Your accumulative transfer-out amount is over the daily maximum, {0}{1}. You can't transfer out for the time being.
Your accumulative transfer-in amount is over the daily maximum, {0}{1}. You can't transfer in for the time being.
Your accumulative net transfer-out amount is over the daily maximum, {0}{1}. You can't transfer out for the time being.
Your accumulative net transfer-in amount is over the daily maximum, {0}{1}. You can't transfer in for the time being.
The platform's accumulative transfer-out amount is over the daily maximum. You can't transfer out for the time being.
The platform's accumulative transfer-in amount is over the daily maximum. You can't transfer in for the time being.
The platform's accumulative net transfer-out amount is over the daily maximum. You can't transfer out for the time being.
The platform's accumulative net transfer-in amount is over the daily maximum. You can't transfer in for the time being.
Transfer failed. Please try again later or contact customer service.
Abnormal service, transfer failed. Please try again later.
You don’t have access permission as you have not opened contracts trading.
This contract type doesn't exist.

Future WebSocket Reference

API List

Permission Content Type Request Method Type Description Authentication Required
Read Market Data Interface market.$symbol.kline.$period sub Subscribe Kline data No
Read Market Data Interface market.$symbol.kline.$period req Request Kline Data Nos
Read Market Data Interface market.$symbol.depth.$type sub Subscribe Market Depth Data No
Read Market Data Interface market.$symbol.depth.size_${size}.high_freq sub Subscribe Incremental Market Depth Data No
Read Market Data Interface market.$symbol.bbo sub Subscribe BBO Data No
Read Market Data Interface market.$symbol.detail sub Subscribe Market Detail Data No
Read Market Data Interface market.$symbol.trade.detail req Request Trade Detail Data No
Read Market Data Interface market.$symbol.trade.detail sub Subscribe Trade Detail Data No
Read System Status Interface public.$service.heartbeat sub Subscription system status updates No
Trade Trade Interface orders.$symbol sub Subscribe Order Data Yes
Trade Trade Interface matchOrders.$symbol sub Subscribe Order Data Yes
Read Account Interface accounts.$symbol sub Subscribe asset change Information of a given coin Yes
Read Account Interface positions.$symbol sub Subscribe position change Information of a given coin Yes
Read Account Interface trigger_order.$symbol sub Subscribe trigger orders updates Yes
Read Trade Interface public.$symbol.liquidation_orders sub Subscribe liquidation Order information of a given coin Yes

Huobi Future WebSocket Subscription Address

Market Data Request and Subscription: wss://api.hbdm.com/ws

Order Push Subscription: wss://api.hbdm.com/notification

Index Kline Data and Basis Data Subscription: wss://api.hbdm.com/ws_index

System status updates subscription ：wss://api.hbdm.com/center-notification

If the url: api.hbdm.com can't be accessed, please use the url below:

Market Data Request and Subscription Address: wss://api.btcgateway.pro/ws;

Order Push Subscription：wss://api.btcgateway.pro/notification

Index Kline Data and Basis Data Subscription: wss://api.btcgateway.pro/ws_index

System status updates subscription ：wss://api.btcgateway.pro/center-notification

If you have further queries about Huobi Future order push subscription, please refer to Demo

Note:

If you can't connect "https://api.hbdm.com", please use "https://api.btcgateway.pro" for debug purpose. If your server is deployed in AWS, we recommend using "https://api.hbdm.vn".

API Rate Limit Illustration

There is rate limit for both public and private interfaces. More details are laid out as below:

(1) For restful interface：800 times/second for one IP at most

(2) The rate limit for “req” request is 50 times/s at most. No limit for “sub” request as the data will be pushed by server voluntarily.

Note: The rate limit of WS order push and RESTFUL private interface are separated from each other with no relations.

Response the following strings for “Header” via API

WebSocket Heartbeat and Authentication Interface

Market Heartbeat

WebSocket API supports two-way heartbeat. Both Server and Client can send ping message, which the opposite side can return with pong message.

{"ping": 18212558000}

{"pong": 18212558000}

Note: Once the WebSocket Client and WebSocket Server get connected, the server will send a heartbeat every 5 seconds (the frequency might change). The connection will get disconnected automatically if the WebSocket Client ignores the heartbeat message for 5 times. The server will remain connection if the WebSocket Client responds one “ping” value within the latest 2 heartbeat messages.

Order Push Heartbeat

WebSocket API supports one-way heartbeat. The Server initiates ping message and the Client will return pong message. The Server sends back a heartbeat:

{

"op": "ping",

"ts": "1492420473058"

}

{

"op": "pong",

"ts": "1492420473058"

}

Note

{

"op": "pong"

"ts": "1492420473027",

"err-code": 2011,

"err-msg": “detailed error message”

}

{

"op": "close", // indicate Websocket Server disconnected automatically

"ts": long // The local timestamp of Server push

}

{

"op": "error", // indicate that receive illegal Op or internal error

"ts": long// The local timestamp of Server push

}

Order Push Address

wss://api.hbdm.com/notification

Note:

If you can't connect "https://api.hbdm.com", please use "https://api.btcgateway.pro" for debug purpose. If your server is deployed in AWS, we recommend using "https://api.hbdm.vn".

Please note that the WS request connection should not go over 30 normally.

Data Compression

All response data from WebSocket server are compressed into GZIP format. Clients have to decompress them for further use.

Illustration of Request(req and rep) Data

-All request data has fixed format. Please note that Huobi Future API document will only focus on data illustration in non-fixed format.

Request data format is laid out as below:


  {
  "op": string, // Required; Client requests operator name (Server will returns the same value), For detailed operator name list, please refer to the appendix
  "cid": string, // Optional;Request unique ID( Client generate a unique ID which server will return the same value)
  // Others required/ Optional string
  }

All responses push data will be returned in fixed format，Huobi Future API document will only focus on data illustration， Response data format is laid out as below；


  {
  "op": string, // Required; Clients request operator name
  "cid": string, // optional; Client requests unique ID
  "ts": long, // required; Server responds local timestamp
  "err-code": integer, // required; return error code, “0” means successfully responded, others means error. For detailed return error code list, please refer to appendix
  "err-msg": string, only responds error message when error occurs, detailed error information. 
  "data": object // optional; return data object， request valid data after error removed 
  }

Push Data Format is laid out as below:


  {
  "op": "string", // required;Server pushes operator name, For detailed operator type list, please refer to appendix
  "ts": long, // required; Server pushes local timestamp
  "data": object // required;返return data object
  }

Server voluntarily disconnects connection

During making connection and authentication, server will disconnect connection automatically when error occurs. Before disconnecting, server will send notification below,

{

`"op": "close", // represents server disconnect connection voluntarily

`"ts": long // Server pushes local timestamp

}

Server return error code but remain connection

After authentication, if clients encountered internal error or request data out from Operator List, WebSocket server will return error message. But server will remain connection

{

"op": "error", // means server receive data out from Operator List or clients got internal error

"ts": long// Server pushes local timestamp

}

Authentication

Clients can create Access Key and Secret Key on Huobi which Access Key is the API access key kept by the client. The Secret Key is used to sign the request (available only for request). To apply/change API key, please go to “Account-API Management” on Huobi Futures. Make name for the API Key and click “create” to finish. It’s optional to bind IP address to the API Key.

For the Trade WebSocket interface, server have to do authentication for topics require authentication before making connection.

Note: These two keys are closely related to account security and should not be disclosed to others at any time.

Authentication Format Example:

{

"op": "auth",

"type": "api",

"AccessKeyId": "e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx",

"SignatureMethod": "HmacSHA256",

"SignatureVersion": "2",

"Timestamp": "2017-05-11T15:19:30",

"Signature": "4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=",

}

Illustration on Authentication Format Data

Field type Description
op string required； Operator type， Requested authentication operator type is auth
type string required； Signature method sign via API means API interface signature, sign via ticket means terminal signature
cid string Optional； Client requests the unique ID
AccessKeyId string required if users use API signature； API Access key is the API AccessKey you applied.
SignatureMethod string required if users use API signature； Signature method, user computes signature basing on the protocol of hash ,the API uses HmacSHA256
SignatureVersion string required if the users use API signature； the signature protocol version, the API uses 2
Timestamp string required if users use API signature； timestamp, the time you request(UTC timezone) this value can help to avoid request data interception by the third party for example ：2017-05-11T16:22:06 (UTC time zone)
Signature string required if the users use API signature； signature, the value computed is ensure valid authentication without being tampered
ticket string required if users use ticket signature ； return when logged in

Notice：

Signature Illustration：

Example on Signature Computing Process:，

GET\n

api.hbdm.com\n

/notification\n

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30

Signature Computing, transmit the two parameters below into cryptographic hash: strings needed to be computed, API SecretKey. Get the signature computing result and get it encoded with Base 64 code standard.

Add computed value into the Signature parameter in API request. Please note the computed value SHOULD NOT be encoded into URL cdoe.

Authentication Response Format Illustration

Field type description
op string required； Operator type， Authentication response type is auth
type string required； Return data according to the requested parameters
cid string optional； Return data when “cid” string requested
err-code integer 0 means successfully response, others means response failure成功返回 0 , For detailed Response code（Err-Code）, please refer to appendix
err-msg string optional， response detailed error code when error occurs
ts long server responds timestamp
user-id long client ID

Example of A Success Authentication Response


{
  "op": "auth",
  "type":"api",
  "ts": 1489474081631,
  "err-code": 0,
  "data": {
    "user-id": 12345678
  }
}

Example of Authentication Response with Error


{
"op": "auth",
"type":"api",
"ts": 1489474081631, 
"err-code": xxxx， 
"err-msg" : "Error details "
}

WebSocket Market Interface

Subscribe Kline data

To subscribe Kline data, clients have to connect WebSocket API server and send subscribe request with the format below：

{

"sub": "market.$symbol.kline.$period",

"id": "id generate by client"

}

Example of a successful subscription request：


    {
    "sub": "market.BTC_CQ.kline.1min",
    "id": "id1"
    }

Request Parameter

Parameter Name Mandatory Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$symbol.kline.$period，For parameter details please check sub Subscribe Parameter Rules
id false string id automatically generated by the business party

sub Subscribe Parameter Rules

Parameter Name Mandatory Type Description Default Value Range
symbol true string Pairs Case-Insenstive.Both uppercase and lowercase are supported..E.G.: "BTC_CW" stands for BTC weekly contract, "BTC_NW" stands for BTC Bi-weekly contract, "BTC_CQ" stands for BTC quarterly contract."BTC_NQ" stands for BTC next quarterly contract. contract code is supported too, e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)
period true string Kline Period Case-Senstive.Only lowercase is supported. 1min, 5min, 15min, 30min, 60min,4hour,1day,1week, 1mon

After subscription, clients can receive updates upon any change. Example:


{
    "ch":"market.BTC_CW.kline.1min",
    "ts":1604385120328,
    "tick":{
        "id":1604385120,
        "mrid":113842458873,
        "open":13436.12,
        "close":13436.12,
        "high":13436.12,
        "low":13436.12,
        "amount":0,
        "vol":0,
        "count":0
    }
}

Return Parameter

Parameter Name Mandatory Type Description
ch true string Request Parameter
ts true long Time of Respond Generation，Unit：Millisecond
<tick>
id true long kline id,the same as kline timestamp, kline start timestamp
mrid true long Order ID
vol true decimal Trade Volume(Cont.)
count true decimal Order Quantity
open true decimal Open Price
close true decimal Clos Price, the price in the last kline is the latest order price
low true decimal Low Price
high true decimal High Price
amount true decimal Trade Amount(Coin), trade amount(coin)=sum(order quantity of a single order * face value of the coin/order price)
</tick>

Request Kline data

To request Kline data, clients have to make connection to WebSocket API Server and send subscribe request in the format below：

{

"req": "market.$symbol.kline.$period",

"id": "id generated by client",

"from": " type: long, the time from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00, unit: s",

"to": "type: long, the time from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00, unit: s , the 'to' value should be larger than 'from' value"

}

Example of Kline Data Subscription Request：


{
    "req": "market.BTC_CQ.kline.1min",
    "id": "id4",
    "from": 1571000000,
    "to": 1573106298
}

Request Parameter

Parameter Name Mandatory Type Desc
req true string the themes that need to be subscribed; the interface is fixed at: market.$symbol.kline.$period，For parameter details please check req Subscribe Parameter Rules
id false string id automatically generated by the business party
from true long Start Time
to true long End Time

req Subscribe Parameter Rules

Parameter Name Mandatory Type Description Default Value Range
symbol true string Pairs Case-Insenstive.Both uppercase and lowercase are supported..E.g.: "BTC_CW" stands for BTC weekly contract, "BTC_NW" stands for BTC bi-weekly contract, "BTC_CQ" stands for BTC quarterly contract."BTC_NQ" stands for BTC next quarterly contract. contract code is supported too, e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly).
period false string Kline Period Case-Senstive.Only lowercase is supported.1min, 5min, 15min, 30min, 60min,4hour,1day,1week, 1mon

Note

If between time range [t1, t5], there are t1-t5 Klines in quantity.

from: t1, to: t5, return [t1, t5].

from: t5, to: t1, which t5 > t1, return [].

from: t5, return [t5].

from: t3, return [t3, t5].

to: t5, return [t1, t5].

from: t which t3 < t <t4, return [t4, t5].

to: t which t3 < t <t4, return [t1, t3].

from: t1 and to: t2, should satisfy 1325347200 < t1 < t2 < 2524579200.

Clients can request 2000 Klines at most in one request

After subscription, Clients can receive the most recent data upon any update：


{
    "id":"id4",
    "rep":"market.BTC_CQ.kline.15min",
    "wsid":498385304,
    "status":"ok",
    "data":[
        {
            "id":1599667200,
            "open":10262.31,
            "close":10244.93,
            "low":10234.84,
            "high":10282,
            "amount":1849.4984536479908439463088799853871134642,
            "vol":189634,
            "count":5342
        },
        {
            "id":1599668100,
            "open":10244.94,
            "close":10242.07,
            "low":10216.55,
            "high":10244.94,
            "amount":1586.9623024248859129381285787325037896282,
            "vol":162334,
            "count":4375
        }
    ]
}

Return Parameter

Parameter Name Mandatory Type Description
rep true string Request Parameter
status true string status
id true string Request ID
wsid true long wsid
<data>
id true long kline id,the same as kline timestamp, kline start timestamp
vol true decimal Trade Volume(Cont.)
count true decimal Order quantity
open true decimal Open Price
close true decimal Clos Price, the price in the latest Kline is the last order price
low true decimal Low Price
high true decimal High Price
amount true decimal Trade Amount(Coin), trade amount(coins)=sum(order quantity of a single order * face value of the coin/order price)
</data>

Subscribe Market Depth Data

To subscribe market depth data, clients have to make connection to WebSocket API Server and send subscribe request in the format below：

{

"sub": "market.$symbol.depth.$type",

"id": "id generated by client"

}

Example of a successful request ：


    {
    "sub": "market.BTC_CQ.depth.step0",
    "id": "id5"
    }

Request Parameter

Parameter Name Mandatory Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$symbol.depth.$type，For parameter details please check sub Subscribe Parameter Rules
id false string id automatically generated by the business party

sub Subscribe Parameter Rules

Parameter Name Mandatory Type Description Default Value Range
symbol true string Pairs Case-Insenstive.Both uppercase and lowercase are supported..E.g.: "BTC_CW" stands for BTC weekly contract, "BTC_NW" stands for BTC bi-weekly contract, "BTC_CQ" stands for BTC quarterly contract."BTC_NQ" stands for BTC next quarterly contract. contract code is supported too, e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)
type true string Depth Type Get depth data within step 150, use step0, step1, step2, step3, step4, step5, step14, step15（merged depth data 0-5, 14-15）；when step is 0，depth data will not be merged; Get depth data within step 20, use step6, step7, step8, step9, step10, step11, step12, step13(merged depth data 7-13); when step is 6, depth data will not be merged.

Note:

Depth precision
step1、step7 0.00001
step2、step8 0.0001
step3、step9 0.001
step4、step10 0.01
step5、step11 0.1
step14、step12 1
step15、step13 10

Clients can receive data if there is any update upon market depth. Example：


{
    "ch":"market.BTC_CQ.depth.step6",
    "ts":1604385453899,
    "tick":{
        "mrid":113842765361,
        "id":1604385453,
        "bids":[
            [
                13584.33,
                1483
            ],
            [
                13584,
                1
            ]
        ],
        "asks":[
            [
                13584.34,
                126
            ],
            [
                13584.35,
                24
            ]
        ],
        "ts":1604385453896,
        "version":1604385453,
        "ch":"market.BTC_CQ.depth.step6"
    }
}

Return Parameter

Parameter Name Mandatory Type Description Value Range
ts true long Time of Respond Generation, Unit: Millisecond
ch true string Data channel, Format： market.period
<tick>
mrid true long Order ID
id true ling tick ID
asks true object Sell,[price(Ask price), vol(Ask orders (cont.) )], price in ascending sequence
bids true object Buy,[price(Bid price), vol(Bid orders(Cont.))], Price in descending sequence
ts true long Timestamp for depth generation; generated once every 100ms, unit: millisecond
version true long version ID
ch true string Data channel, Format： market.period
</tick>

Subscribe Incremental Market Depth Data

To subscribe incremental market depth data, clients have to make connection to WebSocket API Server and send subscribe request in the format below：

{

"sub": "market.$symbol.depth.size_${size}.high_freq",

"data_type":"incremental",

"id": "id generated by client"

}

Example of a successful request


{
  "sub": "market.btc_cw.depth.size_20.high_freq",
  "data_type":"incremental",
  "id": "id generated by client"
}

Request Parameter

Parameter Name Mandatory Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$symbol.depth.size_${size}.high_freq，For parameter details please check sub Subscribe Parameter Rules
id false string id automatically generated by the business party
data_type false string Depth size

sub Request Parameter Rules

Parameter Name Mandatory Type Description Default Value Range
symbol true string Pairs Case-Insenstive.Both uppercase and lowercase are supported.. E.g.: "BTC_CW" stands for BTC weekly contract, "BTC_NW" stands for BTC bi-weekly contract, "BTC_CQ" stands for BTC quarterly contract."BTC_NQ" stands for BTC next quarterly contract. contract code is supported too, e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)
size true integer Depth size. 20: stands for 20 unmerged data. 150:stands for 150 unmerged data.

Return Parameter

Parameter Name Mandatory Type Description Value Range
ts true int Timestamp of Respond Generation, Unit: Millisecond
ch true string Data channel, Format：market.$symbol.depth.size_${size}.high_freq
<tick>
mrid true long Order ID
id true long tick ID
asks true object Sell,[price(Ask price), vol(Ask orders (cont.) )], price in ascending sequence
bids true object Buy,[price(Bid price), vol(Bid orders(Cont.))], Price in descending sequence
ts true int Timepoint for system detecting orderbook, unit: millisecond
version true long version ID,auto increment ID.
event true string event type: update or snapshot
ch true string Data channel, Format： market.$symbol.depth.size_${size}.high_freq
</tick>

Note:

Response example:


{
    "ch":"market.BTC_CQ.depth.size_20.high_freq",
    "tick":{
        "asks":[
            [
                13576.41,
                2627
            ],
            [
                13576.53,
                122
            ]
        ],
        "bids":[
            [
                13576.4,
                1648
            ],
            [
                13574.17,
                398
            ]
        ],
        "ch":"market.BTC_CQ.depth.size_20.high_freq",
        "event":"snapshot",
        "id":113842925649,
        "mrid":113842925649,
        "ts":1604385634838,
        "version":330099154
    },
    "ts":1604385634838
}

Subscribe Market BBO Data

To subscribe market BBO data, clients have to make connection to WebSocket API Server and send subscribe request in the format below：

{

"sub": "market.$symbol.bbo",

"id": "id generated by client"

}

Example of a successful request


{
  "sub": "market.$symbol.bbo",
  "id": "id generated by client"
}

Request Parameter

Parameter Name Mandatory Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$symbol.bbo，For parameter details please check sub Subscribe Parameter Rules
id false string id automatically generated by the business party

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol true string Pairs Case-Insenstive.Both uppercase and lowercase are supported.. E.g.: "BTC190412" stands for BTC contract with the the delivery date of 20190412, "BTC_CW" stands for BTC weekly contract, "BTC_NW" stands for BTC bi-weekly contract, "BTC_CQ" stands for BTC quarterly contract."BTC_NQ" stands for BTC next quarterly contract. contract code is supported too, e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)

Response:


{
    "ch":"market.BTC_CQ.bbo",
    "ts":1604385767803,
    "tick":{
        "mrid":113843014986,
        "id":1604385767,
        "bid":[
            13579.06,
            1488
        ],
        "ask":[
            13579.07,
            1535
        ],
        "ts":1604385767803,
        "version":113843014986,
        "ch":"market.BTC_CQ.bbo"
    }
}

Return Parameter

Parameter Name Mandatory Type Description Value Range
ts true int Timestamp of Respond Generation, Unit: Millisecond
ch true string Data channel, Format：market.$symbol.bbo
<tick>
mrid true long Order ID
id true long tick ID
ask true object Best Ask Quotation,[price(Ask price), vol(Ask order (cont.) )]
bid true object Best Bid Quotation,[price(Bid price), vol(Bid order(Cont.))]
ts true long Time of Respond Generation, Unit: Millisecond
version true long version ID.
ch true string Data channel, Format： market.$symbol.bbo
</tick>

Note:

Subscribe Market Detail Data

To subscribe market details, the clients have to make connection to WebSocket Server and send subscribe request in the format below:

{

"sub": "market.$symbol.detail",

"id": "id generated by client"

}

Example of Subscribe Market Detail Data：


    {
     "sub": "market.BTC_CQ.detail",
     "id": "id6"
    }

Request Parameter

Parameter Name Mandatory Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$symbol.detail，For parameter details please check sub Subscribe Parameter Rules
id false string id automatically generated by the business party

sub Subscribe Parameter Rules

Parameter Name Mandatory Type Description Default Value Range
symbol true string Pairs Case-Insenstive.Both uppercase and lowercase are supported..E.g.： "BTC_CW" stands for BTC Weekly contract, "BTC_NW" stands for BTC Bi-weekly contract, "BTC_CQ" stands for BTC Quarterly contract,"BTC_NQ" stands for BTC next quarterly contract. contract code is supported too, e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)

Return Parameter

Parameter Name Mandatory Type Description
ch true string Data channel，Format： market.$symbol.detail.merged
ts true long Time of Respond Generation, Unit: Millisecond
<tick>
id true long ID
mrid true long Order ID
open true decimal Open Price
close true decimal Clos Price, the price from the latest kline is the last order price
high true decimal High Price
low true decimal Low Price
amount true decimal Trade amount(Coins), Trade amount(Coin)=SUM(quantity(cont.)*face value/ order price
vol true decimal Trade amount(Cont.)， the sum volume of both buy and sell sides
count true decimal fulfilled order quantity
</tick>

Example of a successful return data：


{
    "ch":"market.BTC_CQ.detail",
    "ts":1604385863717,
    "tick":{
        "id":1604385840,
        "mrid":113843084999,
        "open":13607.17,
        "close":13589,
        "high":13830.63,
        "low":13411.89,
        "amount":261417.4288915740193389700120854767791857974,
        "vol":35572590,
        "count":586972
    }
}

Request Trade Detail Data

To request Trade detail data, Clients have to make connection to the WebSocket Server and send request data in the format below：

{

"req": "market.$symbol.trade.detail",

"id": "id generated by client" // “id” string is optional currently. Server will return with null because client ID is not necessary

}

Return to the current trade detail data only

Example of requesting market detail data：



    {
     "req": "market.BTC_CQ.trade.detail",
     "size": 10,
     "id": "id8"
    }

Subscribe Parameter

Parameter Name Mandatory Type Description Default
req true string Theme for Requesting Data; the interface is fixed at: market.$symbol.trade.detail; for details of the parameter please check req Request Parameter Rules
id false string id automatically generated by the business party
size false int number of data; no more than 50; default 50 if not filled [1,50]

req Request Parameter Rules

Parameter Name Mandatory Type Description Default Value Range
symbol true string contract type Case-Insenstive.Both uppercase and lowercase are supported..E.g.: "BTC_CW" stands for BTC weekly contract, "BTC_NW" stands for BTC bi-weekly contract, "BTC_CQ" stands for BTC quarterly contract."BTC_NQ" stands for BTC next quarterly contract. contract code is supported too, e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)

Example of a successful return data：


{
    "data":[
        {
            "amount":"4",
            "ts":1604386167285,
            "id":1138433247400000,
            "price":"13586.25",
            "direction":"buy"
        },
        {
            "amount":"20",
            "ts":1604386167469,
            "id":1138433248730000,
            "price":"13586.25",
            "direction":"buy"
        }
    ],
    "id":"id8",
    "rep":"market.BTC_CQ.trade.detail",
    "status":"ok",
    "ts":1604386202755
}

Return Parameter

Parameter Name Mandatory Type Description Default
rep true string Data Channel，Format： market.$symbol.trade.detail
status true string Request Status
id true string Request ID
<data>
id true long Unique Transaction Id(symbol level)
price true string Price
amount true string Trade amount(Coin), trade amount(coin)=sum(order quantity of a single order * face value of the coin/order price)
direction true string Active transaction direction
ts true long Order Creation Time
</data>
ts true long server response time

Subscribe Trade Detail Data

To subscribe trade detail data, the Client has to make connection to the Server and send subscribe request in the format below：

{

"sub": "market.$symbol.trade.detail",

"id": "id generated by client"

}

Example of a successful subscribe request：


    {
     "sub": "market.BTC_CQ.trade.detail",
     "id": "id7"
    }

Request Parameter

Parameter Name Mandatory Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at:market.$symbol.trade.detail，For parameter details please check sub Subscribe Parameter Rules
id false string id automatically generated by the business party

sub Subscribe Parameter Rules

Parameter Name Mandatory Type Description Default Value Range
symbol true string contract type Case-Insenstive.Both uppercase and lowercase are supported..E.g.: "BTC_CW" stands for BTC weekly contract, "BTC_NW" stands for BTC bi-weekly contract, "BTC_CQ" stands for BTC quarterly contract."BTC_NQ" stands for BTC next quarterly contract. contract code is supported too, e.g.: "BTC200918"(weekly), "BTC200925"(Bi-weekly),"BTC201225"(quarterly),"BTC210326"(next quarterly)

Return Parameter

Parameter Name Mandatory Type Description Default
ch true string Data channel,format: market.$symbol.trade.detail
ts true long server response time
<tick>
id true long Unique Order Id(symbol level).
ts true long tick time
<data>
amount true decimal quantity(Cont.)
ts true long trade timestamp
id true long Unique Transaction Id(symbol level)
price true decimal Price
direction true string Order direction
</data>
</tick>

When there is any update upon trade detail data, clients will receive notification from server. Example：


{
    "ch":"market.BTC_CQ.trade.detail",
    "ts":1604386599136,
    "tick":{
        "id":113843672389,
        "ts":1604386599123,
        "data":[
            {
                "amount":120,
                "ts":1604386599123,
                "id":1138436723890000,
                "price":13562.5,
                "direction":"sell"
            },
            {
                "amount":2,
                "ts":1604386599123,
                "id":1138436723890001,
                "price":13562.5,
                "direction":"sell"
            }
        ]
    }
}

WebSocket Index and Basis Interface

The websocket url of Index and Basis Data is：wss://api.hbdm.com/ws_index

Subcribe Index Kline Data

To subscribe index kline data, the Client has to make connection to the Server and send subscribe request in the format below:

{

"sub": "market.$symbol.index.$period",

"id": "id generate by client"

}

example of the subscription of index kline data：


    {
    "sub": "market.BTC-USD.index.1min",
    "id": "id1"
    }

Request Parameter

Parameter Name Mandatory Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$symbol.index.$period，For parameter details please check sub Subscribe Parameter Rules
id false string id automatically generated by the business party

sub Subscribe Parameter Rules

Parameter Name Mandatory Type Desc Default Value Range
symbol true string index symbol Case-Insenstive.Both uppercase and lowercase are supported.."BTC-USD","ETH-USD"...
period true string kline type 1min, 5min, 15min, 30min, 60min,4hour,1day, 1mon

Note

results pushed by the server


{
    "ch":"market.BTC-USD.index.1min",
    "ts":1604387688243,
    "tick":{
        "id":1604387640,
        "open":"13419.4325",
        "close":"13420.3325",
        "high":"13424.4925",
        "low":"13419.4325",
        "amount":"0",
        "vol":"0",
        "count":0
    }
}

Returning Parameter

parameter name Mandatory type desc Value Range
ch true string Data channel，Format：market.$symbol.index.$period
tick true object array Details：tick parameters
ts true long Time of Respond Generation, Unit: Millisecond

tick parameters

parameter name type desc
id string index kline id,the same as kline timestamp,kline start timestamp
vol string Trade Volume. The value is 0.
count decimal count. The value is 0.
open string open index price
close string close index price
low string lowest index price
high string highest index price
amount string amount based on coins.

Request Index Kline Data

To subscribe index kline data, the Client has to make connection to the Server and send subscribe request in the format below:

{

"req": "market.$symbol.index.$period",

"id": "id generated by client",

"from": "type: long, from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00",

"to": "type: long, from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00 .Larger than 'from' value. ",

}

example of the subscription of index kline data：


  {
    "req": "market.bct_cw.index.1min",
    "id": "id4",
    "from":1571000000,
    "to":1573098606
  }

Request Parameter

Parameter Name Mandatory Type Desc
req true string the themes that need to be subscribed; the interface is fixed at: market.$symbol.index.$period，For parameter details please check req Subscribe Parameter Rules
id false string id automatically generated by the business party
from true long start time, from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00. timestamp unit：seconds
to true long end time, from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00. timestamp unit：seconds. larger than 'from' value

req Subscribe Parameter Rules：

Parameter Name Mandotary Type Desc Default Value Range
symbol true string symbol Case-Insenstive.Both uppercase and lowercase are supported.."BTC-USD","ETH-USD"...
period true string kline type 1min, 5min, 15min, 30min, 60min,4hour,1day, 1mon

Note：

response example：


{
    "id":"id4",
    "rep":"market.BTC-USD.index.60min",
    "wsid":915217437,
    "status":"ok",
    "data":[
        {
            "id":1604160000,
            "open":13862.65,
            "close":13832.615,
            "low":13822.41,
            "high":13890.2225,
            "amount":0,
            "vol":0,
            "count":0
        },
        {
            "id":1604163600,
            "open":13832.7725,
            "close":13788.6625,
            "low":13751.9075,
            "high":13833.41,
            "amount":0,
            "vol":0,
            "count":0
        }
    ]
}

Returning Parameter

parameter name Mandatory type desc Value Range
req true string Data channel，Format：market.$symbol.index.$period
status true string Request processing result "ok" , "error"
id true string ID
wsid true long wsid
ts true long Time of Respond Generation, Unit: Millisecond
data true object array Details：data parameters

data parameters

parameter name type desc
id int index kline id,the same as kline timestamp,kline start timestamp
vol decimal Trade Volume. The value is 0.
count decimal count. The value is 0.
open decimal open index price
close decimal close index price
low decimal lowest index price
high decimal highest index price
amount decimal amount based on coins.

Subscribe Basis Data

To subscribe basis data, the Client has to make connection to the Server and send subscribe request in the format below:

{

"sub": "market.$symbol.basis.$period.$basis_price_type",

"id": "id generate by client"

}

example of the subscription of basis data：


    {
    "sub": "market.BTC_CW.basis.1min.open",
    "id": "id1"
    }

Request Parameter

Parameter Name Mandatory Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$symbol.basis.$period.$basis_price_type，For parameter details please check sub Subscribe Parameter Rules
id false string id automatically generated by the business party

sub Subscribe Parameter Rules：

Parameter Name Mandotary Type Desc Default Value Range
symbol true string symbol name Case-Insenstive.Both uppercase and lowercase are supported..e.g. "BTC_CW" represents BTC “This Week”，"BTC_NW" represents BTC “Next Week”，"BTC_CQ" represents BTC “Quarter”."BTC_NQ" represents BTC “Next Quarter”.
period true string kline period 1min,5min, 15min, 30min, 60min,4hour,1day,1mon
basis_price_type false string use basis price type to calculate the basis data Using open price default open price："open"，close price："close"，highest price："high"，lowest price："low"，avg=（high price +low price）/2："average"

Note:

Response Example


{
    "ch":"market.BTC_CW.basis.5min.close",
    "ts":1604387856115,
    "tick":{
        "id":1604387700,
        "index_price":"13434.5075",
        "contract_price":"13454.01",
        "basis":"19.5025",
        "basis_rate":"0.0014516721212147151654052074480586653"
    }
}

Returning Parameter

parameter name Mandatory type desc Value Range
ch true string Data channel，Format：market.$symbol.basis.$period.$basis_price_type
tick true object array Details：tick parameters
ts true long Time of Respond Generation, Unit: Millisecond

tick Parameters

parameter name Mandatory Type Desc Value Range
id true long unique id
contract_price true string contract last price
index_price true string index price
basis true string basis=contract_price - index_price
basis_rate true string basis_rate=basis/index_price

Request Basis Data

To subscribe basis data, the Client has to make connection to the Server and send subscribe request in the format below:

{

"req": "market.$symbol.basis.$period.$basis_price_type",

"id": "id generated by client",

"from": "type: long, from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00",

"to": "type: long, from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00 .Larger than 'from' value. "

}

example of the subscription of basis data：


  {
    "req": "market.btc_cw.basis.1min.open",
    "id": "id4",
    "from":1571000000,
    "to":1573098606
  }

Request Parameter

Parameter Name Mandatory Type Desc
req true string the themes that need to be subscribed; the interface is fixed at: market.$symbol.basis.$period.$basis_price_type，For parameter details please check req Subscribe Parameter Rules
id false string id automatically generated by the business party
from true long start time, from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00. timestamp unit：seconds
to true long end time, from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00. timestamp unit：seconds. larger than 'from' value

req Subscribe Parameter Rules：

Parameter Name Mandotary Type Desc Default Value Range
symbol true string symbol name Case-Insenstive.Both uppercase and lowercase are supported..e.g. "BTC_CW" represents BTC “This Week”，"BTC_NW" represents BTC “Next Week”，"BTC_CQ" represents BTC “Quarter”."BTC_NQ" represents BTC “Next Quarter”.
period true string kline type 1min, 5min, 15min, 30min, 60min,4hour,1day, 1mon
basis_price_type false string use basis price type to calculate the basis data Using open price default open price："open"，close price："close"，highest price："high"，lowest price："low"，avg=（high price +low price）/2："average"

Note：

response example：


{
    "data":[
        {
            "basis":"20.357500000000073",
            "basis_rate":"0.0014671752201438544",
            "contract_price":"13895.66",
            "id":1604160000,
            "index_price":"13875.3025"
        },
        {
            "basis":"20.13249999999971",
            "basis_rate":"0.001454177342461542",
            "contract_price":"13864.73",
            "id":1604160300,
            "index_price":"13844.5975"
        }
    ],
    "id":"id4",
    "rep":"market.BTC_CW.basis.5min.close",
    "status":"ok",
    "ts":1604387965575,
    "wsid":3823737955
}

Returning Parameter

parameter name Mandatory type desc Value Range
req true string Data channel，Format：market.$symbol.basis.$period.$basis_price_type
status true string Request processing result "ok" , "error"
id true string ID
wsid true long wsid
ts true long Time of Respond Generation, Unit: Millisecond
tick true object array Details：tick parameters

tick Parameters

parameter name Mandatory Type Desc Value Range
id true long unique id
contract_price true string contract last price
index_price true string index price
basis true string basis=contract_price - index_price
basis_rate true string basis_rate=basis/index_price

Orders and Accounts WebSocket Interfaces

Subscribe Order Data(sub)

To subscribe order data, Clients have to make connection to the Server and send subscribe request in the format below:

Subscribe Request Format

{

“op”: “sub”,

"cid": "id generated by client”,

“topic": "orders.$symbol”

}

Example of a successful subscribe request:


{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "orders.btc"
}

Data format illustration of orders subscription

Field Name Type Description
op string Required； Operator Name，required subscribe value is sub
cid string Optional; ID Client requests unique ID
topic string Required；Topic name format: orders.$symbol; symbol is case-insenstive.Both uppercase and lowercase are supported. e.g.:"BTC,ETH"

Note:

Illustration on detailed data format of orders Notification


{
    "op":"notify",
    "topic":"orders.ada",
    "ts":1604388667226,
    "symbol":"ADA",
    "contract_type":"quarter",
    "contract_code":"ADA201225",
    "volume":1,
    "price":0.0905,
    "order_price_type":"post_only",
    "direction":"sell",
    "offset":"open",
    "status":6,
    "lever_rate":20,
    "order_id":773207641127878656,
    "order_id_str":"773207641127878656",
    "client_order_id":null,
    "order_source":"web",
    "order_type":1,
    "created_at":1604388667146,
    "trade_volume":1,
    "trade_turnover":10,
    "fee":-0.022099447513812154,
    "trade_avg_price":0.0905,
    "margin_frozen":0,
    "profit":0,
    "trade":[
        {
            "trade_fee":-0.022099447513812154,
            "fee_asset":"ADA",
            "trade_id":113913755890,
            "id":"113913755890-773207641127878656-1",
            "trade_volume":1,
            "trade_price":0.0905,
            "trade_turnover":10,
            "created_at":1604388667194,
            "role":"maker"
        }
    ],
    "canceled_at":0,
    "fee_asset":"ADA",
    "uid":"123456789",
    "liquidation_type":"0"
}

Format Illustration on return data of order push

Filed Name Type Description
op string Required;Operator Name，Order push value is notify ;
topic string Required; Order push topic
uid string account uid
ts long Server responses timestamp
symbol string Coin
contract_type string Contract Type
contract_code string Contract Code
volume decimal Order quantity
price decimal Order price
order_price_type string Order price type "limit":Limit,"opponent":opponent,"post_only":Post-Only Order, No order limit but position limit for post-only orders.，"lightning":lightning, "optimal_5":optimal 5，"optimal_10":optimal 10，"optimal_20":optimal 20，"fok":FOK Order，"ioc":IOC Order, "opponent_ioc": opponent ioc，"lightning_ioc": lightning ioc，"optimal_5_ioc": optimal_5 ioc，"optimal_10_ioc": optimal_10 ioc，"optimal_20_ioc"：optimal_20 ioc，"opponent_fok"： opponent fok，"lightning_fok"：lightning fok，"optimal_5_fok"：optimal_5 fok，"optimal_10_fok"：optimal_10 fok，"optimal_20_fok"：optimal_20 fok
direction string "buy" Long "sell": Short
offset string "open": Open "close": Close
status int Order status(1. Placing orders to order book; 2 Placing orders to order book; 3. Placed to order book 4. Partially fulfilled; 5 partially fulfilled but cancelled by client; 6. Fully fulfilled; 7. Cancelled;)
lever_rate int Leverage
order_id long Order ID
order_id_str string Order ID
client_order_id long Client ID
order_source string Order source(system、web、api、m、risk、settlement、ios、android、windows、mac、trigger)
order_type int Order type 1Requested orders; 2. Cancelled orders; 3. Liquidated orders; 4. Delivered orders
created_at long order creation time
canceled_at long order canceled time
trade_volume decimal trade volume(volume)
trade_turnover decimal Turnover
fee decimal Fees
trade_avg_price decimal Average order price
margin_frozen decimal Frozen Margin
profit decimal Profits&Losses
fee_asset string the corresponding cryptocurrency to the given fee
liquidation_type string 0:Not Forced Liquidation Type，1：Netting Type， 2: Partial Takeover，3：All Takeover
<trade>
id string the global unique id of the trade.。
trade_id long In this interface, trade_id is the same with match_id of api/v1/contract_matchresults. trade_id is the result of sets of order execution and trade confirmation. NOTE: trade_id is not unique, which includes all trade records of a taker order and N maker orders. If the taker order matches with N maker orders, it will create N trades with same trade_id.
trade_volume decimal trade volume
trade_price decimal trade price
trade_fee decimal trading fees
trade_turnover decimal turnover
created_at long trade creation time
role string taker or maker
fee_asset string fee asset
</trade>

Unsubscribe Order Data（unsub）

To unsubscribe order data, the clients have to make connection to the server and send unsubscribe request in the format below:

Format of Unsubscribe order data

{

“op”: “unsub”,

“topic": "orders.$symbol”,

"cid": "id generated by client”,

}

Example of a successful unsubscribe request：


{
  "op": "unsub",
  "topic": "orders.btc",
  "cid": "40sG903yz80oDFWr"
}

Format illustration of unsubscribe order data

Filed Type Description
op string Required;Operator Name，value for unsubscribe is unsub;
cid string Optional; Client requests unique ID
topic string Required；Unsubscribe topic name: orders.$symbol; symbol is case-insenstive.Both uppercase and lowercase are supported.e.g: "BTC,ETH" ; when $symbol value is *, it stands for unsubscribing the data of all coins;

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe( unsub) ) Rule
orders.* orders.* Allowed
orders.symbol1 orders.* Not Allowed
orders.symbol1 orders.symbol1 Allowed
orders.symbol1 orders.symbol2 Not Allowed
orders.* orders.symbol1 Not Allowed

Subscribe Match Order Data（sub）

To subscribe order data, Clients have to make connection to the Server and send subscribe request in the format below:

Subscribe Request Format

{

“op”: “sub”,

"cid": "cid”,

“topic": "matchOrders.$symbol”

}

sub example:


{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "matchOrders.btc"
}

Format of subscribe match order data

attr type desc
op string Required； Operator Name，required subscribe value is sub
cid string Optional; ID Client requests unique ID
topic string Required；Topic name format: matchOrders.$symbol; symbol is case-insenstive.Both uppercase and lowercase are supported. e.g.:"BTC,ETH"

Illustration on detailed data format of orders Notification

Note:

response


{
    "op":"notify",
    "topic":"matchOrders.ada",
    "ts":1604388667219,
    "symbol":"ADA",
    "contract_code":"ADA201225",
    "contract_type":"quarter",
    "status":6,
    "order_id":773207641127878656,
    "order_id_str":"773207641127878656",
    "client_order_id":null,
    "order_type":1,
    "created_at":1604388667146,
    "trade":[
        {
            "trade_id":113913755890,
            "id":"113913755890-773207641127878656-1",
            "trade_volume":1,
            "trade_price":0.0905,
            "trade_turnover":10,
            "created_at":1604388667194,
            "role":"maker"
        }
    ],
    "uid":"123456789",
    "volume":1,
    "trade_volume":1,
    "direction":"sell",
    "offset":"open",
    "lever_rate":20,
    "price":0.0905,
    "order_source":"web",
    "order_price_type":"post_only"
}

format of order data pushed

Parameter Name Type Desc
op string notify;
topic string topic
uid string account uid
ts long Time of Respond Generation
symbol string symbol
contract_type string contract type
contract_code string contract code
status int 1. Ready to submit the orders; 2. Ready to submit the orders; 3. Have sumbmitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled;
order_id bigint order id
order_id_str string order id
client_order_id long the client ID that is filled in when the order is placed
order_type int Order type: 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
trade_volume decimal total filled volume of the order
volume decimal total volume of the order
<trade>
id string the global unique id of the trade.
trade_id long In this interface, trade_id is the same with match_id of api/v1/contract_matchresults. trade_id is the result of sets of order execution and trade confirmation. NOTE: trade_id is not unique, which includes all trade records of a taker order and N maker orders. If the taker order matches with N maker orders, it will create N trades with same trade_id.
trade_volume decimal trade volume
trade_price decimal trade price
trade_turnover decimal trade turnover
created_at long created at
role string taker or maker
</trade>
direction string direction "buy" or "sell"
offset string offset: "open" or "close"
lever_rate int lever rate
price decimal trigger price
created_at long created at
order_source string order source
order_price_type string order price type: "limit":Limit,"opponent":opponent,"post_only":Post-Only Order, No order limit but position limit for post-only orders.，"lightning":lightning, "optimal_5":optimal 5，"optimal_10":optimal 10，"optimal_20":optimal 20，"fok":FOK Order，"ioc":IOC Order, "opponent_ioc": opponent ioc，"lightning_ioc": lightning ioc，"optimal_5_ioc": optimal_5 ioc，"optimal_10_ioc": optimal_10 ioc，"optimal_20_ioc"：optimal_20 ioc，"opponent_fok"： opponent fok，"lightning_fok"：lightning fok，"optimal_5_fok"：optimal_5 fok，"optimal_10_fok"：optimal_10 fok，"optimal_20_fok"：optimal_20 fok

Unsubscribe Match Order Data（unsub）

To unsubscribe order data, the clients have to make connection to the server and send unsubscribe request in the format below:

Format of Unsubscribe order data

{

“op”: “unsub”,

“topic": "matchOrders.$symbol”,

"cid": "id generated by client”,

}

Example of a successful unsubscribe request：


{
  "op": "unsub",
  "topic": "matchOrders.btc",
  "cid": "40sG903yz80oDFWr"
}

Format illustration of unsubscribe order data

Filed Type Description
op string Required;Operator Name，value for unsubscribe is unsub;
cid string Optional; Client requests unique ID
topic string Required；Unsubscribe topic name: matchOrders.$symbol; symbol is case-insenstive.Both uppercase and lowercase are supported.e.g: "BTC,ETH" ; when $symbol value is *, it stands for unsubscribing the data of all coins;

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe( unsub) ) Rule
matchOrders.* matchOrders.* allowed
matchOrders.symbol1 matchOrders.* Not Allowed
matchOrders.symbol1 matchOrders.symbol1 allowed
matchOrders.symbol1 matchOrders.symbol2 Not Allowed
matchOrders.* matchOrders.symbol1 Not Allowed

Subscribe Account Equity Updates Data(sub)

To subscribe accounts equity data updates, the client has to make connection to the server and send subscribe request in the format below:

Request Format for Subscribe Account Equity Updates Data

{

"op": "sub",

"cid": "id generated by client”,

“topic": "accounts.$symbol”

}

Example of a successful subscribe request:


{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "accounts.btc"
}

Format illustration on request subscribe account equity updates data

Field Name Type Description
op string Required； Operator Name，Subscribe value is sub
cid string Optional; Client requests unique ID
topic string Required；Topic name format: accounts.$symbol; symbol is case-insenstive.Both uppercase and lowercase are supported. e.g.:"BTC,ETH"

When there is any balance change, the Server will send a notification with the return parameter. For example:


{
    "op":"notify",
    "topic":"accounts.ada",
    "ts":1604388667226,
    "event":"order.match",
    "data":[
        {
            "symbol":"ADA",
            "margin_balance":446.417641681222726716,
            "margin_static":445.554085945257745136,
            "margin_position":11.049723756906077348,
            "margin_frozen":0,
            "margin_available":435.367917924316649368,
            "profit_real":21.627049781983019459,
            "profit_unreal":0.86355573596498158,
            "risk_rate":40.000796572150656768,
            "liquidation_price":0.018674308027108984,
            "withdraw_available":423.927036163274725677,
            "lever_rate":20,
            "adjust_factor":0.4
        }
    ],
    "uid":"123456789"
}

Format Illustration of Notification

Field Name Type Description
op string notify;
topic string topic
uid string account uid
ts long Time of Respond Generation, Unit: Millisecond
event string notification on account asset change such as commit order(order.open), fulfill order(order.match)(excluding liquidated order and settled orders), settlement and delivery(settlement), fulfill liquidation order(order.liquidation)(including voluntarily fulfilled liquidation order and the fulfilled liquidation order taken over by system ) , cancel order(order.cancel), asset transfer（contract.transfer) (including withdraw and deposit), system (contract.system), other asset change(other), switch leverages(switch_lever_rate), initial margin(init)
<data>
symbol string Coins. When the $symbol value is “*”, it stands for subscribing data of all coins
margin_balance decimal Account Equity
margin_static decimal Static Equity
margin_position decimal Position Margi(the margin for holding currenty positions)
margin_frozen decimal Frozen Margin
margin_available decimal Available Margin
profit_real decimal Realized Profits&Losses
profit_unreal decimal Unrealized Profits&Losses
risk_rate decimal Margin Ratio
liquidation_price decimal Liquidation Price
withdraw_available decimal Assets available to withdraw
lever_rate decimal Leverage
adjust_factor decimal Adjustment Factor
</data>

Note

Unsubscribe Account Equity Updates Data (ubsub)

To unsubscribe account equity updates data, the client has to make connection to the server and send unsubscribe request in the format below:

Request Format of Unsubscribe Account Equity Updates Data

{

“op”: “unsub”,

“topic": "accounts.$symbol”,

"cid": "id generated by client”,

}

Example of a successful subscription request


{
  "op": "unsub",
  "topic": "accounts.btc",
  "cid": "40sG903yz80oDFWr"
}

Format Illustration on Unsubscribe Account Equity Updates

Filed Name Type Description
op string Required; Operator Name，Subscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Required；Unsubscribe topic name: accounts.$symbol; symbol is case-insenstive.Both uppercase and lowercase are supported.e.g: "BTC,ETH" ; when $symbol value is *, it stands for unsubscribing the data of all coins;

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
accounts.* accounts.* Allowed
accounts.symbol1 accounts.* Allowed
accounts.symbol1 accounts.symbol1 Allowed
accounts.symbol1 accounts.symbol2 Not Allowed
accounts.* accounts.symbol1 Not Allowed

Subscribe Position Updates(sub)

To subscribe position updates data, the client has to make connection to the server and send subscribe request in the format below:

Subscribe Request Format

{

“op”: “sub”,

"cid": "id generated by client”,

“topic": "positions.$symbol”

}

Example of a successful subscribe request:


{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "positions.btc"
}

Format Illustration of Subscribe Position Updates

Filed Name Type Description
op string Required；Operator Name，Subscribe value is sub
cid string Optional ; Client requests unique ID
topic string Required；Topic name format: positions.$symbol; symbol is case-insenstive.Both uppercase and lowercase are supported. e.g.:"BTC,ETH"

When there is any position update, the server will send notification with return parameter. For example:


{
    "op":"notify",
    "topic":"positions.ada",
    "ts":1604388667226,
    "event":"order.match",
    "data":[
        {
            "symbol":"ADA",
            "contract_code":"ADA201225",
            "contract_type":"quarter",
            "volume":1,
            "available":1,
            "frozen":0,
            "cost_open":0.0905,
            "cost_hold":0.0905,
            "profit_unreal":0,
            "profit_rate":0,
            "profit":0,
            "position_margin":5.524861878453038674,
            "lever_rate":20,
            "direction":"sell",
            "last_price":0.0905
        }
    ],
    "uid":"123456789"
}

Return Parameter Illustration

Filed Name Type Description
op string notify;
topic string topic
uid string account uid
ts long Time of Respond Generation, Unit: Millisecond
event string Related events of position change notification, such as order creation and position closing (order.close), order filled (order.match) (except for liquidation, settlement and delivery), settlement and delivery (settlement), order liquidation (order.liquidation), order cancellation (order.cancel),switch leverage（switch_lever_rate）, initial positions (init), triggered by system periodic push (snapshot).
<data>
symbol string Coin, when $symbol value is *, it stands for subscribing the data of all coins
contract_code string Contract Code
contract_type string Contract Type, Weekly contract: "this_week", Bi-weeklycontract: "next_week", Quarterly Contract: "quarter", Next Quarterly Contract: "next_quarter"“delivered”
volume decimal Open Interest
available decimal Positions available to close
frozen decimal Frozen Margin
cost_open decimal Open price
cost_hold decimal Position Price
profit_unreal decimal Unrealized Profits&Losses
profit_rate decimal Profit/Losses Ratio
profit decimal Profits/Losses
position_margin decimal Position Margin
lever_rate decimal Leverage
direction string Position direction "buy":Long "sell":Short
last_price decimal Last Price
</data>

Note

Unsubscribe Position Updates Data(unsub)

To unsubscribe, the client has to make connection to the server and send unsubscribe request in the format below:

Request Format of Unsubscribe Position Updates

{

“op”: “unsub”,

“topic": "positions.$symbol”,

"cid": "id generated by client”,

}

Example of a successful unsubscribe request:


{
  "op": "unsub",
  "topic": "positions.btc",
  "cid": "40sG903yz80oDFWr"
}

Format Illustration of Unsubscribe Position Updates

Field Name Type Description
op string Required; Operator Name，Subscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Required；Unsubscribe topic name: positions.$symbol; symbol is case-insenstive.Both uppercase and lowercase are supported.e.g: "BTC,ETH" ; when $symbol value is *, it stands for unsubscribing the data of all coins;

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
positions.* positions.* Allowed
positions.symbol1 positions.* Allowed
positions.symbol1 positions.symbol1 Allowed
positions.symbol1 positions.symbol2 Not Allowed
positions.* positions.symbol1 Not Allowed

Subscribe Liquidation Order Data(No authentication) (sub)

Subscription Request Format of Liquidation order data

{

“op”: “sub”,

“topic": "public.$symbol.liquidation_orders”,

"cid": "id generated by client”,

}

Example of a successful subscription request:


{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "public.BTC.liquidation_orders"
}

Data format illustration of orders subscription

Field Name Type Description
op string Required； Operator Name，required subscribe value is sub
cid string Optional; ID Client requests unique ID
topic string Required；Topic name format: public.$symbol.liquidation_orders. symbol is case-insenstive.Both uppercase and lowercase are supported. e.g:"BTC"

Return Parameter

Field Name Type Description
op string value:"notify"
topic string topic subscribed
ts long Time of Respond Generation，Unit：Millisecond
<data> array object
symbol string Coin
contract_code string contract code
direction string Long or short
offset string Open or close
volume decimal liquidated volume(cont)
amount decimal liquidation amount (token)
price decimal bankruptcy price
created_at long Order Creation Time
<\data>

When there commences any liquidation order, the server will send notification with return parameter. For example：


{
    "op":"notify",
    "topic":"public.BTC.liquidation_orders",
    "ts":1606293144641,
    "data":[
        {
            "contract_code": "BTC201225",
            "symbol": "BTC",
            "direction": "buy",
            "offset": "close",
            "volume": 26,
            "price": 19674.96,
            "created_at": 1606293144641,
            "amount": 0.132147663832607537
        }
    ]
}

Unsubscribe Liquidation Order Data(no authentication)(unsub)

Unsubscribe Request Format

{

“op”: “unsub”,

“topic": "public.$symbol.liquidation_orders”,

"cid": "id generated by client”,

}

Example of a successful unsubscribe request :


{
  "op": "unsub",
  "topic": "public.BTC.liquidation_orders",
  "cid": "40sG903yz80oDFWr"
}

Data format illustration of orders subscription

Field Name Type Description
op string Required； Operator Name，required subscribe value is sub
cid string Optional; ID Client requests unique ID
topic string Required；Unsubscribe topic name: public.$symbol.liquidation_orders; symbol is case-insenstive.Both uppercase and lowercase are supported.e.g: "BTC,ETH" ; when $symbol value is *, it stands for unsubscribing the data of all coins;

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
public.*.liquidation_orders public.*.liquidation_orders Allowed
public.symbol1.liquidation_orders public.*.liquidation_orders Allowed
public.symbol1.liquidation_orders public.symbol1.liquidation_orders Allowed
public.symbol1.liquidation_orders public.symbol2.liquidation_orders Not Allowed
public.*.liquidation_orders public.symbol1.liquidation_orders Not Allowed

Subscribe Contract Info (no authentication)（sub）

To subscribe contract info, the client has to make connection to the server and send subscribe request in the format below:

{

"op": "sub",

"cid": "40sG903yz80oDFWr",

"topic": "public.$symbol.contract_info"

}

Example of a successful request:


{
  "op": "sub",
  "topic": "public.btc.contract_info",
  "cid": "40sG903yz80oDFWr"
}

Data format illustration of orders subscription

Field Name Type Description
op string Required； Operator Name，required subscribe value is sub
cid string Optional; ID Client requests unique ID
topic string Required；Topic name format: public.$symbol.contract_info.; symbol is case-insenstive.Both uppercase and lowercase are supported. e.g:"BTC,ETH"

Response example：


{
    "op":"notify",
    "topic":"public.btc.contract_info",
    "ts":1604389592693,
    "event":"snapshot",
    "data":[
        {
            "symbol":"BTC",
            "contract_code":"BTC201106",
            "contract_type":"this_week",
            "contract_size":100,
            "price_tick":0.01,
            "delivery_date":"20201106",
            "create_date":"20201016",
            "contract_status":1
        },
        {
            "symbol":"BTC",
            "contract_code":"BTC201113",
            "contract_type":"next_week",
            "contract_size":100,
            "price_tick":0.01,
            "delivery_date":"20201113",
            "create_date":"20201023",
            "contract_status":1
        },
        {
            "symbol":"BTC",
            "contract_code":"BTC201225",
            "contract_type":"quarter",
            "contract_size":100,
            "price_tick":0.01,
            "delivery_date":"20201225",
            "create_date":"20200612",
            "contract_status":1
        },
        {
            "symbol":"BTC",
            "contract_code":"BTC210326",
            "contract_type":"next_quarter",
            "contract_size":100,
            "price_tick":0.01,
            "delivery_date":"20210326",
            "create_date":"20200904",
            "contract_status":1
        }
    ]
}

Response data fields

Field Name Type Description Value Range
op string value: "notify";
topic string topic subscribed
ts long timestamp of server response.unit: millionseconds
event string event "init", "update", "snapshot"
<data> object array
symbol string symbol,"BTC","ETH"...
contract_code string contract code "EOS200113"
contract_type string contract type "this_week","next_week", "quarter", "next_quarter", Next Quarterly Contract: "next_quarter"
contract_size decimal Contract Value (USD of one contract). such as 10,100 10, 100...
price_tick decimal Minimum Variation of Contract Price 0.001, 0.01...
delivery_date string delivery date such as "20200327"
create_date string Contract Listing Date such as "20180706"
contract_status int contract status 0: Delisting,1: Listing,2: Pending Listing,3: Suspension,4: Suspending of Listing,5: In Settlement,6: Delivering,7: Settlement Completed,8: Delivered, 9 Suspending of Trade
</data>

Note：

Unsubscribe Contract Info Data(no authentication)(unsub)

To unsubscribe contract info data, the client has to make connection to the server and send subscribe request in the format below:

request format of unsubscribing contract info

{

"op": "unsub",

"topic": "public.$symbol.contract_info",

"cid": "id generated by client",

}

example of unsubscribing contract info::


{                                    
  "op": "unsub",                     
  "topic": "public.BTC.contract_info",   
  "cid": "40sG903yz80oDFWr"          
}

request field desc of unsubscrbing contract info

field datatype desc
op string Required; Operator Name，subscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Required；Unsubscribe topic name: public.$symbol.contract_info; symbol is case-insenstive.Both uppercase and lowercase are supported.e.g: "BTC,ETH" ; when $symbol value is *, it stands for unsubscribing the data of all coins;

Data format of subscription and unsubscription of contract info

subscribe(sub) unsubscribe(unsub) rules
public.*.contract_info pubic.*.contract_info Allowed
public.symbol1.contract_info public.*.contract_info Allowed
public.symbol1.contract_info public.symbol1.contract_info Allowed
public.symbol1.contract_info public.symbol2.contract_info Not Allowed
public.*.contract_info public.symbol1.contract_info Not Allowed

Subscribe trigger orders updates

To subscribe basis data, the Client has to make connection to the Server and send subscribe request in the format below:

{

"op": "sub",

"cid": "id generated by client",

"topic": "trigger_order.$symbol"

}

request


{                                    
  "op": "sub",                     
  "topic": "trigger_order.BTC",   
  "cid": "40sG903yz80oDFWr"          
}

Request Parameter

Parameter Name Mandotary Type Desc Value Range
op true string Required； Operator Name，required subscribe value is sub
cid false string Optional; ID Client requests unique ID
topic true string Required；format: trigger_order.$symbol; symbol is case-insenstive.Both uppercase and lowercase are supported.e.g.:"BTC,ETH" ;when $symbol value is *, it stands for subscribing the data of all coins;

Return example：


{
    "op":"notify",
    "topic":"trigger_order.ADA",
    "ts":1604390110568,
    "event":"order",
    "uid":"123456789",
    "data":[
        {
            "symbol":"ADA",
            "contract_code":"ADA201225",
            "contract_type":"quarter",
            "trigger_type":"le",
            "volume":1,
            "order_type":1,
            "direction":"buy",
            "offset":"close",
            "lever_rate":20,
            "order_id":28312417,
            "order_id_str":"28312417",
            "relation_order_id":"-1",
            "order_price_type":"limit",
            "status":2,
            "order_source":"web",
            "trigger_price":0.09,
            "triggered_price":null,
            "order_price":0.09,
            "created_at":1604390110565,
            "triggered_at":0,
            "order_insert_at":0,
            "canceled_at":0,
            "fail_code":null,
            "fail_reason":null
        }
    ]
}

Format Illustration on return data of order push：

Parameter Name Mandotary Type Desc Value Range
op true string Required;Operator Name，Order push value is notify
topic true string Required; Order push topic
ts true long Time of Respond Generation, Unit: Millisecond
uid true string account uid
event true string Event notification description trigger order placed successfully（order），trigger order canceled successfully（cancel），order triggered successfully（trigger_success），order failed to be triggered（trigger_fail）
<data> true object array
symbol true string Variety code
contract_type true string contract type Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter" Next Quarterly Contract: "next_quarter"：“next_quarter”
contract_code true string contract code "BTC180914" ...
trigger_type true string trigger type gegreat than or equal to；leless than or equal to
volume true decimal trigger order volume
order_type true int Transaction Type 1. Place orders
direction true string order direction [buy,sell]
offset true string offset direction [open,close]
lever_rate true int Leverage
order_id true long trigger order ID
order_id_str true string the order ID with string
relation_order_id true string Relation order ID is the string related to the limit orders , The value is -1 before the trigger orders executed.
order_price_type true string Order price type "limit": limit order，"optimal_5":optimal 5，"optimal_10":optimal 10，"optimal_20":optimal 20
status true int order status 2. Ready to submit the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched;
order_source true string Order Source
trigger_price true decimal trigger price
triggered_price true decimal the price when trigger orders executed
order_price true decimal the preset price by the client
created_at true long order creation time
triggered_at true long the execution time when orders getting triggered
order_insert_at true long the time when the triggered orders filled successfully
canceled_at true long Order cancelation time
fail_code true int the error code when the triggered orders failed to be filled
fail_reason true string the error message with failure reason when triggered orders failed to filled
</data>

Rule：

Unsubscribe trigger orders updates（unsub）

To subscribe basis data, the Client has to make connection to the Server and send subscribe request in the format below:

Format of Unsubscribe order data

{

"op": "unsub",

"topic": "trigger_order.$symbol",

"cid": "id generated by client",

}

Example of a successful unsubscribe request:


{                                    
  "op": "unsub",                     
  "topic": "trigger_order.*",   
  "cid": "40sG903yz80oDFWr"          
}

Format illustration of unsubscribe order data

Field Name Type Description
op string Required; Operator Name，subscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Required；Unsubscribe topic name: trigger_order.$symbol; symbol is case-insenstive.Both uppercase and lowercase are supported.e.g: "BTC,ETH" ; when $symbol value is *, it stands for unsubscribing the data of all coins;

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe( unsub) Rule
trigger_order.* trigger_order.* allowed
trigger_order.symbol1 trigger_order.* allowed
trigger_order.symbol1 trigger_order.symbol1 allowed
trigger_order.symbol1 trigger_order.symbol2 Not Allowed
trigger_order.* trigger_order.symbol1 Not Allowed

WebSocket interface for system status updates

Subscribe system status updates

After successfully establishing a connection with the WebSocket API, users could send data in the following format to the server to request data:

{

"op": "sub",

"cid": "id generated by client",

"topic ": "public.$service.heartbeat"

}

Example on using parameters to request data: 


{
    "op": "sub",
    "cid": "id generated by client",
    "topic ": "public.futures.heartbeat"
}

Request Parameter:

Name Mandatory Type Desc Value Range
op true string The fixed value of subscription is sub
cid false string Client requests a unique ID
topic true string Subscription topic name is required (public.$service.heartbeat), Subscribe system status information of a certain business

subscription parameter description:

Name Mandatory Type Desc Value Range
service true string Business Code futures

Return Parameter Example:


{
    "op": "notify",
    "topic": "public.futures.heartbeat",
    "event": "init",
    "ts":1580815422403,
    "data":{
        "heartbeat": 0,
        "estimated_recovery_time": 1408076414000
    }
}

Return Parameter Rules：

Name Mandatory Type Desc Value Range
op true string Operation name, the fixed value of push is notify;
topic true string Push topic
event true string Description on notification related event The initial system status information returned by a successful subscription (init), triggered by system status change (update)
ts true long Server response timestamp
<data>
heartbeat true int System Status 1 is available, 0 is not available
estimated_recovery_time true long Estimated system recovery time, unit: millisecond When the system status is available, return NULL
</data>

Note

Appendix

Operator Type(OP)

Type Description
ping Server sends heatbeat with a Ping
pong Clients responds heatbeat with a Pong
auth Authentication
sub Subscribe Message
unsub Unsubscribe Message
notify Server pushes subscribe message

Topic Type

Type applicative operator type Description
orders.$symbol sub,ubsub Subscribe/unsubscribe the order data of a given pair; when the $symbol value is *, it stands for subscribing/unsubscribing the data of all pairs

Response code（Err-Code）

Return Error Code Return description
0 Request successfully.
2001 Invalid authentication.
2002 Authentication required.
2003 Authentication failed.
2004 Number of visits exceeds limit.
2005 Connection has been authenticated.
2010 Topic error.
2011 Contract doesn't exist.
2012 Topic not subscribed.
2013 Authentication type doesn't exist.
2014 Repeated subscription.
2030 Exceeds connection limit of single user.
2040 Missing required parameter.






shell