Navbar
现货 币本位交割合约 币本位永续合约 U本位合约 new API
简体中文
shell

Introduction

API Documentation Summary

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

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

Market Maker Program

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

Eligibility Criteria as a Market Maker on Huobi Futures

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 more than 100000 USDT in your Huobi USDT Margined Contracts account, please send the following information to Vip@global-hgroup.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

More detail in here: Huobi USDT-Margined Contracts Market Maker Preferential Policy

Colocation

Solution Architecture

Huobi swap API colocation solution is built on AWS infrastructure. Client will connect via AWS “PrivateLink” to access Huobi’s services directly through fast AWS connection without being routed to public networks.

Performance Improvement

The network delay of colocation solution is estimated to be 10ms to 50ms faster than the ordinary connection. This improvement estimated should be used as a guidance only as the actual improvement depends on many factors.

Eligibility

Colocation is only available to higher tier market makers. To check if your account is eligible please talk to your dedicated account manager.

Setting

Detail in here: Huobi Futures Colocation

Risk Mechanism

Partial Liquidation

Margin ratio is an indicator to estimate the risk of users’assets. When the margin ratio is less than or equal to 0%, liquidation will be triggered.
It is recommended that you pay close attention to margin ratio changes, so as to avoid your positions from liquidation.
Huobi contracts implement a partial liquidation mechanism, in which the system will lower the corresponding tier of an adjustment factor to avoid your positions from being liquidated at one time.
More detail to see: Partial Liquidation

Insurance Funds and Clawback Mechanism

Insurance funds are designed to cover the losses from forced liquidation.
In a fluctuating market, users’ positions may be liquidated. When the order cannot be filled at the takeover price, resulting in huge losses that are greater than the part insurance funds can undertake, the platform will implement the “clawback” mechanism. Each profitable account in the current period compensates the over loss of liquidation according to its profit ratio.
More detail in here: Partial Liquidation

Tiered Adjustment Factor

The adjustment factor is designed to prevent users from extended margin call loss. Huobi Contracts use a tiered adjustment factor mechanism, which supports up to five tiers based on the position amount.
For contracts with different expirations under the different account modes, they are separately calculated. The larger the use’s net positions, the higher the tier, and the greater the risk.
More detail in here: Tiered Adjustment Factor of USDT-margined Contract

Matching Mechanism

  1. Matching System: Order accepted by the Order System will enter the Matching System. Once orders are matched/filled, the settlement service will be executed and the matching result will be returned to the Order System; otherwise, the unfilled orders will go into the order book for matching.
  2. Price Priority: Higher-priced buy orders have priority over lower-priced buy orders; the reverse is true, lower-priced sell orders have priority over higher-priced sell orders.
  3. Time Priority: Buy orders at the same price are executed according to the time of entry to the Server.
  4. When the highest bid price is the same as the lowest ask price of the order book, this price is what we call transaction price.
  5. When the bid price is higher than the lowest ask price of the order book up to the minute, the lowest ask price will be the transaction price.
  6. When the ask price is lower than the highest bid price of the order book up to the minute, the highest bid price will be the transaction price.

Changelog

1.1.8 2022-11-10 [Added interface]

1、Added Account type query

2、Added Account Type Change

1.1.8 2022-09-01 [Added V3 interface]

1、Added [General] Query account financial

2、Added [General]Query account financial records via Multiple Fields(New)

3、Added [Cross]Get History Match Results via Multiple Fields(New)

4、Added [Cross] Get History Match Results(New)

5、Added [Isolated]Get History Match Results via Multiple Fields(New)

6、Added [Isolated] Acquire History Match Results(New)

7、Added [Cross]Get History Orders via Multiple Fields(New)

8、Added [Cross] Get History Orders(New)

9、Added [Isolated] Get History Orders via Multiple Fields(New)

10、Added [Isolated] Get History Orders(New)

11、Added [General] Query Liquidation Orders(New)

1.1.7 2022-06-24 [Modify the interface restriction content using lever]

1、Modified Place a Batch of Orders (Isolated)(Request parameter lever_rate field removes the restrictions of the master account high leverage agreement)

2、Modified Place a Batch of Orders (cross)(Request parameter lever_rate field removes the restrictions of the master account high leverage agreement)

3、Modified Place an Order (Isolated)(Request parameter lever_rate field removes the restrictions of the master account high leverage agreement)

4、Modified Place an Order (Cross)(Request parameter lever_rate field removes the restrictions of the master account high leverage agreement)

5、Modified Place Trigger Order (Isolated)(Request parameter lever_rate field removes the restrictions of the master account high leverage agreement)

6、Modified Place Trigger Order (Cross)(Request parameter lever_rate field removes the restrictions of the master account high leverage agreement)

7、Modified Switch Leverage (General)(Request parameter lever_rate field removes the restrictions of the master account high leverage agreement)

8、Modify Switch Leverage (Isolated)(Request parameter lever_rate field removes the restrictions of the master account high leverage agreement)

1.1.6 2022-04-24 [Added Get a Batch of Market Data Overview(V2) interface]

1. Added Get a Batch of Market Data Overview(V2) interface

1.1.5 2022-02-25 [Added interface and other content about One-way Mode]

1. Added Switch Position Mode(isolated) interface

2. Added Switch Position Mode(cross) interface

3. Modified Query User’s Position Information(isolated) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

4. Modified Query User’s Position Information(cross) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

5. Modified Query a single sub-account's assets information(isolated) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

6. Modified Query a single sub-account's assets information(cross) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

7. Modified Query Assets And Positions(isolated) interface(Add position_mode field in the response "data" and "positions", indicating the position mode of the current contract.)

8. Modified Query Assets And Positions(cross) interface(Add position_mode field in the response "data" and "positions", indicating the position mode of the current contract.)

9. Modified Subscribe Account Equity Updates Data(sub)(isolated) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

10. Modified Subscribe Account Equity Updates Data(sub)(cross) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

11. Modified Query User’s Position Information(isolated) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

12. Modified Query User’s Position Information(cross) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

13. Modified Query a single sub-account's position information(isolated) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

14. Modified Query a single sub-account's position information(cross) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

15. Modified Subscribe Position Updates(sub)(isolated) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

16. Modified Subscribe Position Updates(sub)(cross) interface(Add position_mode field in the response "data", indicating the position mode of the current contract.)

17. Modified Place an Order(isolated) interface(Added an optional parameter reduce_only, indicating whether it is a reduction-only order, 1 means yes, and 0 means no. In hedge mode it is invalid, and in one-way mode it's value is 0 when not filled. The input parameter offset is changeded to optional. In hedge mode it is a required field, and in the one-way mode it is optional paramater which's value must be both when filled.)

18. Modified Place an Order(cross) interface(Added an optional parameter reduce_only, indicating whether it is a reduction-only order, 1 means yes, and 0 means no. In hedge mode it is invalid, and in one-way mode it's value is 0 when not filled. The input parameter offset is changeded to optional. In hedge mode it is a required field, and in the one-way mode it is optional paramater which's value must be both when filled.)

19. Modified Place a Batch of Orders(isolated) interface(Added an optional parameter reduce_only, indicating whether it is a reduction-only order, 1 means yes, and 0 means no. In hedge mode it is invalid, and in one-way mode it's value is 0 when not filled. The input parameter offset is changeded to optional. In hedge mode it is a required field, and in the one-way mode it is optional paramater which's value must be both when filled.)

20. Modified Place a Batch of Orders(cross) interface(Added an optional parameter reduce_only, indicating whether it is a reduction-only order, 1 means yes, and 0 means no. In hedge mode it is invalid, and in one-way mode it's value is 0 when not filled. The input parameter offset is changeded to optional. In hedge mode it is a required field, and in the one-way mode it is optional paramater which's value must be both when filled.)

21. Modified Place Trigger Order(isolated) interface(Added an optional parameter reduce_only, indicating whether it is a reduction-only order, 1 means yes, and 0 means no. In hedge mode it is invalid, and in one-way mode it's value is 0 when not filled. The input parameter offset is changeded to optional. In hedge mode it is a required field, and in the one-way mode it is optional paramater which's value must be both when filled.)

22. Modified Place Trigger Order(cross) interface(Added an optional parameter reduce_only, indicating whether it is a reduction-only order, 1 means yes, and 0 means no. In hedge mode it is invalid, and in one-way mode it's value is 0 when not filled. The input parameter offset is changeded to optional. In hedge mode it is a required field, and in the one-way mode it is optional paramater which's value must be both when filled.)

23. Modified Place a Trailing Order(isolated) interface(Added an optional parameter reduce_only, indicating whether it is a reduction-only order, 1 means yes, and 0 means no. In hedge mode it is invalid, and in one-way mode it's value is 0 when not filled. The input parameter offset is changeded to optional. In hedge mode it is a required field, and in the one-way mode it is optional paramater which's value must be both when filled.)

24. Modified Place a Trailing Order(cross) interface(Added an optional parameter reduce_only, indicating whether it is a reduction-only order, 1 means yes, and 0 means no. In hedge mode it is invalid, and in one-way mode it's value is 0 when not filled. The input parameter offset is changeded to optional. In hedge mode it is a required field, and in the one-way mode it is optional paramater which's value must be both when filled.)

25. Modified Get Information of an Order(isolated) interface(Added reduce_only in the response "data" parameter, indicating whether it is only reduced position.)

26. Modified Get Information of an Order(cross) interface(Added reduce_only in the response "data" parameter, indicating whether it is only reduced position.)

27. Modified Order details acquisition(isolated) interface(Added reduce_only in the response "data" parameter, indicating whether it is only reduced position.)

28. Modified Order details acquisition(cross) interface(Added reduce_only in the response "data" parameter, indicating whether it is only reduced position.)

29. Modified Current unfilled order acquisition(isolated) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

30. Modified Current unfilled order acquisition(cross) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

31. Modified Get History Orders(isolated) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

32. Modified Get History Orders(cross) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

33. Modified Get History Orders via Multiple Fields(isolated) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

34. Modified Get History Orders via Multiple Fields(cross) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

35. Modified Acquire History Match Results(isolated) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "trades", indicating whether it is only reducing the position.)

36. Modified Acquire History Match Results(cross) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "trades", indicating whether it is only reducing the position.)

37. Modified Get History Match Results via Multiple Fields(isolated) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "trades", indicating whether it is only reducing the position.)

38. Modified Get History Match Results via Multiple Fields(cross) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "trades", indicating whether it is only reducing the position.)

39. Modified Query Trigger Order Open Orders(isolated) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

40. Modified Query Trigger Order Open Orders(cross) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

41. Modified Query Trigger Order History(isolated) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

42. Modified Query Trigger Order History(cross) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

43. Modified Current unfilled trailing order acquisition(isolated) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

44. Modified Current unfilled trailing order acquisition(cross) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

45. Modified Get History Trailing Orders(isolated) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

46. Modified Get History Trailing Orders(cross) interface(Added two enumeration value for trade_type parameter: 17 buy and 18 sell(one-way mode), and added reduce_only filed in response "orders", indicating whether it is only reducing the position.)

47. Modified Subscribe Order Data(sub)(isolated) interface(Added reduce_only parameter in response, indicating whether it is only reducing the position.)

48. Modified Subscribe Order Data(sub)(cross) interface(Added reduce_only parameter in response, indicating whether it is only reducing the position.)

49. Modified Subscribe Match Order Data(sub)(isolated) interface(Added reduce_only parameter in response, indicating whether it is only reducing the position.)

50. Modified Subscribe Match Order Data(sub)(cross) interface(Added reduce_only parameter in response, indicating whether it is only reducing the position.)

51. Modified Subscribe trigger orders updates(sub)(isolated) interface(Added reduce_only in the response "data" parameter, indicating whether it is only reduced position.)

52. Modified Subscribe trigger orders updates(sub)(cross) interface(Added reduce_only in the response "data" parameter, indicating whether it is only reduced position.)

1.1.4 2021-12-22 【Added the content about USDT Margined Futures interfaces】

1. Modified Query Swap Info interface(Add optional parameters in request: business_type, contract_type, pair. Add fields in return parameter "data": contract_type, pair, business_type, delivery_date(contract delivery date, this field is an empty string when it is swap contract))

2. Modified Query Swap Price Limitation interface(Add optional parameters in request: business_type, contract_type, pair. Add fields in return parameter "data": contract_type, business_type, pair)

3. Modified Get Swap Open Interest Information interface(Add optional parameters in request: business_type, contract_type, pair. Add fields in return parameter "data": business_type, contract_type, pair)

4. Modified Query information on contract insurance fund balance and estimated clawback rate interface(Add optional parameters in request: business_type. Add fields in return parameter "data": business_type, pair)

5. Modified Query history records of insurance fund balance interface( Add fields in return parameter "data": business_type, pair)

6. Modified Query Information On Tiered Adjustment Factor(Cross) interface(Add optional parameters in request: business_type, contract_type, pair. Add fields in return parameter "data": business_type, contract_type, pair)

7. Modified Query information on open interest interface(Add optional parameters in request: contract_type, pair. Add fields in return parameter "data": business_type, contract_type, pair)

8. Modified Query Top Trader Sentiment Index Function-Account interface(Add fields in return parameter "data": business_type, pair)

9. Modified Query Top Trader Sentiment Index Function-Position interface(Add fields in return parameter "data": business_type, pair)

10. Modified Query Liquidation Orders interface(Add optional parameters in request: pair. Add fields in return parameter "data.orders": business_type, pair)

11. Modified Query historical settlement records of the platform interface(Add fields in return parameter "data.settlement_record": business_type, pair)

12. Modified Get the estimated settlement price interface(Add optional parameters in request: business_type, contract_type, pair. Add fields in return parameter "data": business_type, contract_type, pair)

13. Modified Query Information On Trade State(Cross) interface(Add optional parameters in request: business_type, contract_type, pair. Add fields in return parameter "data": business_type, contract_type, pair)

14. Modified Get Market Depth interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

15. Modified Get KLine Data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

16. Modified Query information on Tiered Margin (Cross) interface(Add optional parameters in request: business_type, contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; Add fields in return parameter "data": business_type, contract_type, pair)

17. Modified Get Market BBO Data interface(Add one optional parameter in request: business_type. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly). Add one field in return parameter "ticks": business_type)

18. Modified Get Market Data Overview interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

19. Modified Get a Batch of Market Data Overview interface(Add one optional parameter in request: business_type. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly). Add one field in return parameter "data": business_type)

20. Modified Query Basis Data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

21. Modified Get Kline Data of Mark Price interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

22. Modified Query The Last Trade of a Contract interface(Add one optional parameter in request: business_type. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly). Add one field in return parameter "data": business_type)

23. Modified Query a Batch of Trade Records of a Contract interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

24. Modified Query User's Account Information(Cross) interface( Added a field futures_contract_detail under the data field, indicating the relevant fields of all delivery contracts in the cross margin model. the member fields of futures_contract_detail are as same as the contract_detail. Add fields in return parameter "contract_detail","futures_contract_detail": contract_type, business_type, pair)

25. Modified Query User's Position Information(Cross) interface(Add optional parameters in request: contract_type, pair. Add fields in return parameter "data": business_type, contract_type, pair)

26. Modified Query A Sub-Account's Assets Information(Cross) interface( Added a field futures_contract_detail under the data field, indicating the relevant fields of all delivery contracts in the cross margin model. the member fields of futures_contract_detail are as same as the contract_detail. Add fields in return parameter "contract_detail","futures_contract_detail": contract_type, business_type, pair)

27. Modified Query A Sub-Account's Position Information(Cross) interface(Add optional parameters in request: contract_type, pair. Add fields in return parameter "data": business_type, contract_type, pair)

28. Modified Query account financial recordsinterface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-211225)

29. Modified Query account financial records via Multiple Fieldsinterface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-211225)

30. Modified Query swap information on order limit interface(Add optional parameters in request: business_type, contract_type, pair. Add fields in return parameter "data": business_type, contract_type, pair)

31. Modified Query information on swap trading fee interface(Add optional parameters in request: business_type, contract_type, pair. Add fields in return parameter "data": contract_type, business_type, pair, delivery_fee)

32. Modified Query Information On Position Limit (Cross) interface(Add optional parameters in request: business_type, contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101. Add fields in return parameter "data": business_type, contract_type, pair,lever_rate, buy_limit_value, sell_limit_value, mark_price)

33. Modified Query Assets And Positions(Cross) interface(Added a field futures_contract_detail under the data field, indicating the relevant fields of all delivery contracts in the cross margin model. the member fields of futures_contract_detail are as same as the contract_detail. Add fields in return parameters "positions"，"contract_detail" and "futures_contract_detail": contract_type, business_type, pair)

34. Modified Query Settlement Records of Users(Cross) interface(Add one field in return parameters "contract_detail" and "positions": pair)

35. Modified Query User’s Available Leverage(Cross) interface(Add optional parameters in request: business_type, contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101. Add fields in return parameter "data": business_type, contract_type, pair)

36. Modified Switch Leverage(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101. Add fields in return parameter "data": business_type, contract_type, pair)

37. Modified Place An Order(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

38. Modified Place a Batch of Orders(Cross) interface(orders_data Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

39. Modified Cancel An Order(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

40. Modified Cancel All Orders(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

41. Modified Get Information of order(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data": business_type, contract_type, pair)

42. Modified Get Detail Information of order(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data": business_type, contract_type, pair)

43. Modified Current unfilled order acquisition(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data.orders": contract_type, business_type, pair)

44. Modified Get History Orders(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data.orders": contract_type, business_type, pair)

45. Modified Get History Match Results(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter. Add fields in return parameter "data.trades": contract_type, business_type, pair)

46. Modified Get History Orders via Multiple Fields(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data.orders": contract_type, business_type, pair)

47. Modified Get History Match Results via Multiple Fields(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter. Add fields in return parameter "data.trades": contract_type, business_type, pair)

48. Modified Place Lightning Close Position(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

49. Modified Place Trigger Order(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

50. Modified Cancel Trigger Order(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

51. Modified Cancel All Trigger Orders(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

52. Modified Query Trigger Order Open Orders(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data.orders": contract_type, business_type, pair)

53. Modified Query Trigger Order History(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data.orders": contract_type, business_type, pair)

54. Modified Set a Take-profit and Stop-loss Order for an Existing Position(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

55. Modified Cancel a Take-profit and Stop-loss Order(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

56. Modified Cancel all Take-profit and Stop-loss Orders(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

57. Modified Query Open Take-profit and Stop-loss Orders(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data.orders": contract_type, business_type, pair)

58. Modified Query Take-profit and Stop-loss History Orders(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data.orders": contract_type, business_type, pair)

60. Modified Place a Trailing Order(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

61. Modified Cancel a Trailing Order(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

62. Modified Cancel All Trailing Orders(Cross) interface(Add optional parameters in request: contract_type, pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter)

63. Modified Current unfilled trailing order acquisition(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data": business_type, contract_type, pair)

64. Modified Get History Trailing Orders(Cross) interface(Add one optional parameter in request: pair. The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101 and it has be changed to be optional parameter.Add fields in return parameter "data": business_type, contract_type, pair)

65. Modified Subscribe Kline data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

66. Modified Request Kline data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

67. Modified Subscribe Market Depth Data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

68. Modified Subscribe Incremental Market Depth Data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

69. Modified Subscribe market BBO data push interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

70. Modified Subscribe Market Detail Data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

71. Modified Request Trade Detail Data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

72. Modified Subscribe Trade Detail Data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

73. Modified Subscribe Basis Data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

74. Modified Request Basis Data interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

75. Modified Subscribe Liquidation Orders(no authentication)(sub) interface(Add one optional field in the outer layer of subscription parameters: business_type, which is at the same level as topic. Add fields in the return parameter "data": pair, contract_type, business_type. All of that is at the same level as contract_code. business_type should be filled when unsubscribed)

76. Modified Subscribe Contract Info(no authentication)(sub) interface(Add one optional field in the outer layer of subscription parameters: business_type, which is at the same level as topic.Add fields in the return parameter "data": pair, contract_type, business_type, delivery_date. All of that is at the same level as contract_code. business_type should be filled when unsubscribed)

77. Modified Subscribe Kline Data of Mark Priceinterface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

78. Modified Request Kline Data of Mark Price interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101; at the same time, it supports the contract identifier, in that the format is BTC-USDT(swap), BTC-USDT-CW(current week), BTC-USDT-NW(next week), BTC-USDT-CQ(current quarterly), BTC-USDT-NQ(next quarterly))

79. Modified Subscribe Account Equity Updates Data(sub)(Cross) interface( Added a field futures_contract_detail under the data field, indicating the relevant fields of all delivery contracts in the cross margin model. the member fields of futures_contract_detail are as same as the contract_detail. Add fields in return parameter "contract_detail","futures_contract_detail": contract_type, business_type, pair)

80. Modified Subscribe Order Data(sub)(Cross) interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101. Add fields in the return data: pair, contract_type, business_type. All of that is at the same level as contract_code)

81. Modified Subscribe Position Updates(sub)(Cross) interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101. Add fields in the return data: pair, contract_type, business_type. All of that is at the same level as contract_code)

82. Modified Subscribe Match Order Data(sub)(Cross) interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101. Add fields in the return data: pair, contract_type, business_type. All of that is at the same level as contract_code)

83. Modified Subscribe trigger orders updates(sub)(Cross) interface(The request parameter "contract_code" supports the contract code of futures, in that the format is BTC-USDT-201101. Add fields in the return data: pair, contract_type, business_type. All of that is at the same level as contract_code)

84, Modified Query Information On Position Limit(isolated) interface(Add returning parameters: lever_rate, buy_limit_value, sell_limit_value, mark_price)

85, Added Query Users' Position Limit for All Leverages(isolated) interface

86, Added Query Users' Position Limit for All Leverages(cross) interface

1.1.3 2021-5-17 【Transfer between master and sub account（Added parameters in request: client_order_id）。Transfer between different margin accounts under the same account（Added parameters in request: client_order_id）】

1、Transfer between master and sub account（Added parameters in request: client_order_id）

2、Transfer between different margin accounts under the same account（Added parameters in request: client_order_id）

1.1.2 2021-05-12 【Added: Trailing Order interface. 】

1. Added Place a Trailing Order(isolated) interface

2. Added Place a Trailing Order(cross) interface

3. Added Cancel a Trailing Order(isolated) interface

4. Added Cancel a Trailing Order(cross) interface

5. Added Cancel All Trailing Orders(isolated) interface

6. Added Cancel All Trailing Orders(cross) interface

7. Added Current unfilled trailing order acquisition(isolated) interface

8. Added Current unfilled trailing order acquisition(cross) interface

9. Added Get History Trailing Orders(isolated) interface

10. Added Get History Trailing Orders(cross) interface

1.1.1 2021-04-29 【Modified Cancel an Order(Change the valid time of the client_order_id from 24 hours to 8 hours. Clients can't get the order info with client_order_id which order placed beyond 8 hours). Modified Get Information of an Order(Change the valid time of the client_order_id from 24 hours to 8 hours. Clients can't get the order info with client_order_id which order placed beyond 8 hours.Client can query the order info which has been cancelled within 2 hours(original is 4 hours)）】

1. Modified Cancel an Order(isolated) interface(Change the valid time of the client_order_id from 24 hours to 8 hours. Clients can't get the order info with client_order_id which order placed beyond 8 hours)

2. Modified Cancel an Order(cross) interface(Change the valid time of the client_order_id from 24 hours to 8 hours. Clients can't get the order info with client_order_id which order placed beyond 8 hours)

3. Modified Get Information of an Order(isolated) interface(Change the valid time of the client_order_id from 24 hours to 8 hours. Clients can't get the order info with client_order_id which order placed beyond 8 hours. Client can query the order info which has been cancelled within 2 hours(original is 4 hours)）

4. Modified Get Information of an Order(cross) interface(Change the valid time of the client_order_id from 24 hours to 8 hours. Clients can't get the order info with client_order_id which order placed beyond 8 hours. Client can query the order info which has been cancelled within 2 hours(original is 4 hours)）

1.1.0 2021-4-28 【Added: Get Market BBO Data interface. 】

1. Added Get Market BBO Data interface

1.0.9 2021-2-26 【Added: Query Asset Valuation interface, Query a Batch of Funding Rate interface. Modified Query Swap Price Limitation interface(Support users not to fill in all input parameters, and the interface returns the price limit data of all available contracts). Modified Query The Last Trade of a Contract interface(Support users not to fill in all input parameters, the interface returns the latest transaction data of all available contracts; And in that case, the return parameter "ch" value is "market.*trade.detail". Added one field in return "tick" parameter: "contract_code")】

1. Added Query Asset Valuation interface

2. Added Query a Batch of Funding Rate interface

3. Modified Query Swap Price Limitation interface(Support users not to fill in all input parameters, and the interface returns the price limit data of all available contracts)

4. Modified Query The Last Trade of a Contract interface(Support users not to fill in all input parameters, the interface returns the latest transaction data of all available contracts; And in that case, the return parameter "ch" value is "market.*trade.detail". Added one field in return "data" parameter: "contract_code")

1.0.8 2021-2-5 【Added: Get History Orders via Multiple Fields(cross margin and isolated margin), Get History Match Results via Multiple Fields(cross margin and isolated margin), Query account financial records via Multiple Fields, Query information on Tiered Margin(cross margin and isolated margin), Set a Batch of Sub-Account Trading Permissions, Query a Batch of Sub-Account's Assets Information(cross margin and isolated margin)。11-14 Modified the existing interfaces and added new parameters】

1. Added Get History Orders via Multiple Fields interface[Isolated]

2. Added Get History Orders via Multiple Fields interface[Cross]

3. Added Get History Match Results via Multiple Fields interface[Isolated]

4. Added Get History Match Results via Multiple Fields interface[Cross]

5. Added Query account financial records via Multiple Fields interface

6. Added Query information on Tiered Margin interface[Isolated]

7. Added Query information on Tiered Margin interface[Cross]

8. Added Set a Batch of Sub-Account Trading Permissions interface

9. Added Query a Batch of Sub-Account's Assets Information interface[Isolated]

10. Added Query a Batch of Sub-Account's Assets Information interface[Cross]

11. Modified Query The Last Trade of a Contract interface(Added "quantity" in return parameter "data", which means the trading quantity(coin), Calculation formula: quantity(coin) = trading quantity(cont) * contract size. Added "trade_turnover" in return parameter "data", which represents the trading amount(quoted currency). Calculation formula: trade_turnover(quoted currency) = trading quantity(cont) * contract size * trading price.)

12. Modified Query a Batch of Trade Records of a Contract interface(Added "quantity" in return parameter "data", which means the trading quantity(coin), Calculation formula: quantity(coin) = trading quantity(cont) * contract size. Added "trade_turnover" in return parameter "data", which represents the trading amount(quoted currency). Calculation formula: trade_turnover(quoted currency) = trading quantity(cont) * contract size * trading price.)

13. Modified Subscribe Trade Detail Data interface(Added "quantity" in return parameter "data", which means the trading quantity(coin), Calculation formula: quantity(coin) = trading quantity(cont) * contract size. Added "trade_turnover" in return parameter "data", which represents the trading amount(quoted currency). Calculation formula: trade_turnover(quoted currency) = trading quantity(cont) * contract size * trading price.)

14. Modified Request Trade Detail Data interface(Added "quantity" in return parameter "data", which means the trading quantity(coin), Calculation formula: quantity(coin) = trading quantity(cont) * contract size. Added "trade_turnover" in return parameter "data", which represents the trading amount(quoted currency). Calculation formula: trade_turnover(quoted currency) = trading quantity(cont) * contract size * trading price.)

1. Added Get a Batch of Market Data Overview

2. Added Get Kline Data of Mark Price

3. Added Subscribe Kline Data of Mark Price

4. Added Request Kline Data of Mark Price

5. Added [Isolated]Query Settlement Records of Users

6. Added [Cross]Query Settlement Records of Users

7. Modified [Isolated]Cancel All Orders(Added two optional parameters in request: direction, indicates order direction, if not filled in means both with available values: “buy”, “sell”; offset, order offset, if not filled in means both with available values: “open”, “close”.)

8. Modified [Cross]Cancel All Orders(Added two optional parameters in request: direction, indicates order direction, if not filled in means both with available values: “buy”, “sell”. offset, order offset, if not filled in means both with available values: “open”, “close”.)

9. Modified [Isolated]Get Information of an Order(Added one field in return "data": real_profit(real profit when close position).)

10. Modified [Cross]Get Information of an Order(Added one field in return "data": real_profit(real profit when close position).)

11. Modified [Isolated]Order details acquisition(Added field in return parameters both "data" and "trades": real_profit(real profit when close position). And added one filed in "trades" to indicates each trade profit：profit(profit when close position))

12. Modified [Cross]Order details acquisition(Added field in return parameters both "data" and "trades": real_profit(real profit when close position). And added one filed in "trades" to indicates each trade profit：profit(profit when close position))

13. Modified [Isolated]Current unfilled order acquisition(Added two optional parameters in request: sort_by, is sort field, if not filled in means order by create_at descending, with available values “created_at”(descending order), “update_time”(descending order); trade_type, indicates trade type, if not filled in means all, with available values: 0:all, 1:open long, 2:open short, 3:close short, 4:close long. Added two fields in return parameter "orders": update_time(order updated time, in milliseconds), real_profit(real profit when close position).)

14. Modified [Cross]Current unfilled order acquisition(Added two optional parameters in request: sort_by, is sort field, if not filled in means order by create_at descending, with available values “created_at”(descending order), “update_time”(descending order); trade_type, indicates trade type, if not filled in means all, with available values: 0:all, 1:open long, 2:open short, 3:close short, 4:close long. Added two fields in return parameter "orders": update_time(order updated time, in milliseconds); real_profit(real profit when close position).)

15. Modified [Isolated]Get History Orders(Added one field in return parameter "orders": real_profit(real profit when close position).)

16. Modified [Cross]Get History Orders(Added one field in return parameter "orders": real_profit(real profit when close position).)

17. Modified [Isolated]Acquire History Match Results(Added one field in return parameter "trades": real_profit(real profit when close position).)

18. Modified [Cross]Acquire History Match Results(Added one field in return parameter "trades": real_profit(real profit when close position).)

19. Modified [Isolated]Subscribe Order Data(sub)(Added one field in return data: real_profit(real profit when close position). added field in return parameter "trade": profit(profit when close position), real_profit(real profit when close position))

20. Modified [Cross]Subscribe Order Data(sub)(Added one field in return data: real_profit(real profit when close position). added field in return parameter "trade": profit(profit when close position), real_profit(real profit when close position))

21. Modified [Isolated]Cancel All Trigger Orders(Added two optional parameters in request: direction, indicates order direction, if not filled in means both with available values: “buy”, “sell”; offset, order offset, if not filled in means both with available values: “open”, “close”.)

22. Modified [Cross]Cancel All Trigger Orders(Added two optional parameters in request: direction, indicates order direction, if not filled in means both with available values: “buy”, “sell”; offset, order offset, if not filled in means both with available values: “open”, “close”.)

23. Modified [Isolated]Cancel all Take-profit and Stop-loss Orders(Added one option parameter in request: direction, indicates order direction, if not filled in means cancel all)

24. Modified [Cross]Cancel all Take-profit and Stop-loss Orders(Added one option parameter in request: direction, indicates order direction, if not filled in means cancle all)

25. Modified [Isolated]Query Trigger Order Open Orders(Added one optional parameter in request: trade_type, order trade type, if not filled in means all with available values 0:all, 1:open long, 2:open short, 3:close short, 4:close long.)

26. Modified [Cross]Query Trigger Order Open Orders(Added one optional parameter in request: trade_type, order trade type, if not filled in means all with available values 0:all, 1:open long, 2:open short, 3:close short, 4:close long.)

27. Modified [Isolated]Query Open Take-profit and Stop-loss Orders(Added one optional parameter in request: trade_type, order trade type, if not filled in means all with available values 0:all, 3:close short, 4:close long.)

28. Modified [Cross]Query Open Take-profit and Stop-loss Orders(Added one optional parameter in request: trade_type, order trade type, if not filled in means all with available values 0:all, 3:close short, 4:close long.)

1. Added Get the estimated settlement price

2. Added Set a Take-profit and Stop-loss Order for an Existing Position(Isolated)

3. Added Set a Take-profit and Stop-loss Order for an Existing Position(Cross)

4. Added Cancel a Take-profit and Stop-loss Order(Isolated)

5. Added Cancel a Take-profit and Stop-loss Order(Cross)

6. Added Cancel all Take-profit and Stop-loss Orders(Isolated)

7. Added Cancel all Take-profit and Stop-loss Orders(Cross)

8. Added Query Open Take-profit and Stop-loss Orders (Isolated)

9. Added Query Open Take-profit and Stop-loss Orders(Cross)

10. Added Query Take-profit and Stop-loss History Orders(Isolated)

11. Added Query Take-profit and Stop-loss History Orders(Cross)

14. Modifed "Place an order" Interface(Isolated)（added optional parameters: tp_trigger_price (Trigger price of take-profit order), tp_order_price (Order price of take-profit order), tp_order_price_type (Order type of take-profit order), sl_trigger_price (Trigger price of stop-loss order), sl_order_price (Order price of stop-loss order), sl_order_price_type (Order type of stop-loss order)）

15. Modifed "Place an order" Interface(Cross)（added optional parameters: tp_trigger_price (Trigger price of take-profit order), tp_order_price (Order price of take-profit order), tp_order_price_type (Order type of take-profit order), sl_trigger_price (Trigger price of stop-loss order), sl_order_price (Order price of stop-loss order), sl_order_price_type (Order type of stop-loss order)）

16. Modified "Place a batch of orders"Interface(Isolated) (added optional parameters in parameters "orders_data": tp_trigger_price (Trigger price of take-profit order)，tp_order_price (Order price of take-profit order), tp_order_price_typeOrder type of take-profit order), sl_trigger_price (Trigger price of stop-loss order), sl_order_price (Order price of stop-loss order), sl_order_price_type (Order type of stop-loss order)）

17. Modified "Place a batch of orders"Interface(Cross) (added optional parameters in parameters "orders_data": tp_trigger_price (Trigger price of take-profit order)，tp_order_price (Order price of take-profit order), tp_order_price_typeOrder type of take-profit order), sl_trigger_price (Trigger price of stop-loss order), sl_order_price (Order price of stop-loss order), sl_order_price_type (Order type of stop-loss order)）

18. Modified "Get Information of an Order" Interface(Isolated)（Added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no); added "enumerated values" in return parameter "order_source"（“tpsl” indicates triggered by take-profit and stop-loss））

19. Modified "Get Information of an Order" Interface(Cross)（Added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no); added "enumerated values" in return parameter "order_source"（“tpsl” indicates triggered by take-profit and stop-loss））

20. Modified "Order details acquisition" Interface(Isolated)（Added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no); added "enumerated values" in return parameter "order_source"（“tpsl” indicates triggered by take-profit and stop-loss））

21. Modified "Order details acquisition" Interface(Cross)（Added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no); added "enumerated values" in return parameter "order_source"（“tpsl” indicates triggered by take-profit and stop-loss））

22. Modified "Query Open Orders" Interface(Isolated)（Added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no); added "enumerated values"in return parameter "order_source"（“tpsl” indicates triggered by take-profit and stop-loss））

23. Modified "Query Open Orders" Interface(Cross)（Added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no); added "enumerated values"in return parameter "order_source"（“tpsl” indicates triggered by take-profit and stop-loss））

24. Modified "Get History Orders" Interface(Isolated)（Added paprameter "sort_by" to represent "sort fields" with optional value“create_date” and “update_time"; added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no), and "update_time" to indicate order's update time）; and "enumerated values" in return parameter "order_source"（“tpsl” indicates triggered by take-profit or stop-loss））

25. Modified "Get History Orders" Interface(Cross)（Added paprameter "sort_by" to represent "sort fields" with optional value“create_date” and “update_time"; added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no), and "update_time" to indicate order's update time）; and "enumerated values" in return parameter "order_source"（“tpsl” indicates triggered by take-profit or stop-loss））

26. Modified "Subscribe Order Data(sub)" Interface(Isolated)（Added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no); added "enumerated values" in return parameter "order_source"（“tpsl” indicates triggered by take-profit and stop-loss））

27. Modified "Subscribe Order Data(sub)" Interface(Cross)（Added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no); added "enumerated values" in return parameter "order_source"（“tpsl” indicates triggered by take-profit and stop-loss））

28. Modified "Subscribe Match Order Data（sub）" Interface(Isolated)（Added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no); added "enumerated values" in return parameter "order_source"（“tpsl” indicates triggered by take-profit and stop-loss））

29. Modified "Subscribe Match Order Data（sub）" Interface(Cross)（Added return parameter "is_tpsl" to indicate whether to set take-profit and stop-loss order, 1: yes, 0: no); added "enumerated values" in return parameter "order_source"（“tpsl” indicates triggered by take-profit and stop-loss））

30. Modified "Query Trigger Order History" Interface(Isolated)（Added paprameter "sort_by" to represent "sort fields" with optional values “created_at” and “update_time”). added "update_time" to indicate order's update time））

31. Modified "Query Trigger Order History" Interface(Cross)（Added paprameter "sort_by" to represent "sort fields" with optional values “created_at” and “update_time”). added "update_time" to indicate order's update time））

32. Modified "Get Swap Open Interest Information" Interface (Added "trade_volume" in return parameter "data" to indicate trading volume within the last 24 hours (cont), and "trade_amount" to indicate trading volume within the last 24 hours (coin), and "trade_turnover" to represent trading amount within the last 24 hours.)

33. Modified "Subscribe Market Detail Data" Interface (Added "ask" in return parameter “tick” to represent “sell one” and “bid” to represent "buy one".)

34. Modified "Query Swap Info" Interface（Added "delivery_time" in return parameter "data" to represent delivery time（millesecond timestamp））

35. Modified "Subscribe Contract Info" Interface（Added "delivery_time" in return parameter "data" to represent delivery time（millesecond timestamp））

1.0.5 2020-12-18 【Newly added：Added WS interface for subscribing system status updates push】

1.Added WS interface for subscribing system status updates push

1.0.4 2020-12-11 【1-33 Added interfaces for cross margin mode. 34-60 Added fields to modify interface】

1、Added Cross Margin Mode Query Information On Tiered Adjustment Factor

2、Added Cross Margin Mode Query Information On Transfer State

3、Added Cross Margin Mode Query Information On Trade State

4、Added Cross Margin Mode Query User's Account Information

5、Added Cross Margin Mode Query User's Position Information

6、Added Cross Margin Mode Query Assets Information Of All Sub-Accounts Under The Master Account

7、Added Cross Margin Mode Query A Sub-Account's Assets Information

8、Added Cross Margin Mode Query A Sub-Account's Position Information

9、Added Cross Margin Mode Query Information On Transfer Limit

10、Added Cross Margin Mode Query Information On Position Limit

11、Added Cross Margin Mode Query Assets And Positions

12、Added Cross Margin Mode Query User’s Available Leverage

13、Added Cross Margin Mode Switch Leverage

14、Added Cross Margin Mode Place An Order

15、Added Cross Margin Mode Place A Batch Of Orders

16、Added Cross Margin Mode Cancel An Order

17、Added Cross Margin Mode Cancel All Orders

18、Added Cross Margin Mode Get Information of order

19、Added Cross Margin ModeGet Detail Information of order

20、Added Cross Margin Mode Current unfilled order acquisition

21、Added Cross Margin Mode Get History Orders

22、Added Cross Margin Mode Get History Match Results

23、Added Cross Margin Mode Place Lightning Close Position

24、Added Cross Margin Mode Place Trigger Order

25、Added Cross Margin Mode Cancel Trigger Order

26、Added Cross Margin Mode Cancel All Trigger Orders

27、Added Cross Margin Mode Query Open Trigger Order

28、Added Cross Margin Mode Query Trigger Order History

29、Added Cross Margin Mode Subscribe Order Data

30、Added Cross Margin Mode Subscribe Account Equity Updates Data

31、Added Cross Margin Mode Subscribe Position Updates

32、Added Cross Margin Mode Subscribe Match Order Data

33、Added Cross Margin Mode Subscribe trigger orders updates

34、Query Swap Info Added fields (added “support_margin_mode” parameter; added “support_margin_mode” in return parameter “data” to represent the margin mode that a contract supports.)

35、Query information on Tiered Adjustment Factor Added fields for return parameters ( added “margin_mode” to represent margin mode)

36、Query information on system status Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

37、Query User’s Account Information Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

38、Query a single sub-account's assets information Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

39、Query Assets And Positions Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

40、Query assets information of all sub-accounts under the master account Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

41、Query User’s Position Information Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

42、Query a single sub-account's position information Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

43、Query account financial records Added fields (added “contract_code” to represent contract code)

44、Order details acquisition Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

45、Current unfilled order acquisition Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

46、Get History Orders Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

47、Acquire History Match Results Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

48、Query Trigger Order Open Orders Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

49、Query Trigger Order History Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

50、Query information on Transfer Limit Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

51、Query information on position limit Added fields for return parameters ( added “margin_mode” to represent margin mode)

52、Query user’s available leverage Added fields for return parameters ( added “margin_mode” to represent margin mode)

53、Switch Leverage Added fields for return parameters ( added “margin_mode” to represent margin mode)

54、Subscribe Order Data Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

55、Subscribe Match Order Data Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

56、Subscribe trigger orders updates Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

57、Subscribe Position Updates Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

58、Subscribe Account Equity Updates Data Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

59、Subscribe Contract Info (no authentication) Added fields for return parameters ( added “support_margin_mode” to represent support margin mode)

60、Get Information of an Order Added fields for return parameters (added “margin_account” for return parameters to represent margin account; added “margin_mode” to represent margin mode)

1.0.3 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.)】

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

1.0.2 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” and “trade_turnover” are added for return parameter orders". ）

3、Added fields of return parameter for "Subscribe Liquidation Order Data" interface（“amount” and “trade_turnover” are added for return parameter “data".）

1.0.1 2020-10-29 【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;】

1、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".）

2、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).）

1.0.0 2020-10-26 14:00(GMT+8)

Swap API Access Guide

API List

permission type Content Type Interface Mode Context Request Type Desc Signature Required
Read Market Data general /linear-swap-api/v1/swap_contract_info GET Get Contracts Information No
Read Market Data general /linear-swap-api/v1/swap_index GET Get contract Index Price Information No
Read Market Data general /linear-swap-api/v1/swap_price_limit GET Query Swap Price Limitation No
Read Market Data general /linear-swap-api/v1/swap_open_interest GET Get Contract Open Interest Information No
Read Market Data general /linear-swap-api/v1/swap_risk_info GET Query information on contract insurance fund balance and estimated clawback rate No
Read Market Data general /inear-swap-api/v1/swap_insurance_fund GET Query history records of insurance fund balance No
Read Market Data isolated margin /linear-swap-api/v1/swap_adjustfactor GET Query information on Tiered Adjustment Factor No
Read Market Data general /linear-swap-api/v1/swap_his_open_interest GET Query information on open interest No
Read Market Data general /linear-swap-api/v1/swap_elite_account_ratio GET Query Top Trader Sentiment Index Function-Account No
Read Market Data general /linear-swap-api/v1/swap_elite_position_ratio GET Query Top Trader Sentiment Index Function-Position No
Read Market Data general /linear-swap-api/v1/swap_liquidation_orders GET Query Liquidation Order Information No
Read Market Data general /linear-swap-api/v1/swap_settlement_records GET Query historical settlement records of the platform interface No
Read Market Data isolated margin /linear-swap-api/v1/swap_api_state GET Query information on system status No
Read Market Data general /linear-swap-api/v1/swap_funding_rate GET Query funding rate No
Read Market Data general /linear-swap-api/v1/swap_batch_funding_rate GET [General]Query a Batch of Funding Rate No
Read Market Data general /linear-swap-api/v1/swap_historical_funding_rate GET Query Historical Funding Rate No
Read Market Data general /linear-swap-ex/market/depth GET Get Market Depth No
Read Market Data General /linear-swap-ex/market/bbo GET Get Market BBO Data No
Read Market Data general /linear-swap-ex/market/history/kline GET Get KLine Data No
Read Market Data general /index/market/history/linear_swap_mark_price_kline GET Get Kline Data of Mark Price No
Read Market Data general /linear-swap-ex/market/detail/merged GET Get Market Data Overview No
Read Market Data general /linear-swap-ex/market/detail/batch_merged GET Get a Batch of Market Data Overview No
Read Market Data general /v2/linear-swap-ex/market/detail/batch_merged GET Get a Batch of Market Data Overview(V2) No
Read Market Data general /index/market/history/linear_swap_basis GET Query Basis Data No
Read Market Data general /index/market/history/linear_swap_premium_index_kline GET Query Liquidation Order Information No
Read Market Data general /index/market/history/linear_swap_estimated_rate_kline GET Query Swap Market Data interface No
Read Market Data general /linear-swap-ex/market/trade GET Query The Last Trade of a Contract No
Read Market Data general /linear-swap-ex/market/history/trade GET Query a Batch of Trade Records of a Contract No
Read Market Data cross margin /linear-swap-api/v1/swap_cross_adjustfactor GET Query Information On Tiered Adjustment Factor No
Read Market Data cross margin /linear-swap-api/v1/swap_cross_transfer_state GET Query Information On Transfer State No
Read Market Data cross margin /linear-swap-api/v1/swap_cross_trade_state GET Query Information On Trade State No
Read Market Data general /linear-swap-api/v1/swap_estimated_settlement_price GET Get the estimated settlement price No
Read Market Data general /linear-swap-api/v1/swap_ladder_margin GET [Isolated]Query information on Tiered Margin No
Read Market Data general /linear-swap-api/v1/swap_cross_ladder_margin GET [Cross]Query information on Tiered Margin No
Read Account isolated margin /linear-swap-api/v1/swap_balance_valuation POST [General]Query Asset Valuation Yes
Read Account isolated margin /linear-swap-api/v1/swap_account_info POST Query User’s Account Information Yes
Read Account isolated margin /linear-swap-api/v1/swap_position_info POST Query User’s position Information Yes
Read Account isolated margin /linear-swap-api/v1/swap_available_level_rate POST Query user’s available leverage Yes
Trade Account general /linear-swap-api/v1/swap_sub_auth POST [General]Set a Batch of Sub-Account Trading Permissions Yes
Read Account isolated margin /linear-swap-api/v1/swap_sub_account_list POST Query assets information of all sub-accounts under the master account (Query by coins) Yes
Read Account cross margin /linear-swap-api/v1/swap_sub_account_info_list POST [Isolated]Query a Batch of Sub-Account's Assets Information Yes
Read Account isolated margin /linear-swap-api/v1/swap_cross_sub_account_info_list POST [Cross]Query a Batch of Sub-Account's Assets Information Yes
Read Account isolated margin /linear-swap-api/v1/swap_sub_account_info POST Query a single sub-account's assets information Yes
Read Account isolated margin /linear-swap-api/v1/swap_sub_position_info POST Query a single sub-account's position information Yes
Read Account general /linear-swap-api/v1/swap_financial_record POST Query account financial records Yes
Read Account general /linear-swap-api/v1/swap_financial_record_exact POST [General]Query account financial records via Multiple Fields Yes
Read Account isolated margin /linear-swap-api/v1/swap_user_settlement_records POST Query Settlement Records of Users Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_user_settlement_records POST Query Settlement Records of Users Yes
Read Account general /linear-swap-api/v1/swap_order_limit POST Query contract information on order limit Yes
Read Account general /linear-swap-api/v1/swap_fee POST Query information on contract trading fee Yes
Read Account isolated margin /linear-swap-api/v1/swap_transfer_limit POST Query information on Transfer Limit Yes
Read Account isolated margin /linear-swap-api/v1/swap_position_limit POST Query information on position limit Yes
Read Account isolated margin /linear-swap-api/v1/swap_lever_position_limit POST [Isolated]Query Users' Position Limit for All Leverages Yes
Read Account isolated margin /linear-swap-api/v1/swap_account_position_info POST Query Assets And Positions Yes
Trade Account general /linear-swap-api/v1/swap_master_sub_transfer POST Transfer between master account and sub-accounts Yes
Read Account general /linear-swap-api/v1/swap_master_sub_transfer_record POST Query transfer records of master account Yes
Trade Account general /linear-swap-api/v1/swap_transfer_inner POST Transfer between different margin accounts under the same account Yes
Read Account general /linear-swap-api/v1/swap_api_trading_status GET Query user's API indicator disable information Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_account_info POST Query User's Account Information Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_position_info POST Query User's Position Information Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_sub_account_list POST Query Assets Information Of All Sub-Accounts Under The Master Account Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_sub_account_info POST Query A Sub-Account's Assets Information Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_sub_position_info POST Query A Sub-Account's Position Information Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_transfer_limit POST Query Information On Transfer Limit Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_position_limit POST Query Information On Position Limit Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_lever_position_limit POST [Cross]Query Users' Position Limit for All Leverages Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_account_position_info POST Query Assets And Positions Yes
Read Account cross margin /linear-swap-api/v1/swap_cross_available_level_rate POST Query User’s Available Leverage Yes
Trade Trade isolated margin /linear-swap-api/v1/swap_switch_position_mode POST [Isolated]Switch Position Mode Yes
Trade Trade cross margin /linear-swap-api/v1/swap_cross_switch_position_mode POST [Cross]Switch Position Mode Yes
Trade Trade isolated margin /linear-swap-api/v1/swap_order POST Place an Order Yes
Trade Trade isolated margin /linear-swap-api/v1/swap_batchorder POST Place a Batch of Orders Yes
Trade Trade isolated margin /linear-swap-api/v1/swap_switch_lever_rate POST Switch Leverage Yes
Trade Trade isolated margin /linear-swap-api/v1/swap_cancel POST Cancel an Order Yes
Trade Trade isolated margin /linear-swap-api/v1/swap_cancelall POST Cancel All Orders Yes
Read Trade isolated margin /linear-swap-api/v1/swap_order_info POST Get Information of an Order Yes
Read Trade isolated margin /linear-swap-api/v1/swap_order_detail POST Get Trade Details of an Order Yes
Read Trade isolated margin /linear-swap-api/v1/swap_openorders POST Get Current Orders Yes
Read Trade isolated margin /linear-swap-api/v1/swap_hisorders POST Get History Orders Yes
Read Trade isolated margin /linear-swap-api/v1/swap_matchresults POST Acquire History Match Results Yes
Read Trade isolated margin /linear-swap-api/v1/swap_hisorders_exact POST [Isolated]Get History Orders via Multiple Fields Yes
Read Trade Cross margin /linear-swap-api/v1/swap_cross_hisorders_exact POST [Cross]Get History Orders via Multiple Fields Yes
Read Trade Isolated margin /linear-swap-api/v1/swap_matchresults_exact POST [Isolated]Get History Match Results via Multiple Fields Yes
Read Trade Cross margin /linear-swap-api/v1/swap_cross_matchresults_exact POST [Cross]Get History Match Results via Multiple Fields Yes
Trade Trade isolated margin /linear-swap-api/v1/swap_lightning_close_position POST Place Lightning Close Order Yes
Trade Strategy isolated margin /linear-swap-api/v1/swap_trigger_order POST Place an Trigger Order Yes
Trade Strategy isolated margin /linear-swap-api/v1/swap_trigger_cancel POST Cancel a Trigger Order Yes
Trade Strategy isolated margin /linear-swap-api/v1/swap_trigger_cancelall POST Cancel all trigger Orders Yes
Read Strategy isolated margin /linear-swap-api/v1/swap_trigger_openorders POST Get all open trigger Orders Yes
Read Strategy isolated margin /linear-swap-api/v1/swap_trigger_hisorders POST Get all history trigger Orders Yes
Trade Trade cross margin /linear-swap-api/v1/swap_cross_switch_lever_rate POST Switch Leverage Yes
Trade Trade cross margin /linear-swap-api/v1/swap_cross_order POST Place An Order Yes
Trade Trade cross margin /linear-swap-api/v1/swap_cross_batchorder POST Place A Batch Of Orders Yes
Trade Trade cross margin /linear-swap-api/v1/swap_cross_cancel POST Cancel An Order Yes
Trade Trade cross margin /linear-swap-api/v1/swap_cross_cancelall POST Cancel All Orders Yes
Read Trade cross margin /linear-swap-api/v1/swap_cross_order_info POST Get Information of order Yes
Read Trade cross margin /linear-swap-api/v1/swap_cross_order_detail POST Get Detail Information of order Yes
Read Trade cross margin /linear-swap-api/v1/swap_cross_openorders POST Current unfilled order acquisition Yes
Read Trade cross margin /linear-swap-api/v1/swap_cross_hisorders POST Get History Orders Yes
Read Trade cross margin /linear-swap-api/v1/swap_cross_matchresults POST Get History Match Results Yes
Trade Trade cross margin /linear-swap-api/v1/swap_cross_lightning_close_position POST Place Lightning Close Position Yes
Trade Strategy cross margin /linear-swap-api/v1/swap_cross_trigger_order POST Place Trigger Order Yes
Trade Strategy cross margin /linear-swap-api/v1/swap_cross_trigger_cancel POST Cancel Trigger Order Yes
Trade Strategy cross margin /linear-swap-api/v1/swap_cross_trigger_cancelall POST Cancel All Trigger Orders Yes
Read Strategy cross margin /linear-swap-api/v1/swap_cross_trigger_openorders POST Query Open Trigger Order Yes
Read Strategy cross margin /inear-swap-api/v1/swap_cross_trigger_hisorders POST Query Trigger Order History Yes
Trade Strategy isolated margin /linear-swap-api/v1/swap_tpsl_order POST [Isolated]Set a Take-profit and Stop-loss Order for an Existing Position Yes
Trade Strategy isolated margin /linear-swap-api/v1/swap_tpsl_cancel POST [Isolated]Cancel a Take-profit and Stop-loss Order Yes
Trade Strategy isolated margin /linear-swap-api/v1/swap_tpsl_cancelall POST [Isolated]Cancel all Take-profit and Stop-loss Orders Yes
Read Strategy isolated margin /linear-swap-api/v1/swap_tpsl_openorders POST [Isolated]Open take-profit and stop-loss orders Yes
Read Strategy isolated margin /linear-swap-api/v1/swap_tpsl_hisorders POST [Isolated]Take-profit and stop-loss histoty orders yes
Read Strategy isolated margin /linear-swap-api/v1/swap_relation_tpsl_order POST [Isolated]Query Info Of Take-profit and Stop-loss Order That Related To Position Opening Order Yes
Trade Strategy cross margin /linear-swap-api/v1/swap_cross_tpsl_order POST [Cross]Set a Take-profit and Stop-loss Order for an Existing Position Yes
Trade Strategy cross margin /linear-swap-api/v1/swap_cross_tpsl_cancel POST [Cross]Cancel a Take-profit and Stop-loss Order Yes
Trade Strategy cross margin /linear-swap-api/v1/swap_cross_tpsl_cancelall POST [Cross]Cancel all Take-profit and Stop-loss Orders Yes
Read Strategy cross margin /linear-swap-api/v1/swap_cross_tpsl_openorders POST [Cross]Open take-profit and stop-loss orders Yes
Read Strategy cross margin /linear-swap-api/v1/swap_cross_tpsl_hisorders POST [Cross]Take-profit and stop-loss histoty orders Yes
Read Strategy cross margin /linear-swap-api/v1/swap_cross_relation_tpsl_order POST [Cross]Query Info Of Take-profit and Stop-loss Order That Related To Position Opening Order Yes
Trade Account general https://api.huobi.pro/v2/account/transfer POST Transfer margin between Spot account and USDT Margined Contracts account Yes
Trade Strategy Isolated /linear-swap-api/v1/swap_track_order POST 【Isolated】Place a Trailing Order Yes
Trade Strategy Isolated /linear-swap-api/v1/swap_track_cancel POST 【Isolated】Cancel a Trailing Order Order Yes
Trade Strategy Isolated /linear-swap-api/v1/swap_track_cancelall POST 【Isolated】Cancel All Trailing Orders Yes
Read Strategy Isolated /linear-swap-api/v1/swap_track_openorders POST 【Isolated】Current unfilled trailing order acquisition Yes
Read Strategy Isolated /linear-swap-api/v1/swap_track_hisorders POST 【Isolated】Get History Trailing Orders Yes
Trade Strategy Cross /linear-swap-api/v1/swap_cross_track_order POST 【Cross】Place a Trailing Order Yes
Trade Strategy Cross /linear-swap-api/v1/swap_cross_track_cancel POST 【Cross】Cancel a Trailing Order Order Yes
Trade Strategy Cross /linear-swap-api/v1/swap_cross_track_cancelall POST 【Cross】Cancel All Trailing Orders Yes
Read Strategy Cross /linear-swap-api/v1/swap_cross_track_openorders POST 【Cross】Current unfilled trailing order acquisition Yes
Read Strategy Cross /linear-swap-api/v1/swap_cross_track_hisorders POST 【Cross】Get History Trailing Orders Yes

Address

Address Applicable sites Applicable functions Applicable trading pairs
https://api.hbdm.com Huobi USDT Margined Contracts API Trading pairs provided by Huobi USDT Margined Contracts

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 Guide

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/linear-swap-api/v1/swap_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"

/linear-swap-api/v1/swap_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

/linear-swap-api/v1/swap_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/linear-swap-api/v1/swap_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 Contracts 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

API Best Practice

1. Query contract history orders interface: /linear-swap-api/v1/swap_hisorders

2. Query contract match results interface: /linear-swap-api/v1/swap_matchresults

3. Query contract financial record interface: /linear-swap-api/v1/swap_financial_record

4. Query contract order detail interface: /linear-swap-api/v1/swap_order_detail

5. WebSocket subscription to Market Depth data:

{

"sub": "market.BTC-USDT.depth.step6",

"id": "id5"

}

{

"sub": "market.BTC-USDT.depth.size_20.high_freq",

"data_type":"incremental",

"id": "id1"

}

6. Place order interface (URL: /linear-swap-api/v1/swap_order) and place a batch of orders interface (URL:/linear-swap-api/v1/swap_batchorder):

7. The best deployment of program server

Code Demo

PS: USDT Margined Contracts api is similar to Coin margined swap api and future api.

Swap API FAQ

Access and Authentication

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

Yes. The Swap 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 or api.hbdm.vn to debug for China mainland 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 USDT Margined Contracts 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 USDT Margined Contracts is similar to huobi future and coin margined swap . In addition to the following precautions,please refer to the swap or future 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 USDT Margined Contracts 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 shoule 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
  11. The host in signature text should be the same as the host in your API request.The proxy may change the request host, you can try without proxy;Some http/websocket library may include port in the host, you can try to append port in signature host, like "api.hbdm.com:443"
  12. The hidden text in API Key and Secret Key may have impact on the signature.

If the reason for signature failure has not been found through the above methods. And you can confirm that by this demo which is specially explaining the signature.

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 swap?

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.

Settlement

Q1: What is the USDT Margined Swap funding rate settlement cycle? Which interface can be used to check the status when the fund rate is settled?

We warmly remind you that Huobi USDT Margined Swap is settled every 8 hours, and the settlement will be at the end of each period. For example, 00:00 - 08:00 is a period, and its settlement time would be at 08:00; 08:00 - 16:00 is a period, and its settlement time would be at 16:00; 16:00 - 00:00 (+1 day) is a period, and its settlement time would be at 00:00. All times mentioned above are Singapore Standard time (GMT+8).

（1）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 by this two ways:

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.

（2）When querying fund or position information during the settlement period, error codes will be returned. Error code and their meaning are as following:

  1. Error code "1077" indicates that "the fund query of current perpetual swap trading pair failed during the settlement";
  2. Error code "1078" indicates that "the fund query of part of perpetual swap trading pairs failed during the settlement";
  3. Error code "1079" indicates that "the position query of current perpetual swap trading pair failed during the settlement";
  4. 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: How to query the system status of the exchange?

There are two common statuses of the exchange systems: settlement/delivery in progress; suspended for maintenance; when the system is in these two kinds of statuses, the system will return the response error code and error information when calling the related API interfaces.

a. How to judge whether the settlement/delivery has been done?

Users can judge from the value “contract_status” returned by the “Get Information of an Order” interface (/linear-swap-api/v1/swap_contract_info);

or Subscribe Contract Info (no authentication): public.$symbol.contract_info

If the return parameter contract_status is 1, it means that the settlement/delivery has been done and the trading has been resumed now.

b. How to judge whether the system is suspended for maintenance or not?

Users can judge from the value “heartbeat” pushed by the “Queried if system interface is available” interface (https://api.hbdm.com/heartbeat/)

or the “Subscribe system status updates” interface ("topic: public.$service.heartbeat");

If the return parameter heartbeat is 1, it means that the system is available now and can be connected normally.

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 symbol 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 order price type.
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}{1}. Sell price must exceed {2}{3}.
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 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}{1}.
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 of current contract.
1078 In settlement or delivery. Unable to get assets of some contracts.
1079 In settlement or delivery. Unable to get positions of current contract.
1080 In settlement or delivery. Unable to get positions of some contracts.
1081 The number of your {0} contract trigger orders exceeds the limit {1}.
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 Transfer is temporarily restricted for {0} account, please contact customer service support.
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 Delivery or settlement in progress, unable to 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 You have not activated contract trading currently, please activate first.
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 For {0} contracts, the number of the position-opening orders which are not fully filled cannot exceed {1}.
1235 For {0} contracts, the number of the position-closing orders which are not fully filled 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
1343 Invalid indicator, please reset
1344 Sorry, {0} contracts can add market reminders currently at most
1345 Sorry, currently {0} can set up to {1} reminders
1346 The indicator already exists, please do not set it repeatedly
1347 {0} parameter is incorrect, please modify.
1348 This contract does not support cross margin mode.
1349 The leverage of the order does not match the leverage of the current position, please switch the leverage first.
1401 order price shall be lower than the strike price.
1403 The number of take-profit and stop-loss orders for {0} contract shall not exceed {1}
1404 Take-profit and stop-loss orders can only be bound with orders for opening a position
1405 The take-profit price shall not be {0}{1}{2}
1406 Your chances of lucky draw have been used up
1407 The stop-loss price shall not be {0}{1}{2}
1408 Unable to cancel because the take-profit and stop-loss order does not take effect.
1409 You have no access to set a take-profit and stop-loss order, please contact our customer service.
1410 The number of sub-accounts for batch operation cannot exceed {0}
1411 Settlement in progress, unable to query order information.
1412 {0} does not meet with the price precision limit {1}.
1413 You have no access to set a Trailing Stop order, please contact our customer service.
1414 You have not activated the grid trading. Please log in to the Web or APP with your main account, and agree with the protocol to activate the grid trading.
1415 Terminate price (Take-profit/Stop-loss price) cannot be within the range of grid price, please modify!
1416 Exceeds the maximum running time, which is{0} days and {1} hours, please modify!
1417 Exceeds the range of grid quantity, which is ({0} ~ {1}), please modify!
1418 At most {0} grids trading orders can be running at the same time, please cancel other grid trading orders first.
1419 Exceeds the range of initial margin ({0} ~ {1}} {2}).
1420 You have no access to grid trading on Huobi Futures, please contact our customer service.
1421 There are open orders or positions of the current contract, please cancel these orders or close these positions first.
1422 The PnL per grid is expected to be less than 0, please modify!
1423 The spread between the lowest and the highest grid price is unreasonable, please modify!
1424 This grid trading has been terminated for other reasons. Therefore, it cannot be modified or manually terminated now.
1425 The callback rate should be {0}{1}, please modify!
1426 The activation price should be {0} the latest price.
1427 The number of your {0} contract trailing stop order orders exceeds the limit {1}.
1428 The coupon for the same type of contract can only be collected once by each user.
1429 Already received; please do not collect again!
1430 Invalid coupon; please refresh!
1431 The system is in maintenance and is expected to resume at {0} (GMT+8).
1432 A grid trading is being initialized or terminated; unable to place an order currently.
1433 The grid trading is terminated caused by placing/canceling order manually; please check “Order History” for details.
1434 Less than the minimum initial margin ({0}{1}), which causes the quantity per grid less than the minimum order quantity, please modify!
1435 The grid has been terminated by you.
1436 The grid trading exceeds the effective duration; terminated automatically.
1437 The grid trading has been terminated for system reasons, please contact our customer service.
1438 The grid trading has been terminated due to the termination condition being triggered.
1439 The grid trading has been terminated due to a liquidation being triggered.
1440 {0} contracts fail to be cancelled.
1441 The trigger price must be lower than the highest termination price and higher than the lowest termination price, please modify!
1442 The effective duration must be a minute longer than the running time, please modify!
1443 Delivery of {0} contract causes grid trading termination.
1450 The risk level you ranked does not support the use of current leverage.
1451 The risk level you ranked does not support the use of current leverage, please log in the main account for checking.
1452 The number of grid orders exceeds the order quantity limits; Unable to place any order temporarily.
1453 The number of all your trigger orders exceeds the limit set by the platform; Unable to place any orders temporarily.
1454 The number of all your take profit and stop loss orders exceeds the limit set by the platform; Unable to place any orders temporarily.
1455 The number of all your trailing stop orders exceeds the limit set by the platform; Unable to place any orders temporarily.
1484 Reverse order involves Reduce Only order.
1485 One-way mode is unavailable for grid trading.
1486 One-way mode is unavailable temporarily.
1487 We are sorry you have no access to one-way mode.
1488 Opening positions is unavailable in one-way mode temporarily.
1489 Closing positions is unavailable in one-way mode temporarily.
1490 Opening after closing exceeds the limit (conts).
1491 Reduce Only order parameter error!
1492 Amount of Reduce Only order exceeds the amount available to close.
1493 Position mode cannot be adjusted for open orders.
1494 Position mode cannot be adjusted for existing positions.
1495 Position mode cannot be adjusted for open grid orders.
1496 Position mode cannot be adjusted due to the contract’s non-trading status.
1497 Position mode parameter passing error!
1498 Margin account incorrect!
1499 Hedge mode currently; Unavailable to place orders in one-way mode.
1500 One-way mode currently; Unavailable to place orders in hedge mode.
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.

Market and Websocket

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

The snapshot orderbook subscription(market.$contract_code.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?

The historical kline data can be obtained via API interface /market/history/kline with the request params from, to (the time period cannot exceed two years). And the qty of data records cannot be exceeding 2000 in each time.

The historical trade data can be obtained by subscribing the websocket topic: market.$symbol.trade.detail

or can be downloaded from download historical market data

But also, you can download that data using The demo of downloading historical market data

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.$contract_code.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.$contract_code.depth.$type：

step16 and step18 are merged by 7 decimal places.bids down,asks up. step17 and step19 are merged by 6 decimal places.bids down,asks up. 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 to step17；

20 price level: step6 to step13, step18, step19;

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-USDT".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-USDT".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.$contract_code.detail) is the merged market data. It will be checked every 0.5s,pushed once trade event updates,including the OHLCV data,etc.Trade Detail(market.$contract_code.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.$contract_code.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.$contract_code.depth.$type is snapshot MBP data，market.$contract_code.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.$contract_code.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: What's the difference between "funding_rate" and "realized_rate" in the response of /linear-swap-api/v1/swap_historical_funding_rate interface?

Generally, "funding_rate" is equal to "realized_rate".Only when the payment of funding fee will cause the liquidation of the user's position, the funding fee is under or not charged(And the fee is the actual funding fee:"realized_rate").The current funding rate:"funding_rate" remains unchanged.

Q15: When subscribing the same topic of several contract codes, will several ws be needed?

Since Futures, Coin Margined swaps, USDT Margined Contracts and Options are different contracts with different interface addresses, different ws will be needed.

In Futures, Coin Margined swaps, USDT Margined Contracts and Options thereof, as long as the interface address is the same, one ws is enough.

Q16: Is it available to place/cancel an order via WS??

Currently, it is not supported.

Q17: How to subscribe order status?

a. Successfully trade: “Subscribe Match Order Data (matchOrders.$contract_code)” or “Subscribe Order Data (orders.$contract_code)”

b. Successfully cancel: Subscribe Account Equity Updates Data (accounts.$contract_code)

Q18: What is the difference between the “Subscribe Match Order Data (matchOrders.$contract_code)” and “Subscribe Order Data (orders.$contract_code)”?

The pushed data of these two interfaces are different. Compared to “Subscribe Match Order Data (matchOrders.$contract_code)”, there are more fields for “Subscribe Order Data (orders.$contract_code)”

In general, the match order data (Subscribe Match Order Data “matchOrders.$contract_code”) may be pushed faster than the settled order data (Subscribe Order Data “orders.$contract_code”).

The orders of forced liquidation and netting will not be pushed in “Subscribe Match Order Data (matchOrders.$contract_code)”

Q19: How often is the “Subscribe Kline Data (market.$contract_code.kline.$period)” pushed?

If any transaction is completed, it will push every 500ms. If not, it will push according to the subscribe period

Q20: How to judge whether the push is delayed?

Please first synchronize the time of the server through https://api.hbdm.com/api/v1/timestamp), and the “ts” in the returned data is timestamp (ms) and the corresponding time zone is UTC+8.

The outer layer of each pushed data has a “ts”, which represents the time stamp (ms) when the server pushes the data to the client and the corresponding time zone is UTC+8.

When the data pushed arrive, the procedure will record the local time “ts”. When the local time “ts” is much later than the pushing data “ts”, you can use the following methods to improve the delay:

a. Reduce the data pushed by reducing the number of WS subscriptions.

b. Check the stability and speed of the network between procedure and the servers (please replace api.btcgateway.pro with the domain name used by the program)

curl -o /dev/null -s -w time_namelookup"(s)":%{time_namelookup}"\n"time_connect"(s)":%{time_connect}"\n"time_starttransfer"(s)":%{time_starttransfer}"\n"time_total"(s)":%{time_total}"\n"speed_download"(B/s)":%{speed_download}"\n" api.btcgateway.pro

and you will receive data as below:

time_namelookup(s):0.001378

time_connect(s):0.128641

time_starttransfer(s):0.276588

time_total(s):0.276804

speed_download(B/s):2010.000

If you run the above command multiple times in a row, and the results obtained each time are very different, you can: a. Select an appropriate Huobi domain name, b. Optimize or reselect the network where the program is located.

Order and Trade

Q1: 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.

Q2: 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 /linear-swap-api/v1/swap_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.

Q3: What is the delay for the round trip of huobi USDT Margined swap?

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

Q4: 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.

Q5: 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 ).

Q6: 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 it is disconnected ,please try to reconnect.

Q7: 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.

Q8: Is there an interface to get the total assets in BTC of my account ?

No.

Q9: 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 /linear-swap-api/v1/swap_order_info.

Q10: Does the order status of 10 mean the order is failed?

Query the order status by /linear-swap-api/v1/swap_order_info.If the status is 10,the order is failed。

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 an interface: /linear-swap-api/v1/swap_order_info

Q12: How to get historical liquidation orders?

To obtain historical liquidation orders, you can access the one of two api interfaces: Get History Orders (/linear-swap-api/v1/swap_hisorders【Isolated】or /linear-swap-api/v1/swap_cross_hisorders【Cross】), Get History Match Results (/linear-swap-api/v1/swap_matchresults【Isolated】or /linear-swap-api/v1/swap_cross_matchresults【Cross】) with the return field order_source (order source) to judge. When order_source returns "risk", it means that this order is a liquidated order.

Q13: Does Huob Futures support holding bi-directional position?

Yes, Huobi Futures supports long and short positions being held at the same time.

Q14: How to ensure the order to be rapidly filled?

At present, Huobi Futures does not support market price when placing an order. To increase the probability of a transaction, users can choose to place an order based on BBO price (opponent), optimal 5 (optimal_5), optimal 10 (optimal_10), optimal 20 (optimal_20), among which the success probability of optimal 20 is the largest, while the slippage always is the largest as well.

It is important to note that the above methods will not guarantee the order to be filled in 100%. The system will obtain the optimal N price at that moment and place the order.

Q15: How can API procedure be connected to the exchange more rapidly?

It’s recommended to use a AWS Tokyo c-zone server and the domain name “api.hbdm.vn” to connect to the system.

Q16: It occurs an “abnormal service” error when transferring assets between spots and derivatives.

a. Check whether the request address is the address of Huobi: api.huobi.pro?

b. Check whether the precision of the coin does not exceed 8 decimal places?

Q17: How to confirm whether the position is opened or closed successfully?

Placing an order successfully through “Place an Order” interface (/linear-swap-api/v1/swap_order) or “Place a batch of orders” interface (/linear-swap-api/v1/swap_batchorder) just means the server has received your order placing instructions rather than you have opened/closed a position successfully.

You can check the order status by filling the returned “order_id” in the “Get Information of an Order” interface (/linear-swap-api/v1/swap_order_info) or the “Order Details Acquisition” interface (/linear-swap-api/v1/swap_order_detail); If the order has been filled, the “status” value in the return parameter will turn out 6 (wholly filled)

It is important to note:

a. For “Get Information of an order” interface (/linear-swap-api/v1/swap_order_info), after the settlement or delivery, the system will delete all the orders in ended status (5: partially filled orders have been cancelled; 6: wholly filled; 7: cancelled);

b. There is a delay in “Order Details Acquisition” interface (/linear-swap-api/v1/swap_order_detail), so it is better to fill in “created_at” (order timestamp) and “order_type” (order type, fill in 1 by default). In this way, it will directly query the database, so the query results will be more timely.

Q18: Why are orders canceled by the system automatically?

The order_price_type which can be chosen are IOC, FOK and Maker (Post Only). When the order book cannot meet with the corresponding conditions, the system will cancel the orders automatically:

Post_only: If the order placed is filled with an existing order on the order book immediately, the order will be cancelled to ensure the user is always a maker.

IOC order: If the order cannot be filled immediately, the unfilled part will be cancelled at once;

FOK order: If the order cannot be filled in its entirety, it will be wholly cancelled. No partial fulfillments are allowed.

Q19: How to query the maximum amount (cont) available to open by using users’ current assets?

At present, we do not have an interface by which users can directly query the maximum amount (cont) available to open by using users’ the current asset.

Q20: Are the “order_id” and “order_id_str” the same?

The “order_id_str” is the string format of “order_id”, whose values are the same.

For the “order_id” with 18 bits, the “JSON.parse” in “nodejs” and “javascript” will be “int” by default, and mistakes will occur when analyzing. Thus, we advise using “order_id_str”.

Q21: How to get the active buying/selling quantity in transaction data?

Users can get the data via “Query The Last Trade of a Contract” (/linear-swap-ex/market/trade) interface or by subscribing "sub": "market.$contract_code.trade.detail", thereinto

Amount refers to the trading volume (cont), which is the sum of the buying/selling volume;

Direction refers to the active trading direction.

Q22: The interval between “from” and “to” is “2000*period” when acquiring KLine data, then why the data obtained is []?

When acquiring the Kline data, the two time points “from” and “to” are contained, therefore it includes 2001 pieces of data. However, this exceeds the maximum limit 2000. Therefore, the system will return [].

Besides, the returned data will be [] as well if the interval between “from” and “to” exceeds 2 years.

Q23: How to get the latest price?

There are two methods to get the latest price:

a. Invoking the “Get KLine Data(/linear-swap-ex/market/history/kline)” interface and filling in any “period”, the “close” of the last data in return data will be the latest price;

b. Invoking the “Query The Last Trade of a Contract(/linear-swap-ex/market/trade)” interface, the returned “price” will be the latest price.

Q24: How to get the latest index price?

There are two methods to get the latest index price:

a. Calling the “Get Contract Index Price Information” interface (/linear-swap-api/v1/swap_index), the returned “index_price” will be the latest index price.

b. Calling the “Subscribe Index Kline Data” websocket (market.$contract_code.index.$period), the “close” of the last Kline data in returned data will be the latest index price.

Q25: Will API upgrade affect the operation of the program?

In general, API upgrade will partly influence the ws disconnection. To avoid this, you can set up a ws-reconnect mechanism in advance; Please subscribe to the upgrade announcements for more details:

Coin-margined futures: https://status-dm.huobigroup.com/

Coin-margined swaps: https://status-swap.huobigroup.com/

USDT-margined Contracts: https://status-linear-swap.huobigroup.com/

Q26: What does mean the “margin_balance” in “Query User’s Account Information” interface (api/v1/contract_account_info)?

”margin_balance” refers to the account equity

  1. margin_balance = margin_static + profit_unreal

  2. margin_balance = Account balance + profit_real + profit_unreal

Note: Account balance = margin_static - profit_real, there is only margin_static in the return data of api interface

Each of the two calculation methods above can get the margin_balance

Q27: Is the “risk_rate” (margin rate) in “Query User’s Account Information” interface (/linear-swap-api/v1/swap_account_info) the same as the margin rate on WEB?

Yes, it is

When the “risk_rate” is less than or equal to 0, the position will be liquidated.

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.

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 /linear-swap-api/v1/swap_position_info to get your available position.

  1. Check whether the amount (cont) of position-closing order exceeds the limit? (When there is limit order for closing a position, the quantity that available to be closed will be occupied; hence we kindly remind you to cancel these orders and try again.)

  2. Check whether direction and offset are wrong as follows:

close long: sell to close a long position (direction: sell; offset: close);

close short: buy to close a short position (direction: buy; offset: close);

Only “direction” need to be uploaded when placing a flash close order (close long: sell; close short: buy).

  1. The pending take-profit and stop-loss (tp/sl) orders and trigger orders will not occupy the quantity of the position.

Q3: What is the reason for 1032 error code?

1032 means that your request exceeds the ratelimit. The coin margined swap, future and USDT margined Contracts 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.

The usage of and the difference between cross margin mode and isolated margin mode

  1. Under the cross margin mode, all swaps share the USDT in the cross margin account as the margin, which indicates that all positions under the cross margin mode share the same account equity, and their PnL, occupied margin and margin ratio are calculated jointly. Under the isolated margin mode, the account equity for each swaps are calculated separately, and the position margin and PnL of each swaps will not affect each other.

  2. The cross margin mode and the isolated margin mode use different margin accounts, and the assets are independent of each other. Users can trade, or hold positions under the two modes at the same time. For example, in BTC/USDT swaps trading, the margin account for cross margin trading is USDT, while the margin account for isolated margin trading is BTC-USDT.

  3. API users can use the support_margin_mode field (margin mode supported by the contract) of the API interface [Query Swap Info: linear-swap-api/v1/swap_contract_info] to check which mode (cross/isolated) the contract supports.

  4. The API interface is divided into three modes, [Cross], [Isolated] and [General]. These three modes are marked on the API interface name and the interface list. [Cross] indicates that the API interface only supports cross margin mode. [Isolated] indicates that the API interface only supports isolated margin mode, and [General] indicates that the API interface supports both two modes, indicating that it can be called by both the cross margin mode and isolated margin mode.

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 /linear-swap-api/v1/swap_order_info to keep the complete log returned and provide your UID and order number.

Reference Data

Account type query

Remarks

Request Parameter

NO

Response: 

{
    "code":200,
    "msg":"ok",
    "data":{
        "account_type":1
    },
    "ts":1668057324200
}

Return Parameter

Parameter Name Required Type Desc Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> true
account_type true int account type 1:Non-unified account (cross-margin and isolated-margin account) 2:Unified account
</data> true

Account Type Change

Remarks

Request Parameter

Request: 


{
  "account_type": 1
}

请求参数

Parameter Name Required Type Desc Value Range
account_type true int account type 1:Non-unified account (cross-margin and isolated-margin account)

Response: 

{
    "code":200,
    "msg":"ok",
    "data":{
        "account_type":1
    },
    "ts":1668057324200
}

Return Parameter

Parameter Name Required Type Desc Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> true
account_type true int account type 1:Non-unified account (cross-margin and isolated-margin account)
</data> true

[General] Query historical settlement records of the platform interface

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code true string Contract Code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
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

Response: 

{
    "status": "ok",
    "data": {
        "total_page": 1,
        "current_page": 1,
        "total_size": 12,
        "settlement_record": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211203",
                "settlement_time": 1638518400000,
                "clawback_ratio": 0E-18,
                "settlement_price": 56792.300000000000000000,
                "settlement_type": "delivery",
                "business_type": "futures",
                "pair": "BTC-USDT"
            },
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211203",
                "settlement_time": 1638489600000,
                "clawback_ratio": 0E-18,
                "settlement_price": 57028.600000000000000000,
                "settlement_type": "settlement",
                "business_type": "futures",
                "pair": "BTC-USDT"
            }
        ]
    },
    "ts": 1638756873768
}

Return Parameter

Parameter Name Required 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
contract_code true string Contract Code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
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
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
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</settlement_record>
total_page true int Total Pages
current_page true int Current Page
total_size true int Total page items
</data>

[General] Query Liquidation Orders(New)

Remarks

Request:


    /linear-swap-api/v3/swap_liquidation_orders?trade_type=5&contract=BTC-USDT

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions, 17:buy(one-way mode), 18:sell(one-way mode)
start_time false long Query start time, query by data creation time Value range [((end-time) – 2h), (end-time)], maximum query window size is 2 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 452057,
                "contract_code": "BTC-USDT-211210",
                "symbol": "USDT",
                "direction": "sell",
                "offset": "close",
                "volume": 479.000000000000000000,
                "price": 51441.700000000000000000,
                "created_at": 1638593647864,
                "amount": 0.479000000000000000,
                "trade_turnover": 24640.574300000000000000,
                "business_type": "futures",
                "pair": "BTC-USDT"
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> true object array
query_id true long Query id, which can be used as the from_id field for the next query request.
symbol true string symbol
contract_code true string contract code e.g. swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
created_at true long liquidation time
direction true string "buy":buy"sell": sell
offset true string "open":open "close": close, "both"
volume true decimal liquidation volume (cont)
amount true decimal liquidation amount (token)
price true decimal bankruptcy price
trade_turnover true decimal liquidation amount (quotation token)
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</data>

[General] Query historical funding rate

curl "https://api.hbdm.com/linear-swap-api/v1/swap_historical_funding_rate?contract_code=BTC-USDT"

Remarks

Request Parameters

parameter name Required Type Desc Value Range
contract_code true string contract code Case-Insenstive.eg:"BTC-USDT" ...
page_index false int page index. 1 by default
page_size false int page size.20 by default. 50 at most [1-50]

Response:


{
    "status": "ok",
    "data": {
        "total_page": 14,
        "current_page": 1,
        "total_size": 14,
        "data": [
            {
                "avg_premium_index": "0.000049895833333333",
                "funding_rate": "0.000100000000000000",
                "realized_rate": "0.000100000000000000",
                "funding_time": "1603670400000",
                "contract_code": "BTC-USDT",
                "symbol": "BTC",
                "fee_asset": "USDT"
            }
        ]
    },
    "ts": 1603696680599
}

Response Parameters

parameter name type desc value range
status string response status "ok" , "error"
ts long response timestamp.unit:millionSeconds.
<data>
<data>
symbol string symbol eg:"BTC","ETH"...
contract_code string contract code eg: "BTC-USDT
fee_asset string fee asset eg:"USDT"
funding_time string funding time
funding_rate string funding rate
realized_rate string realized funding rate
avg_premium_index string average premium index
</data>
total_page int total page
current_page int current page
total_size int total size
</data>

[General]Query a Batch of Funding Rate

Note

Request Parameter

Parameter Name Required Parameter Type Description Value Range
contract_code false string contract code，if not filled in, default as all "BTC-USDT" ...

Response

{
    "status": "ok",
    "data": [
        {
            "estimated_rate": "-0.007500000000000000",
            "funding_rate": "-0.007500000000000000",
            "contract_code": "ETC-USDT",
            "symbol": "ETC",
            "fee_asset": "USDT",
            "funding_time": "1613976000000",
            "next_funding_time": "1614004800000"
        },
        {
            "estimated_rate": "-0.007500000000000000",
            "funding_rate": "-0.007500000000000000",
            "contract_code": "ADA-USDT",
            "symbol": "ADA",
            "fee_asset": "USDT",
            "funding_time": "1613976000000",
            "next_funding_time": "1614004800000"
        }
    ],
    "ts": 1614045373795
}

Returning Parameter

Parameter Name Required Parameter Type Description Value Range
status true string the result of server handles for the request "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
symbol true string symbol
contract_code true string contract code "BTC-USDT" ...
fee_asset true string fee asset "USDT...
funding_time true string current funding time(Millisecond)
funding_rate true string current funding rate
estimated_rate true string estimated funding rate of current period
next_funding_time true string estimated funding rate of next period(Millisecond)
</data>

[General] Query funding rate

curl "https://api.hbdm.com/linear-swap-api/v1/swap_funding_rate?contract_code=BTC-USDT"

Remarks

Request Parameters

Parameter Name Required Type Desc Value Range
contract_code true string contract code Case-Insenstive."BTC-USDT" ...

Response: 


{
    "status": "ok",
    "data": {
        "estimated_rate": "0.000100000000000000",
        "funding_rate": "0.000100000000000000",
        "contract_code": "BTC-USDT",
        "symbol": "BTC",
        "fee_asset": "USDT",
        "funding_time": "1603699200000",
        "next_funding_time": "1603728000000"
    },
    "ts": 1603696494714
}

Response Parameters

field name type desc value range
status string response status "ok" , "error"
ts long response timestamp.unit:millionSeconds.
<data>
symbol string symbol "BTC","ETH"...
contract_code string contract code,eg:"BTC-USDT"
fee_asset string fee asset eg:"BTC","ETH"...
funding_time string current funding time
funding_rate string current funding rate
estimated_rate string estimated funding rate of current period（Updated once a minute）
next_funding_time string estimated funding rate of next period
</data>

[Isolated] Query information on system status

curl "https://api.hbdm.com/linear-swap-api/v1/swap_api_state"

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code false string contract code Case-Insenstive.e.g. "BTC-USDT"

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "margin_mode": "isolated",
            "margin_account": "BTC-USDT",
            "open": 1,
            "close": 1,
            "cancel": 1,
            "transfer_in": 1,
            "transfer_out": 1,
            "master_transfer_sub": 1,
            "sub_transfer_master": 1,
            "master_transfer_sub_inner_in": 1,
            "master_transfer_sub_inner_out": 1,
            "sub_transfer_master_inner_in": 1,
            "sub_transfer_master_inner_out": 1,
            "transfer_inner_in": 1,
            "transfer_inner_out": 1
        }
    ],
    "ts": 1603696366019
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string Contract Code "BTC-USDT"...
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
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
master_transfer_sub_inner_in true int Transfer_in access for transfer from main account to sub-account - crossing account: "1" represents "available", "0" represents "unavailable"
master_transfer_sub_inner_out true int Transfer_out access for transfer from main account to sub-account - crossing account: "1" represents "available", "0" represents "unavailable"
sub_transfer_master_inner_in true int Transfer_in access for transfer from sub-account to main account - crossing account: "1" represents "available", "0" represents "unavailable"
sub_transfer_master_inner_out true int Transfer_out access for transfer from sub-account to main account - crossing account: "1" represents "available", "0" represents "unavailable"
transfer_inner_in true int Transfer_in access for transfer between different margin accounts under the same account："1" represents "available", "0" represents "unavailable"
transfer_inner_out true int Transfer_out access for transfer between different margin accounts under the same account："1" represents "available", "0" represents "unavailable"
</data>

[General] Query Top Trader Sentiment Index Function-Position

curl "https://api.hbdm.com/linear-swap-api/v1/swap_elite_position_ratio?contract_code=BTC-USDT&period=60min"

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-FUTURES" ...
period true string period 5min, 15min, 30min, 60min,4hour,1day

Response:


{
    "status":"ok",
    "data":{
        "list":[
            {
                "buy_ratio":0.5,
                "sell_ratio":0.5,
                "ts":1638460800000
            }
        ],
        "symbol":"BTC",
        "contract_code":"BTC-USDT-FUTURES",
        "business_type":"futures",
        "pair":"BTC-USDT"
    },
    "ts":1638756121395
}

Returning Parameter

Parameter Name Required 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 symbol "BTC","ETH"...
contract_code true string contract code e.g. swap: "BTC-USDT"... , future: "BTC-USDT-FUTURES" ...
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
<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>

[General] Query Top Trader Sentiment Index Function-Account

curl "https://api.hbdm.com/linear-swap-api/v1/swap_elite_account_ratio?contract_code=BTC-USDT&period=60min"

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-FUTURES" ...
period true string period 5min, 15min, 30min, 60min,4hour,1day

Response:


{
    "status":"ok",
    "data":{
        "list":[
            {
                "buy_ratio":0.5,
                "sell_ratio":0.5,
                "locked_ratio":0,
                "ts":1638115200000
            }
        ],
        "symbol":"BTC",
        "contract_code":"BTC-USDT",
        "business_type":"swap",
        "pair":"BTC-USDT"
    },
    "ts":1638169688105
}

Returning Parameter

Parameter Name Required Type Desc Vaue Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data>
symbol true string symbol "BTC","ETH"...
contract_code true string contract code e.g. swap: "BTC-USDT"... , future: "BTC-USDT-FUTURES" ...
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
<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>

[Cross]Query information on Tiered Margin

Note

Request Parameter

Parameter Name Required Parameter Type Description Value Range
contract_code false string contract code, if not filled in return all contract infomation swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
contract_type false string contract type swap, this_week, next_week, quarter, next_quarter
business_type false(more see remarks) string business type, default is swap futures, swap, all

Response

{
    "status":"ok",
    "data":[
        {
            "margin_account":"USDT",
            "symbol":"BTC",
            "contract_code":"BTC-USDT",
            "margin_mode":"cross",
            "list":[
                {
                    "lever_rate":2,
                    "ladders":[
                        {
                            "min_margin_balance":0,
                            "max_margin_balance":null,
                            "min_margin_available":0,
                            "max_margin_available":null
                        }
                    ]
                }
            ],
            "business_type":"swap",
            "pair":"BTC-USDT",
            "contract_type":"swap"
        }
    ],
    "ts":1638755685337
}

Returning Parameter

Parameter Name Required Parameter Type Description Value Range
status true string result of server handled request "ok" , "error"
<data> true object array
symbol true string symbol such as: "BTC"
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross
margin_account true string margin account such as:USDT”
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
<list> true object array
lever_rate true int lever rate
<ladders> true object array ladders for margin
min_margin_balance true decimal min margin balance(the starting point in this ladder, included in this ladder)
max_margin_balance true decimal max margin balance(the end point in this ladder, excluded in this ladder, is next ladder's min_margin_balance)
min_margin_available true decimal min margin available(in the range of this ladder margin balance)
max_margin_available true decimal max margin available（not in the range of this ladder margin balance, is next ladder's min_margin_available)
</ladders>
</list>
</data>
ts true long Time of Respond Generation，Unit：Millisecond

[Isolated]Query information on Tiered Margin

Note

Request Parameter

Parameter Name Required Parameter Type Description Value Range
contract_code false string contract code, if not filled in return all contract infomation such as: “BTC-USDT”, “ETH-USDT”。。。

Response

{
    "status": "ok",
    "data": [
        {
            "margin_account": "BTC-USDT",
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "margin_mode": "isolated",
            "list": [
                {
                    "lever_rate": 20,
                    "ladders": [
                        {
                            "min_margin_balance": 0,
                            "max_margin_balance": 250000,
                            "min_margin_available": 0,
                            "max_margin_available": 250000
                        },
                        {
                            "min_margin_balance": 250000,
                            "max_margin_balance": 2500000,
                            "min_margin_available": 250000,
                            "max_margin_available": 1000000
                        },
                        {
                            "min_margin_balance": 2500000,
                            "max_margin_balance": 10000000,
                            "min_margin_available": 1000000,
                            "max_margin_available": 2500000
                        },
                        {
                            "min_margin_balance": 10000000,
                            "max_margin_balance": 85000000,
                            "min_margin_available": 2500000,
                            "max_margin_available": 10000000
                        },
                        {
                            "min_margin_balance": 85000000,
                            "max_margin_balance": null,
                            "min_margin_available": 10000000,
                            "max_margin_available": null
                        }
                    ]
                }
            ]
        }
    ],
    "ts": 1612504906880
}

Returning Parameter

Parameter Name Required Parameter Type Description Value Range
status true string status "ok" , "error"
<data> true object array
symbol true string symbol such as: "BTC"
contract_code true string contract code such as: "BTC-USDT"
margin_mode true string margin mode isolated: isolated
margin_account true string margin account such as: “BTC-USDT”
<list> true object array
lever_rate true int lever rate
<ladders> true object array ladders for margin
min_margin_balance true decimal min margin balance(the starting point in this ladder, included in this ladder)
max_margin_balance true decimal max margin balance(the end point in this ladder, excluded in this ladder, is next ladder's min_margin_balance)
min_margin_available true decimal min margin available(in the range of this ladder margin balance)
max_margin_available true decimal max margin available（not in the range of this ladder margin balance, is next ladder's min_margin_available)
</ladders>
</list>
</data>
ts true long Time of Respond Generation，Unit：Millisecond

[General]Get the estimated settlement price

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false string contract code, return all without filling in swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
contract_type false string contract type swap, this_week, next_week, quarter, next_quarter
business_type false(more see remarks) string business type, default is swap futures, swap, all

Response

{
    "status": "ok",
    "data": [
        {
            "contract_code": "BTC-USDT-211210",
            "estimated_settlement_price": null,
            "settlement_type": "settlement",
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "this_week"
        },
        {
            "contract_code": "BTC-USDT-211217",
            "estimated_settlement_price": null,
            "settlement_type": "settlement",
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "next_week"
        },
        {
            "contract_code": "BTC-USDT-211231",
            "estimated_settlement_price": null,
            "settlement_type": "settlement",
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "quarter"
        },
        {
            "contract_code": "BTC-USDT",
            "estimated_settlement_price": null,
            "settlement_type": "settlement",
            "business_type": "swap",
            "pair": "BTC-USDT",
            "contract_type": "swap"
        }
    ],
    "ts": 1638755400222
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status
<data> true object array
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
estimated_settlement_price true decimal Current-period estimated settlement price /Current-period estimated delivery price (When the settlement type is "delivery", it is estimated delivery price; Otherwise, it is estimated settlement price)
settlement_type true string settlement type “delivery”，“settlement”
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</data>
ts true long Time of Respond Generation，Unit: Millisecond

Note

[Cross] Query Information On Tiered Adjustment Factor

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
contract_type false string contract type swap, this_week, next_week, quarter, next_quarter
business_type false(more see remarks) string business type, default is swap futures, swap, all

Response:


{
    "status":"ok",
    "data":[
        {
            "symbol":"BTC",
            "contract_code":"BTC-USDT-211210",
            "margin_mode":"cross",
            "list":[
                {
                    "lever_rate":1,
                    "ladders":[
                        {
                            "ladder":0,
                            "min_size":0,
                            "max_size":3999,
                            "adjust_factor":0.005
                        },
                        {
                            "ladder":1,
                            "min_size":4000,
                            "max_size":39999,
                            "adjust_factor":0.01
                        },
                        {
                            "ladder":2,
                            "min_size":40000,
                            "max_size":79999,
                            "adjust_factor":0.015
                        },
                        {
                            "ladder":3,
                            "min_size":80000,
                            "max_size":119999,
                            "adjust_factor":0.02
                        },
                        {
                            "ladder":4,
                            "min_size":120000,
                            "max_size":null,
                            "adjust_factor":0.025
                        }
                    ]
                }
            ],
            "business_type":"futures",
            "pair":"BTC-USDT",
            "contract_type":"this_week"
        }
    ],
    "ts":1638754992327
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
<list> true object array
lever_rate true decimal lever rate
<ladders> true object array
min_size true decimal min net position limit
max_size true decimal max net position limit
ladder true int tier from 0
adjust_factor true decimal adjustment factor
</ladders>
</list>
</data>

[Isolated] Query information on Tiered Adjustment Factor

curl "https://api.hbdm.com/linear-swap-api/v1/swap_adjustfactor"

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false string contract code Case-Insenstive.e.g. "BTC-USDT"

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "margin_mode": "isolated",
            "list": [
                {
                    "lever_rate": 125,
                    "ladders": [
                        {
                            "ladder": 0,
                            "min_size": 0,
                            "max_size": 8999,
                            "adjust_factor": 0.650000000000000000
                        },
                        {
                            "ladder": 1,
                            "min_size": 9000,
                            "max_size": 89999,
                            "adjust_factor": 0.800000000000000000
                        },
                        {
                            "ladder": 2,
                            "min_size": 90000,
                            "max_size": null,
                            "adjust_factor": 0.850000000000000000
                        }
                    ]
                }
            ]
        }
    ],
    "ts": 1603695606565
}

Returning Parameter

Parameter Name Required 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 symbol "BTC","ETH"...
contract_code true string contract code e.g. "BTC-USDT"
margin_mode true string margin mode isolated : "isolated"
<list>
lever_rate true decimal Leverage
<ladders>
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
</ladders>
</list>
</data>

[General] Query history records of insurance fund balance

curl "https://api.hbdm.com/linear-swap-api/v1/swap_insurance_fund?contract_code=ETH-USDT"

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-FUTURES" ...
page_index false int page index. 1 by default
page_size false int page size.100 by default. 100 at most [1-100]

Response:


{
    "status": "ok",
    "data": {
        "total_page": 1,
        "current_page": 1,
        "total_size": 4,
        "symbol": "BTC",
        "contract_code": "BTC-USDT-FUTURES",
        "tick": [
            {
                "insurance_fund": 16174.621898868113476721,
                "ts": 1638691200000
            },
            {
                "insurance_fund": 130.912398868113476721,
                "ts": 1638604800000
            },
            {
                "insurance_fund": 0.002860554220000000,
                "ts": 1638518400000
            },
            {
                "insurance_fund": 0,
                "ts": 1638432000000
            }
        ],
        "business_type": "futures",
        "pair": "BTC-USDT"
    },
    "ts": 1638754881217
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> Dictionary Data
symbol true string symbol "BTC","ETH"...
contract_code true string contract code e.g. swap: "BTC-USDT"... , future: "BTC-USDT-FUTURES" ...
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
<tick>
insurance_fund true decimal Insurance Fund Balance
ts true long Timestamp, Unit: Millisecond
</tick>
total_page true int total page
current_page true int current page
total_size true int total size
</data>

[General] Query information on contract insurance fund balance and estimated clawback rate

curl "https://api.hbdm.com/linear-swap-api/v1/swap_risk_info"

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-FUTURES" ...
business_type false string business type, default is swap futures, swap, all

Response:


{
    "status": "ok",
    "data": [
        {
            "contract_code": "BTC-USDT",
            "insurance_fund": 16174.621898868113476721,
            "estimated_clawback": 0E-18,
            "business_type": "swap",
            "pair": "BTC-USDT"
        },
        {
            "contract_code": "BTC-USDT-FUTURES",
            "insurance_fund": 16174.621898868113476721,
            "estimated_clawback": 0E-18,
            "business_type": "futures",
            "pair": "BTC-USDT"
        },
        {
            "contract_code": "ETH-USDT",
            "insurance_fund": 16174.621898868113476721,
            "estimated_clawback": 0E-18,
            "business_type": "swap",
            "pair": "ETH-USDT"
        },
        {
            "contract_code": "ETH-USDT-FUTURES",
            "insurance_fund": 16174.621898868113476721,
            "estimated_clawback": 0E-18,
            "business_type": "futures",
            "pair": "ETH-USDT"
        }
    ],
    "ts": 1638754774555
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data>
contract_code true string contract code e.g. swap: "BTC-USDT"... , future: "BTC-USDT-FUTURES" ...
insurance_fund true decimal Insurance Fund Balance
estimated_clawback true decimal Estimated Clawback Rate
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</data>

[General] Get Swap Open Interest Information

Example

curl "https://api.hbdm.com/linear-swap-api/v1/swap_open_interest?contract_code=BTC-USDT"

Remarks

Request Parameter

Parameter Name Parameter Type Required Desc
contract_code string false eg swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair string false pair, BTC-USDT
contract_type string false contract type: swap, this_week, next_week, quarter, next_quarter
business_type string false(more see remarks) business type, default is swap: futures, swap, all

Response:


{
    "status": "ok",
    "data": [
        {
            "volume": 78696.000000000000000000,
            "amount": 78.696000000000000000,
            "symbol": "BTC",
            "value": 3823138.245600000000000000,
            "contract_code": "BTC-USDT",
            "trade_amount": 0,
            "trade_volume": 0,
            "trade_turnover": 0,
            "business_type": "swap",
            "pair": "BTC-USDT",
            "contract_type": "swap"
        },
        {
            "volume": 10925.000000000000000000,
            "amount": 10.925000000000000000,
            "symbol": "BTC",
            "value": 530662.210000000000000000,
            "contract_code": "BTC-USDT-211217",
            "trade_amount": 0,
            "trade_volume": 0,
            "trade_turnover": 0,
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "next_week"
        },
        {
            "volume": 27104.000000000000000000,
            "amount": 27.104000000000000000,
            "symbol": "BTC",
            "value": 1316937.283200000000000000,
            "contract_code": "BTC-USDT-211210",
            "trade_amount": 0,
            "trade_volume": 0,
            "trade_turnover": 0,
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "this_week"
        },
        {
            "volume": 201143.000000000000000000,
            "amount": 201.143000000000000000,
            "symbol": "BTC",
            "value": 9775067.056800000000000000,
            "contract_code": "BTC-USDT-211231",
            "trade_amount": 0,
            "trade_volume": 0,
            "trade_turnover": 0,
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "quarter"
        }
    ],
    "ts": 1638754059540
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<data>
symbol true string Variety code "BTC", "ETH" ...
volume true decimal Position quantity(volume). Sum of both buy and sell sides
amount true decimal Position quantity(Currency). Sum of both buy and sell sides
contract_code true string Contract Code eg swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
value true decimal Total position volume（The unit is the denominated currency of the contract. e.g:USDT）
trade_amount true decimal trading volume within the last 24 hours (coin). Sum of both buy and sell sides
trade_volume true decimal trading volume within the last 24 hours (cont). Sum of both buy and sell sides
trade_turnover true decimal trading amount within the last 24 hours. Sum of both buy and sell sides
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</data>
ts true long Time of Respond Generation, Unit: Millisecond

Note

[General] Query Swap Price Limitation

Example

curl "https://api.hbdm.com/linear-swap-api/v1/swap_price_limit?contract_code=BTC-USDT"

Remarks

Request Parameter

Parameter Name Parameter Type Required Desc
contract_code string false swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair string false pair, BTC-USDT
contract_type string false contract type: swap, this_week, next_week, quarter, next_quarter
business_type string false(more see remarks) business type, default is swap: futures, swap, all

Response


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "high_limit": 38766.300000000000000000000000000000000000,
            "low_limit": 37250.700000000000000000000000000000000000,
            "business_type": "swap",
            "pair": "BTC-USDT",
            "contract_type": "swap"
        }
    ],
    "ts": 1621936043576
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" ,"error"
<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 swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
<data>
ts true long Time of Respond Generation, Unit: Millisecond

[General] Query Swap Index Price Information

Example

curl "https://api.hbdm.com/linear-swap-api/v1/swap_index?contract_code=BTC-USDT"

Remarks

Request Parameter

Parameter Name Parameter Type Required Desc
contract_code string false Case-insenstive."BTC-USDT","ETH-USDT"...

Response


{
    "status": "ok",
    "data": [
        {
            "index_price": 13076.329865680000000000,
            "index_ts": 1603694592011,
            "contract_code": "BTC-USDT"
        }
    ],
    "ts": 1603694596400
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<data>
contract_code true string contract code "BTC-USDT","ETH-USDT"...
index_price true decimal Index Price
index_ts true Long Index time
</data>
ts true long Time of Respond Generation，Unit：Millisecond

[General] Query Swap Info

Example

curl "https://api.hbdm.com/linear-swap-api/v1/swap_contract_info"

Remarks

Request Parameter

Parameter Name Type Required Description
contract_code string false swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
support_margin_mode string false support margin mode cross："cross"；isolated："isolated"；all："all"
pair string false BTC-USDT
contract_type string false swap, this_week, next_week, quarter, next_quarter
business_type string false(more see remarks) futures, swap, all(default is swap)

Response


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211203",
            "contract_size": 0.001000000000000000,
            "price_tick": 0.100000000000000000,
            "delivery_date": "20211203",
            "delivery_time": "1638518400000",
            "create_date": "20211202",
            "contract_status": 1,
            "settlement_date": "1638518400000",
            "support_margin_mode": "cross",
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "this_week"
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211210",
            "contract_size": 0.001000000000000000,
            "price_tick": 0.100000000000000000,
            "delivery_date": "20211210",
            "delivery_time": "1639123200000",
            "create_date": "20211202",
            "contract_status": 1,
            "settlement_date": "1638518400000",
            "support_margin_mode": "cross",
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "next_week"
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211231",
            "contract_size": 0.001000000000000000,
            "price_tick": 0.100000000000000000,
            "delivery_date": "20211231",
            "delivery_time": "1640937600000",
            "create_date": "20211202",
            "contract_status": 1,
            "settlement_date": "1638518400000",
            "support_margin_mode": "cross",
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "quarter"
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "contract_size": 0.001000000000000000,
            "price_tick": 0.100000000000000000,
            "delivery_date": "",
            "delivery_time": "",
            "create_date": "20211202",
            "contract_status": 1,
            "settlement_date": "1638518400000",
            "support_margin_mode": "all",
            "business_type": "swap",
            "pair": "BTC-USDT",
            "contract_type": "swap"
        }
    ],
    "ts": 1638517765776
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string Request Processing Result "ok" , "error"
<data>
symbol true string symbol "BTC","ETH"...
contract_code true string Contract Code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
contract_size true decimal Contract Value (USDT of one contract) 10, 100...
price_tick true decimal Minimum Variation of Contract Price 0.001, 0.01...
settlement_date true string Settlement Date eg "1490759594752"
create_date true string Listing Date eg "20190808"
delivery_time true string delivery time（When the contract does not need to be delivered, the field value is an empty string），millesecond timestamp
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
support_margin_mode false string support margin mode cross："cross"；isolated："isolated"；all："all"
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
delivery_date true string delivery date, empty string when swap such as: "20180720"
</data>
ts true long Time of Respond Generation，Unit：Millisecond

Maintenance with service suspended

During the maintenance of the business system, in addition to the below two interfaces(Get system status, Query whether the system is available) for users to query the system status, all “rest” interfaces of the API business will return this in a fixed manner:{"status": "maintain"}. During maintenance with service suspended，all websocket notify interfaces except subscribing system status updates（Subscribe system status updates）can't work，and will push 1006 error code to clients.

Response

{
    "status": "maintain"
}

for getting the infomation that system maintenance with service suspended, could by subscrib system status updates websocket interface.

Get current system timestamp

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

request

null

response


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

Returning Parameter

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

Note:

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(maintenance with service suspended)
swap_heartbeat int coin margined swap 1: avaiable 0: not available(maintenance with service suspended)
estimated_recovery_time long null: normal. estimated recovery time :millionseconds.
swap_estimated_recovery_time long null: normal. coin margined swap estimated recovery time millionseconds.
linear_swap_heartbeat long USDT margined Contracts 1: avaiable 0: not available(maintenance with service suspended)
linear_swap_estimated_recovery_time long null: normal. USDT margined Contracts estimated recovery time millionseconds.
</data>

Response:


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

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-linear-swap.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 Futures-USDT-margined Swaps",  // page name
    "url": "https://status-linear-swap.huobigroup.com", // page url
    "time_zone": "Asia/Singapore", // 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

Swap Market Data interface

[General] Get Market Depth

Example

curl "https://api.hbdm.com/linear-swap-ex/market/depth?contract_code=BTC-USDT&type=step5"

Remarks

Request Parameter

Parameter Name Parameter Type Required Desc
contract_code string true swap: "BTC-USDT"... , future: "BTC-USDT-220325" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
type string true Get depth data within step 150, use step0, step1, step2, step3, step4, step5, step14, step15, step16, step17（merged depth data 0-5,14-17）；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, step18, step19(merged depth data 7-13,18-19); when step is 6, depth data will not be merged.

Node

Response:


{
    "ch": "market.BTC-USDT-CQ.depth.step6",
    "status": "ok",
    "tick": {
        "asks": [
            [
                48611.5,
                741
            ],
            [
                48635.2,
                792
            ]
        ],
        "bids": [
            [
                48596.4,
                90
            ],
            [
                48585.7,
                180
            ]
        ],
        "ch": "market.BTC-USDT-CQ.depth.step6",
        "id": 1638754215,
        "mrid": 1250406,
        "ts": 1638754215640,
        "version": 1638754215
    },
    "ts": 1638754216092
}

Returning Parameter

Parameter Name Required 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 false object Sell,[price(Ask price), vol(Ask orders (cont.) )], price in ascending sequence
bids false object 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>

[General]Get Market BBO Data

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-220325" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
business_type false(more see remarks) string business type, default is swap futures, swap, all

Response

{
    "status": "ok",
    "ticks": [
        {
            "business_type": "futures",
            "contract_code": "BTC-USDT-CW",
            "ask": [
                48637.3,
                746
            ],
            "bid": [
                48482.5,
                385
            ],
            "mrid": 1251224,
            "ts": 1638754357868
        },
        {
            "business_type": "futures",
            "contract_code": "BTC-USDT-NW",
            "ask": [
                48620.1,
                1000
            ],
            "bid": [
                48461,
                524
            ],
            "mrid": 1251162,
            "ts": 1638754344746
        },
        {
            "business_type": "futures",
            "contract_code": "BTC-USDT-CQ",
            "ask": [
                48630.9,
                868
            ],
            "bid": [
                48577.1,
                63
            ],
            "mrid": 1251236,
            "ts": 1638754359301
        },
        {
            "business_type": "swap",
            "contract_code": "BTC-USDT",
            "ask": [
                48511.6,
                91
            ],
            "bid": [
                48508.9,
                95
            ],
            "mrid": 334931,
            "ts": 1638754361719
        }
    ],
    "ts": 1638754363648
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" , "error"
<ticks> true object array
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-220325" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
business_type true string business type futures, swap
mrid true long Match ID, unique identification
ask false array [Ask 1 price, Ask 1 qty (cont)]
bid false array [Bid 1 price, Bid 1 qty (cont)]
ts true long The system detects the orderbook time point, unit: milliseconds
</ticks>
ts true long Time of Respond Generation, Unit: Millisecond

[General] Get KLine Data

Example

curl "https://api.hbdm.com/linear-swap-ex/market/history/kline?period=1min&size=200&contract_code=BTC-USDT"

Remarks

Request Parameter

Parameter Name Required Type Desc Default Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-220325" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
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

Response:


{
    "ch": "market.BTC-USDT.kline.1min",
    "data": [
        {
            "amount": 0.004,
            "close": 13076.8,
            "count": 1,
            "high": 13076.8,
            "id": 1603695060,
            "low": 13076.8,
            "open": 13076.8,
            "trade_turnover": 52.3072,
            "vol": 4
        }
    ],
    "status": "ok",
    "ts": 1603695099234
}

Returning Parameter

Parameter Name Required 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
<data> kline data
id true long kline id,the same as kline timestamp, kline start timestamp
vol true decimal Trade Volume(Cont.) . Sum of both buy and sell sides
count true decimal Order Quantity. Sum of both buy and sell sides
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). Sum of both buy and sell sides
trade_turnover true decimal Transaction amount, that is, sum (transaction quantity * contract face value * transaction price). Sum of both buy and sell sides
</data>

[General]Get Kline Data of Mark Price

Note：

Request Parameter：

Parameter Name Required Type Description Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
period true string period 1min, 5min, 15min, 30min, 60min,4hour,1day, 1week,1mon
size true int size [1,2000]

Note：

Response：

{
    "ch": "market.BTC-USDT.mark_price.5min",
    "data": [
        {
            "amount": "0",
            "close": "31078.68",
            "count": "0",
            "high": "31078.68",
            "id": 1611105300,
            "low": "31078.68",
            "open": "31078.68",
            "trade_turnover": "0",
            "vol": "0"
        },
        {
            "amount": "0",
            "close": "31078.68",
            "count": "0",
            "high": "31078.68",
            "id": 1611105600,
            "low": "31078.68",
            "open": "31078.68",
            "trade_turnover": "0",
            "vol": "0"
        }
    ],
    "ts": 1611106791703
}

Returning Parameter：

Parameter Name Required Type Description Default Value Value Range
ch true string channel, format: market.period
<data> true object array
id true long id
vol true string trade vol(cont), value is 0
count true string trade count, value is 0
open true string open price
close true string close price
low true string low price
high true string high price
amount true string trade amount, value is 0
trade_turnover true string trade turnover, value is 0
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[General] Get Market Data Overview

Example

curl "https://api.hbdm.com/linear-swap-ex/market/detail/merged?contract_code=BTC-USDT"

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-220325" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ

Response:


{
    "ch": "market.BTC-USDT.detail.merged",
    "status": "ok",
    "tick": {
        "amount": "12.526",
        "ask": [
            13084.2,
            131
        ],
        "bid": [
            13082.9,
            38
        ],
        "close": "13076.8",
        "count": 2920,
        "high": "13205.3",
        "id": 1603695162,
        "low": "12877.5",
        "open": "12916.2",
        "trade_turnover": "163247.3982",
        "ts": 1603695162580,
        "vol": "12526"
    },
    "ts": 1603695162580
}

Returning Parameter

Parameter Name Required 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"
ts true long Time of Respond Generation, Unit: Millisecond
<tick> true object 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.), from nowtime - 24 hours. Sum of both buy and sell sides
count true decimal Order Quantity, from nowtime - 24 hours. Sum of both buy and sell sides
open true string Opening Price
close true string Closing Price, the price in the last kline is the latest order price
low true string Low
high true string High
amount true string Trade Amount(Coin), trade amount(coin)=sum(order quantity of a single order * face value of the coin/order price),from nowtime - 24 hours. Sum of both buy and sell sides
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
trade_turnover true string Transaction amount, that is, sum (transaction quantity * contract face value * transaction price),from nowtime - 24 hours. Sum of both buy and sell sides
ts true long Timestamp
</tick>

[General]Get a Batch of Market Data Overview

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code false string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
business_type false(more see remarks) string business type, default is swap futures, swap, all

Note

Response:

{
    "status": "ok",
    "ticks": [
        {
            "id": 1622102803,
            "ts": 1622102804786,
            "ask": [
                18000,
                11
            ],
            "bid": [
                1167.89012345,
                12
            ],
            "business_type": "futures",
            "contract_code": "BTC-USDT-CQ",
            "open": "18000",
            "close": "18000",
            "low": "18000",
            "high": "18000",
            "amount": "0.004",
            "count": 2,
            "vol": "4",
            "trade_turnover": "38.3488642"
        }
    ],
    "ts": 1622102804786
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok" , "error"
<ticks> true object array
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
business_type true string business type futures, swap
id true long id
amount true string Trade Amount(Coin) ,from nowtime - 24 hours. Sum of both buy and sell sides
ask true array [ask one price, ask one vol(cont)]
bid true array [bid one price, bid one vol(cont)]
open true string open price
close true string close price
count true decimal Order Quantity, from nowtime - 24 hours. Sum of both buy and sell sides
high true string high price
low true string low price
vol true string Trade Volume(Cont.), from nowtime - 24 hours. Sum of both buy and sell sides
trade_turnover true string Transaction amount, from nowtime - 24 hours. Sum of both buy and sell sides
ts true long timestamp
</ticks>
ts true long Time of Respond Generation, Unit: Millisecond

[General]Get a Batch of Market Data Overview(V2)

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code false string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
business_type false(more see remarks) string business type, default is swap futures, swap, all

Note

Response:

{
    "status": "ok",
    "ticks": [
        {
            "id": 1650792083,
            "ts": 1650792083179,
            "ask": [
                39736.6,
                1285
            ],
            "bid": [
                39736.5,
                6070
            ],
            "business_type": "swap",
            "contract_code": "BTC-USDT",
            "open": "39760",
            "close": "39736.6",
            "low": "39316.3",
            "high": "39971.2",
            "amount": "6891.566",
            "count": 48262,
            "vol": "273472535.834",
            "number_of": "6891566"
        }
    ],
    "ts": 1650792083179
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok" , "error"
<ticks> true object array
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
business_type true string business type futures, swap
id true long id
amount true string Trade Amount(Coin) ,from nowtime - 24 hours. Sum of both buy and sell sides
ask true array [ask one price, ask one vol(cont)]
bid true array [bid one price, bid one vol(cont)]
open true string open price
close true string close price
count true decimal Order Quantity, from nowtime - 24 hours. Sum of both buy and sell sides
high true string high price
low true string low price
vol true string Transaction amount, from nowtime - 24 hours. Sum of both buy and sell sides
number_of true string number of(cont), from nowtime - 24 hours. Sum of both buy and sell sides
ts true long timestamp
</ticks>
ts true long Time of Respond Generation, Unit: Millisecond

[General] Query The Last Trade of a Contract

Example

curl "https://api.hbdm.com/linear-swap-ex/market/trade?contract_code=BTC-USDT"

Remarks

Request Parameter

Parameter Name Required Type Desc
contract_code false string contract code or contract type, swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
business_type false(more see remarks) string business type, default is swap: futures, swap, all

Response:


{
    "ch": "market.*.trade.detail",
    "status": "ok",
    "tick": {
        "data": [
            {
                "amount": "6",
                "ts": 1603695230083,
                "id": 1314755250000,
                "price": "13083",
                "direction": "buy",
                "quantity": 0.006,
                "contract_code": "BTC-USDT",
                "business_type":"swap",
                "trade_turnover": 78.498
            }
        ],
        "id": 1603695235127,
        "ts": 1603695235127
    },
    "ts": 1603695235127
}

Returning Parameter

Parameter Name Required Type Desc Value Range
ch true string Data belonged channel，Format： market.$contract_code.trade.detail
status true string "ok","error"
ts true long Sending time
<tick>
id true long Unique Order Id(symbol level).
ts true long Latest Creation Time
<data>
id true long Unique Transaction Id(symbol level)
price true string Price
amount true string Quantity(Cont.). Sum of both buy and sell sides
direction true string The direction to buy or sell is the direction of the taker (active transaction)
ts true long Order Creation Time
quantity true string trading quantity(coin)
contract_code true string Contract Code or Contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
business_type true string business type futures, swap
trade_turnover true string trade turnover(quoted currency)
</data>
</tick>

[General] Query a Batch of Trade Records of a Contract

Example

curl "https://api.hbdm.com/linear-swap-ex/market/history/trade?contract_code=BTC-USDT&size=100"

Remarks

Request Parameter

Parameter Name Required Data Type Desc Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
size true int Number of Trading Records Acquisition [1, 2000]

Response:

Response:


{
    "ch": "market.BTC-USDT.trade.detail",
    "data": [
        {
            "data": [
                {
                    "amount": 2,
                    "direction": "buy",
                    "id": 1314767870000,
                    "price": 13081.3,
                    "ts": 1603695383124,
                    "quantity": 0.002,
                    "trade_turnover": 26.1626
                }
            ],
            "id": 131476787,
            "ts": 1603695383124
        }
    ],
    "status": "ok",
    "ts": 1603695388965
}

Returning Parameter

Parameter Name Required Data Type Desc Value Range
ch true string Data belonged channel，Format： market.$contract_code.trade.detail
<data> true object array
<data> true object array
amount true decimal Quantity(Cont.). Sum of both buy and sell sides
direction true string The direction to buy or sell is the direction of the taker (active transaction)
id true long Unique Transaction Id(symbol level)
price true decimal Price
ts true long Order Creation Time
quantity true decimal trading quantity(coin)
trade_turnover true decimal trade turnover(quoted currency)
</data>
id true long Unique Order Id(symbol level).
ts true long Latest transaction time
</data>
status true string "ok"，"error"
ts true long Time of Respond Generation, Unit: Millisecond

Notice

[General] Query information on open interest

curl "https://api.hbdm.com/linear-swap-api/v1/swap_his_open_interest?contract_code=BTC-USDT&period=60min&amount_type=1"

Remarks

Request Parameter

Parameter Name Required Type Desc Data Range
contract_code false(more see remarks) string contract_code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, 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",
        "tick": [
            {
                "volume": 27112.0000000000000000,
                "amount_type": 1,
                "ts": 1638720000000,
                "value": 1321498.52640000000000000000000000000000000
            }
        ],
        "contract_code": "BTC-USDT-211210",
        "business_type": "futures",
        "pair": "BTC-USDT",
        "contract_type": "this_week"
    },
    "ts": 1638755582116
}

Returning Parameter

Parameter Name Required Type Desc Data Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> Dictionary Data
symbol true string symbol "BTC","ETH"...
contract_code true string contract code e.g. swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
<tick>
volume true decimal Open Interest.
amount_type true int Open Interest Unit 1:-cont，2:- cryptocurrency
value true decimal Total position volume (the unit shall be the denominated currency of the contract, eg, USDT)
ts true long Recording Time
</tick>
</data>

Notice

[Cross] Query Information On Transfer State

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
margin_account false string margin account, return all margin when null "USDT"，only support USDT now

Response 


{
    "status": "ok",
    "data": [
        {
            "margin_mode": "cross",
            "margin_account": "USDT",
            "transfer_in": 1,
            "transfer_out": 1,
            "master_transfer_sub": 1,
            "sub_transfer_master": 1,
            "master_transfer_sub_inner_in": 1,
            "master_transfer_sub_inner_out": 1,
            "sub_transfer_master_inner_in": 1,
            "sub_transfer_master_inner_out": 1,
            "transfer_inner_in": 1,
            "transfer_inner_out": 1
        }
    ],
    "ts": 1606905619516
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
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
master_transfer_sub_inner_in true int Transfer_in access for transfer from main account to sub-account - crossing account: "1" represents "available", "0" represents "unavailable"
master_transfer_sub_inner_out true int Transfer_out access for transfer from main account to sub-account - crossing account: "1" represents "available", "0" represents "unavailable"
sub_transfer_master_inner_in true int Transfer_in access for transfer from sub-account to main account - crossing account: "1" represents "available", "0" represents "unavailable"
sub_transfer_master_inner_out true int Transfer_out access for transfer from sub-account to main account - crossing account: "1" represents "available", "0" represents "unavailable"
transfer_inner_in true int Transfer_in access for transfer between different margin accounts under the same account："1" represents "available", "0" represents "unavailable"
transfer_inner_out true int Transfer_out access for transfer between different margin accounts under the same account："1" represents "available", "0" represents "unavailable"
</data>

[Cross] Query Information On Trade State

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
contract_type false string contract type swap, this_week, next_week, quarter, next_quarter
business_type false(more see remarks) string business type, default is swap futures, swap, all

Response


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211210",
            "margin_mode": "cross",
            "margin_account": "USDT",
            "open": 1,
            "close": 1,
            "cancel": 1,
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "this_week"
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211217",
            "margin_mode": "cross",
            "margin_account": "USDT",
            "open": 1,
            "close": 1,
            "cancel": 1,
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "next_week"
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211231",
            "margin_mode": "cross",
            "margin_account": "USDT",
            "open": 1,
            "close": 1,
            "cancel": 1,
            "business_type": "futures",
            "pair": "BTC-USDT",
            "contract_type": "quarter"
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "margin_mode": "cross",
            "margin_account": "USDT",
            "open": 1,
            "close": 1,
            "cancel": 1,
            "business_type": "swap",
            "pair": "BTC-USDT",
            "contract_type": "swap"
        }
    ],
    "ts": 1638756343093
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
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"
</data>

[General] Query Premium Index Kline Data

example

curl "https://api.hbdm.com/index/market/history/linear_swap_premium_index_kline?contract_code=BTC-USDT&period=1min&size=1"

Remarks

request parameters

Parameter name Required Type Desc Value Range
contract_code true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT","ETH-USDT".
period true string kline period 1min,5min, 15min, 30min, 60min,4hour,1day,1week,1mon
size true int kline size [1,2000]

Response Example：


{
    "ch": "market.BTC-USDT.premium_index.1min",
    "data": [
        {
            "amount": "0",
            "close": "0.0000079166666666",
            "count": "0",
            "high": "0.0000079166666666",
            "id": 1603696920,
            "low": "0.0000079166666666",
            "open": "0.0000079166666666",
            "trade_turnover": "0",
            "vol": "0"
        }
    ],
    "status": "ok",
    "ts": 1603696958348
}

response parameters：

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

[General] Query Estimated Funding Rate Kline Data

example

curl "https://api.hbdm.com/index/market/history/linear_swap_estimated_rate_kline?contract_code=BTC-USDT&period=1min&size=1"

Remarks

request parameters

Parameter name Required Type Desc Default Value Range
contract_code true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT","ETH-USDT".
period true string kline period 1min,5min, 15min, 30min, 60min,4hour,1day,1week,1mon
size true int kline size [1,2000]

Response Example：


{
    "ch": "market.BTC-USDT.estimated_rate.1min",
    "data": [
        {
            "amount": "0",
            "close": "0.0001",
            "count": "0",
            "high": "0.0001",
            "id": 1603697100,
            "low": "0.0001",
            "open": "0.0001",
            "trade_turnover": "0",
            "vol": "0"
        }
    ],
    "status": "ok",
    "ts": 1603697104902
}

response parameters：

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

[General] Query Basis Data

example

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

Remarks

request parameters

Parameter name Required Type Desc Default Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
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 int data size 150 [1,2000]

Response example：


{
    "ch": "market.BTC-USDT.basis.1min.open",
    "data": [
        {
            "basis": "15.29074235666667",
            "basis_rate": "0.001170582317307796",
            "contract_price": "13077.8",
            "id": 1603697160,
            "index_price": "13062.509257643333"
        }
    ],
    "status": "ok",
    "ts": 1603697170804
}

response parameters

parameter name Required Type Desc Value Range
ch true string data channel，eg： market.basis
<data> object array
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>
status true string status "ok" , "error"
ts true long created time

Swap Account Interface

[General]Query Asset Valuation

Note

Request Parameter

Parameter Name Required Parameter Type Description Value Range
valuation_asset false string The valuation according to the certain fiat currency. If not fill in, default as BTC "BTC", "USD", "USDT", "CNY", "EUR", "GBP", "VND", "HKD", "TWD", "MYR", "SGD", "KRW", "RUB", "TRY"

Response: 

{
    "status": "ok",
    "data": [
        {
            "valuation_asset": "BTC",
            "balance": "0.378256726579799383"
        }
    ],
    "ts": 1614045417046
}

Returning Parameter

Parameter Name Required Parameter Type Description Value Range
status true string the result of server handles for the request
<data> true object array
valuation_asset true string The valuation according to the certain fiat currency "BTC", "USD", "USDT", "CNY", "EUR", "GBP", "VND", "HKD", "TWD", "MYR", "SGD", "KRW", "RUB", "TRY"
balance true string Asset Valuation
</data>
ts true long timestamp

[Isolated] Query User’s Account Information

Example

Remarks

Request Parameter

Parameter Name Required Type Desc
contract_code false string Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"

Response:



{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "margin_balance": 99.755058840000000000,
            "margin_position": 0,
            "margin_frozen": 12.730000000000000000,
            "margin_available": 87.025058840000000000,
            "profit_real": 0,
            "profit_unreal": 0,
            "risk_rate": 7.761218290652003142,
            "withdraw_available": 87.025058840000000000000000000000000000,
            "liquidation_price": null,
            "lever_rate": 10,
            "adjust_factor": 0.075000000000000000,
            "margin_static": 99.755058840000000000,
            "contract_code": "BTC-USDT",
            "margin_asset": "USDT",
            "margin_mode": "isolated",
            "margin_account": "BTC-USDT",
            "position_mode": "dual_side"
        }
    ],
    "ts": 1603697381238
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<data>
symbol true string Variety code "BTC","ETH"...
contract_code true string contract code "BTC-USDT" ...
margin_asset true string Margin Asset
margin_balance true decimal Account rights
margin_position true decimal Position Margin
margin_frozen true decimal Frozen 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
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
position_mode true string position mode single_side，dual_side
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Cross] Query User's Account Information

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
margin_account false string margin account，return all margin account info when null "USDT"...，but now only USDT

Response

{
    "status": "ok",
    "data": [
        {
            "futures_contract_detail": [
                {
                    "symbol": "BTC",
                    "contract_code": "BTC-USDT-211217",
                    "margin_position": 0,
                    "margin_frozen": 0,
                    "margin_available": 10000.000000000000000000,
                    "profit_unreal": 0E-18,
                    "liquidation_price": null,
                    "lever_rate": 5,
                    "adjust_factor": 0.040000000000000000,
                    "contract_type": "next_week",
                    "pair": "BTC-USDT",
                    "business_type": "futures"
                },
                {
                    "symbol": "BTC",
                    "contract_code": "BTC-USDT-211210",
                    "margin_position": 0,
                    "margin_frozen": 0,
                    "margin_available": 10000.000000000000000000,
                    "profit_unreal": 0E-18,
                    "liquidation_price": null,
                    "lever_rate": 5,
                    "adjust_factor": 0.040000000000000000,
                    "contract_type": "this_week",
                    "pair": "BTC-USDT",
                    "business_type": "futures"
                },
                {
                    "symbol": "BTC",
                    "contract_code": "BTC-USDT-211231",
                    "margin_position": 0,
                    "margin_frozen": 0,
                    "margin_available": 10000.000000000000000000,
                    "profit_unreal": 0E-18,
                    "liquidation_price": null,
                    "lever_rate": 5,
                    "adjust_factor": 0.040000000000000000,
                    "contract_type": "quarter",
                    "pair": "BTC-USDT",
                    "business_type": "futures"
                }
            ],
            "margin_mode": "cross",
            "margin_account": "USDT",
            "margin_asset": "USDT",
            "margin_balance": 10000.000000000000000000,
            "margin_static": 10000.000000000000000000,
            "margin_position": 0,
            "margin_frozen": 0,
            "profit_real": 0E-18,
            "profit_unreal": 0,
            "withdraw_available": 1E+4,
            "risk_rate": null,
            "position_mode": "dual_side",
            "contract_detail": [
                {
                    "symbol": "BTC",
                    "contract_code": "BTC-USDT",
                    "margin_position": 0,
                    "margin_frozen": 0,
                    "margin_available": 10000.000000000000000000,
                    "profit_unreal": 0E-18,
                    "liquidation_price": null,
                    "lever_rate": 5,
                    "adjust_factor": 0.040000000000000000,
                    "contract_type": "swap",
                    "pair": "BTC-USDT",
                    "business_type": "swap"
                }
            ]
        }
    ],
    "ts": 1638757139907
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts long long Time of Respond Generation, Unit: Millisecond
<data> true object array
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
margin_asset true string margin asset
margin_balance true decimal account equity
margin_static true decimal static margin
margin_position true decimal position margin (summary of all contract)
margin_frozen true decimal frozen margin (summary of all contract)
profit_real true decimal realized profits and losses (summary of all contract)
profit_unreal true decimal unrealized profits and losses (summary of all contract)
withdraw_available true decimal available transfer amount
risk_rate true decimal margin rate
position_mode true string position mode single_side，dual_side
<contract_detail> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"...
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_unreal true decimal unrealized profits and losses
liquidation_price true decimal estimated liquidation price
lever_rate true decimal lever rate
adjust_factor true decimal adjustment factor
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</contract_detail>
<futures_contract_detail> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code future: "BTC-USDT-210625" ...
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_unreal true decimal unrealized profits and losses
liquidation_price true decimal estimated liquidation price
lever_rate true decimal lever rate
adjust_factor true decimal adjustment factor
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</futures_contract_detail>
</data>

[Isolated] Query User’s Position Information

Example

Remarks

Request Parameter

Parameter Name Required Type Desc
contract_code false string Case-Insenstive.Both uppercase and lowercase are supported..e.g. "BTC-USDT"

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "volume": 1.000000000000000000,
            "available": 1.000000000000000000,
            "frozen": 0,
            "cost_open": 13068.000000000000000000,
            "cost_hold": 13068.000000000000000000,
            "profit_unreal": 0,
            "profit_rate": 0,
            "lever_rate": 10,
            "position_margin": 1.306800000000000000,
            "direction": "buy",
            "profit": 0,
            "last_price": 13068,
            "margin_asset": "USDT",
            "margin_mode": "isolated",
            "margin_account": "BTC-USDT",
            "position_mode": "dual_side"
        }
    ],
    "ts": 1603697821846
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<data>
symbol true string Variety code "BTC","ETH"...
contract_code true string contract code e.g. "BTC-USDT"
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
margin_asset true string Margin Asset
position_margin true decimal Position margin
lever_rate true int Leverage rate
direction true string transaction direction of positions "buy":long "sell":short
last_price true decimal Latest price
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
position_mode true string position mode single_side，dual_side
</data>
ts true long Time of Respond Generation, Unit: Millisecond

Note

[Cross] Query User's Position Information

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-211225" ...
pair false string pair BTC-USDT
contract_type false string contract type swap, this_week, next_week, quarter, next_quarter

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "volume": 1.000000000000000000,
            "available": 1.000000000000000000,
            "frozen": 0E-18,
            "cost_open": 48945.900000000000000000,
            "cost_hold": 48945.900000000000000000,
            "profit_unreal": -0.003800000000000000,
            "profit_rate": -0.000388183688521410,
            "lever_rate": 5,
            "position_margin": 9.788420000000000000,
            "direction": "buy",
            "profit": -0.003800000000000000,
            "last_price": 48942.1,
            "margin_asset": "USDT",
            "margin_mode": "cross",
            "margin_account": "USDT",
            "contract_type": "swap",
            "pair": "BTC-USDT",
            "business_type": "swap",
            "position_mode": "dual_side"
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211210",
            "volume": 1.000000000000000000,
            "available": 1.000000000000000000,
            "frozen": 0E-18,
            "cost_open": 48929.700000000000000000,
            "cost_hold": 48929.700000000000000000,
            "profit_unreal": -0.049800000000000000,
            "profit_rate": -0.005088933715105550,
            "lever_rate": 5,
            "position_margin": 9.775980000000000000,
            "direction": "buy",
            "profit": -0.049800000000000000,
            "last_price": 48879.9,
            "margin_asset": "USDT",
            "margin_mode": "cross",
            "margin_account": "USDT",
            "contract_type": "this_week",
            "pair": "BTC-USDT",
            "business_type": "futures",
            "position_mode": "dual_side"
        }
    ],
    "ts": 1638758525147
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
volume true decimal position quantity
available true decimal available position can be closed
frozen true decimal frozen quantity
cost_open true decimal opening average price
cost_hold true decimal average price of position
profit_unreal true decimal unrealized profits and losses
profit_rate true decimal profit rate
profit true decimal profit
margin_asset true string margin asset
position_margin true decimal position margin
lever_rate true int lever rate
direction true string transaction direction of positions "buy":long "sell":short
last_price true decimal latest price
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
position_mode true string position mode single_side，dual_side
</data>

[Isolated] Query Assets And Positions

Remarks

params

field Required type desc range
contract_code true string contract code Case-Insenstive.Both uppercase and lowercase are supported. "BTC-USDT","ETH-USDT"....

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "margin_balance": 99.751731640000000000,
            "margin_position": 1.306990000000000000,
            "margin_frozen": 12.730000000000000000,
            "margin_available": 85.714741640000000000,
            "profit_real": -0.005227200000000000,
            "profit_unreal": 0.001900000000000000,
            "risk_rate": 7.031347702748238760,
            "withdraw_available": 85.712841640000000000000000000000000000,
            "liquidation_price": null,
            "lever_rate": 10,
            "adjust_factor": 0.075000000000000000,
            "margin_static": 99.749831640000000000,
            "positions": [
                {
                    "symbol": "BTC",
                    "contract_code": "BTC-USDT",
                    "volume": 1.000000000000000000,
                    "available": 1.000000000000000000,
                    "frozen": 0,
                    "cost_open": 13068.000000000000000000,
                    "cost_hold": 13068.000000000000000000,
                    "profit_unreal": 0.001900000000000000,
                    "profit_rate": 0.001453933272115090,
                    "lever_rate": 10,
                    "position_margin": 1.306990000000000000,
                    "direction": "buy",
                    "profit": 0.001900000000000000,
                    "last_price": 13069.9,
                    "margin_asset": "USDT",
                    "margin_mode": "isolated",
                    "margin_account": "BTC-USDT",
                    "position_mode": "dual_side"
                }
            ],
            "margin_asset": "USDT",
            "margin_mode": "isolated",
            "margin_account": "BTC-USDT",
            "position_mode": "dual_side"
        }
    ],
    "ts": 1603697944138
}

response

attr type Required desc Value
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
symbol true string contract symbol "BTC","ETH"...
contract_code true string contract code "BTC-USDT" ...
margin_asset true string Margin Asset
margin_balance true decimal Balance Margin
margin_static true decimal Balance static
margin_position true decimal Postion Margin
margin_frozen true decimal Frozen Margin
margin_available true decimal Available Margin
profit_real true decimal Realized Profit
profit_unreal true decimal Unreadlized Profit
risk_rate true decimal risk rate
liquidation_price true decimal Estimated Liquidation Price
withdraw_available true decimal Available Withdraw
lever_rate true decimal Leverage Rate
adjust_factor true decimal Adjustment Factor
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
position_mode true string position mode single_side，dual_side
<positions> true object array
symbol true string Variety Code "BTC","ETH"...
contract_code true string Contract Code "BTC-USDT" ...
volume true decimal Position Quantity
available true decimal Available position quatity can be closed
frozen true decimal forzen postion Quantity
cost_open true decimal Opening Average Price
cost_hold true decimal Average position price
profit_unreal true decimal Unrealized profit
profit_rate true decimal Profit Rate
profit true decimal Profit
margin_asset true string Margin Asset
position_margin true decimal Position Margin
lever_rate true int Leverage Rate
direction true string transaction direction of positions "buy":long "sell":short
last_price true decimal Last Price
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
position_mode true string position mode single_side，dual_side
</positions>
</data>

[Cross] Query Assets And Positions

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
margin_account true string margin account "USDT"...，but now only USDT

Response

{
    "status": "ok",
    "data": {
        "positions": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "volume": 1.000000000000000000,
                "available": 1.000000000000000000,
                "frozen": 0E-18,
                "cost_open": 48945.900000000000000000,
                "cost_hold": 48945.900000000000000000,
                "profit_unreal": 0.034200000000000000,
                "profit_rate": 0.003493653196692670,
                "lever_rate": 5,
                "position_margin": 9.796020000000000000,
                "direction": "buy",
                "profit": 0.034200000000000000,
                "last_price": 48980.1,
                "margin_asset": "USDT",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "contract_type": "swap",
                "pair": "BTC-USDT",
                "business_type": "swap",
                "position_mode": "dual_side"
            },
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "volume": 1.000000000000000000,
                "available": 1.000000000000000000,
                "frozen": 0E-18,
                "cost_open": 48929.700000000000000000,
                "cost_hold": 48929.700000000000000000,
                "profit_unreal": 0.036900000000000000,
                "profit_rate": 0.003770715945530015,
                "lever_rate": 5,
                "position_margin": 9.793320000000000000,
                "direction": "buy",
                "profit": 0.036900000000000000,
                "last_price": 48966.6,
                "margin_asset": "USDT",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures",
                "position_mode": "dual_side"
            }
        ],
        "futures_contract_detail": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211217",
                "margin_position": 0,
                "margin_frozen": 0,
                "margin_available": 9716.437716790000000000,
                "profit_unreal": 0E-18,
                "liquidation_price": null,
                "lever_rate": 5,
                "adjust_factor": 0.040000000000000000,
                "contract_type": "next_week",
                "pair": "BTC-USDT",
                "business_type": "futures"
            },
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "margin_position": 9.793320000000000000,
                "margin_frozen": 0E-18,
                "margin_available": 9716.437716790000000000,
                "profit_unreal": 0.036900000000000000,
                "liquidation_price": null,
                "lever_rate": 5,
                "adjust_factor": 0.040000000000000000,
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures"
            },
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211231",
                "margin_position": 0,
                "margin_frozen": 264.000000000000000000,
                "margin_available": 9716.437716790000000000000000000000000000,
                "profit_unreal": 0E-18,
                "liquidation_price": null,
                "lever_rate": 1,
                "adjust_factor": 0.005000000000000000,
                "contract_type": "quarter",
                "pair": "BTC-USDT",
                "business_type": "futures"
            }
        ],
        "margin_mode": "cross",
        "margin_account": "USDT",
        "margin_asset": "USDT",
        "margin_balance": 10000.027056790000000000,
        "margin_static": 9999.955956790000000000,
        "margin_position": 19.589340000000000000,
        "margin_frozen": 264.000000000000000000,
        "profit_real": -0.044043210000000000,
        "profit_unreal": 0.071100000000000000,
        "withdraw_available": 9716.36661679,
        "risk_rate": 4752.827989089613978802,
        "position_mode": "dual_side",
        "contract_detail": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "margin_position": 9.796020000000000000,
                "margin_frozen": 0E-18,
                "margin_available": 9716.437716790000000000,
                "profit_unreal": 0.034200000000000000,
                "liquidation_price": null,
                "lever_rate": 5,
                "adjust_factor": 0.040000000000000000,
                "contract_type": "swap",
                "pair": "BTC-USDT",
                "business_type": "swap"
            }
        ]
    },
    "ts": 1638758699818
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts long long Time of Respond Generation, Unit: Millisecond
<data> true object array
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
margin_asset true string margin asset
margin_balance true decimal account equity
margin_static true decimal static margin
margin_position true decimal position margin (summary of all contract)
margin_frozen true decimal frozen margin (summary of all contract)
profit_real true decimal realized profits and losses
profit_unreal true decimal unrealized profits and losses (summary of all contract)
withdraw_available true decimal available transfer amount
risk_rate true decimal margin rate
position_mode true string position mode single_side，dual_side
<contract_detail> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"...
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_unreal true decimal unrealized profits and losses
liquidation_price true decimal estimated liquidation price
lever_rate true decimal lever rate
adjust_factor true decimal adjustment factor
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</contract_detail>
<futures_contract_detail> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code future: "BTC-USDT-210625" ...
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_unreal true decimal unrealized profits and losses
liquidation_price true decimal estimated liquidation price
lever_rate true decimal lever rate
adjust_factor true decimal adjustment factor
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</futures_contract_detail>
<positions> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
volume true decimal position quantity
available true decimal available position can be closed
frozen true decimal frozen quantity
cost_open true decimal opening average price
cost_hold true decimal average price of position
profit_unreal true decimal unrealized profits and losses
profit_rate true decimal profit rate
profit true decimal profit
margin_asset true string margin asset
position_margin true decimal position margin
lever_rate true int lever rate
direction true string transaction direction of positions "buy":long "sell":short
last_price true decimal latest price
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
position_mode true string position mode single_side，dual_side
</positions>
</data>

[General]Set a Batch of Sub-Account Trading Permissions

Note：

Request Parameter

Parameter Name Required Type Description Value Range
sub_uid true string sub-account uid (multiple uids are separated by ",", and one time 10 sub uid at most)
sub_auth true int sub auth, 1:enable, 0:disable

Note：

Response:


{
    "status": "ok",
    "data": {
        "errors": [
            {
                "sub_uid": "1234567",
                "err_code": 1010,
                "err_msg": "Account doesnt exist."
            }
        ],
        "successes": "123456789"
    },
    "ts": 1612504316476
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string result of server handled request "ok" , "error"
<data> true
<errors> true object array
sub_uid true string the list of sub uid which failed
err_code true int error code
err_msg true string error msg
</errors>
successes true string the list of sub uid which successes
</data>
ts true long Time of Respond Generation，Unit：Millisecond

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

Remarks

Request Parameters

Parameter name Must fill or not Type Description Value range
contract_code false string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"

Response:


{
    "status": "ok",
    "data": [
        {
            "sub_uid": 123456789,
            "list": [
                {
                    "symbol": "BTC",
                    "margin_balance": 20,
                    "liquidation_price": null,
                    "risk_rate": null,
                    "contract_code": "BTC-USDT",
                    "margin_asset": "USDT",
                    "margin_mode": "isolated",
                    "margin_account": "BTC-USDT"
                }
            ]
        }
    ],
    "ts": 1603698380336
}

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"...
contract_code true string contract code e.g. "BTC-USDT"
margin_asset true string margin asset
margin_balance true decimal account equity
liquidation_price true decimal estimated liquidation price
risk_rate true decimal margin rate
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
</list>
</data>

Notice

[Cross] Query Assets Information Of All Sub-Accounts Under The Master Account

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
margin_account false string margin account，return all margin account info when null "USDT"...，but now only USDT

Response


{
    "status": "ok",
    "data": [
        {
            "sub_uid": 123456789,
            "list": [
                {
                    "margin_balance": 163.561708129559110889,
                    "risk_rate": 78.896729392251481019,
                    "margin_asset": "USDT",
                    "margin_mode": "cross",
                    "margin_account": "USDT"
                }
            ]
        }
    ],
    "ts": 1606962745633
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
sub_uid true long sub-account UID
<list> true object array
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
margin_asset true string margin asset
margin_balance true decimal account equity
risk_rate true decimal margin rate
</list>
</data>

Notice

[Isolated]Query a Batch of Sub-Account's Assets Information

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false string contract code "BTC-USDT"... ,if not filled, return all
page_index false int page index, if not filled in as 1st
page_size false int if not filled in as 20，50 at most

Note：

Response:

{
    "status": "ok",
    "data": {
        "total_page": 1,
        "current_page": 1,
        "total_size": 1,
        "sub_list": [
            {
                "sub_uid": 123456789,
                "account_info_list": [
                    {
                        "symbol": "BTC",
                        "margin_balance": 0,
                        "liquidation_price": null,
                        "risk_rate": null,
                        "contract_code": "BTC-USDT",
                        "margin_asset": "USDT",
                        "margin_mode": "isolated",
                        "margin_account": "BTC-USDT"
                    }
                ]
            }
        ]
    },
    "ts": 1612504756853
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string result of server handled request "ok" , "error"
ts true long Time of Respond Generation，Unit：Millisecond
<data> true object
<sub_list> true object array
sub_uid true long sub uid
<account_info_list> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code "BTC-USDT" ...
margin_account true string margin account such as:BTC-USDT”
margin_mode true string margin mode isolated: isolated
margin_asset true string margin asset)
margin_balance true decimal margin balance
liquidation_price true decimal liquidation price
risk_rate true decimal risk rate
</account_info_list>
</sub_list>
current_page true int current page
total_page true int total page
total_size true int total size
</data>

[Cross]Query a Batch of Sub-Account's Assets Information

Note

Request Parameter

Parameter Name Required Type Description Value Range
margin_account false string margin account，if not filled in return all margin account "USDT"，but now just has one account usdt
page_index false int page index, if not filled in as 1st
page_size false int if not filled in as 20，50 at most

Note：

Response:

{
    "status": "ok",
    "data": {
        "total_page": 1,
        "current_page": 1,
        "total_size": 1,
        "sub_list": [
            {
                "sub_uid": 12345678,
                "account_info_list": [
                    {
                        "margin_balance": 2,
                        "risk_rate": null,
                        "margin_asset": "USDT",
                        "margin_mode": "cross",
                        "margin_account": "USDT"
                    }
                ]
            }
        ]
    },
    "ts": 1612504845679
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string result of server handled request "ok" , "error"
ts true long Time of Respond Generation，Unit：Millisecond
<data> true object
<sub_list> true object array
sub_uid true long sub uid
<account_info_list> true object array
margin_mode true string margin mode cross；
margin_account true string margin account such as:USDT”
margin_asset true string margin asset
margin_balance true decimal margin balance
risk_rate true decimal risk rate
</account_info_list>
</sub_list>
current_page true int current page
total_page true int total page
total_size true int total size
</data>

[Isolated] Query a single sub-account's assets information

Remarks

Request Parameters

Parameter name Must fill or not Type Description
contract_code false string Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"
sub_uid true long sub-account UID

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "margin_balance": 20,
            "margin_position": 0,
            "margin_frozen": 0,
            "margin_available": 20.000000000000000000,
            "profit_real": 0,
            "profit_unreal": 0,
            "risk_rate": null,
            "withdraw_available": 20.000000000000000000,
            "liquidation_price": null,
            "lever_rate": 5,
            "adjust_factor": 0.040000000000000000,
            "margin_static": 20,
            "contract_code": "BTC-USDT",
            "margin_asset": "USDT",
            "margin_mode": "isolated",
            "margin_account": "BTC-USDT",
            "position_mode": "dual_side"
        }
    ],
    "ts": 1603698523200
}

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 e.g. "BTC-USDT"
margin_asset true string margin asset
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 int leverage ratios
adjust_factor true decimal Adjustment Factor
margin_static true decimal Static Margin
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
position_mode true string position mode single_side，dual_side
</data>

Notice

[Cross] Query A Sub-Account's Assets Information

Remarks

Request Parameter*

Parameter Name Required Type Desc Data Value
sub_uid true long sub-account UID
margin_account false string margin account，return all margin account info when null "USDT"...，but now only USDT

Response:


{
    "status": "ok",
    "data": [
        {
            "futures_contract_detail": [
                {
                    "symbol": "BTC",
                    "contract_code": "BTC-USDT-211217",
                    "margin_position": 0,
                    "margin_frozen": 0,
                    "margin_available": 500.000000000000000000,
                    "profit_unreal": 0E-18,
                    "liquidation_price": null,
                    "lever_rate": 5,
                    "adjust_factor": 0.040000000000000000,
                    "contract_type": "next_week",
                    "pair": "BTC-USDT",
                    "business_type": "futures"
                },
                {
                    "symbol": "BTC",
                    "contract_code": "BTC-USDT-211210",
                    "margin_position": 0,
                    "margin_frozen": 0,
                    "margin_available": 500.000000000000000000,
                    "profit_unreal": 0E-18,
                    "liquidation_price": null,
                    "lever_rate": 5,
                    "adjust_factor": 0.040000000000000000,
                    "contract_type": "this_week",
                    "pair": "BTC-USDT",
                    "business_type": "futures"
                },
                {
                    "symbol": "BTC",
                    "contract_code": "BTC-USDT-211231",
                    "margin_position": 0,
                    "margin_frozen": 0,
                    "margin_available": 500.000000000000000000,
                    "profit_unreal": 0E-18,
                    "liquidation_price": null,
                    "lever_rate": 5,
                    "adjust_factor": 0.040000000000000000,
                    "contract_type": "quarter",
                    "pair": "BTC-USDT",
                    "business_type": "futures"
                }
            ],
            "margin_mode": "cross",
            "margin_account": "USDT",
            "margin_asset": "USDT",
            "margin_balance": 500,
            "margin_static": 500,
            "margin_position": 0,
            "margin_frozen": 0,
            "profit_real": 0,
            "profit_unreal": 0,
            "withdraw_available": 5E+2,
            "risk_rate": null,
            "position_mode": "dual_side",
            "contract_detail": [
                {
                    "symbol": "BTC",
                    "contract_code": "BTC-USDT",
                    "margin_position": 0,
                    "margin_frozen": 0,
                    "margin_available": 500.000000000000000000,
                    "profit_unreal": 0E-18,
                    "liquidation_price": null,
                    "lever_rate": 5,
                    "adjust_factor": 0.040000000000000000,
                    "contract_type": "swap",
                    "pair": "BTC-USDT",
                    "business_type": "swap"
                }
            ]
        }
    ],
    "ts": 1638759191747
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts long long Time of Respond Generation, Unit: Millisecond
<data> true object array
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
margin_asset true string margin asset
margin_balance true decimal account equity
margin_static true decimal static margin
margin_position true decimal position margin (the margin used by current positions)
margin_frozen true decimal frozen margin
profit_real true decimal realized profits and losses
profit_unreal true decimal unrealized profits and losses
withdraw_available true decimal available transfer amount
risk_rate true decimal margin rate
position_mode true string position mode single_side，dual_side
<contract_detail> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap:"BTC-USDT" ...
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_unreal true decimal unrealized profits and losses
liquidation_price true decimal estimated liquidation price
lever_rate true decimal lever rate
adjust_factor true decimal adjustment factor
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</contract_detail>
<futures_contract_detail> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code future:"BTC-USDT-211231" ...
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_unreal true decimal unrealized profits and losses
liquidation_price true decimal estimated liquidation price
lever_rate true decimal lever rate
adjust_factor true decimal adjustment factor
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</futures_contract_detail>
</data>

Notice

[Isolated] Query a single sub-account's position information

Remarks

Request Parameters

Parameter name Must fill or not Type Description
contract_code false string Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"
sub_uid true long sub-account UID

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "volume": 1.000000000000000000,
            "available": 1.000000000000000000,
            "frozen": 0,
            "cost_open": 13038.700000000000000000,
            "cost_hold": 13038.700000000000000000,
            "profit_unreal": 0,
            "profit_rate": 0,
            "lever_rate": 10,
            "position_margin": 1.303870000000000000,
            "direction": "buy",
            "profit": 0,
            "last_price": 13038.7,
            "margin_asset": "USDT",
            "margin_mode": "isolated",
            "margin_account": "BTC-USDT",
            "position_mode": "dual_side"
        }
    ],
    "ts": 1603699081114
}

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 "BTC-USDT" ...
margin_asset true string margin asset
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
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
position_mode true string position mode single_side，dual_side
</data>

[Cross] Query A Sub-Account's Position Information

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
sub_uid true long sub-account UID
pair false string pair BTC-USDT
contract_type false string contract type swap, this_week, next_week, quarter, next_quarter

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211231",
            "volume": 1.000000000000000000,
            "available": 1.000000000000000000,
            "frozen": 0E-18,
            "cost_open": 48886.700000000000000000,
            "cost_hold": 48886.700000000000000000,
            "profit_unreal": -0.065300000000000000,
            "profit_rate": -0.001335741622977210,
            "lever_rate": 1,
            "position_margin": 48.952000000000000000,
            "direction": "sell",
            "profit": -0.065300000000000000,
            "last_price": 48952,
            "margin_asset": "USDT",
            "margin_mode": "cross",
            "margin_account": "USDT",
            "contract_type": "quarter",
            "pair": "BTC-USDT",
            "business_type": "futures",
            "position_mode": "dual_side"
        }
    ],
    "ts": 1638759509329
}

Returning Parameter

Parameter Name Required Type Desc Value range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
volume true decimal position quantity
available true decimal available position can be closed
frozen true decimal frozen quantity
cost_open true decimal opening average price
cost_hold true decimal average price of position
profit_unreal true decimal unrealized profits and losses
profit_rate true decimal profit rate
profit true decimal profit
margin_asset true string margin asset
position_margin true decimal position margin
lever_rate true int lever rate
direction true string transaction direction of positions "buy":long "sell":short
last_price true decimal latest price
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
position_mode true string position mode single_side，dual_side
</data>

[General] Query account financial records(New)

Note

Request:


    {
        "contract": "BTC-USDT",
        "mar_acct": "BTC-USDT",
        "type": "3,4,5,6,7",
        "start_time": 1660119810000,
        "end_time": 1660274746031,
        "direct": "next",
        "from_id": 1110
    }

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract false string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
mar_acct true string margin account swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... margin_account
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; 30:Funding fee-income; 31:Funding fee-expenditure; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master; 38:transfer from other margin account; 39:transfer to another margin account;
start_time false long Query start time, query by data creation time Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 138798248,
                "id": 117840,
                "type": 5,
                "amount": -0.024464850000000000,
                "ts": 1638758435635,
                "contract_code": "BTC-USDT-211210",
                "asset": "USDT",
                "margin_account": "USDT",
                "face_margin_account": ""
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> true object array
query_id true long
id true long
ts true long create time
asset true string asset "USDT"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_account true string margin account "BTC-USDT","USDT"...
face_margin_account true string the counterparty margin account, only has value when the transaction Type is 34, 35, 36, 37, 38, 39, and the other types are empty strings "BTC-USDT"...
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; 30:Funding fee-income; 31:Funding fee-expenditure; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master; 38:transfer from other margin account; 39:transfer to another margin account;
amount true decimal amount(quote currency)
</data>

[General]Query account financial records via Multiple Fields(New)

Note

Request:


    {
        "contract": "BTC-USDT",
        "mar_acct": "BTC-USDT",
        "type": "3,4,5,6,7",
        "start_time": 1660119810000,
        "end_time": 1660274746031,
        "direct": "next",
        "from_id": 1110
    }

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract false string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
mar_acct true string margin account swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... margin_account
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; 30:Funding fee-income; 31:Funding fee-expenditure; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master; 38:transfer from other margin account; 39:transfer to another margin account;
start_time false long Query start time, query by data creation time Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 138798248,
                "id": 117840,
                "type": 5,
                "amount": -0.024464850000000000,
                "ts": 1638758435635,
                "contract_code": "BTC-USDT-211210",
                "asset": "USDT",
                "margin_account": "USDT",
                "face_margin_account": ""
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> true object array
query_id true long
id true long
ts true long create time
asset true string asset "USDT"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_account true string margin account "BTC-USDT","USDT"...
face_margin_account true string the counterparty margin account, only has value when the transaction Type is 34, 35, 36, 37, 38, 39, and the other types are empty strings "BTC-USDT"...
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; 30:Funding fee-income; 31:Funding fee-expenditure; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master; 38:transfer from other margin account; 39:transfer to another margin account;
amount true decimal amount(quote currency)
</data>

[Isolated]Query Settlement Records of Users

Note：

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract_code "BTC-USDT"...
start_time false long start time(timestamp, Unit: Millisecond) Value Range：[(now - 90 days), now] , now - 90 days
end_time false long end time(timestamp, Unit: Millisecond) Value Range：(start_time, now], now
page_index false int page index if not filled in is 1st
page_size false int page size if not filled in is 20, and 50 at most(if more than 50, treated as 50

Note:

Response: 

{
    "status":"ok",
    "data":{
        "total_page":1,
        "current_page":1,
        "total_size":13,
        "settlement_records":[
            {
                "symbol":"BTC",
                "contract_code":"BTC-USDT",
                "margin_mode":"isolated",
                "margin_account":"BTC-USDT",
                "margin_balance_init":5000,
                "margin_balance":4891.74704672,
                "settlement_profit_real":-108.25295328,
                "settlement_time":1611040802012,
                "clawback":0,
                "funding_fee":0,
                "offset_profitloss":0,
                "fee":-2.63615328,
                "fee_asset":"USDT",
                "positions":[
                    {
                        "symbol":"BTC",
                        "contract_code":"BTC-USDT",
                        "direction":"buy",
                        "volume":12,
                        "cost_open":27900,
                        "cost_hold_pre":27900,
                        "cost_hold":27459.93,
                        "settlement_profit_unreal":-52.8084,
                        "settlement_price":27459.93,
                        "settlement_type":"settlement"
                    },
                    {
                        "symbol":"BTC",
                        "contract_code":"BTC-USDT",
                        "direction":"sell",
                        "volume":12,
                        "cost_open":27019.86,
                        "cost_hold_pre":27019.86,
                        "cost_hold":27459.93,
                        "settlement_profit_unreal":-52.8084,
                        "settlement_price":27459.93,
                        "settlement_type":"settlement"
                    }
                ]
            }
        ]
    },
    "ts":1611052289681
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status
<data> true object
<settlement_records> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code "BTC-USDT" ...
margin_mode true string margin mode cross/isolated
margin_account true string margin account such as: “BTC-USDT”
margin_balance_init true decimal margin balance init
margin_balance true decimal margin balance
settlement_profit_real true decimal settlement profit real
settlement_time true long settlement time/delivery time
clawback true decimal clawback
funding_fee true decimal current funding fee(or current delivery fee)
offset_profitloss true decimal offset profit or loss
fee true decimal fee
fee_asset true string fee asset
<positions> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code "BTC-USDT" ...
direction true string direction "buy"/"sell"
volume true decimal volume before settlement(cont)
cost_open true decimal cost open
cost_hold_pre true decimal cost hold before settlement
cost_hold true decimal cost hold after settlement
settlement_profit_unreal true decimal settlement profit unreal
settlement_price true decimal settlement price/delivery time
settlement_type true string settlement type settlement/delivery
</positions>
</settlement_records>
total_page true int total page
current_page true int current page
total_size true int total size
</data>
ts true long timestamp

[Cross]Query Settlement Records of Users

Note：

Request Parameter

Parameter Name Required Type Description Value Range
margin_account true string margin account "USDT", now only support USDT
start_time false long start time(timestamp, Unit: Millisecond) Value Range：[(now - 90 days), now] , now - 90 days
end_time false long end time(timestamp, Unit: Millisecond) Value Range：(start_time, now], now
page_index false int page index if not filled in is 1st
page_size false int page size if not filled is 10, 25 at most(if more than 25, treated as 50)

Note:

Response: 

{
    "status":"ok",
    "data":{
        "total_page":2,
        "current_page":1,
        "total_size":13,
        "settlement_records":[
            {
                "margin_mode":"cross",
                "margin_account":"USDT",
                "margin_balance_init":5000,
                "margin_balance":5007.6708,
                "settlement_profit_real":7.6708,
                "settlement_time":1611051602040,
                "clawback":0,
                "funding_fee":0,
                "offset_profitloss":0,
                "fee":0.6708,
                "fee_asset":"USDT",
                "contract_detail":[
                    {
                        "symbol":"BTC",
                        "contract_code":"BTC-USDT",
                        "offset_profitloss":0,
                        "fee":0.6708,
                        "fee_asset":"USDT",
                        "positions":[
                            {
                                "symbol":"BTC-USDT",
                                "contract_code":"BTC-USDT",
                                "direction":"buy",
                                "volume":9,
                                "cost_open":27911.111111111111111111,
                                "cost_hold_pre":27911.111111111111111111,
                                "cost_hold":34361.25,
                                "settlement_profit_unreal":580.5125,
                                "settlement_price":34361.25,
                                "settlement_type":"settlement"
                            },
                            {
                                "symbol":"BTC-USDT",
                                "contract_code":"BTC-USDT",
                                "direction":"sell",
                                "volume":9,
                                "cost_open":27988.888888888888888888,
                                "cost_hold_pre":27988.888888888888888888,
                                "cost_hold":34361.25,
                                "settlement_profit_unreal":-573.5125,
                                "settlement_price":34361.25,
                                "settlement_type":"settlement"
                            }
                        ]
                    }
                ]
            },
            {
                "margin_mode":"cross",
                "margin_account":"USDT",
                "margin_balance_init":5000,
                "margin_balance":5000,
                "settlement_profit_real":0,
                "settlement_time":1611047654316,
                "clawback":0,
                "funding_fee":0,
                "offset_profitloss":0,
                "fee":0,
                "fee_asset":"USDT",
                "contract_detail":[

                ]
            }
        ]
    },
    "ts":1611051729365
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status
<data> true object
<settlement_records> true object array
margin_mode true string margin mode cross/isolated
margin_account true string margin account such as “USDT”
margin_balance_init true decimal margin balance init
margin_balance true decimal margin balance after current settlement
settlement_profit_real true decimal settlement profit real
settlement_time true long settlement time/delivery time
clawback true decimal clawback
funding_fee true decimal total funding fee(delivery fee included)
offset_profitloss true decimal offset profit or loss
fee true decimal fee
fee_asset true string fee asset
<contract_detail> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code "BTC-USDT" ...
offset_profitloss true decimal offset profit or loss current settlement
fee true decimal fee current settlement
fee_asset true string fee asset
pair true string pair such as: “BTC-USDT”
<positions> true object array positions(just place when has positions)
symbol true string symbol "BTC","ETH"...
contract_code true string contract code "BTC-USDT" ...
direction true string direction "buy"/"sell"
volume true decimal volume before settlement(cont)
cost_open true decimal cost open
cost_hold_pre true decimal cost hold before settlement
cost_hold true decimal cost hold after current settlement
settlement_profit_unreal true decimal settlement profit unreal
settlement_price true decimal settlement price/delivery price
settlement_type true string settlement type settlement/delivery
pair true string pair such as: “BTC-USDT”
</positions>
</contract_detail> true
</settlement_records>
total_page true int total page
current_page true int current page
total_size true int total size
</data>
ts true long timestamp

[Isolated] Query user’s available leverage

Remarks

Request Parameter：

Parameter Name Required Type Desc Value Range
contract_code false string Contract code, if not filled in, the actual available leverage of all contracts will be returned by default “BTC-USDT”...

Response：


{
    "status": "ok",
    "data": [
        {
            "contract_code": "BTC-USDT",
            "margin_mode": "isolated",
            "available_level_rate": "1,2,3,5,10,20,30,50,75,100,125"
        }
    ],
    "ts": 1603699467348
}

Returning Parameter：

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<data> true object array
contract_code true string contract code "BTC-USDT"
margin_mode true string margin mode isolated : "isolated"
available_level_rate true string available level rate,splited by ',' "1,5,10"
</data>
ts true long Response generation time point, unit: millisecond

[Cross] Query User’s Available Leverage

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false string contract code，return all contract info when null swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
contract_type false string contract type swap, this_week, next_week, quarter, next_quarter
business_type false(more see remarks) string business type, default is swap futures, swap, all

Response


{
    "status": "ok",
    "data": [
        {
            "contract_code": "ETH-USDT",
            "available_level_rate": "1,2,3,5",
            "margin_mode": "cross",
            "contract_type": "swap",
            "pair": "ETH-USDT",
            "business_type": "swap"
        },
        {
            "contract_code": "ETH-USDT-211210",
            "available_level_rate": "1,2,3,5",
            "margin_mode": "cross",
            "contract_type": "this_week",
            "pair": "ETH-USDT",
            "business_type": "futures"
        },
        {
            "contract_code": "ETH-USDT-211217",
            "available_level_rate": "1,2,3,5",
            "margin_mode": "cross",
            "contract_type": "next_week",
            "pair": "ETH-USDT",
            "business_type": "futures"
        },
        {
            "contract_code": "ETH-USDT-211231",
            "available_level_rate": "1,2,3,5",
            "margin_mode": "cross",
            "contract_type": "quarter",
            "pair": "ETH-USDT",
            "business_type": "futures"
        }
    ],
    "ts": 1638760001689
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object array
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
available_level_rate true string available level rate,splited by ',' "1,5,10"
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[General] Query swap information on order limit

Remarks

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false string contract type code Case-Insenstive.Both uppercase and lowercase are supported.e.g. swap:"BTC-USDT"... , future:"BTC-USDT-210625"...
order_price_type true string Order Type "limit": Limit Order，"opponent":BBO，"lightning": Lightning 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
pair false string pair BTC-USDT
contract_type false string contract type swap, this_week, next_week, quarter, next_quarter
business_type false(more see remarks) string business type, default is swap futures, swap, all

Response:


{
    "status": "ok",
    "data": {
        "order_price_type": "limit",
        "list": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "open_limit": 170000.000000000000000000,
                "close_limit": 170000.000000000000000000,
                "business_type": "swap",
                "contract_type": "swap",
                "pair": "BTC-USDT"
            },
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211217",
                "open_limit": 170000.000000000000000000,
                "close_limit": 170000.000000000000000000,
                "business_type": "futures",
                "contract_type": "next_week",
                "pair": "BTC-USDT"
            },
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "open_limit": 170000.000000000000000000,
                "close_limit": 170000.000000000000000000,
                "business_type": "futures",
                "contract_type": "this_week",
                "pair": "BTC-USDT"
            },
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211231",
                "open_limit": 170000.000000000000000000,
                "close_limit": 170000.000000000000000000,
                "business_type": "futures",
                "contract_type": "quarter",
                "pair": "BTC-USDT"
            }
        ]
    },
    "ts": 1638760136200
}

Returning Parameter

Parameter Name Required 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": Lightning 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
<list>
symbol true string symbol "BTC","ETH"...
contract_code true string contract type code swap:"BTC-USDT"... , future:"BTC-USDT-210625"...
open_limit true decimal Max open order limit
close_limit true decimal Max close order limit
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</list>
</data>

[General] Query information on swap trading fee

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code false string contract type code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
contract_type false string contract type swap, this_week, next_week, quarter, next_quarter
business_type false(more see remarks) string business type, default is swap futures, swap, all

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "open_maker_fee": "0.0002",
            "open_taker_fee": "0.0004",
            "close_maker_fee": "0.0002",
            "close_taker_fee": "0.0004",
            "fee_asset": "USDT",
            "delivery_fee": "0",
            "business_type": "swap",
            "contract_type": "swap",
            "pair": "BTC-USDT"
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211217",
            "open_maker_fee": "0.0002",
            "open_taker_fee": "0.0005",
            "close_maker_fee": "0.0002",
            "close_taker_fee": "0.0005",
            "fee_asset": "USDT",
            "delivery_fee": "0.00015",
            "business_type": "futures",
            "contract_type": "next_week",
            "pair": "BTC-USDT"
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211210",
            "open_maker_fee": "0.0002",
            "open_taker_fee": "0.0005",
            "close_maker_fee": "0.0002",
            "close_taker_fee": "0.0005",
            "fee_asset": "USDT",
            "delivery_fee": "0.00015",
            "business_type": "futures",
            "contract_type": "this_week",
            "pair": "BTC-USDT"
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211231",
            "open_maker_fee": "0.0002",
            "open_taker_fee": "0.0005",
            "close_maker_fee": "0.0002",
            "close_taker_fee": "0.0005",
            "fee_asset": "USDT",
            "delivery_fee": "0.00015",
            "business_type": "futures",
            "contract_type": "quarter",
            "pair": "BTC-USDT"
        }
    ],
    "ts": 1638760715804
}

Returning Parameter

Parameter Name Required 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 Variety code
contract_code true string contract type code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
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
fee_asset true string the corresponding cryptocurrency to the given fee "USDT"...
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
delivery_fee true string delivery fee rate
</data>

[Isolated] Query information on Transfer Limit

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code false string contract type code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "transfer_in_max_each": 100000000.000000000000000000,
            "transfer_in_min_each": 1.0000000000E-8,
            "transfer_out_max_each": 10000000.000000000000000000,
            "transfer_out_min_each": 1.0000000000E-8,
            "transfer_in_max_daily": 1000000000.000000000000000000,
            "transfer_out_max_daily": 200000000.000000000000000000,
            "net_transfer_in_max_daily": 500000000.000000000000000000,
            "net_transfer_out_max_daily": 100000000.000000000000000000,
            "margin_account": "BTC-USDT",
            "margin_mode": "isolated"
        }
    ],
    "ts": 1640852376293
}

Returning Parameter

Parameter Name Required 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 symbol "BTC","ETH"...
contract_code true string contract type code "BTC-USDT",...
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
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account e.g: "BTC-USDT" ...
</data>

[Cross] Query Information On Transfer Limit

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
margin_account false string margin account, return all margin account info when null "USDT"...，but now only USDT

Response:


{
    "status": "ok",
    "data": [
        {
            "transfer_in_max_each": 999999999999999999,
            "transfer_in_min_each": 0.0001,
            "transfer_out_max_each": 999999999999999999,
            "transfer_out_min_each": 0.0001,
            "transfer_in_max_daily": 900000000999999999,
            "transfer_out_max_daily": 900000099999999999,
            "net_transfer_in_max_daily": 900000000099999999,
            "net_transfer_out_max_daily": 123456789012345678.12345678,
            "margin_account": "USDT",
            "margin_mode": "cross"
        }
    ],
    "ts": 1606964432217
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
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>

[Isolated] Query information on position limit

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code false string contract type code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "buy_limit": 1026154,
            "sell_limit": 1026154,
            "margin_mode": "isolated",
            "lever_rate": 5,
            "buy_limit_value": 50000000.000000000000000000,
            "sell_limit_value": 50000000.000000000000000000,
            "mark_price": 48725.6
        }
    ],
    "ts": 1638770954672
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Responding Generation, Unit: Millisecond
<data>
symbol true string symbol "BTC","ETH"...
contract_code true string contract type code "BTC-USDT",...
margin_mode true string margin mode isolated : "isolated"
buy_limit true decimal max qty of position on long positions, unit: piece(calculated with mark_price)
sell_limit true decimal max qty of position on short positions, unit: piece(calculated with mark_price)
lever_rate true int leverage rate
buy_limit_value true decimal upper limit on long positions, unit: usdt
sell_limit_value true decimal upper limit on short positions, unit: usdt
mark_price true decimal mark price(use this price to calculate the qty of open positions)
</data>

[Cross] Query Information On Position Limit

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
contract_type false string contract type swap, this_week, next_week, quarter, next_quarter
business_type false(more see remarks) string business type, default is swap futures, swap, all

Response

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "margin_mode": "cross",
            "buy_limit": 1021671,
            "sell_limit": 1021671,
            "business_type": "swap",
            "contract_type": "swap",
            "pair": "BTC-USDT",
            "lever_rate": 5,
            "buy_limit_value": 50000000.000000000000000000,
            "sell_limit_value": 50000000.000000000000000000,
            "mark_price": 48939.4
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211217",
            "margin_mode": "cross",
            "buy_limit": 1021865,
            "sell_limit": 1021865,
            "business_type": "futures",
            "contract_type": "next_week",
            "pair": "BTC-USDT",
            "lever_rate": 5,
            "buy_limit_value": 50000000.000000000000000000,
            "sell_limit_value": 50000000.000000000000000000,
            "mark_price": 48930.1
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211210",
            "margin_mode": "cross",
            "buy_limit": 1023478,
            "sell_limit": 1023478,
            "business_type": "futures",
            "contract_type": "this_week",
            "pair": "BTC-USDT",
            "lever_rate": 5,
            "buy_limit_value": 50000000.000000000000000000,
            "sell_limit_value": 50000000.000000000000000000,
            "mark_price": 48853
        },
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211231",
            "margin_mode": "cross",
            "buy_limit": 1021867,
            "sell_limit": 1021867,
            "business_type": "futures",
            "contract_type": "quarter",
            "pair": "BTC-USDT",
            "lever_rate": 1,
            "buy_limit_value": 50000000.000000000000000000,
            "sell_limit_value": 50000000.000000000000000000,
            "mark_price": 48930
        }
    ],
    "ts": 1638760890261
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
buy_limit true decimal max qty of position on long positions, unit: piece(calculated with mark_price)
sell_limit true decimal max qty of position on short positions, unit: piece(calculated with mark_price)
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
lever_rate true int leverage rate
buy_limit_value true decimal upper limit on long positions, unit: usdt
sell_limit_value true decimal upper limit on short positions, unit: usdt
mark_price true decimal mark price(use this price to calculate the qty of open positions)
</data>

[Isolated]Query Users' Position Limit for All Leverages

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code false string contract code, NA means all such as "BTC-USDT", "ETH-USDT"
lever_rate false int leverage rate, NA means all

Note

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "margin_mode": "isolated",
            "list": [
                {
                    "lever_rate": 2,
                    "buy_limit_value": 50000000.000000000000000000,
                    "sell_limit_value": 50000000.000000000000000000
                }
            ]
        }
    ],
    "ts": 1638769536897
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string status code "ok" , "error"
<data> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code "BTC-USDT" ...
margin_mode true string margin mode isolated
<list> true object array
lever_rate true int leverage rate
buy_limit_value true decimal upper limit on long positions, unit: usdt
sell_limit_value true decimal upper limit on short positions, unit: usdt
</list>
</data>
ts true long Time of Respond Generation，Unit：Millisecond

[Cross]Query Users' Position Limit for All Leverages

Request Parameter

Parameter Name Required Type Desc Value Range
business_type false(more to see Note) string business type, NA means all futures, swap, all
contract_type false string contract type, NA means all swap, this_week, next_week, quarter, next_quarter
pair false string pair, NA means all such as "BTC-USDT"
contract_code false string contract_code, NA means all swap: "BTC-USDT"... future: "BTC-USDT-211231"...
lever_rate false int leverage rate, NA means all

Note

Response:

{
    "status": "ok",
    "data": [
        {
            "business_type": "swap",
            "contract_type": "swap",
            "pair": "BTC-USDT",
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "margin_mode": "cross",
            "list": [
                {
                    "lever_rate": 2,
                    "buy_limit_value": 50000000.000000000000000000,
                    "sell_limit_value": 50000000.000000000000000000
                }
            ]
        },
        {
            "business_type": "futures",
            "contract_type": "next_week",
            "pair": "BTC-USDT",
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211217",
            "margin_mode": "cross",
            "list": [
                {
                    "lever_rate": 2,
                    "buy_limit_value": 50000000.000000000000000000,
                    "sell_limit_value": 50000000.000000000000000000
                }
            ]
        },
        {
            "business_type": "futures",
            "contract_type": "this_week",
            "pair": "BTC-USDT",
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211210",
            "margin_mode": "cross",
            "list": [
                {
                    "lever_rate": 2,
                    "buy_limit_value": 50000000.000000000000000000,
                    "sell_limit_value": 50000000.000000000000000000
                }
            ]
        },
        {
            "business_type": "futures",
            "contract_type": "quarter",
            "pair": "BTC-USDT",
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211231",
            "margin_mode": "cross",
            "list": [
                {
                    "lever_rate": 2,
                    "buy_limit_value": 50000000.000000000000000000,
                    "sell_limit_value": 50000000.000000000000000000
                }
            ]
        }
    ],
    "ts": 1638769370732
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string status "ok" , "error"
<data> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"... futures: "BTC-USDT-211231"...
margin_mode true string margin mode cross
business_type true string business type futures, swap
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: "BTC-USDT"
<list> true object array
lever_rate true int leverage rate
buy_limit_value true decimal upper limit on long positions, unit: usdt
sell_limit_value true decimal upper limit on short positions, unit: usdt
</list>
</data>
ts true long Time of Respond Generation，Unit：Millisecond

[General] Transfer between master and sub account

Remarks

Request Parameters

Parameter Name Required Type Desc Value Range
sub_uid true long uid of sub account
asset true string asset "USDT"...
from_margin_account true string from margin account "BTC-USDT","USDT"...
to_margin_account true string to margin account "BTC-USDT","USDT"...
amount true decimal transfer amount
type true string transfer type "master_to_sub" or "sub_to_master"
client_order_id false long Clients fill and maintain themselves. [1, 9223372036854775807]

Note：

Response:


{
    "status": "ok",
    "data": {
        "order_id": "770320047276195840"
    },
    "ts": 1603700211160
}

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
client_order_id false long the client ID that is filled in when the order is placed, if it’s not filled, it won’t be returned
</data>

[General] Query transfer records between master and sub account

Remarks

request

Parameter Name Required Type Desc Value Range
margin_account true string margin account "BTC-USDT","USDT"...
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
page_size false int 20 by default.less than or equal to 50. [1-50]

Response:


{
    "status": "ok",
    "data": {
        "total_page": 2,
        "current_page": 1,
        "total_size": 2,
        "transfer_record": [
            {
                "id": 57920,
                "transfer_type": 34,
                "amount": -10.000000000000000000,
                "ts": 1603700211125,
                "sub_uid": "12343678",
                "sub_account_name": "tom",
                "margin_account": "BTC-USDT",
                "asset": "USDT",
                "to_margin_account": "BTC-USDT",
                "from_margin_account": "BTC-USDT"
            }
        ]
    },
    "ts": 1603700414957
}

response

Parameter Name Required Type Desc Value Range
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
asset true string asset "USDT"...
margin_account true string margin account "BTC-USDT"...
from_margin_account true string from margin account "BTC-USDT"...
to_margin_account true string to margin account "BTC-USDT"...
sub_uid true string subaccount uid
sub_account_name true string subaccount name
transfer_type true int transfer type 35:transfer from subaccount; 34:transfer to subaccount;
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>

[General] Transfer between different margin accounts under the same account

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
asset true string asset "USDT"...
from_margin_account true string from margin account "BTC-USDT","USDT"...
to_margin_account true string to margin account "ETH-USDT","USDT"...
amount true decimal amount（The unit is the denominated currency of the contract.）
client_order_id false long Clients fill and maintain themselves. [1, 9223372036854775807]

Note:

response：


{
    "status": "ok",
    "data": {
        "order_id": "770321554893758464"
    },
    "ts": 1603700570600
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string response status "ok" , "error"
<data> object array
order_id true string order id
client_order_id false long 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 response millionseconds.

[General] Query user's API indicator disable information

Remarks

request body

null

Response:

attr required type desc Value Range
status true string response status "ok" , "error"
ts true long response millionseconds
<data> true array object
is_disable true int 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 int 1：triggered，0：not triggered
is_active true int 1：active，0：not active
</TDN> true dict object
</data>

Response：

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

Swap Trade Interface

[Isolated]Switch Position Mode

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
margin_account true string margin account such as: "BTC-USDT", "ETH-USDT" ...
position_mode true string position mode single_side; dual_side

response

{
    "status":"ok",
    "data":[
        {
            "margin_account":"BTC-USDT",
            "position_mode":"single_side"
        }
    ],
    "ts":1566899973811
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string status "ok" , "error"
<data> true object array
margin_account true string margin account such as: "BTC-USDT", "ETH-USDT" ...
position_mode true string position mode single_side; dual_side
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Cross]Switch Position Mode

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
margin_account true string margin account such as: "USDT"
position_mode true string position mode single_side; dual_side

response

{
    "status":"ok",
    "data":[
        {
            "margin_account":"USDT",
            "position_mode":"single_side"
        }
    ],
    "ts":1566899973811
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string status "ok" , "error"
<data> true object array
margin_account true string margin account such as: "USDT"
position_mode true string position mode single_side; dual_side
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Isolated] Place an Order

Example

Remarks

Request

{
    "contract_code": "btc-usdt",
    "direction": "buy",
    "offset":"open",
    "price":"29999",
    "lever_rate": 5,
    "volume": 1,
    "order_price_type":"opponent",
    "tp_trigger_price": 31000,
    "tp_order_price": 31000,
    "tp_order_price_type": "optimal_5",
    "sl_trigger_price": "29100",
    "sl_order_price": "29100",
    "sl_order_price_type": "optimal_5"
}

Request Parameter

Parameter Name Parameter Type Required Desc
contract_code string true Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"
reduce_only int false reduce only(in hedge mode it is invalid, and in one-way mode it's value is 0 when not filled.) 0: no, 1: yes
client_order_id long false Clients fill and maintain themselves. the value must be in [1, 9223372036854775807]
price decimal false Price
volume long true Numbers of orders (volume)
direction string true Transaction direction
offset string false(more see remarks) "open", "close", "both"
lever_rate int true Leverage rate [ if“Open”is multiple orders in 10 rate, there will be not multiple orders in 20 rate; high leverage has a high risk factor, so please use it with caution.
order_price_type string true "market": Market Order，"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
tp_trigger_price decimal false Trigger price of take-profit order
tp_order_price decimal false Order price of take-profit order（The order price is not required to fill in for Optimal N)
tp_order_price_type string false Order type of take-profit order default is market;market， limit，optimal_5，optimal_10，optimal_20
sl_trigger_price decimal false Trigger price of stop-loss order
sl_order_price decimal false Order price of stop-loss order（The order price is not required to fill in for Optimal N）
sl_order_price_type string false Order type of take-profit order default is market;market， limit，optimal_5，optimal_10，optimal_20

Note ：

"limit"，"post_only"，"ioc" and "fok" the four order price type need price value and the other don't need.

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 5,000,000 for open/close orders.

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.

Only open orders can support setting take profit and stop loss.

The take profit trigger price is a required field for setting a take profit order, and the stop loss trigger price is a required field for setting a stop loss order; if the trigger price field is not filled in, the corresponding take profit order or stop loss order will not be set.

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.

offset, in hedge mode it is a required field, and in one-way mode it is optional paramater which's value must be both when filled.

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 1 and 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": 770323133537685504,
        "client_order_id": 57012021022,
        "order_id_str": "770323133537685504"
    },
    "ts": 1603700946949
}

Returning Parameter

Parameter Name Required 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 long 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

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 json-bigint package.

[Cross] Place An Order

Remarks

Request

{
    "contract_code": "btc-usdt",
    "direction": "buy",
    "offset":"open",
    "price":"29999",
    "lever_rate": 5,
    "volume": 1,
    "order_price_type":"opponent",
    "tp_trigger_price": 31000,
    "tp_order_price": 31000,
    "tp_order_price_type": "optimal_5",
    "sl_trigger_price": "29100",
    "sl_order_price": "29100",
    "sl_order_price_type": "optimal_5"
}

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
reduce_only false int reduce only(in hedge mode it is invalid, and in one-way mode it's value is 0 when not filled.) 0: no, 1: yes
client_order_id false long Clients fill and maintain themselves. [1, 9223372036854775807]
price false decimal price
volume true long Numbers of orders (volume)
direction true string Transaction direction "buy"/"sell"
offset false(more see remarks) string "open", "close" "open","close","both"
lever_rate true int leverage [ if“Open”is multiple orders in 10 rate, there will be not multiple orders in 20 rate; high leverage has a high risk factor, so please use it with caution.
order_price_type true string type of order price "market": Market Order，"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
tp_trigger_price decimal false Trigger price of take-profit order
tp_order_price decimal false Order price of take-profit order（The order price is not required to fill in for Optimal N)
tp_order_price_type string false Order type of take-profit order default is limit; Order type of take-profit order default is market;market， limit，optimal_5，optimal_10，optimal_20
sl_trigger_price decimal false Trigger price of stop-loss order
sl_order_price decimal false Order price of stop-loss order（The order price is not required to fill in for Optimal N）
sl_order_price_type string false Order type of stop-loss order default is limit; Order type of take-profit order default is market;market， limit，optimal_5，optimal_10，optimal_20

Note

"limit"，"post_only"，"ioc" and "fok" the four order price type need price value and the other don't need.

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 5,000,000 for open/close orders.

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.

Only open orders can support setting take profit and stop loss.

The take profit trigger price is a required field for setting a take profit order, and the stop loss trigger price is a required field for setting a stop loss order; if the trigger price field is not filled in, the corresponding take profit order or stop loss order will not be set.

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.

offset, in hedge mode it is a required field, and in one-way mode it is optional paramater which's value must be both when filled.

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 1 and 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": 784017187857760256,
        "order_id_str": "784017187857760256"
    },
    "ts": 1606965863952
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object
order_id true long order ID
order_id_str true string order ID
client_order_id false long 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

[Isolated] Place a Batch of Orders

Example

Remarks

Request

{
    "orders_data": [
        {
            "contract_code": "btc-usdt",
            "direction": "sell",
            "offset": "open",
            "price": "29999",
            "lever_rate": 5,
            "volume": 1,
            "order_price_type": "opponent",
            "tp_trigger_price": 27000,
            "tp_order_price": 27000,
            "tp_order_price_type": "optimal_5",
            "sl_trigger_price": "30100",
            "sl_order_price": "30100",
            "sl_order_price_type": "optimal_5"
        },
        {
            "contract_code": "btc-usdt",
            "direction": "buy",
            "offset": "open",
            "price": "29999",
            "lever_rate": 5,
            "volume": 1,
            "order_price_type": "post_only",
            "tp_trigger_price": 31000,
            "tp_order_price": 31000,
            "tp_order_price_type": "optimal_5",
            "sl_trigger_price": "29100",
            "sl_order_price": "29100",
            "sl_order_price_type": "optimal_5"
        }
    ]
}

Request Parameter

Parameter Name Parameter Type Required Desc
orders_data List<Object> 10 orders at most.
Parameter Name Parameter Type Required Desc
contract_code string true Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"
reduce_only int false reduce only(in hedge mode it is invalid, and in one-way mode it's value is 0 when not filled.) 0: no, 1: yes
client_order_id long false Clients fill and maintain themselves. the value must be in [1, 9223372036854775807]
price decimal false Price
volume long true Numbers of orders (volume)
direction string true Transaction direction
offset string false(more see remarks) "open", "close", "both"
lever_rate int true Leverage rate [ if“Open”is multiple orders in 10 rate, there will be not multiple orders in 20 rate; high leverage has a high risk factor, so please use it with caution.
order_price_type string true "market": Market Order，"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
tp_trigger_price decimal false Trigger price of take-profit order
tp_order_price decimal false Order price of take-profit order（The order price is not required to fill in for Optimal N)
tp_order_price_type string false Order type of take-profit order default is market;market， limit，optimal_5，optimal_10，optimal_20
sl_trigger_price decimal false Trigger price of stop-loss order
sl_order_price decimal false Order price of stop-loss order（The order price is not required to fill in for Optimal N）
sl_order_price_type string false Order type of take-profit order default is market;market， limit，optimal_5，optimal_10，optimal_20

Note ：

"limit"，"post_only"，"ioc" and "fok" the four order price type need price value and the other don't need.

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.

Only open orders can support setting take profit and stop loss.

The take profit trigger price is a required field for setting a take profit order, and the stop loss trigger price is a required field for setting a stop loss order; if the trigger price field is not filled in, the corresponding take profit order or stop loss order will not be set.

No need to transfer BBO order price(ask 1 and 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.

offset, in hedge mode it is a required field, and in one-way mode it is optional paramater which's value must be both when filled.

10 orders at most

Response:


{
    "status": "ok",
    "data": {
        "errors": [
            {
                "index": 2,
                "err_code": 1050,
                "err_msg": "Customers order number is repeated. Please try again later."
            }
        ],
        "success": [
            {
                "order_id": 770323847022211072,
                "client_order_id": 57012021024,
                "index": 1,
                "order_id_str": "770323847022211072"
            }
        ]
    },
    "ts": 1603701117058
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<data> object
<errors> array
index true int order Index
err_code true int Error code
err_msg true string Error information
</errors>
<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
</success>
</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 json-bigint package.

[Cross] Place A Batch Of Orders

Remarks

Request

{
    "orders_data": [
        {
            "contract_code": "btc-usdt",
            "direction": "sell",
            "offset": "open",
            "price": "29999",
            "lever_rate": 5,
            "volume": 1,
            "order_price_type": "opponent",
            "tp_trigger_price": 27000,
            "tp_order_price": 27000,
            "tp_order_price_type": "optimal_5",
            "sl_trigger_price": "30100",
            "sl_order_price": "30100",
            "sl_order_price_type": "optimal_5"
        },
        {
            "contract_code": "btc-usdt",
            "direction": "buy",
            "offset": "open",
            "price": "29999",
            "lever_rate": 5,
            "volume": 1,
            "order_price_type": "post_only",
            "tp_trigger_price": 31000,
            "tp_order_price": 31000,
            "tp_order_price_type": "optimal_5",
            "sl_trigger_price": "29100",
            "sl_order_price": "29100",
            "sl_order_price_type": "optimal_5"
        }
    ]
}

Request Parameter

Parameter Name Required Type Desc Data Value
<orders_data> true object array
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
reduce_only false int reduce only(in hedge mode it is invalid, and in one-way mode it's value is 0 when not filled.) 0: no, 1: yes
client_order_id false long Clients fill and maintain themselves. [1, 9223372036854775807]
price false decimal price
volume true long Numbers of orders (volume)
direction true string Transaction direction "buy"/"sell"
offset false(more see remarks) string offset "open","close","both"
lever_rate true int leverage [ if“Open”is multiple orders in 10 rate, there will be not multiple orders in 20 rate; high leverage has a high risk factor, so please use it with caution.
order_price_type true string type of order price "market": Market Order，"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
tp_trigger_price false decimal Trigger price of take-profit order
tp_order_price false decimal Order price of take-profit order（The order price is not required to fill in for Optimal N)
tp_order_price_type false string Order type of take-profit order default is limit; Order type of take-profit order default is market;market， limit，optimal_5，optimal_10，optimal_20
sl_trigger_price false decimal Trigger price of stop-loss order
sl_order_price false decimal Order price of stop-loss order（The order price is not required to fill in for Optimal N）
sl_order_price_type false string Order type of stop-loss order default is limit; Order type of take-profit order default is market;market， limit，optimal_5，optimal_10，optimal_20
</orders_data>

Note

"limit"，"post_only"，"ioc" and "fok" the four order price type need price value and the other don't need.

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.

Only open orders can support setting take profit and stop loss.

The take profit trigger price is a required field for setting a take profit order, and the stop loss trigger price is a required field for setting a stop loss order; if the trigger price field is not filled in, the corresponding take profit order or stop loss order will not be set.

No need to transfer BBO order price(ask 1 and 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.

offset, in hedge mode it is a required field, and in one-way mode it is optional paramater which's value must be both when filled.

25 orders at most

Response:

{
    "status": "ok",
    "data": {
        "errors": [
            {
                "index": 2,
                "err_code": 1045,
                "err_msg": "Unable to switch leverage due to open orders."
            }
        ],
        "success": [
            {
                "order_id": 784022175422087168,
                "index": 1,
                "order_id_str": "784022175422087168"
            }
        ]
    },
    "ts": 1606967053089
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object
<errors> true object array
index true int order index
err_code true int error code
err_msg true string error message
</errors>
<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
</success>
</data>
ts true long Time of Respond Generation, Unit: Millisecond

Note

[Isolated] Cancel an Order

Example

Remarks

Request Parameter

Parameter Name Required Type Desc
order_id false(more detail see the note) string Order ID（different IDs are separated by ",", maximum 10 orders can be withdrew at one time）
client_order_id false(more detail see the note) string Client order ID (different IDs are separated by ",", maximum 10 orders can be withdrew at one time)
contract_code true string Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"

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.

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

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


{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "770323133537685504",
                "err_code": 1071,
                "err_msg": "Repeated withdraw."
            }
        ],
        "successes": "770323847022211072"
    },
    "ts": 1603701351602
}

Returning Parameter

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

[Cross] Cancel An Order

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
order_id false(more see remarks) string order ID（different IDs are separated by ",", maximum 10 orders can be withdrew at one time）
client_order_id false(more see remarks) string Client order ID (different IDs are separated by ",", maximum 10 orders can be withdrew at one time)
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter

Note:

Response


{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "784054331179532288",
                "err_code": 1062,
                "err_msg": "Cancelling. Please be patient."
            }
        ],
        "successes": "784054331179532288"
    },
    "ts": 1606974744952
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object
<errors> true array
order_id true string order ID
err_code true int error code
err_msg true string error message
</errors>
successes true string successfully withdrew list of order_id or client_order_id
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Isolated] Cancel All Orders

Example

Remarks

Request Parameter

Parameter Name Required Type Desc
contract_code true string Case-Insenstive.Both uppercase and lowercase are supported..e.g. "BTC-USDT"
direction false string Transaction direction(if not filled in means all) ["buy" , "sell"]
offset false string offset direction（if not filled in means all） ["open" , "close"]

Note:

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


{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "768883002062282752,770325103371542528,770325103388319744"
    },
    "ts": 1603701437838
}

Returning Parameter

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

[Cross] Cancel All Orders

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
direction false string Transaction direction(if not filled in means all) ["buy" , "sell"]
offset false string offset direction（if not filled in means all） ["open" , "close"]

Note:

Response


{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "784055473531781120,784055473842159616"
    },
    "ts": 1606974998510
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object
<errors> true array
order_id true string order ID
err_code true int error code
err_msg true string error message
</errors>
successes true string the list order which's successful
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Isolated] Switch Leverage

Note

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code true string contract code "BTC-USDT"...
lever_rate true int The leverage multiple to be switched; high leverage has a high risk factor, so please use it with caution.

Response:


OK：
{
    "status": "ok",
    "data": {
        "contract_code": "btc-usdt",
        "margin_mode": "isolated",
        "lever_rate": 10
    },
    "ts": 1603699417036
}
No：
{
    "status": "error",
    "err_code": 1045,
    "err_msg": "Unable to switch leverage due to current holdings or open orders.",
    "ts": 1603701654205
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string status: ok,error
<data> false object
contract_code false string contract code "BTC-USDT"...
margin_mode false string margin mode isolated : "isolated"
lever_rate false int Switched leverage
</data>
err_code false int error code
err_msg false string error msg
ts true long Timestamp

[Cross] Switch Leverage

Note

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false(more detail see the note) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more detail see the note) string pair BTC-USDT
contract_type false(more detail see the note) string contract type swap, this_week, next_week, quarter, next_quarter
lever_rate true int The leverage multiple to be switched; high leverage has a high risk factor, so please use it with caution.

Response


{
    "status": "ok",
    "data": {
        "contract_type": "swap",
        "pair": "BTC-USDT",
        "business_type": "swap",
        "contract_code": "BTC-USDT",
        "lever_rate": 2,
        "margin_mode": "cross"
    },
    "ts": 1639099382678
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string ok/error
<data> false object
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode false string margin mode cross: cross margin mode
lever_rate false int switched leverage
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</data>
err-code false int error code
err-msg false string error message
ts true long timestamp

[Isolated] Place Lightning Close Order

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code true string Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"
volume true long Order Quantity(Cont)
direction true string “buy”:Open，“sell”:Close
client_order_id false long Client needs to provide unique API and have to maintain the API themselves afterwards. [1, 9223372036854775807]
order_price_type false string "lightning" by default. "lightning_fok": lightning FOK type,"lightning_ioc": lightning IOC type "market" by default."market": market Order type," "lightning_fok": lightning FOK type,"lightning_ioc": lightning IOC type

Note:

Response:


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

Returning Parameter

Parameter Name Required 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: Millisecond
<data> Dictionary
order_id true long 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": 1603704587846
}

[Cross] Place Lightning Close Position

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false(more detail see the note) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more detail see the note) string pair BTC-USDT
contract_type false(more detail see the note) string contract type swap, this_week, next_week, quarter, next_quarter
volume true decimal place volume
direction true string direction “buy”/“sell”
client_order_id false long client order ID [1, 9223372036854775807]
order_price_type false string type of order price "market" by default."market": market Order type," "lightning_fok": lightning FOK type,"lightning_ioc": lightning IOC type

Note

Response


{
    "status": "ok",
    "data": {
        "order_id": 784063527799226368,
        "order_id_str": "784063527799226368"
    },
    "ts": 1606976912267
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok"/"error"
ts true long Time of Respond Generation, Unit: Millisecond
<data> true object
order_id true long order ID
order_id_str true string order ID
client_order_id false int client order ID
</data>

[Isolated] Get Information of an Order

Remarks

Request Parameter

Parameter Name Required Type Desc
order_id false(Please see the notes) string Order ID（different IDs are separated by ",", maximum 50 orders can be withdrew at one time）
client_order_id false(Please see the notes) string Client order ID Order ID（different IDs are separated by ",", maximum 50 orders can be withdrew at one time)
contract_code true string Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"

Note ：

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

At least one of order_id and client_order_id must be filled in

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 of funding rate on 00:00(GMT+8), 08:00(GMT+8) and 16:00(GMT+8).

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

Response:


{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT",
            "volume": 1,
            "price": 13059.8,
            "order_price_type": "opponent",
            "order_type": 1,
            "direction": "sell",
            "offset": "open",
            "lever_rate": 10,
            "order_id": 770334322963152896,
            "client_order_id": 57012021045,
            "created_at": 1603703614712,
            "trade_volume": 1,
            "trade_turnover": 13.059800000000000000,
            "fee": -0.005223920000000000,
            "trade_avg_price": 13059.800000000000000000,
            "margin_frozen": 0,
            "profit": 0,
            "status": 6,
            "order_source": "api",
            "order_id_str": "770334322963152896",
            "fee_asset": "USDT",
            "liquidation_type": "0",
            "canceled_at": 0,
            "margin_asset": "USDT",
            "margin_mode": "isolated",
            "margin_account": "BTC-USDT",
            "is_tpsl": 0,
            "real_profit": 0,
            "reduce_only": 0
        }
    ],
    "ts": 1603703631815
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<data>
symbol true string symbol eg."BTC"
contract_code true string Contract Code "BTC-USDT" ...
volume true decimal Numbers of order
price true decimal Price committed
order_price_type true string order price type "market": Market Order，"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
order_type true int Order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
direction true string Transaction direction "buy":"sell"
offset true string "open": "close" "open", "close", "both"
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 Creation time
canceled_at true long Canceled time
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction aggregate amount
fee true decimal Service fee
trade_avg_price true decimal Transaction average price
margin_frozen true decimal Frozen margin
margin_asset true string margin asset
profit true decimal profit when close position (calculated with the average price of position, exclude profit in history settlement.)
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、tpsl）
fee_asset true string the corresponding cryptocurrency to the given fee "USDT"...
liquidation_type true string Liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
real_profit true decimal real profit (calculated with the opening average price, include profit in history settlement.)
reduce_only true int reduce only 0: no, 1: yes
</data>
ts true long Timestamp

Note:

[Cross] Get Information of order

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
order_id false(more detail see the note) string order ID（different IDs are separated by ",", maximum 50 orders can be withdrew at one time）
client_order_id false(more detail see the note) string client order ID Order ID（different IDs are separated by ",", maximum 50 orders can be withdrew at one time)
contract_code false(more detail see the note) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more detail see the note) string pair BTC-USDT

Note：

Response

{
    "status": "ok",
    "data": [
        {
            "business_type": "futures",
            "contract_type": "quarter",
            "pair": "BTC-USDT",
            "symbol": "BTC",
            "contract_code": "BTC-USDT-211231",
            "volume": 1.000000000000000000,
            "price": 66000.000000000000000000,
            "order_price_type": "post_only",
            "order_type": 1,
            "direction": "sell",
            "offset": "open",
            "lever_rate": 1,
            "order_id": 917361800293453824,
            "client_order_id": null,
            "created_at": 1638757696945,
            "trade_volume": 0E-18,
            "trade_turnover": 0E-18,
            "fee": 0E-18,
            "trade_avg_price": null,
            "margin_frozen": 66.000000000000000000,
            "profit": 0E-18,
            "status": 3,
            "order_source": "api",
            "order_id_str": "917361800293453824",
            "fee_asset": "USDT",
            "liquidation_type": "0",
            "canceled_at": 0,
            "margin_asset": "USDT",
            "margin_account": "USDT",
            "margin_mode": "cross",
            "is_tpsl": 0,
            "real_profit": 0,
            "reduce_only": 0
        }
    ],
    "ts": 1639099755552
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object array
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
volume true decimal place volume
price true decimal place price
order_price_type true string type of order price "market": Market Order，"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
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
lever_rate true int leverage
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 created time
trade_volume true decimal trade quantity
trade_turnover true decimal trade amount
fee true decimal service fee
trade_avg_price true decimal trade average price
margin_asset true string margin asset
margin_frozen true decimal frozen margin
profit true decimal profit when close position (calculated with the average price of position, exclude profit in history settlement.)
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
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
fee_asset true string fee asset （"USDT"...）
liquidation_type true string 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
canceled_at true long canceled time
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
real_profit true decimal real profit (calculated with the opening average price, include profit in history settlement.)
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</data>
ts true long timestamp

Note:

[Isolated] Order details acquisition

Remarks

Request Parameter

Parameter Name Required Type Desc
contract_code true string Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"
order_id true long Order ID
created_at false long Timestamp
order_type false int Order type: 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order; 22. ADL reduction-only 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 6-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 jaso-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.

Please note that created_at can't be "0"

Response:


{
    "status": "ok",
    "data": {
        "symbol": "BTC",
        "contract_code": "BTC-USDT",
        "instrument_price": 0,
        "final_interest": 0,
        "adjust_value": 0,
        "lever_rate": 10,
        "direction": "sell",
        "offset": "open",
        "volume": 1.000000000000000000,
        "price": 13059.800000000000000000,
        "created_at": 1603703614712,
        "canceled_at": 0,
        "order_source": "api",
        "order_price_type": "opponent",
        "margin_frozen": 0,
        "profit": 0,
        "trades": [
            {
                "trade_id": 131560927,
                "trade_price": 13059.800000000000000000,
                "trade_volume": 1.000000000000000000,
                "trade_turnover": 13.059800000000000000,
                "trade_fee": -0.005223920000000000,
                "created_at": 1603703614715,
                "role": "taker",
                "fee_asset": "USDT",
                "profit": 0,
                "real_profit": 0,
                "id": "131560927-770334322963152896-1"
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1,
        "liquidation_type": "0",
        "fee_asset": "USDT",
        "fee": -0.005223920000000000,
        "order_id": 770334322963152896,
        "order_id_str": "770334322963152896",
        "client_order_id": 57012021045,
        "order_type": "1",
        "status": 6,
        "trade_avg_price": 13059.800000000000000000,
        "trade_turnover": 13.059800000000000000,
        "trade_volume": 1.000000000000000000,
        "margin_asset": "USDT",
        "margin_mode": "isolated",
        "margin_account": "BTC-USDT",
        "real_profit": 0,
        "is_tpsl": 0,
        "reduce_only": 0
    },
    "ts": 1603703678477
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result "ok" , "error"
<data>
symbol true string Variety code
contract_code true string Contract Code "BTC-USDT" ...
lever_rate true int Leverage Rate 1\5\10\20
direction true string Transaction direction "buy", "sell"
offset true string "open": "close" "open", "close", "both"
volume true decimal Number of Order
price true decimal Price committed
created_at true long Creation time
canceled_at true long Canceled time
order_source true string Order Source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true string order price type "market": Market Order，"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 Frozen margin
margin_asset true string margin asset
profit true decimal total profit or loss of order when close position (calculated with the average price of position, exclude profit in history settlement.)
order_id true long Order ID
order_id_str true string Order ID
client_order_id true long Client order ID
order_type true string order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order ; 22. ADL reduction-only order
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.
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction aggregate amount
trade_avg_price true decimal Transaction average price
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 "USDT"...
fee true decimal total amount of fees
liquidation_type true string Liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
real_profit true decimal total real profit of order (calculated with the opening average price, include profit in history settlement.)
reduce_only true int reduce only 0: no, 1: yes
<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 linear-swap-api/v1/swap_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
profit true decimal profit or loss of the transaction (calculated with the average price of position, exclude profit in history settlement.)
real_profit true decimal real profit of the transaction (calculated with the opening average price, include profit in history settlement.)
</trades>
</data >
ts true long Timestamp

Note:

[Cross] Get Detail Information of order

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false(more detail see the note) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more detail see the note) string pair BTC-USDT
order_id true long order ID
created_at false long created timestamp
order_type false int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order; 5. ADL reduction-only 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 6-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 jaso-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.

Please note that created_at can't be "0"

Response

{
    "status": "ok",
    "data": {
        "contract_type": "this_week",
        "pair": "BTC-USDT",
        "business_type": "futures",
        "symbol": "BTC",
        "contract_code": "BTC-USDT-211210",
        "instrument_price": 0,
        "final_interest": 0,
        "adjust_value": 0,
        "lever_rate": 5,
        "direction": "buy",
        "offset": "open",
        "volume": 100.000000000000000000,
        "price": 48555.600000000000000000,
        "created_at": 1639100651569,
        "canceled_at": 0,
        "order_source": "api",
        "order_price_type": "opponent",
        "margin_frozen": 0E-18,
        "profit": 0E-18,
        "trades": [
            {
                "trade_id": 2902136,
                "trade_price": 48555.600000000000000000,
                "trade_volume": 100.000000000000000000,
                "trade_turnover": 4855.560000000000000000,
                "trade_fee": -2.427780000000000000,
                "created_at": 1639100651577,
                "role": "taker",
                "fee_asset": "USDT",
                "real_profit": 0E-18,
                "profit": 0E-18,
                "id": "2902136-918800256249405440-1"
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1,
        "liquidation_type": "0",
        "fee_asset": "USDT",
        "fee": -2.427780000000000000,
        "order_id": 918800256249405440,
        "order_id_str": "918800256249405440",
        "client_order_id": null,
        "order_type": "1",
        "status": 6,
        "trade_avg_price": 48555.600000000000000000,
        "trade_turnover": 4855.560000000000000000,
        "trade_volume": 100.000000000000000000,
        "margin_asset": "USDT",
        "margin_account": "USDT",
        "margin_mode": "cross",
        "is_tpsl": 0,
        "real_profit": 0,
        "reduce_only": 0
    },
    "ts": 1639100665681
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
lever_rate true int leverage
direction true string direction "buy","sell"
offset true string offset "open", "close", "both"
volume true decimal place volume
price true decimal place price
created_at true long created time
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true string type of order price "market": Market Order，"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_asset true string margin asset
margin_frozen true decimal frozen margin
profit true decimal total profit or loss of order when close position (calculated with the average price of position, exclude profit in history settlement.)
instrument_price true decimal liquidation price
final_interest true decimal account balance after liquidation
adjust_value true decimal adjustment factor of liquidating order
fee true decimal total fee
fee_asset true string fee asset （"USDT"...）
liquidation_type true string liquidation type
canceled_at true long canceled time
order_id true long order ID
order_id_str true string order ID
client_order_id true long client order ID
order_type true string order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order ; 22. ADL reduction-only order
status true int order 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.
trade_avg_price true decimal trade average price
trade_turnover true decimal trade total amount
trade_volume true decimal trade total amount
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
total_page true int total page
current_page true int current page
total_size true int total size
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
real_profit true decimal total real profit of order (calculated with the opening average price, include profit in history settlement.)
reduce_only true int reduce only 0: no, 1: yes
<trades> true object array
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 linear-swap-api/v1/swap_cross_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 trade price
trade_volume true decimal trade volume
trade_turnover true decimal trade amount
trade_fee true decimal trade fee
role true string taker/maker
created_at true long created time
profit true decimal profit or loss of the transaction (calculated with the average price of position, exclude profit in history settlement.)
real_profit true decimal real profit of the transaction (calculated with the opening average price, include profit in history settlement.)
</trades>
</data>
ts true long timestamp

Note:

[Isolated] Current unfilled order acquisition

Remarks

Request Parameter

Parameter Name Required Type Desc Default Value Range
contract_code true string Contract Code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT"
page_index false int Page, default 1st page 1
page_size false int Default 20，no more than 50 20
sort_by false string sort fields(descending) created_at “created_at”descending order by order created at, "update_time": descending order by order update time
trade_type false int trade type(Default:all) 0 0:all,1: buy long,2: sell short,3: buy short,4: sell long , 17:buy(one-way mode), 18:sell(one-way mode)

Response:


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "volume": 1,
                "price": 13329,
                "order_price_type": "limit",
                "order_type": 1,
                "direction": "sell",
                "offset": "open",
                "lever_rate": 10,
                "order_id": 770326042832437248,
                "client_order_id": 57012021028,
                "created_at": 1603701640576,
                "trade_volume": 0,
                "trade_turnover": 0,
                "fee": 0,
                "trade_avg_price": null,
                "margin_frozen": 1.332900000000000000,
                "profit": 0,
                "status": 3,
                "order_source": "api",
                "order_id_str": "770326042832437248",
                "fee_asset": "USDT",
                "liquidation_type": null,
                "canceled_at": null,
                "margin_asset": "USDT",
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "is_tpsl": 0,
                "update_time": 1606975980467,
                "real_profit": 0,
                "reduce_only": 0
            }
        ],
        "total_page": 2,
        "current_page": 1,
        "total_size": 2
    },
    "ts": 1603703993952
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result
<data> object
<orders> array
symbol true string Variety code
contract_code true string Contract Code "BTC-USDT" ...
volume true decimal Number of Order
price true decimal Price committed
order_price_type true string type of order price "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
order_type true int Order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
direction true string Transaction direction "buy","sell"
offset true string "open": "close" "open", "close", "both"
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 Service fee
trade_avg_price true decimal Transaction average price
margin_frozen true decimal Frozen margin
margin_asset true string margin asset
profit true decimal profit when close position (calculated with the average price of position, exclude profit in history settlement.)
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;
order_source true string Order Source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
fee_asset true string the corresponding cryptocurrency to the given fee "USDT"...
liquidation_type true string liquidation type
canceled_at true long order Cancellation time
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
real_profit true decimal real profit (calculated with the opening average price, include profit in history settlement.)
update_time true Long order update time ，millesecond timestamp
reduce_only true int reduce only 0: no, 1: yes
</orders>
total_page true int Total Pages
current_page true int Current Page
total_size true int Total Size
</data>
ts true long Timestamp

Note:

[Cross] Current unfilled order acquisition

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
page_index false int page index, default 1st page
page_size false int page size, default 20，no more than 50
sort_by false string sort fields(Default: “created_at” descending order) “created_at”: descending order by order created at, "update_time": descending order by order update time
trade_type false int trade type(Default:all) 0:all,1: buy long,2: sell short,3: buy short,4: sell long , 17.buy(one-way mode), 18.sell(one-way mode)

Response

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "update_time": 1639104153425,
                "business_type": "swap",
                "contract_type": "swap",
                "pair": "BTC-USDT",
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "volume": 1,
                "price": 66000,
                "order_price_type": "post_only",
                "order_type": 1,
                "direction": "sell",
                "offset": "open",
                "lever_rate": 5,
                "order_id": 918814943964184578,
                "client_order_id": null,
                "created_at": 1639104153393,
                "trade_volume": 0,
                "trade_turnover": 0,
                "fee": 0,
                "trade_avg_price": null,
                "margin_frozen": 13.200000000000000000,
                "profit": 0,
                "status": 3,
                "order_source": "api",
                "order_id_str": "918814943964184578",
                "fee_asset": "USDT",
                "liquidation_type": null,
                "canceled_at": null,
                "margin_asset": "USDT",
                "margin_account": "USDT",
                "margin_mode": "cross",
                "is_tpsl": 0,
                "real_profit": 0,
                "reduce_only": 0
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1639104160523
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result
<data> true object
<orders> true object
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
volume true decimal place volume
price true decimal place price
order_price_type true string type of order price "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
order_type true int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
direction true string "buy"/"sell" "buy","sell"
offset true string "open"/"close" "open","close","both"
lever_rate true int leverage
order_id true long order ID
order_id_str true string order ID
client_order_id true long client order ID
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
created_at true long created time
trade_volume true decimal trade total volume
trade_turnover true decimal trade total amount
fee true decimal service fee
fee_asset true string fee asset （"USDT"...）
trade_avg_price true decimal trade average price
margin_asset true string margin asset
margin_frozen true decimal frozen margin
profit true decimal profit when close position (calculated with the average price of position, exclude profit in history settlement.)
status true int order status 3. Have sumbmitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled
liquidation_type true string liquidation type
canceled_at true long canceled time
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
real_profit true decimal real profit (calculated with the opening average price, include profit in history settlement.)
update_time true Long order update time ，millesecond timestamp
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</orders>
total_page true int total page
current_page true int current page
total_size true int total size
</data>
ts true long timestamp

Note:

[Isolated] Get History Orders(New)

Remarks

Request:


    {
        "contract": "BTC-USDT",
        "trade_type": 0,
        "status": 0,
        "type": 1,
        "start_time": 1660119810000,
        "end_time": 1660274746031,
        "direct": "next",
        "from_id": 1110
    }

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions, 17:buy(one-way mode), 18:sell(one-way mode)
start_time false long Query start time, query by data creation time Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with
type true int Type 1:All Orders,2:Order in Finished Status
status true string 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;

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 13580806498,
                "order_id": 770336866451992600,
                "contract_code": "BTC-USDT",
                "symbol": "BTC",
                "lever_rate": 10,
                "direction": "sell",
                "offset": "close",
                "volume": 1,
                "price": 13100,
                "create_date": 1603704221118,
                "update_time": 1603704221118,
                "order_source": "web",
                "order_price_type": 6,
                "order_type": 1,
                "margin_frozen": 0,
                "profit": 0,
                "trade_volume": 0,
                "trade_turnover": 0,
                "fee": 0,
                "trade_avg_price": 0,
                "status": 3,
                "order_id_str": "770336866451992576",
                "fee_asset": "USDT",
                "liquidation_type": "0",
                "margin_asset": "USDT",
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "is_tpsl": 0,
                "real_profit": 0,
                "reduce_only": 0
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> 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 in string
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode isolated: isolated
margin_account true string margin account such as:BTC-USDT”
lever_rate true int lever rate
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
volume true decimal volume
price true decimal price
create_date true long create date
update_time true long order update time，millesecond timestamp
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true string order price type "market": Market Order，"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_asset true string margin asset
margin_frozen true decimal margin frozen
profit true decimal profit
real_profit true decimal real profit
trade_volume true decimal trade volume
trade_turnover true decimal trade turnover
fee true decimal fee
trade_avg_price true decimal trade avg 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; 10.Orders failed. 11. Orders cancelling.
order_type true int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
fee_asset true string fee asset （"USDT"...）
liquidation_type true string liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
is_tpsl true int is tpsl 1: yes; 0:no
reduce_only true int reduce only 0: no, 1: yes
</data>

[Cross] Get History Orders(New)

Remarks

Request:


    {
        "contract": "BTC-USDT",
        "trade_type": 0,
        "pair": "BTC-USDT",
        "status": 0,
        "type": 1,
        "start_time": 1660119810000,
        "end_time": 1660274746031,
        "direct": "next",
        "from_id": 1110
    }

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions, 17:buy(one-way mode), 18:sell(one-way mode)
start_time false long Query start time, query by data creation time Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with
type true int Type 1:All Orders,2:Order in Finished Status
status true string 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;

Note

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 13580806498,
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures",
                "order_id": 918800256249405440,
                "contract_code": "BTC-USDT-211210",
                "symbol": "BTC",
                "lever_rate": 5,
                "direction": "buy",
                "offset": "open",
                "volume": 100.000000000000000000,
                "price": 48555.600000000000000000,
                "create_date": 1639100651569,
                "order_source": "api",
                "order_price_type": 3,
                "order_type": 1,
                "margin_frozen": 0E-18,
                "profit": 0E-18,
                "trade_volume": 100.000000000000000000,
                "trade_turnover": 4855.560000000000000000,
                "fee": -2.427780000000000000,
                "trade_avg_price": 48555.6000,
                "status": 6,
                "order_id_str": "918800256249405440",
                "fee_asset": "USDT",
                "liquidation_type": "0",
                "margin_asset": "USDT",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "update_time": 1639100651000,
                "is_tpsl": 0,
                "real_profit": 0,
                "reduce_only": 0
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> 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 in string
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross；
margin_account true string margin account "USDT"...
lever_rate true int lever rate
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
volume true decimal volume
price true decimal price
create_date true long create date
update_time true long order update time，millesecond timestamp
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true string order price type "market": Market Order，"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_asset true string margin asset
margin_frozen true decimal margin frozen
profit true decimal profit
real_profit true decimal real profit
trade_volume true decimal trade volume
trade_turnover true decimal trade turnover
fee true decimal fee
trade_avg_price true decimal trade avg 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; 10.Orders failed. 11. Orders cancelling.
order_type true int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
fee_asset true string fee asset （"USDT"...）
liquidation_type true string liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
is_tpsl true int is tpsl 1: yes; 0:no
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</data>

[Isolated] Get History Orders via Multiple Fields(New)

Remarks

Request:


    {
        "contract": "BTC-USDT",
        "trade_type": 0,
        "status": 0,
        "type": 1,
        "price_type": "opponent",
        "start_time": 1660119810000,
        "end_time": 1660274746031,
        "direct": "next",
        "from_id": 1110
    }

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions, 17:buy(one-way mode), 18:sell(one-way mode)
start_time false long Query start time, query by data creation time Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with
type true int Type 1:All Orders,2:Order in Finished Status
status true string 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;
price_type false string order price type order price type, "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 order_price_type

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 13580806498,
                "order_id": 807038270541733888,
                "contract_code": "BTC-USDT",
                "symbol": "BTC",
                "lever_rate": 10,
                "direction": "buy",
                "offset": "close",
                "volume": 9,
                "price": 36580,
                "create_date": 1612454517740,
                "order_source": "android",
                "order_price_type": "opponent",
                "order_type": 1,
                "margin_frozen": 0,
                "profit": 0.3636,
                "trade_volume": 9,
                "trade_turnover": 329.22,
                "fee": -0.131688,
                "trade_avg_price": 36580,
                "status": 6,
                "order_id_str": "807038270541733888",
                "fee_asset": "BTC-USDT",
                "liquidation_type": "0",
                "is_tpsl": 0,
                "real_profit": 0.2394,
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "reduce_only": 0
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> 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 in string
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode isolated: isolated
margin_account true string margin account such as:BTC-USDT”
lever_rate true int lever rate
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
volume true decimal volume
price true decimal price
create_date true long create date
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true string order price type "market": Market Order，"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 margin frozen
profit true decimal profit
real_profit true decimal real profit
trade_volume true decimal trade volume
trade_turnover true decimal trade turnover
fee true decimal fee
trade_avg_price true decimal trade avg 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; 10.Orders failed. 11. Orders cancelling.
order_type true int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
fee_asset true string fee asset （"USDT"...）
liquidation_type true string liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
is_tpsl true int is tpsl 1: yes; 0:no
reduce_only true int reduce only 0: no, 1: yes
</data>

[Cross]Get History Orders via Multiple Fields(New)

Remarks

Request:


    {
        "contract": "BTC-USDT",
        "trade_type": 0,
        "pair": "BTC-USDT",
        "status": 0,
        "type": 1,
        "price_type": "opponent",
        "start_time": 1660119810000,
        "end_time": 1660274746031,
        "direct": "next",
        "from_id": 1110
    }

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions, 17:buy(one-way mode), 18:sell(one-way mode)
start_time false long Query start time, query by data creation time Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with
type true int Type 1:All Orders,2:Order in Finished Status
status true string 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;
price_type false string order price type order price type, "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 order_price_type

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 452057,
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures",
                "query_id": 136966,
                "match_id": 2902136,
                "order_id": 918800256249405440,
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "direction": "buy",
                "offset": "open",
                "trade_volume": 100.000000000000000000,
                "trade_price": 48555.600000000000000000,
                "trade_turnover": 4855.560000000000000000,
                "trade_fee": -2.427780000000000000,
                "offset_profitloss": 0E-18,
                "create_date": 1639100651577,
                "role": "Taker",
                "order_source": "api",
                "order_id_str": "918800256249405440",
                "id": "2902136-918800256249405440-1",
                "fee_asset": "USDT",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "real_profit": 0E-18,
                "reduce_only": 0
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> 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 in string
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross；
lever_rate true int lever rate
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
volume true decimal volume
price true decimal price
create_date true long create date
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true string order price type "market": Market Order，"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 margin frozen
profit true decimal profit
real_profit true decimal real profit
trade_volume true decimal trade volume
trade_turnover true decimal trade turnover
fee true decimal fee
trade_avg_price true decimal trade avg 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; 10.Orders failed. 11. Orders cancelling.
order_type true int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
fee_asset true string fee asset （"USDT"...）
liquidation_type true string liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
is_tpsl true int is tpsl 1: yes; 0:no
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</data>

[Isolated] Acquire History Match Results(New)

Remarks

Request:


    {
        "contract": "BTC-USDT",
        "trade_type": 0,
        "pair": "BTC-USDT",
        "start_time": 1660119810000,
        "end_time": 1660274746031,
        "direct": "next",
        "from_id": 1110
    }

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions, 17:buy(one-way mode), 18:sell(one-way mode)
start_time false long Query start time, query by data creation time Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 452057,
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures",
                "query_id": 136966,
                "match_id": 2902136,
                "order_id": 918800256249405440,
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "direction": "buy",
                "offset": "open",
                "trade_volume": 100.000000000000000000,
                "trade_price": 48555.600000000000000000,
                "trade_turnover": 4855.560000000000000000,
                "trade_fee": -2.427780000000000000,
                "offset_profitloss": 0E-18,
                "create_date": 1639100651577,
                "role": "Taker",
                "order_source": "api",
                "order_id_str": "918800256249405440",
                "id": "2902136-918800256249405440-1",
                "fee_asset": "USDT",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "real_profit": 0E-18,
                "reduce_only": 0
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> true object array
id true string unique id of the trade, and match_id is not unique id. The specific method of use is to use match_id and id as the joint primary key to form a unique transaction ID.
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_cross.$contract_code 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 in string
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode isolated；
margin_account true string margin account such as:USDT”
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
trade_volume true decimal trade volume
trade_price true decimal trade price
trade_turnover true decimal trade turnover
create_date true long create date
offset_profitloss true decimal profit or loss when cloase position
real_profit true decimal real profit
trade_fee true decimal trade fee
role true string taker or maker
fee_asset true string fee asset （"USDT"...）
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</data>

[Cross] Get History Match Results(New)

Note

Request:


    {
        "contract": "BTC-USDT",
        "trade_type": 0,
        "pair": "BTC-USDT",
        "start_time": 1660119810000,
        "end_time": 1660274746031,
        "direct": "next",
        "from_id": 1110
    }

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions, 17:buy(one-way mode), 18:sell(one-way mode)
start_time false long Query start time, query by data creation time Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 452057,
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures",
                "match_id": 2902136,
                "order_id": 918800256249405440,
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "direction": "buy",
                "offset": "open",
                "trade_volume": 100.000000000000000000,
                "trade_price": 48555.600000000000000000,
                "trade_turnover": 4855.560000000000000000,
                "trade_fee": -2.427780000000000000,
                "offset_profitloss": 0E-18,
                "create_date": 1639100651577,
                "role": "Taker",
                "order_source": "api",
                "order_id_str": "918800256249405440",
                "id": "2902136-918800256249405440-1",
                "fee_asset": "USDT",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "real_profit": 0E-18,
                "reduce_only": 0
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> true object array
id true string unique id of the trade, and match_id is not unique id. The specific method of use is to use match_id and id as the joint primary key to form a unique transaction ID.
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_cross.$contract_code 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 in string
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross；
margin_account true string margin account such as:USDT”
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
trade_volume true decimal trade volume
trade_price true decimal trade price
trade_turnover true decimal trade turnover
create_date true long create date
offset_profitloss true decimal profit or loss when cloase position
real_profit true decimal real profit
trade_fee true decimal trade fee
role true string taker or maker
fee_asset true string fee asset （"USDT"...）
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
true
</data>

[Isolated]Get History Match Results via Multiple Fields(New)

Remarks

Request:


    {
        "contract": "BTC-USDT",
        "trade_type": 0,
        "start_time": 1660119810000,
        "end_time": 1660274746031,
        "direct": "next",
        "from_id": 1110

    }

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions, 17:buy(one-way mode), 18:sell(one-way mode)
start_time false long Query start time, query by data creation time Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 138798248,
                "match_id": 13752484857,
                "order_id": 807038270541733888,
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "direction": "buy",
                "offset": "close",
                "trade_volume": 9,
                "trade_price": 36580,
                "trade_turnover": 329.22,
                "trade_fee": -0.131688,
                "offset_profitloss": 0.3636,
                "create_date": 1612454517757,
                "role": "Taker",
                "order_source": "android",
                "order_id_str": "807038270541733888",
                "id": "13752484857-807038270541733888-1",
                "fee_asset": "USDT",
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "real_profit": 0.2394,
                "reduce_only": 0
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> true object array
id true string unique id of the trade, and match_id is not unique id. The specific method of use is to use match_id and id as the joint primary key to form a unique transaction ID.
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_cross.$contract_code 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 in string
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode isolated；
margin_account true string margin account such as:BTC-USDT”
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
trade_volume true decimal trade volume
trade_price true decimal trade price
trade_turnover true decimal trade turnover
create_date true long create date
offset_profitloss true decimal profit or loss when cloase position
real_profit true decimal real profit
trade_fee true decimal trade fee
role true string taker or maker
fee_asset true string fee asset （"USDT"...）
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
reduce_only true int reduce only 0: no, 1: yes
</data>

[Cross]Get History Match Results via Multiple Fields(New)

Note

Request:


    {
        "contract": "BTC-USDT",
        "trade_type": 0,
        "pair": "BTC-USDT",
        "start_time": 1660119810000,
        "end_time": 1660274746031,
        "direct": "next",
        "from_id": 1110
    }

Request Parameter

Parameter Name Required Type Desc Default Value Range OriginalParameter
contract true string contract code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT" contract_code
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions, 17:buy(one-way mode), 18:sell(one-way mode)
start_time false long Query start time, query by data creation time Value range [((end-time) – 48h), (end-time)], maximum query window size is 48 hours, query window shift should be within past 90 days.
end_time false long Query end time, query data by creation time now Value range [(present-90d), present], maximum query window size is 48 hours, query window shift should be within past 90 days.
direct false string Search direct, If the direction is NEXT, the data is returned in positive chronological order; if the direction is PREV, the data is returned in reverse chronological order next next, prev default is prev
from_id false long If the query direction is prev, from_id should be the min query_id in the last query result. If the query direction is next, from_id should be the max query_id in the last query result Search query_id to begin with

Response:


    {
        "code": 200,
        "msg": "",
        "data": [
            {
                "query_id": 452057,
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures",
                "match_id": 2902136,
                "order_id": 918800256249405440,
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "direction": "buy",
                "offset": "open",
                "trade_volume": 100.000000000000000000,
                "trade_price": 48555.600000000000000000,
                "trade_turnover": 4855.560000000000000000,
                "trade_fee": -2.427780000000000000,
                "offset_profitloss": 0E-18,
                "create_date": 1639100651577,
                "role": "Taker",
                "order_source": "api",
                "order_id_str": "918800256249405440",
                "id": "2902136-918800256249405440-1",
                "fee_asset": "USDT",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "real_profit": 0E-18,
                "reduce_only": 0
            }
        ],
        "ts": 1604312615051
    }

Response Content

Parameter Name Required Type Description Value Range
code true int State code
msg true string The code description
ts true long Timestamp
<data> true object array
id true string unique id of the trade, and match_id is not unique id. The specific method of use is to use match_id and id as the joint primary key to form a unique transaction ID.
query_id true long Query id, which can be used as the from_id field for the next query request.
match_id true long matching result id, not unique, may be repeated
order_id true long order id
order_id_str true string order id in string
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross；
margin_account true string margin account such as:USDT”
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
trade_volume true decimal trade volume
trade_price true decimal trade price
trade_turnover true decimal trade turnover
create_date true long create date
offset_profitloss true decimal profit or loss when cloase position
real_profit true decimal real profit
trade_fee true decimal trade fee
role true string taker or maker
fee_asset true string fee asset （"USDT"...）
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
remain_size true int remain size(In the time range, the size that was not queried due to size restrictions)
next_id true long query_id for next data(It only has a value when the query result exceeds the size limit)
</data>

Swap Strategy Order Interface

[Isolated] Place Trigger Order

Remarks

Request:


{
    "contract_code": "BTC-USDT",
    "trigger_type": "ge",
    "trigger_price": 1111,
    "order_price": 1000,
    "order_price_type":"limit",
    "volume": 111,
    "direction": "buy",
    "offset": "open",
    "lever_rate": 10
}

body

Params Required Type Desc Value Range
contract_code true string contract type BTC-USDT
reduce_only false int reduce only(in hedge mode it is invalid, and in one-way mode it's value is 0 when not filled.) 0: no, 1: yes
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 string order price type： "limit" by default;"optimal_5", "optimal_10"，"optimal_20"
volume true long volume
direction true string buy sell
offset false(more see remarks) string open, close, both
lever_rate false int Long leverage shall be equal to short leverage.high leverage has a high risk factor, so please use it with caution.

Note

Return:


{
    "status": "ok",
    "data": {
        "order_id": 35,
        "order_id_str": "35"
    },
    "ts": 1547521135713
}

Response Desc

field type Required 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 Required Desc
order_id int true order id.
order_id_str string true order id str

Error：


{
    "status": "error",
    "err_code": 1014,
    "err_msg": "This contract doesnt exist.",
    "ts": 1603704820880
}

[Cross] Place Trigger Order

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
reduce_only false int reduce only(in hedge mode it is invalid, and in one-way mode it's value is 0 when not filled.) 0: no, 1: yes
trigger_type true string trigger type 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 string order price type "limit" by default;"optimal_5", "optimal_10"，"optimal_20"
volume true long Numbers of orders (volume)
direction true string direction buy/sell
offset false(more see remarks) string offset open,close,both
lever_rate false int leverage rate Long leverage shall be equal to short leverage.high leverage has a high risk factor, so please use it with caution.

Response


Success：
{
    "status": "ok",
    "data": {
        "order_id": 1880,
        "order_id_str": "1880"
    },
    "ts": 1606977456766
}

Error：
{
    "status": "error",
    "err_code": 1085,
    "err_msg": "Trigger order failed, please modify the price and place the order again or contact the customer service.",
    "ts": 1606977396756
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
ts true long timestamp
<data> true object
order_id true int order ID
order_id_str true string order id
</data>

[Isolated] Cancel Trigger Order

Remarks

request params

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

Response:


{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "34",
                "err_code": 1061,
                "err_msg": "This order doesnt exist."
            }
        ],
        "successes": "1"
    },
    "ts": 1603704887184
}

response

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

[Cross] Cancel Trigger Order

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
order_id true string order id. multiple orderids need to be joined by ",".Max number of order ids is 10 once.

Response

{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "1888",
                "err_code": 1061,
                "err_msg": "This order doesnt exist."
            }
        ],
        "successes": "1880"
    },
    "ts": 1606977508308
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object
<errors> true object array
order_id false string order ID
err_code false int error code
err_msg false string error message
</errors>
successes true string the list order which's successful，joined by ","
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Isolated] Cancel All Trigger Orders

Remarks

Params

field type Required desc
contract_code string true contract code,"BTC-USDT" ...
direction string false Transaction direction(if not filled in means all) ["buy" , "sell"]
offset string false offset direction（if not filled in means all） ["open" , "close"]

Note

Response:


{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "2"
    },
    "ts": 1603704998960
}

response params

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

response error：


{
    "status": "error",
    "err_code": 1051,
    "err_msg": "No orders to cancel.",
    "ts": 1603705063592
}

[Cross] Cancel All Trigger Orders

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
direction false string Transaction direction(if not filled in means all) ["buy" , "sell"]
offset false string offset direction（if not filled in means all） ["open" , "close"]

Note

Response

{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "1879,1878"
    },
    "ts": 1606977712328
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object
<errors> true object array
order_id false string order ID
err_code false int error code
err_msg false string error message
</errors>
successes true string the list order which's successful，joined by ","
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Isolated] Query Trigger Order Open Orders

Remarks

Request Parameter

Parameter Name Type Required Description
contract_code string true contract code "BTC-USDT"...
page_index int false page number，default page 1 if no given instruction
page_size int false default 20 if no given instruction ，no more than 50
trade_type int false trade type(Default:all) 0:all,1: buy long,2: sell short,3: buy short,4: sell long, 17:buy(one-way mode), 18:sell(one-way mode)

Response:


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "trigger_type": "ge",
                "volume": 1.000000000000000000,
                "order_type": 1,
                "direction": "sell",
                "offset": "open",
                "lever_rate": 10,
                "order_id": 4,
                "order_id_str": "4",
                "order_source": "api",
                "trigger_price": 13900.000000000000000000,
                "order_price": 13900.000000000000000000,
                "created_at": 1603705215654,
                "order_price_type": "limit",
                "status": 2,
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "reduce_only": 0
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1603705219567
}

Returning Parameter

Parameter Name Required 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 Type Required Description Value Range
total_page int true total page
current_page int true current page
total_size int true total size
<orders>
symbol string true Cryptocurrency
contract_code string true contract code
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,both]
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 order source( system、web、api、m、risk、settlement、ios、android、windows、mac、trigger )
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 、8：canceled orders but not found、9：canceling order、10：failed'
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
reduce_only true int reduce only 0: no, 1: yes
</orders>

[Cross] Query Trigger Order Open Orders

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
page_index false int page index, default 1st
page_size false int page size default 20，no more than 50
trade_type false int trade type(Default:all) 0:all,1: buy long,2: sell short,3: buy short,4: sell long, 17:buy(one-way mode), 18:sell(one-way mode)

Response

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "contract_type": "quarter",
                "business_type": "futures",
                "pair": "BTC-USDT",
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211231",
                "trigger_type": "le",
                "volume": 1.000000000000000000,
                "order_type": 1,
                "direction": "buy",
                "offset": "open",
                "lever_rate": 1,
                "order_id": 918808635214700544,
                "order_id_str": "918808635214700544",
                "order_source": "api",
                "trigger_price": 40000.000000000000000000,
                "order_price": 40000.000000000000000000,
                "created_at": 1639102649275,
                "order_price_type": "limit",
                "status": 2,
                "margin_mode": "cross",
                "margin_account": "USDT",
                "reduce_only": 0
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1639102667934
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object
total_page true int total page
current_page true int current page
total_size true int total size
<orders> true object array
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
trigger_type true string trigger type： gegreat than or equal to；leless than or equal to
volume true decimal place volume
order_type true int order type 1. Place orders 2. cancel orders
direction true string direction [buy/sell]
offset true string offset [open/close,both]
lever_rate true int leverage
order_id true long order id
order_id_str true string order id
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger
trigger_price true decimal trigger price
order_price true decimal order price
created_at true long created time
order_price_type true string type of order price "limit": limit order，"optimal_5":optimal 5，"optimal_10":optimal 10，"optimal_20":optimal 20
status true int order status：1:ready to submit、2:submited、3:order accepted 、8：canceled orders but not found、9：canceling order、10：failed'
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</orders>
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Isolated] Query Trigger Order History

Remarks

Request:


{
  "contract_code": "BTC-USDT",
  "create_date": 3,
  "trade_type": 0,
  "status":"4,6",
  "page_index":1,
  "page_size":10
}

Request Parameter

Parameter Name Required Type Desc Default Value Range
contract_code true string Contract Code BTC-USDT
trade_type true int Transaction type 0: All ,1: Open Long,2: Close Short,3: Open Short,4: Close Long, 17:buy(one-way mode), 18:sell(one-way mode)；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
sort_by false string sort fields(descending) created_at "created_at"：descending order by order creation time, "update_time": descending order by order update time

NOTE

Response:


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "trigger_type": "ge",
                "volume": 1.000000000000000000,
                "order_type": 1,
                "direction": "sell",
                "offset": "open",
                "lever_rate": 10,
                "order_id": 3,
                "order_id_str": "3",
                "relation_order_id": "-1",
                "order_price_type": "limit",
                "status": 6,
                "order_source": "api",
                "trigger_price": 13900.000000000000000000,
                "triggered_price": null,
                "order_price": 13900.000000000000000000,
                "created_at": 1603705155231,
                "update_time": 1603874287699,
                "triggered_at": null,
                "order_insert_at": 0,
                "canceled_at": 1603705159520,
                "fail_code": null,
                "fail_reason": null,
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "reduce_only": 0
            }
        ],
        "total_page": 3,
        "current_page": 1,
        "total_size": 3
    },
    "ts": 1603705603369
}

Returning Parameter

Parameter Name Type Required 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 Required Type Desc Value Range
total_page int true Total page
current_page int true Current page
total_size int true Total Size
<orders>
symbol string true symbol
contract_code string true Contract Code
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), both]
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
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( system、web、api、m、risk、settlement、ios、android、windows、mac、trigger)
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
update_time long true order update time，millesecond timestamp
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.
margin_mode string true margin mode isolated : "isolated"
margin_account string true margin account "BTC-USDT"...
reduce_only int reduce only 0: no, 1: yes
</orders>

[Cross] Query Trigger Order History

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade type 0: All ,1: Open Long,2: Close Short,3: Open Short,4: Close Long, 17:buy(one-way mode), 18:sell(one-way mode)；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 index, default 1st page page index, default 1st
page_size false int default 20，no more than 50 default 20，no more than 50
sort_by false string sort fields(Default: “created_at” descending order) "created_at"：descending order by order creation time, "update_time": descending order by order update time

Notice：

Response


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "contract_type": "quarter",
                "business_type": "futures",
                "pair": "BTC-USDT",
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211231",
                "trigger_type": "le",
                "volume": 1.000000000000000000,
                "order_type": 1,
                "direction": "buy",
                "offset": "open",
                "lever_rate": 1,
                "order_id": 918808635214700544,
                "order_id_str": "918808635214700544",
                "relation_order_id": "-1",
                "order_price_type": "limit",
                "status": 6,
                "order_source": "api",
                "trigger_price": 40000.000000000000000000,
                "triggered_price": null,
                "order_price": 40000.000000000000000000,
                "created_at": 1639102649275,
                "triggered_at": null,
                "order_insert_at": 0,
                "canceled_at": 1639103205980,
                "fail_code": null,
                "fail_reason": null,
                "margin_mode": "cross",
                "margin_account": "USDT",
                "update_time": 1639103206083,
                "reduce_only": 0
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1639103213233
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result "ok" , "error"
<data> true object
total_page true int total page
current_page true int current page
total_size true int total size
<orders> true object array
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
trigger_type true string trigger type： ge: Equal to or Greater than；le: Less than or Equal to
volume true decimal place volume
order_type true int order type：1、Place orders 2、Cancel orders
direction true string direction [buy/sell]
offset true string offset [open,close,both]
lever_rate true int leverage
order_id true long order id
order_id_str true string order id
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 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 true int status (4:Orders accepted、5: Orders failing being placed、6: Orders canceled )
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger
trigger_price true decimal trigger price
triggered_price true decimal triggered price
order_price true decimal order price
created_at true long created time
update_time true long order update time，millesecond timestamp
triggered_at true long trigger time
order_insert_at true long insert time
canceled_at true long canceled time
fail_code true int fail code
fail_reason true string fail reason
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</orders>
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Isolated]Set a Take-profit and Stop-loss Order for an Existing Position

Note:

Request

{
    "contract_code": "btc-usdt",
    "direction": "sell",
    "volume": 1,
    "tp_trigger_price": 32000,
    "tp_order_price": 32000,
    "tp_order_price_type": "optimal_5",
    "sl_trigger_price": "29000",
    "sl_order_price": "29000",
    "sl_order_price_type": "optimal_5"
}

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code BTC-USDT
direction true string direction "buy", "sell"
volume true decimal Numbers of orders (volume)
tp_trigger_price false decimal Trigger price of take-profit order
tp_order_price false decimal Order price of take-profit order（The order price is not required to fill in for Optimal N)
tp_order_price_type false string Order type of take-profit order default is market; market，limit，optimal_5，optimal_10，optimal_20
sl_trigger_price false decimal Trigger price of stop-loss order
sl_order_price false decimal Order price of stop-loss order（The order price is not required to fill in for Optimal N）
sl_order_price_type false string Order type of stop-loss order default is market; market，limit，optimal_5，optimal_10，optimal_20

Response

{
    "status": "ok",
    "data": {
        "tp_order": {
            "order_id": 795713650661638144,
            "order_id_str": "795713650661638144"
        },
        "sl_order": {
            "order_id": 795713650665832448,
            "order_id_str": "795713650665832448"
        }
    },
    "ts": 1609754517975
}

Error Response

{
    "status": "error",
    "err_code": 1066,
    "err_msg": "contract_code cannot be empty.",
    "ts": 1604369954194
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok" , "error"
ts true long time stamp
<data> false object Returned data when order is placed successfully, and will not be returned when order fails to be placed.
<tp_order> true object Order placing result of take-profit order
order_id true long order id
order_id_str true string order id (string)
</tp_order>
<sl_order> true object Order placing result of stop-loss order
order_id true long order id
order_id_str true string order id (string)
</sl_order>
</data>
err_code false int error code（only when order fails to be placed）
err_msg false string error message（only when order fails to be placed）

Note

[Cross]Set a Take-profit and Stop-loss Order for an Existing Position

Note

Request

{
    "contract_code": "btc-usdt",
    "direction": "sell",
    "volume": 1,
    "tp_trigger_price": 32000,
    "tp_order_price": 32000,
    "tp_order_price_type": "optimal_5",
    "sl_trigger_price": "29000",
    "sl_order_price": "29000",
    "sl_order_price_type": "optimal_5"
}

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
direction true string direction "buy", "sell"
volume true decimal Numbers of orders (volume)
tp_trigger_price false decimal Trigger price of take-profit order
tp_order_price false decimal Order price of take-profit order（The order price is not required to fill in for Optimal N)
tp_order_price_type false string Order type of take-profit order default is market; market，limit，optimal_5，optimal_10，optimal_20
sl_trigger_price false decimal Trigger price of stop-loss order
sl_order_price false decimal Order price of stop-loss order（The order price is not required to fill in for Optimal N）
sl_order_price_type false string Order type of stop-loss order default is market; market，limit，optimal_5，optimal_10，optimal_20

Note:

Response

{
    "status": "ok",
    "data": {
        "tp_order": {
            "order_id": 795714078698749952,
            "order_id_str": "795714078698749952"
        },
        "sl_order": {
            "order_id": 795714078698749953,
            "order_id_str": "795714078698749953"
        }
    },
    "ts": 1609754620038
}

Error Response

{
    "status": "error",
    "err_code": 1066,
    "err_msg": "contract_code cannot be empty.",
    "ts": 1604369954194
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok" , "error"
ts true long time stamp
<data> false object Returned data when order is placed successfully, and will not be returned when order fails to be placed.
<tp_order> true object Order placing result of take-profit order
order_id true long order id
order_id_str true string order id (string)
</tp_order>
<sl_order> true object Order placing result of stop-loss order
order_id true long order id
order_id_str true string order id (string)
</sl_order>
</data>
err_code false int error code（only when order fails to be placed）
err_msg false string error message（only when order fails to be placed）

Note

[Isolated]Cancel a Take-profit and Stop-loss Order

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code "BTC-USDT" ...
order_id true string order ID（different IDs are separated by ",", maximum 10 orders can be withdrew at one time）

Response

{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "795713650661638145",
                "err_code": 1061,
                "err_msg": "This order doesnt exist."
            }
        ],
        "successes": "795713650661638144"
    },
    "ts": 1609754722004
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok", "error"
<data> true object dictionary
<errors> true object dictionary
order_id true string order id
err_code false long error code
err_msg false string error message
</errors>
successes true string successes orders
</data>
ts true long Time of Respond Generation，Unit: Millisecond

[Cross]Cancel a Take-profit and Stop-loss Order

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
order_id true string order ID（different IDs are separated by ",", maximum 10 orders can be withdrew at one time）

Response

{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "795714078698749956",
                "err_code": 1061,
                "err_msg": "This order doesnt exist."
            }
        ],
        "successes": "795714078698749952"
    },
    "ts": 1609754775942
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok", "error"
<data> true object dictionary
<errors> true object dictionary
order_id true string order id
err_code false long error code
err_msg false string error message
</errors>
successes true string successes orders
</data>
ts true long Time of Respond Generation，Unit: Millisecond

[Isolated]Cancel all Take-profit and Stop-loss Orders

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code "BTC-USDT" ...
direction false string direction false string direction（if not filled in means all） ["buy", "sell"]

Response

{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "795713650665832448,795714964661583872,795714964661583873"
    },
    "ts": 1609754843671
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok", "error"
<data> true object dictionary
<errors> true object dictionary
order_id true string order id
err_code false long error code
err_msg false string error message
</errors>
successes true string successes orders
</data>
ts true long Time of Respond Generation，Unit: Millisecond

[Cross]Cancel all Take-profit and Stop-loss Orders

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
direction false string direction false string direction（if not filled in means all） ["buy", "sell"]

Response

{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "795714078698749953,795715192882053120,795715192886247424"
    },
    "ts": 1609754894463
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok", "error"
<data> true object dictionary
<errors> true object dictionary
order_id true string order id
err_code false long error code
err_msg false string error message
</errors>
successes true string successes orders
</data>
ts true long Time of Respond Generation，Unit: Millisecond

[Isolated]Query Open Take-profit and Stop-loss Orders

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code "BTC-USDT" ...
page_index false int page index. 1 by default
page_size false int page size.20 by default. 50 at most
trade_type false int trade type(Default:all) 0:all,3: buy short,4: sell long

Response

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "volume": 1,
                "order_type": 1,
                "direction": "buy",
                "order_id": 795715396674895872,
                "order_id_str": "795715396674895872",
                "order_source": "api",
                "trigger_type": "le",
                "trigger_price": 27000,
                "order_price": 0,
                "created_at": 1609754934244,
                "order_price_type": "optimal_5",
                "status": 2,
                "tpsl_order_type": "tp",
                "source_order_id": "795715396666507264",
                "relation_tpsl_order_id": "795715396674895873"
            }
        ],
        "total_page": 4,
        "current_page": 1,
        "total_size": 4
    },
    "ts": 1609755183516
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok", "error"
<data> true object dictionary
total_page true int total page
total_size true int total size
current_page true int current page
<orders> true object array
symbol true string symbol
contract_code true string contract code "BTC-USDT" ...
margin_mode true string margin mode cross, isolated
margin_account true string margin account such as “USDT”，“BTC-USDT”
volume true decimal Numbers of orders (volume)
order_type true int Order type: 1. Quotation; 2. Cancelled order
tpsl_order_type true string Order type(take-profit order/stop-loss order) “tp”:take-profit order；"sl"stop-loss order
direction true string direction "buy", "sell"
order_id true long order id
order_id_str true string order id in string
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger
trigger_type true string trigger type: ge, le
trigger_price true decimal trigger price
created_at true long created time
order_price_type true string order price type market，limit, optimal_5, optimal_10, optimal_20
order_price true decimal order price
status true int status: 1.Not Activated, 2.Ready to submit the orders, 3.Submitting the orders, 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled, 8.Cancelled order not found, 9.Orders cancelling, 10.Failed, 11.Expired
source_order_id true string Order id of source limit order (the field will have a value only when the order placed is a take-profit and stop-loss order; it is used to indicate that a certain limit order that triggered current take-profit and stop-loss order.)
relation_tpsl_order_id true string related take-profit and stop loss order id（The field will have a value when users set take-profit and stop loss order stimulatenously, otherwise, the value will be "-1".）
</orders>
</data>
ts true long Time of Respond Generation，Unit: Millisecond

[Cross]Query Open Take-profit and Stop-loss Orders

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
page_index false int page index. 1 by default
page_size false int page size.20 by default. 50 at most
trade_type false int trade type(Default:all) 0:all,3: buy short,4: sell long

Response

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "contract_type": "this_week",
                "business_type": "futures",
                "pair": "BTC-USDT",
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "volume": 1.000000000000000000,
                "order_type": 1,
                "direction": "sell",
                "order_id": 918816985859559425,
                "order_id_str": "918816985859559425",
                "order_source": "api",
                "trigger_type": "le",
                "trigger_price": 40000.000000000000000000,
                "order_price": 0E-18,
                "created_at": 1639104640223,
                "order_price_type": "optimal_5",
                "status": 2,
                "tpsl_order_type": "sl",
                "source_order_id": null,
                "relation_tpsl_order_id": "918816985859559424"
            },
            {
                "contract_type": "this_week",
                "business_type": "futures",
                "pair": "BTC-USDT",
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "volume": 1.000000000000000000,
                "order_type": 1,
                "direction": "sell",
                "order_id": 918816985859559424,
                "order_id_str": "918816985859559424",
                "order_source": "api",
                "trigger_type": "ge",
                "trigger_price": 50000.000000000000000000,
                "order_price": 0E-18,
                "created_at": 1639104640223,
                "order_price_type": "optimal_5",
                "status": 2,
                "tpsl_order_type": "tp",
                "source_order_id": null,
                "relation_tpsl_order_id": "918816985859559425"
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 2
    },
    "ts": 1639104794491
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok", "error"
<data> true object dictionary
total_page true int total page
total_size true int total size
current_page true int current page
<orders> true object array
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross, isolated
margin_account true string margin account such as “USDT”，“BTC-USDT”
volume true decimal Numbers of orders (volume)
order_type true int Order type: 1. Quotation; 2. Cancelled order
tpsl_order_type true string Order type(take-profit order/stop-loss order) “tp”:take-profit order；"sl"stop-loss order
direction true string direction "buy", "sell"
order_id true long order id
order_id_str true string order id in string
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger
trigger_type true string trigger type: ge, le
trigger_price true decimal trigger price
created_at true long created time
order_price_type true string order price type market，limit, optimal_5, optimal_10, optimal_20
order_price true decimal order price
status true int status: 1.Not Activated, 2.Ready to submit the orders, 3.Submitting the orders, 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled, 8.Cancelled order not found, 9.Orders cancelling, 10.Failed, 11.Expired
source_order_id true string Order id of source limit order (the field will have a value only when the order placed is a take-profit and stop-loss order; it is used to indicate that a certain limit order that triggered current take-profit and stop-loss order.)
relation_tpsl_order_id true string related take-profit and stop loss order id（The field will have a value when users set take-profit and stop loss order stimulatenously, otherwise, the value will be "-1".）
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</orders>
</data>
ts true long Time of Respond Generation，Unit: Millisecond

[Isolated]Query Take-profit and Stop-loss History Orders

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code "BTC-USDT" ...
status true string status Multiple orders are separated by English commas, and the status of stop-profit and stop-loss orders is: 0:all(representing all orders in the end state), 4:Have sumbmitted the orders, 5:orders failed, 6:orders canceled, 11:expired
create_date true long days 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 index. 1 by default
page_size false int page size.20 by default. 50 at most
sort_by false string for sortting, descende order by created_at when without value "created_at": descending order by order created at, "update_time": descending order by order update time

Response

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "volume": 1,
                "order_type": 1,
                "tpsl_order_type": "sl",
                "direction": "sell",
                "order_id": 795714964661583873,
                "order_id_str": "795714964661583873",
                "order_source": "api",
                "trigger_type": "le",
                "trigger_price": 29000,
                "created_at": 1609754831244,
                "order_price_type": "optimal_5",
                "status": 6,
                "source_order_id": null,
                "relation_tpsl_order_id": "795714964661583872",
                "canceled_at": 1609754844420,
                "fail_code": null,
                "fail_reason": null,
                "triggered_price": null,
                "relation_order_id": "-1",
                "update_time": 1609754850018,
                "order_price": 0
            }
        ],
        "total_page": 17,
        "current_page": 1,
        "total_size": 17
    },
    "ts": 1609756931689
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok", "error"
<data> true object dictionary
total_page true int total page
total_size true int total size
current_page true int current page
<orders> true object array
symbol true string symbol
contract_code true string contract code "BTC-USDT" ...
margin_mode true string margin mode cross, isolated
margin_account true string margin account such as “USDT”，“BTC-USDT”
volume true decimal Numbers of orders (volume)
order_type true int Order type: 1. Quotation; 2. Cancelled order
tpsl_order_type true string Order type(take-profit order/stop-loss order) “tp”:take-profit order；"sl"stop-loss order
direction true string direction "buy", "sell"
order_id true long order id
order_id_str true string order id in string
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger
trigger_type true string trigger type: ge, le
trigger_price true decimal trigger price
created_at true long created time
order_price_type true string order price type market，limit, optimal_5, optimal_10, optimal_20
order_price true decimal order price
status true int status: 1.Not Activated, 2.Ready to submit the orders, 3.Submitting the orders, 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled, 8.Cancelled order not found, 9.Orders cancelling, 10.Failed, 11.Expired
source_order_id true string Order id of source limit order (the field will have a value only when the order placed is a take-profit and stop-loss order; it is used to indicate that a certain limit order that triggered current take-profit and stop-loss order.)
relation_tpsl_order_id true string related take-profit and stop loss order id（The field will have a value when users set take-profit and stop loss order stimulatenously, otherwise, the value will be "-1".）
canceled_at true long canceled time
fail_code true int fail code when triggered
fail_reason true string fail reason when triggered
triggered_price true decimal triggered price
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.
update_time true long update time, unit: Millisecond
</orders>
</data>
ts true long Time of Respond Generation，Unit: Millisecond

[Cross]Query Take-profit and Stop-loss History Orders

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
status true string status Multiple orders are separated by English commas, and the status of stop-profit and stop-loss orders is: 0:all(representing all orders in the end state), 4:Have sumbmitted the orders, 5:orders failed, 6:orders canceled, 11:expired
create_date true long days 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 index. 1 by default
page_size false int page size.20 by default. 50 at most
sort_by false string for sortting, descende order by created_at when without value "created_at": descending order by order created at, "update_time": descending order by order update time

Response

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "contract_type": "this_week",
                "business_type": "futures",
                "pair": "BTC-USDT",
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "volume": 1.000000000000000000,
                "order_type": 1,
                "tpsl_order_type": "tp",
                "direction": "sell",
                "order_id": 918816985859559424,
                "order_id_str": "918816985859559424",
                "order_source": "api",
                "trigger_type": "ge",
                "trigger_price": 50000.000000000000000000,
                "created_at": 1639104640223,
                "order_price_type": "optimal_5",
                "status": 6,
                "source_order_id": null,
                "relation_tpsl_order_id": "918816985859559425",
                "canceled_at": 1639104933147,
                "fail_code": null,
                "fail_reason": null,
                "triggered_price": null,
                "relation_order_id": "-1",
                "update_time": 1639104933172,
                "order_price": 0E-18
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1639104940769
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok", "error"
<data> true object dictionary
total_page true int total page
total_size true int total size
current_page true int current page
<orders> true object array
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross, isolated
margin_account true string margin account such as “USDT”，“BTC-USDT”
volume true decimal Numbers of orders (volume)
order_type true int Order type: 1. Quotation; 2. Cancelled order
tpsl_order_type true string Order type(take-profit order/stop-loss order) “tp”:take-profit order；"sl"stop-loss order
direction true string direction "buy", "sell"
order_id true long order id
order_id_str true string order id in string
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger
trigger_type true string trigger type: ge, le
trigger_price true decimal trigger price
created_at true long created time
order_price_type true string order price type market，limit, optimal_5, optimal_10, optimal_20
order_price true decimal order price
status true int status: 1.Not Activated, 2.Ready to submit the orders, 3.Submitting the orders, 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled, 8.Cancelled order not found, 9.Orders cancelling, 10.Failed, 11.Expired
source_order_id true string Order id of source limit order (the field will have a value only when the order placed is a take-profit and stop-loss order; it is used to indicate that a certain limit order that triggered current take-profit and stop-loss order.)
relation_tpsl_order_id true string related take-profit and stop loss order id（The field will have a value when users set take-profit and stop loss order stimulatenously, otherwise, the value will be "-1".）
canceled_at true long canceled time
fail_code true int fail code when triggered
fail_reason true string fail reason when triggered
triggered_price true decimal triggered price
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.
update_time true long update time, unit: Millisecond
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</orders>
</data>
ts true long Time of Respond Generation，Unit: Millisecond

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code "BTC-USDT" ...
order_id true long order id

Response

{
    "status": "ok",
    "data": {
        "symbol": "BTC",
        "contract_code": "BTC-USDT",
        "margin_mode": "isolated",
        "margin_account": "BTC-USDT",
        "volume": 1,
        "price": 29999,
        "order_price_type": "opponent",
        "direction": "buy",
        "offset": "open",
        "lever_rate": 75,
        "order_id": 795947785812557824,
        "order_id_str": "795947785812557824",
        "client_order_id": null,
        "created_at": 1609810340126,
        "trade_volume": 1,
        "trade_turnover": 29.999,
        "fee": -0.01619946,
        "trade_avg_price": 29999,
        "margin_frozen": 0,
        "profit": 0,
        "status": 6,
        "order_type": 1,
        "order_source": "api",
        "fee_asset": "USDT",
        "canceled_at": 0,
        "tpsl_order_info": [
            {
                "volume": 1,
                "direction": "sell",
                "tpsl_order_type": "tp",
                "order_id": 795947785820946432,
                "order_id_str": "795947785820946432",
                "trigger_type": "ge",
                "trigger_price": 31000,
                "order_price": 0,
                "created_at": 1609810340134,
                "order_price_type": "optimal_5",
                "relation_tpsl_order_id": "795947785820946433",
                "status": 1,
                "canceled_at": 0,
                "fail_code": null,
                "fail_reason": null,
                "triggered_price": null,
                "relation_order_id": "-1"
            },
            {
                "volume": 1,
                "direction": "sell",
                "tpsl_order_type": "sl",
                "order_id": 795947785820946433,
                "order_id_str": "795947785820946433",
                "trigger_type": "le",
                "trigger_price": 29100,
                "order_price": 0,
                "created_at": 1609810340134,
                "order_price_type": "optimal_5",
                "relation_tpsl_order_id": "795947785820946432",
                "status": 1,
                "canceled_at": 0,
                "fail_code": null,
                "fail_reason": null,
                "triggered_price": null,
                "relation_order_id": "-1"
            }
        ]
    },
    "ts": 1609810352828
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok", "error"
<data> true object dictionary
symbol true string symbol
contract_code true string contract code "BTC180914" ...
margin_mode true string margin mode cross, isolated
margin_account true string margin account such as “USDT”，“BTC-USDT”
volume true decimal Numbers of orders (volume)
price true decimal price
order_price_type true string order price type "market": Market Order，"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
direction true string direction "buy","sell"
offset true string offset "open", "close", "both"
lever_rate true int lever rate
order_id true long order id
order_id_str true string order id in string
client_order_id true long client order id
created_at true long created at
trade_volume true decimal trade volume
trade_turnover true decimal trade turnover
fee true decimal fee
trade_avg_price true decimal trade avg price
margin_frozen true decimal margin frozen
profit true decimal profit when close position (calculated with the average price of position, exclude profit in history settlement.)
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
order_source true string order source system. web. api. m. risk. settlement. ios. android. windows. mac. trigger
fee_asset true string fee asset （"BTC","ETH"...）
canceled_at true long canceled at
<tpsl_order_info> true object array related take-profit and stop loss order info
volume true decimal Numbers of orders (volume)
tpsl_order_type true string Order type(take-profit order/stop-loss order) “tp”:take-profit order；"sl"stop-loss order
direction true string direction "buy", "sell"
order_id true long order id
order_id_str true string order id in string
trigger_type true string trigger type: ge, le
trigger_price true decimal trigger price
created_at true long created time
order_price_type true string order price type limit, optimal_5, optimal_10, optimal_20
order_price true decimal order price
status true int status 1.Not Activated, 2.Ready to submit the orders, 3.Submitting the orders, 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled, 8.Cancelled order not found, 9.Orders cancelling, 10.Failed, 11.Expired. 12. Not Activated-Expired
relation_tpsl_order_id true string related take-profit and stop loss order id（The field will have a value when users set take-profit and stop loss order stimulatenously, otherwise, the value will be "-1".）
canceled_at true long canceled time
fail_code true int fail code when triggered
fail_reason true string fail reason when triggered
triggered_price true decimal triggered price
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.
</tpsl_order_info>
</data>
ts true long Time of Respond Generation，Unit: Millisecond

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
order_id true long open order id

Response

{
    "status": "ok",
    "data": {
        "contract_type": "this_week",
        "business_type": "futures",
        "pair": "BTC-USDT",
        "symbol": "BTC",
        "contract_code": "BTC-USDT-211210",
        "margin_mode": "cross",
        "margin_account": "USDT",
        "volume": 1,
        "price": 48592.2,
        "order_price_type": "opponent",
        "direction": "buy",
        "offset": "open",
        "lever_rate": 5,
        "order_id": 918819004716982272,
        "order_id_str": "918819004716982272",
        "client_order_id": null,
        "created_at": 1639105121550,
        "trade_volume": 1,
        "trade_turnover": 48.592200000000000000,
        "fee": -0.024296100000000000,
        "trade_avg_price": 48592.200000000000000000,
        "margin_frozen": 0E-18,
        "profit": 0,
        "status": 6,
        "order_type": 1,
        "order_source": "api",
        "fee_asset": "USDT",
        "canceled_at": 0,
        "tpsl_order_info": [
            {
                "volume": 1.000000000000000000,
                "direction": "sell",
                "tpsl_order_type": "tp",
                "order_id": 918819004746342400,
                "order_id_str": "918819004746342400",
                "trigger_type": "ge",
                "trigger_price": 50000.000000000000000000,
                "order_price": 0E-18,
                "created_at": 1639105121563,
                "order_price_type": "optimal_5",
                "relation_tpsl_order_id": "918819004750536704",
                "status": 2,
                "canceled_at": 0,
                "fail_code": null,
                "fail_reason": null,
                "triggered_price": null,
                "relation_order_id": "-1"
            },
            {
                "volume": 1.000000000000000000,
                "direction": "sell",
                "tpsl_order_type": "sl",
                "order_id": 918819004750536704,
                "order_id_str": "918819004750536704",
                "trigger_type": "le",
                "trigger_price": 40000.000000000000000000,
                "order_price": 0E-18,
                "created_at": 1639105121564,
                "order_price_type": "optimal_5",
                "relation_tpsl_order_id": "918819004746342400",
                "status": 2,
                "canceled_at": 0,
                "fail_code": null,
                "fail_reason": null,
                "triggered_price": null,
                "relation_order_id": "-1"
            }
        ]
    },
    "ts": 1639105149621
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string status "ok", "error"
<data> true object dictionary
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross, isolated
margin_account true string margin account such as “USDT”，“BTC-USDT”
volume true decimal Numbers of orders (volume)
price true decimal price
order_price_type true string order price type "market": Market Order，"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
direction true string direction "buy","sell"
offset true string offset "open", "close", "both"
lever_rate true int lever rate
order_id true long order id
order_id_str true string order id in string
client_order_id true long client order id
created_at true long created at
trade_volume true decimal trade volume
trade_turnover true decimal trade turnover
fee true decimal fee
trade_avg_price true decimal trade avg price
margin_frozen true decimal margin frozen
profit true decimal profit when close position (calculated with the average price of position, exclude profit in history settlement.)
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
order_source true string order source system. web. api. m. risk. settlement. ios. android. windows. mac. trigger
fee_asset true string fee asset （"BTC","ETH"...）
canceled_at true long canceled at
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
<tpsl_order_info> true object array related take-profit and stop loss order info
volume true decimal Numbers of orders (volume)
tpsl_order_type true string Order type(take-profit order/stop-loss order) “tp”:take-profit order；"sl"stop-loss order
direction true string direction "buy", "sell"
order_id true long order id
order_id_str true string order id in string
trigger_type true string trigger type: ge, le
trigger_price true decimal trigger price
created_at true long created time
order_price_type true string order price type limit, optimal_5, optimal_10, optimal_20
order_price true decimal order price
status true int status 1.Not Activated, 2.Ready to submit the orders, 3.Submitting the orders, 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled, 8.Cancelled order not found, 9.Orders cancelling, 10.Failed, 11.Expired. 12. Not Activated-Expired
relation_tpsl_order_id true string related take-profit and stop loss order id（The field will have a value when users set take-profit and stop loss order stimulatenously, otherwise, the value will be "-1".）
canceled_at true long canceled time
fail_code true int fail code when triggered
fail_reason true string fail reason when triggered
triggered_price true decimal triggered price
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.
</tpsl_order_info>
</data>
ts true long Time of Respond Generation，Unit: Millisecond

[Isolated]Place a Trailing Order

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code BTC-USDT
reduce_only false int reduce only(in hedge mode it is invalid, and in one-way mode it's value is 0 when not filled.) 0: no, 1: yes
direction true string direction buy, sell
offset false(more see remarks) string offset open, close, both
lever_rate false int lever rate, is required when open position, is optional when close position
volume true decimal volume(cont)
callback_rate true decimal callback rate Such as: 0.01 means 1%. And must be not less than 0.001 (0.1%)
active price true decimal active price
order_price_type true string order price type optimal_5, optimal_10, optimal_20, formula_price

Note

Response: 

{
    "status": "ok",
    "data": {
        "order_id": 826052268312821760,
        "order_id_str": "826052268312821760"
    },
    "ts": 1616987808080
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" , "error"
ts true long timestamp
<data> true object the returned data which is successful
order_id true long trailing order id[Globally Unique]
order_id_str true string trailing order id in string format
</data>

[Cross]Place a Trailing Order

Note:

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
reduce_only false int reduce only(in hedge mode it is invalid, and in one-way mode it's value is 0 when not filled.) 0: no, 1: yes
direction true string direction buy, sell
offset false(more see remarks) string offset open, close, both
lever_rate false int lever rate, is required when open position, is optional when close position
volume true decimal volume(cont)
callback_rate true decimal callback rate Such as: 0.01 means 1%. And must be not less than 0.001 (0.1%)
active price true decimal active price
order_price_type true string order price type optimal_5, optimal_10, optimal_20, formula_price

Note

Response: 

{
    "status": "ok",
    "data": {
        "order_id": 826052906719444992,
        "order_id_str": "826052906719444992"
    },
    "ts": 1616987960287
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" , "error"
ts true long timestamp
<data> true object the returned data which is successful
order_id true long trailing order id[Globally Unique]
order_id_str true string trailing order id in string format
</data>

[Isolated]Cancel a Trailing Order

Note:

Parameter Name Required Type Description Value Range
contract_code true string contract code BTC-USDT
order_id true string User's trailing order id (multiple order IDs are separated by ",", a maximum of 10 orders are allowed to be withdrawn at a time)

Response: 

{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "826052268312821761",
                "err_code": 1061,
                "err_msg": "This order doesnt exist."
            }
        ],
        "successes": "826052268312821760"
    },
    "ts": 1616988039695
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" :success, "error": failed
<data> true object dictionary
<errors> true object dictionary
order_id true string trailing order id[Globally Unique]
err_code false long error code
err_msg false string error msg
</errors>
successes true string the orders that are success
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Cross]Cancel a Trailing Order

Note:

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
order_id true string User's trailing order id (multiple order IDs are separated by ",", a maximum of 10 orders are allowed to be withdrawn at a time)

Response: 

{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "826052906719444993",
                "err_code": 1061,
                "err_msg": "This order doesnt exist."
            }
        ],
        "successes": "826053970168446976"
    },
    "ts": 1616988232517
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" :success, "error": failed
<data> true object dictionary
<errors> true object dictionary
order_id true string trailing order id[Globally Unique]
err_code false long error code
err_msg false string error msg
</errors>
successes true string the orders that are success
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Isolated]Cancel All Trailing Orders

Note:

### Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code BTC-USDT
direction false string direction(if not filled in as all) buy, sell
offset false string offset(if not filledin as all) open, close

Response: 

{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "826054603831312384,826054608491184128,826054686706565120"
    },
    "ts": 1616988392280
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" :success, "error": failed
<data> true object dictionary
<errors> true object dictionary
order_id true string trailing order id[Globally Unique]
err_code false long error code
err_msg false string error msg
</errors>
successes true string the orders that are success
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Cross]Cancel All Trailing Orders

Note:

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
contract_type false(more see remarks) string contract type swap, this_week, next_week, quarter, next_quarter
direction false string direction(if not filled in, means all) buy, sell
offset false string offset (if not filled in, means all) open, close

Response: 

{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "826054813483597824,826054818734866432,826054867657228288"
    },
    "ts": 1616988442893
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" :success, "error": failed
<data> true object dictionary
<errors> true object dictionary
order_id true string trailing order id[Globally Unique]
err_code false long error code
err_msg false string error msg
</errors>
successes true string the orders that are success
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Isolated]Current unfilled trailing order acquisition

Note:

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code BTC-USDT
trade_type false int trade type(if not filled in, means all) 0:all,1: buy long,2: sell short,3: buy short,4: sell long, 17:buy(one-way mode), 18:sell(one-way mode)
page_index false int page index, if not filled in as 1st
page_size false int if not filled in as 20, and no more than 50

Response: 

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "volume": 1.000000000000000000,
                "order_type": 1,
                "direction": "buy",
                "offset": "open",
                "lever_rate": 5,
                "order_id": 826055066114916352,
                "order_id_str": "826055066114916352",
                "order_source": "api",
                "created_at": 1616988475122,
                "order_price_type": "formula_price",
                "status": 2,
                "callback_rate": 0.030000000000000000,
                "active_price": 48888.000000000000000000,
                "is_active": 0,
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "reduce_only": 0
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1616988497109
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" :success, "error": failed
<data> true object dictionary
total_page true int total page
total_size true int total size
current_page true int current page
<orders> true object array
symbol true string symbol
contract_code true string contract code BTC-USDT
volume true decimal volume
order_type true int order type: 1. Quotation; 2. Cancelled order
direction true string direction buy, sell
offset true string offset open, close, both
lever_rate true int lever rate
order_id true long trailing order id
order_id_str true string trailing order id in string format
order_source true string order source
created_at true long created at
order_price_type true string order price type optimal_5, optimal_10, optimal_20, formula_price
status true int order status 2.Ready to submit the orders, 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled
callback_rate true decimal callback rate such as: 0.01 means 1%
active price true decimal active price
is_active true int Is the active price activated? 1: activated; 0: not activated
margin_mode true string margin mode isolated
margin_account true string margin account e.g：“BTC-USDT”
reduce_only true int reduce only 0: no, 1: yes
</orders>
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Cross]Current unfilled trailing order acquisition

Note:

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false string pair BTC-USDT
trade_type false int trade type(if not filled in, means all) 0:all,1: buy long,2: sell short,3: buy short,4: sell long, 17:buy(one-way mode), 18:sell(one-way mode)
page_index false int page index, if not filled in as 1st
page_size false int if not filled in as 20, and no more than 50

Response: 

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "contract_type": "quarter",
                "business_type": "futures",
                "pair": "BTC-USDT",
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211231",
                "volume": 1.000000000000000000,
                "order_type": 1,
                "direction": "buy",
                "offset": "open",
                "lever_rate": 1,
                "order_id": 918819679173152768,
                "order_id_str": "918819679173152768",
                "order_source": "api",
                "created_at": 1639105282359,
                "order_price_type": "formula_price",
                "status": 2,
                "callback_rate": 0.030000000000000000,
                "active_price": 41111.000000000000000000,
                "is_active": 0,
                "margin_mode": "cross",
                "margin_account": "USDT",
                "reduce_only": 0
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1639105312766
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" :success, "error": failed
<data> true object dictionary
total_page true int total page
total_size true int total size
current_page true int current page
<orders> true object array
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
volume true decimal volume
order_type true int order type: 1. Quotation; 2. Cancelled order
direction true string direction buy, sell
offset true string offset open, close, both
lever_rate true int lever rate
order_id true long trailing order id
order_id_str true string trailing order id in string format
order_source true string order source
created_at true long created at
order_price_type true string order price type optimal_5, optimal_10, optimal_20, formula_price
status true int order status 2.Ready to submit the orders, 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled
callback_rate true decimal callback rate such as: 0.01 means 1%
active price true decimal active price
is_active true int Is the active price activated? 1: activated; 0: not activated
margin_mode true string margin mode cross
margin_account true string margin account e.g：“BTC-USDT”
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</orders>
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Isolated]Get History Trailing Orders

Note:

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code BTC-USDT
status true string order status Multiple separated by English commas, Trailing Order status: 0:all(representing all orders in the end state), 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled
trade_type true int trade type 0:all,1: buy long,2: sell short,3: buy short,4: sell long, 17:buy(one-way mode), 18:sell(one-way mode)
create_date true long days 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 index, if not filled in as 1st
page_size false int if not filled in as 20, and no more than 50
sort_by false string sort fields(descending), if not filled in, sort by created_at descending "create_date"：descending order by order create date , "update_time": descending order by order update time

Response: 

{
    "status":"ok",
    "data":{
        "orders":[
            {
                "symbol":"BTC",
                "contract_code":"BTC-USDT",
                "triggered_price":null,
                "volume":1,
                "order_type":1,
                "direction":"sell",
                "offset":"open",
                "lever_rate":5,
                "order_id":826054686706565120,
                "order_id_str":"826054686706565120",
                "order_source":"api",
                "created_at":1616988384665,
                "update_time":1616988430833,
                "order_price_type":"formula_price",
                "status":6,
                "canceled_at":1616988393365,
                "fail_code":null,
                "fail_reason":null,
                "callback_rate":0.03,
                "active_price":51111,
                "is_active":0,
                "market_limit_price":null,
                "formula_price":null,
                "real_volume":0,
                "relation_order_id":"-1",
                "margin_mode":"isolated",
                "margin_account":"BTC-USDT",
                "reduce_only": 0
            }
        ],
        "total_page":1,
        "current_page":1,
        "total_size":4
    },
    "ts":1616989113947
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" :success, "error": failed
<data> true object dictionary
total_page true int total page
total_size true int total size
current_page true int current page
<orders> true object array
symbol true string symbol
contract_code true string contract code BTC-USDT
volume true decimal volume
order_type true int order type: 1. Quotation; 2. Cancelled order
direction true string direction buy, sell
offset true string offset open, close, both
lever_rate true int lever rate
order_id true long trailing order id
order_id_str true string trailing order id in string format
order_source true string order source
created_at true long created at
update_time true long update time, unit: millisecond
order_price_type true string order price type optimal_5, optimal_10, optimal_20, formula_price
status true int order status 2.Ready to submit the orders, 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled
canceled_at true long canceled at
fail_code true int error code when place limit price order
fail_reason true string error reason when place limit price order
callback_rate true decimal callback rate such as: 0.01 means 1%
active price true decimal active price
is_active true int Is the active price activated? 1: activated; 0: not activated
market_limit_price true decimal lowest/highest market price (use the lowest price when buy. use the highest when sell)
formula_price true decimal formula price(the lowest (highest) market price* (1 ± callback rate))
real_volume true decimal real volume
triggered_price true decimal triggered price
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.
margin_mode true string margin mode isolated
margin_account true string margin account e.g：“BTC-USDT”
reduce_only true int reduce only 0: no, 1: yes
</orders>
</data>
ts true long Time of Respond Generation, Unit: Millisecond

[Cross]Get History Trailing Orders

Note:

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
status true string order status Multiple separated by English commas, Trailing Order status: 0:all(representing all orders in the end state), 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled
trade_type true int trade type(if not filled in, means all) 0:all,1: buy long,2: sell short,3: buy short,4: sell long, 17:buy(one-way mode), 18:sell(one-way mode)
create_date true long days 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 index, if not filled in as 1st
page_size false int if not filled in as 20, and no more than 50
sort_by false string sort fields(descending), if not filled in, sort by created_at descending "create_date"：descending order by order create date , "update_time": descending order by order update time

Response: 

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "contract_type": "quarter",
                "business_type": "futures",
                "pair": "BTC-USDT",
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211231",
                "triggered_price": null,
                "volume": 1.000000000000000000,
                "order_type": 1,
                "direction": "buy",
                "offset": "open",
                "lever_rate": 1,
                "order_id": 918819679173152768,
                "order_id_str": "918819679173152768",
                "order_source": "api",
                "created_at": 1639105282359,
                "update_time": 1639105426243,
                "order_price_type": "formula_price",
                "status": 6,
                "canceled_at": 1639105426208,
                "fail_code": null,
                "fail_reason": null,
                "callback_rate": 0.030000000000000000,
                "active_price": 41111.000000000000000000,
                "is_active": 0,
                "market_limit_price": null,
                "formula_price": null,
                "real_volume": 0,
                "relation_order_id": "-1",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "reduce_only": 0
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1639105441911
}

Return Parameter

Parameter Name Required Type Description Value Range
status true string the result of server handling to request "ok" :success, "error": failed
<data> true object dictionary
total_page true int total page
total_size true int total size
current_page true int current page
<orders> true object array
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
volume true decimal volume
order_type true int order type: 1. Quotation; 2. Cancelled order
direction true string direction buy, sell
offset true string offset open, close, both
lever_rate true int lever rate
order_id true long trailing order id
order_id_str true string trailing order id in string format
order_source true string order source
created_at true long created at
update_time true long update time, unit: millisecond
order_price_type true string order price type optimal_5, optimal_10, optimal_20, formula_price
status true int order status 2.Ready to submit the orders, 4.Submit the orders success, 5.Submit the orders failed, 6.Orders cancelled
canceled_at true long canceled at
fail_code true int error code when place limit price order
fail_reason true string error reason when place limit price order
callback_rate true decimal callback rate such as: 0.01 means 1%
active price true decimal active price
is_active true int Is the active price activated? 1: activated; 0: not activated
market_limit_price true decimal lowest/highest market price (use the lowest price when buy. use the highest when sell)
formula_price true decimal formula price(the lowest (highest) market price* (1 ± callback rate))
real_volume true decimal real volume
triggered_price true decimal triggered price
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.
margin_mode true string margin mode cross
margin_account true string margin account e.g：“BTC-USDT”
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</orders>
</data>
ts true long Time of Respond Generation, Unit: Millisecond

Swap Transferring Interface

[General] Transfer margin between Spot account and USDT Margined Contracts account

Example

Notice

The interface supports cross margin mode and isolated margin mode.

This interface is used to transfer assets between Spot account and USDT Margined Contracts account.

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

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

Request Parameter

Parameter Name Required Type Desc Value Range
from true string source，value：spot、linear-swap e.g. spot
to true string destination，value：spot、linear-swap e.g. linear-swap
currency true string currency.Both uppercase and lowercase are supported. e.g. USDT
amount true decimal Transferring amount
margin-account true string margin account e.g. BTC-USDT，ETH-USDT, USDT

note

Response:


 Yes：
{
    "code": 200,
    "data": 176104252,
    "message": "Succeed",
    "success": true
}
No：
 {
   "code":1303,
   "data":null,
   "message":"The single transfer-out amount must be no less than 0.0008BTC",
   "success":false
}

Returning Parameter

Parameter Name Required Type Desc Value Range
success true string status true/false
data true long The generated transfer order id
code true long Response code
message true string Response message

Response Code Table

Response Code Desc in Chinese Desc in English
200 成功 Succeed
403 拒绝访问 Access denied
404 访问的资源不存在 The resource being accessed does not exist
429 太多的请求 too many requests
500 系统错误 System error
501 无效请求 Invalid request
502 无效参数 Invalid parameter
504 缺少参数 Lack of parameter
512 拒绝匿名请求 Reject anonymous requests
513 无效的签名 Invalid signature
10000 币种不存在 Currency does not exist
10001 不支持同业务划转 Does not support transfer within single business
10002 不支持此划转业务 This transfer is not supported
10003 from方check校验不通过 check rejected by the from party
10004 to方check校验不通过 to check rejected by the to party
10005 个人账户平账检查不通过 Personal account balance check failed
10006 系统账户检查失败 System account check failed
10008 黑名单校验不通过 Blacklist check failed
10009 用户有未安全上账资产，禁止划转 No transfer is allowed if the user has any asset that has not been charged to the account safely
10010 用户被锁定 User locked
10011 24小时内修改过安全策略 Security policy has been modified within 24 hours
20001 OTC 人脸识别 OTC Face Recognition
1030 服务异常，请稍后再试 Abnormal service. Please try again later.
1010 用户不存在 Abnormal service. Please try again later.
1012 账户不存在 Abnormal service. Please contact customer service.
1013 合约品种不存在 This contract type doesn't exist.
1018 主账号不存在 Main account doesn't exist.
1089 {0}合约暂时限制划转,请联系客服 {0} contract is restricted of transfer. Please contact customer service.
1102 您没有转入权限,请联系客服 Unable to transfer in currently. Please contact customer service.
1103 您没有转出权限,请联系客服 Unable to transfer out currently. Please contact customer service.
1106 合约状态异常,暂时无法划转 Abnormal contracts status. Can’t transfer.
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.
1114 子账号没有划转权限,请登录主账号授权 The sub-account does not have transfer permissions. Please login main account to authorize.
1300 划转失败 Transfer failed.
1301 可划转余额不足 Insufficient amount available.
1302 系统划转错误 Transfer failed.
1303 单笔转出的数量不能低于{0}{1} The single transfer-out amount must be no less than {0}{1}.
1304 单笔转出的数量不能高于{0}{1} The single transfer-out amount must be no more than {0}{1}.
1305 单笔转入的数量不能低于{0}{1} The single transfer-in amount must be no less than {0}{1}.
1306 单笔转入的数量不能高于{0}{1} The single transfer-in amount must be no more than {0}{1}.
1307 您当日累计转出量超过{0}{1}, 暂无法转出 Your accumulative transfer-out amount is over the daily maximum, {0}{1}. You can't transfer out for the time being.
1308 您当日累计转入量超过{0}{1}, 暂无法转入 Your accumulative transfer-in amount is over the daily maximum, {0}{1}. You can't transfer in for the time being.
1309 您当日累计净转出量超过{0}{1}, 暂无法转出 Your accumulative net transfer-out amount is over the daily maximum, {0}{1}. You can't transfer out for the time being.
1310 您当日累计净转入量超过{0}{1}, 暂无法转入 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 划转金额必须大于0 Invalid amount. Must be more than 0.
1323 服务异常, 划转失败, 请稍后再试 Abnormal service, transfer failed. Please try again later.
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 超出划转精度限制(8位), 请修改后操作 Exceeds limit of transfer accuracy (8 digits). Please modify it.

Swap WebSocket Reference

API List

Permission Content Type Interface Mode Request Method Type Description Authentication Required
Read Market Data Interface general market.$contract_code.kline.$period sub Subscribe KLine data No
Read Market Data Interface general market.$contract_code.kline.$period req Request Kline Data No
Read Market Data Interface general market.$contract_code.depth.$type sub Subscribe Market Depth Data No
Read Market Data Interface general market.$contract_code.depth.size_${size}.high_freq sub Subscribe Incremental Market Depth Data No
Read Market Data Interface general market.$contract_code.bbo sub Subscribe market BBO data push No
Read Market Data Interface general market.$contract_code.detail sub Subscribe Market Detail Data No
Read Market Data Interface general market.$contract_code.trade.detail req Request Trade Detail Data No
Read Market Data Interface general market.$contract_code.trade.detail sub Subscribe Trade Detail Data No
Read Index and Basis Interface general market.$contract_code.index.$period sub Subscribe Index Kline Data No
Read Index and Basis Interface general market.$contract_code.index.$period sub Request Index Kline Data No
Read Index and Basis Interface general market.$contract_code.basis.$period.$basis_price_type sub Subscribe Basis Data No
Read Index and Basis Interface general market.$contract_code.basis.$period.$basis_price_type req Request Basis Data No
Read Index and Basis Interface general market.$contract_code.premium_index.$period sub Subscribe Premium Index Kline Data No
Read Index and Basis Interface general market.$contract_code.premium_index.$period req Request Premium Index Kline Data No
Read Index and Basis Interface general market.$contract_code.estimated_rate.$period sub Subscribe Estimated Funding Rate Kline Data No
Read Index and Basis Interface general market.$contract_code.estimated_rate.$period req Request Estimated Funding Rate Kline Data No
Read Index and Basis Interface general market.$contract_code.mark_price.$period sub Subscribe Kline Data of Mark Price No
Read Index and Basis Interface general market.$contract_code.mark_price.$period req Request Kline Data of Mark Price No
Read Trade Interface general public.$contract_code.liquidation_orders sub Subscribe Liquidation Orders (no authentication) (sub) No
Read Trade Interface general public.$contract_code.funding_rate sub Subscribe funding rate (no authentication)（sub） No
Read Trade Interface general public.$contract_code.contract_info sub Subscribe Contract Info (no authentication)（sub） No
Read Trade Interface Isolated Margin orders.$contract_code sub Subscribe Order Data(sub) Yes
Read Account Interface Isolated Margin accounts.$contract_code sub Subscribe Account Equity Updates Data(sub) Yes
Read Account Interface Isolated Margin positions.$contract_code sub Subscribe Position Updates(sub) Yes
Read Trade Interface Isolated Margin matchOrders.$contract_code sub Subscribe Match Order Data（sub) Yes
Read Trade Interface Isolated Margin trigger_order.$contract_code sub Subscribe trigger orders updates(sub) Yes
Read Account Interface cross margin orders_cross.$contract_code sub Subscribe Order Data Yes
Read Account Interface cross margin accounts_cross.$margin_account sub Subscribe Account Equity Updates Data Yes
Read Trade Interface cross margin positions_cross.$contract_code sub Subscribe Position Updates Yes
Read Trade Interface cross margin matchOrders_cross.$contract_code sub Subscribe Match Order Data Yes
Read Trade Interface cross margin trigger_order_cross.$contract_code sub Subscribe trigger orders updates(sub) Yes
Read System Status Interface cross margin public.$service.heartbeat sub Subscription system status updates No

WebSocket Subscription Address

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

Order Push Subscription: wss://api.hbdm.com/linear-swap-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/linear-swap-ws;

Order Push Subscription：wss://api.btcgateway.pro/linear-swap-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 USDT Margined Contracts 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 interfaces, products, (future, coin margined swap, usdt margined Contracts)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/linear-swap-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

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 USDT Margined Contracts 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 USDT Margined Contracts. 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

/linear-swap-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 int 0 means successfully response, others means response failure return 0 if success , 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 string 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

[General] Subscribe Kline data

Remarks

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

{

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

"id": "id generate by client"

}

Example of a successful subscription request：


    {
    "sub": "market.BTC-USDT.kline.1min",
    "id": "id1"
    }

Request Parameter

Parameter Name Required Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.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 Required Type Description Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
period true string Kline Period 1min, 5min, 15min, 30min, 60min,4hour,1day,1week, 1mon

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


{
    "ch":"market.BTC-USDT.kline.1min",
    "ts":1603707124366,
    "tick":{
        "id":1603707120,
        "mrid":131592424,
        "open":13067.7,
        "close":13067.7,
        "high":13067.7,
        "low":13067.7,
        "amount":0.004,
        "vol":4,
        "trade_turnover":52.2708,
        "count":1
    }
}

Return Parameter

Parameter Name Required 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 ID Order ID
vol true decimal Trade Volume(Cont.). Sum of both buy and sell sides
count true decimal Order Quantity. Sum of both buy and sell sides
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). Sum of both buy and sell sides
trade_turnover true decimal Transaction amount, that is, sum (transaction quantity * contract face value * transaction price). Sum of both buy and sell sides
</tick>

[General] Request Kline data

Remarks

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

{

"req": "market.$contract_code.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-USDT.kline.1min",
    "id": "id4",
    "from": 1571000000,
    "to": 1573106298
    }

Request Parameter

Parameter Name Required Type Desc
req true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.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 Required Type Description Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
period true string Kline Period 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

Example of a successful return data：


{
    "id":"id4",
    "rep":"market.BTC-USDT.kline.60min",
    "wsid":467277265,
    "status":"ok",
    "data":[
        {
            "id":1603270800,
            "open":12198,
            "close":12196.7,
            "low":11715.8,
            "high":12300,
            "amount":0.276,
            "vol":276,
            "trade_turnover":3315.9104,
            "count":39
        },
        {
            "id":1603274400,
            "open":12196.7,
            "close":12277.9,
            "low":12111,
            "high":12289.9,
            "amount":0.198,
            "vol":198,
            "trade_turnover":2420.7728,
            "count":21
        }
    ]
}

Return Parameter

Parameter Name Required 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.). Sum of both buy and sell sides
count true decimal Order quantity. Sum of both buy and sell sides
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). Sum of both buy and sell sides
trade_turnover true decimal Transaction amount, that is, sum (transaction quantity * contract face value * transaction price). Sum of both buy and sell sides
</data>

[General] Subscribe Market Depth Data

Remarks

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

{

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

"id": "id generated by client"

}

Example of a successful request ：


    {
    "sub": "market.BTC-USDT.depth.step0",
    "id": "id5"
    }

Request Parameter

Parameter Name Required Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.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 Required Type Description Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
type true string Depth Type Get depth data within step 150, use step0, step1, step2, step3, step4, step5, step14, step15, step16, step17（merged depth data 0-5,14-17）；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, step18, step19(merged depth data 7-13,18-19); when step is 6, depth data will not be merged.

Note:

Depth precision
step16、step18 0.0000001
step17、step19 0.000001
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-USDT.depth.step6",
    "ts":1603707576468,
    "tick":{
        "mrid":131596447,
        "id":1603707576,
        "bids":[
            [
                13071.9,
                38
            ],
            [
                13068,
                5
            ]
        ],
        "asks":[
            [
                13081.9,
                197
            ],
            [
                13099.7,
                371
            ]
        ],
        "ts":1603707576467,
        "version":1603707576,
        "ch":"market.BTC-USDT.depth.step6"
    }
}

Return Parameter

Parameter Name Required 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 long tick ID
asks false object Sell,[price(Ask price), vol(Ask orders (cont.) )], price in ascending sequence
bids false 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>

[General] Subscribe Incremental Market Depth Data

Remarks

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

{

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

"data_type":"incremental",

"id": "id generated by client"

}

Example of a successful request ：

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

Request Parameter

Parameter Name Required Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.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 data type. snapshot by default. incremental: incremental data.snapshot: full data.

sub Subscribe Parameter Rules

Parameter Name Required Type Description Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
size true int Depth size 20: stands for 20 unmerged data. 150:stands for 150 unmerged data.

Response example:


{
    "ch":"market.BTC-USDT.depth.size_20.high_freq",
    "tick":{
        "asks":[
            [
                13081.9,
                206
            ],
            [
                13099.7,
                371
            ]
        ],
        "bids":[
            [
                13071.9,
                38
            ],
            [
                13060,
                400
            ]
        ],
        "ch":"market.BTC-USDT.depth.size_20.high_freq",
        "event":"snapshot",
        "id":131597620,
        "mrid":131597620,
        "ts":1603707712356,
        "version":1512467
    },
    "ts":1603707712357
}

Return Parameter

Parameter Name Required Type Description Value Range
ts true long Timestamp of Respond Generation, Unit: Millisecond
ch true string Data channel, Format：market.$contract_code.depth.size_${size}.high_freq
<tick>
mrid true long Order ID
id true long tick ID，system timestamp.seconds
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 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.$contract_code.depth.size_${size}.high_freq
</tick>

Note:

[General] Subscribe Market Detail Data

Remarks

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

{

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

"id": "id generated by client"

}

Example of Subscribe Market Detail Data：


    {
     "sub": "market.BTC-USDT.detail",
     "id": "id6"
    }

Request Parameter

Parameter Name Required Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.detail，For parameter details please check sub Subscribe Parameter Rules
id false string should be unique from user-side

sub Subscribe Parameter Rules

Parameter Name Required Type Description Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ

Example of a successful return data：


{
    "ch":"market.BTC-USDT.detail",
    "ts":1603707870528,
    "tick":{
        "id":1603707840,
        "mrid":131599205,
        "open":12916.2,
        "close":13065.8,
        "high":13205.3,
        "low":12852.8,
        "amount":30.316,
        "vol":30316,
        "trade_turnover":395073.4918,
        "count":2983,
        "bid":[
            13684.5,
            10615
        ],
        "ask":[
            13684.6,
            3440
        ]

    }
}

Return Parameter

Parameter Name Required Type Description
ch true string Data channel，Format： market.$contract_code.detail
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. Sum of both buy and sell sides
vol true decimal Trade volume(Cont.)， the sum volume of both buy and sell sides. Sum of both buy and sell sides
count true decimal fulfilled order quantity. Sum of both buy and sell sides
trade_turnover true decimal Transaction amount, that is, sum (transaction quantity * contract face value * transaction price). Sum of both buy and sell sides
ask true object Sell,[price(Ask price), vol(Ask orders (cont.) )]
bid true object Buy,[price(Bid price), vol(Bid orders(Cont.))]
</tick>

Note:

[General] Subscribe market BBO data push

Remarks

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

{

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

"id": "id generated by client"

}

Example of a successful request：


    {
     "sub": "market.BTC-USDT.bbo",
     "id": "id8"
    }

Request Parameter

Parameter Name Mandotary Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.bbo，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 Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ

Return example:


{
    "ch":"market.BTC-USDT.bbo",
    "ts":1603707934525,
    "tick":{
        "mrid":131599726,
        "id":1603707934,
        "bid":[
            13064,
            38
        ],
        "ask":[
            13072.3,
            205
        ],
        "ts":1603707934525,
        "version":131599726,
        "ch":"market.BTC-USDT.bbo"
    }
}

Return Parameter：

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

Rules：

[General] Request Trade Detail Data

Remarks

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

{

"req": "market.$contract_code.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 trade detail data：



    {
     "req": "market.BTC-USDT.trade.detail",
     "size": 10,
     "id": "id8"
    }

Request Parameter

Parameter Name Required Type Desc
req true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.trade.detail，For parameter details please check req Subscribe 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

req Subscribe Parameter Rules

Parameter Name Required Type Description Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ

Example of a successful return data：


{
    "data":[
        {
            "amount":"22",
            "ts":1603706942240,
            "id":1315909380000,
            "price":"13068.4",
            "direction":"sell",
            "quantity": "0.022",
            "trade_turnover": "288.334"
        },
        {
            "amount":"2",
            "ts":1603706947767,
            "id":1315909430000,
            "price":"13068.5",
            "direction":"buy",
            "quantity": "0.002",
            "trade_turnover": "26.334"
        }
    ],
    "id":"id8",
    "rep":"market.BTC-USDT.trade.detail",
    "status":"ok",
    "ts":1603708046534
}

Return Parameter

Parameter Name Required Type Description Default
rep true string Data Channel，Format： market.$contract_code.trade.detail
status true string Request Status
id true long Request ID
<data>
id true long Unique Transaction Id(symbol level)
price true string Price
amount true string Quantity(Cont.). Sum of both buy and sell sides
direction true string The direction to buy or sell is the direction of the taker (active transaction)
ts true long Order Creation Time
quantity true string trading quantity(coin)
trade_turnover true string trade turnover(quoted currency)
</data>
ts true long server response time

Notice

[General] Subscribe Trade Detail Data

Remarks

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

{

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

"id": "id generated by client"

}

Example of a successful subscribe request：


    {
     "sub": "market.BTC-USDT.trade.detail",
     "id": "id7"
    }

Note:

Clients can only access the recent 300 trade detail data

Request Parameter

Parameter Name Required Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.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 Required Type Description Value Range
contract_code true string contract code or contract type swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ

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


{
    "ch":"market.BTC-USDT.trade.detail",
    "ts":1603708208346,
    "tick":{
        "id":131602265,
        "ts":1603708208335,
        "data":[
            {
                "amount":2,
                "ts":1603708208335,
                "id":1316022650000,
                "price":13073.3,
                "direction":"buy",
                "quantity": 0.002,
                "trade_turnover": 26.334
            }
        ]
    }
}

Return Parameter

Parameter Name Required Type Description Default
ch true string Data channel,format: market.$contract_code.trade.detail
ts true long Request time
<tick>
id true long Unique Order Id(symbol level).
ts true long tick time
<data>
amount true decimal quantity(Cont.). Sum of both buy and sell sides
ts true long trade timestamp
id true long Unique Transaction Id(symbol level)
price true decimal Price
direction true string The direction to buy or sell is the direction of the taker (active transaction)
quantity true decimal trading quantity(coin)
trade_turnover true decimal trade turnover(quoted currency)
</data>
</tick>

WebSocket Index and Basis Interface

[General] Subscribe Index Kline Data

Remarks

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

{

"sub": "market.$contract_code.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 Required Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.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 Required Type Desc Value Range
contract_code true string index symbol Case-Insenstive.Both uppercase and lowercase are supported.."BTC-USDT","ETH-USDT"...
period true string kline type 1min, 5min, 15min, 30min, 60min,4hour,1day, 1mon

Note

results pushed by the server


{
    "ch":"market.BTC-USDT.index.15min",
    "ts":1607309592214,
    "tick":{
        "id":1607309100,
        "open":"19213.505",
        "close":"19242.05",
        "high":"19248.31",
        "low":"19213.505",
        "amount":"0",
        "vol":"0",
        "count":0
    }
}

Returning Parameter

parameter name Required type desc Value Range
ch true string Data channel，Format：market.$contract_code.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.

[General] Request Index Kline Data

Remarks

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

{

"req": "market.$contract_code.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.btc-usd.index.1min",
    "id": "id4",
    "from":1571000000,
    "to":1573098606
  }

Request Parameter

Parameter Name Required Type Desc
req true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.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 Value Range
contract_code true string index symbol Case-Insenstive.Both uppercase and lowercase are supported.."BTC-USDT","ETH-USDT"...
period true string kline type 1min, 5min, 15min, 30min, 60min,4hour,1day, 1mon

Note：

response example：


{
    "id":"id4",
    "rep":"market.BTC-USDT.index.15min",
    "wsid":3673570133,
    "ts":1607310136031,
    "status":"ok",
    "data":[
        {
            "id":1607309100,
            "open":19213.505,
            "close":19207.245,
            "low":19207.245,
            "high":19248.31,
            "amount":0,
            "vol":0,
            "count":0
        },
        {
            "id":1607310000,
            "open":19199.655,
            "close":19174.48,
            "low":19174.48,
            "high":19208.11,
            "amount":0,
            "vol":0,
            "count":0
        }
    ]
}

Returning Parameter

parameter name Required type desc Value Range
req true string Data channel，Format：market.$contract_code.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.

[General] Subscribe Premium Index Kline Data

Remarks

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

{

"sub": "market.$contract_code.premium_index.$period",

"id": "id generate by client"

}

example of the subscription of premium index kline data：


    {
    "sub": "market.BTC-USDT.premium_index.1min",
    "id": "id1"
    }

Request Parameter

Parameter Name Required Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.premium_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 Required Type Desc Value Range
contract_code true string contract code Case-Insenstive.Both uppercase and lowercase are supported.."BTC-USDT","ETH-USDT"...
period true string kline type 1min, 5min, 15min, 30min, 60min,4hour,1day, 1week, 1mon

Note

results pushed by the server


{
    "ch":"market.BTC-USDT.premium_index.1min",
    "ts":1603708380380,
    "tick":{
        "id":1603708380,
        "open":"0.000068125",
        "close":"0.000068125",
        "high":"0.000068125",
        "low":"0.000068125",
        "amount":"0",
        "vol":"0",
        "count":"0"
    }
}

Return Parameter

parameter name Required type desc Value Range
ch true string Data channel，Format： market.period
<tick> true object array
id true long index kline id,the same as kline timestamp, kline start timestamp
vol true string Trade Volume(Cont.). The value is 0.
count true string count. The value is 0.
open true string open index price
close true string close index price
low true string lowest index price
high true string highest index price
amount true string amount based on coins.
</tick>
ts true long Time of Respond Generation, Unit: Millisecond

[General] Request Premium Index Kline Data

Remarks

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

{

"req": "market.$contract_code.premium_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 a successful subscribe request


    {
    "req": "market.BTC-USDT.premium_index.1min",
    "id": "id4",
    "from":1571000000,
    "to":1573098606
    }

Request Parameter

Parameter Name Required Type Desc
req true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.premium_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 Value Range
contract_code true string contract code Case-Insenstive.Both uppercase and lowercase are supported.."BTC-USDT","ETH-USDT"...
period true string kline type 1min, 5min, 15min, 30min, 60min,4hour,1day, 1week, 1mon

Note：

response example：


{
    "id":"id4",
    "rep":"market.BTC-USDT.premium_index.15min",
    "wsid":1524762738,
    "ts":1603782744066,
    "status":"ok",
    "data":[
        {
            "id":1603641600,
            "open":"0",
            "close":"0.0000970833333333",
            "low":"0",
            "high":"0.0000997916666666",
            "amount":"0",
            "vol":"0",
            "count":"0"
        }
    ]
}

data parameters

parameter name Required type desc Value Range
rep true string Data channel，Format： market.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
id true long index kline id,the same as kline timestamp, kline start timestamp
vol true string Trade Volume(Cont.). The value is 0.
count true string count. The value is 0.
open true string open index price
close true string close index price
low true string lowest index price
high true string highest index price
amount true string amount based on coins.
</data>

[General] Subscribe Estimated Funding Rate Kline Data

Remarks

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

{

"sub": "market.$contract_code.estimated_rate.$period",

"id": "id generate by client"

}

example of the subscription of estimated funding rate kline data：


    {
    "sub": "market.BTC-USDT.estimated_rate.1min",
    "id": "id1"
    }

Request Parameter

Parameter Name Required Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.estimated_rate.$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 Required Type Desc Value Range
contract_code true string contract code Case-Insenstive.Both uppercase and lowercase are supported.."BTC-USDT","ETH-USDT"...
period true string kline type 1min, 5min, 15min, 30min, 60min,4hour,1day, 1week, 1mon

Note:

results pushed by the server


{
    "ch":"market.BTC-USDT.estimated_rate.1min",
    "ts":1603708560233,
    "tick":{
        "id":1603708560,
        "open":"0.0001",
        "close":"0.0001",
        "high":"0.0001",
        "low":"0.0001",
        "amount":"0",
        "vol":"0",
        "count":"0",
        "trade_turnover":"0"
    }
}

parameters

parameter name Required type desc Value Range
ch true string Data channel，Format： market.period
<tick> true object array
id true long index kline id,the same as kline timestamp
vol true string Trade Volume(Cont.). The value is 0.
count true string count. The value is 0.
open true string open index price
close true string close index price
low true string lowest index price
high true string highest index price
amount true string amount based on coins.
trade_turnover true string Transaction amount, the value is 0.
</tick>
ts true long Time of Respond Generation, Unit: Millisecond

[General] Request Estimated Funding Rate Kline Data

Remarks

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

{

"req": "market.$contract_code.estimated_rate.$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 a successful subscribe request


    {
    "req": "market.btc-usdt.estimated_rate.1min",
    "id": "id4",
    "from":1571000000,
    "to":1573098606
    }

Request Parameter

Parameter Name Required Type Desc
req true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.estimated_rate.$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 Request Parameter：

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

response example：


{
    "id":"id4",
    "rep":"market.BTC-USDT.estimated_rate.15min",
    "wsid":3674722864,
    "ts":1603782867314,
    "status":"ok",
    "data":[
        {
            "id":1603641600,
            "open":"0.0001",
            "close":"0.0001",
            "low":"0.0001",
            "high":"0.0001",
            "amount":"0",
            "vol":"0",
            "count":"0",
            "trade_turnover":"0"
        }
    ]
}

parameters

parameter name Required type desc Value Range
rep true string Data channel, Format： market.period
status true string Request status "ok" , "error"
id true string ID
wsid true long wsid
ts true long Time of Respond Generation, unit: millisecond
<data> true object array
id true long index kline id,the same as kline timestamp
vol true string Trade Volume(Cont.). The value is 0.
count true string count. The value is 0.
open true string open index price
close true string close index price
low true string lowest index price
high true string highest index price
amount true string amount based on coins.
trade_turnover true string Transaction amount, the value is 0.
</data>

[General] Subscribe Basis Data

Remarks

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

{

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

"id": "id generate by client"

}

example of the subscription of basis data：


    {
    "sub": "market.BTC-USDT.basis.1min.open",
    "id": "id1"
    }

Request Parameter

Parameter Name Required Type Desc
sub true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.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
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
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"

Response Example


{
    "ch":"market.BTC-USDT.basis.1min.open",
    "ts":1617164081549,
    "tick":{
        "id":1617164040,
        "index_price":"58686.78333333333",
        "contract_price":"58765",
        "basis":"78.21666666667",
        "basis_rate":"0.0013327816285723049700163397705562309"
    }
}

Response Parameters

parameter name Required Type Desc Value Range
ch string Data belonged channel Format: market.period
<tick> object array
id long unique id
contract_price string contract last price
index_price string index price
basis string basis=contract_price - index_price
basis_rate string basis_rate=basis/index_price
</tick>
ts long Time of Respond Generation, unit: millisecond

[General] Request Basis Data

Remarks

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

{

"req": "market.$contract_code.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 a successful subscribe request


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

Request Parameter

Parameter Name Required Type Desc
req true string the themes that need to be subscribed; the interface is fixed at: market.$contract_code.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

Request Parameter：

Parameter Name Mandotary Type Desc Default Value Range
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
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":"-27.593412766666006",
            "basis_rate":"-0.0021317871729511838",
            "contract_price":"12916.2",
            "id":1603641600,
            "index_price":"12943.793412766667"
        }
    ],
    "id":"id4",
    "rep":"market.BTC-USDT.basis.15min.open",
    "status":"ok",
    "ts":1603783024207,
    "wsid":1308653018
}

Response Parameters

parameter name Required Type Desc Value Range
rep true string Data belonged channel Format: market.basis
status true string Return Statu "ok" , "error"
id true string Request ID
wsid true long wsid
ts true long Time of Respond Generation, unit: millisecond
<data> object array
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>

[General]Subscribe Kline Data of Mark Price

Note：

After connected WebSocket API server, send data as follow:

{

"sub": "market.$contract_code.mark_price.$period",

"id": "id generate by client"

}

Example：


 {
    "sub": "market.BTC-USDT.mark_price.1min",
    "id": "id1"
 }

Request Parameter

Parameter Name Required Type Description Default Value
sub true string topic, format as: market.$contract_code.mark_price.$period, too more detail to see sub Subscribe Parameter Rules
id false string optional; unique ID in client side

sub Subscribe Parameter Rules

Parameter Name Required Type Description Value Range
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
period true string period 1min, 5min, 15min, 30min, 60min,4hour,1day, 1week, 1mon

When the marked price is updated, the client will receive the data, for example:


{
 "ch": "market.BTC-USDT.mark_price.1min",
 "ts": 1489474082831,
 "tick": 
    {
      "vol": "0",
      "close": "9800.12",
      "count": "0",
      "high": "9800.12",
      "id": 1529898780,
      "low": "9800.12",
      "open": "9800.12",
      "trade_turnover": "0",
      "amount": "0"
    }
}

Returning Parameter

Parameter Name Required Type Description Default Value Value Range
ch true string channel, format: market.period
<tick> true object array
id true long id
vol true string trade vol(cont), value is 0
count true string trade count, value is 0
open true string open price
close true string close price
low true string low price
high true string high price
amount true string trade amount, value is 0
trade_turnover true string trade turnover, value is 0
</tick>
ts true number Time of Respond Generation, Unit: Millisecond

[General]Request Kline Data of Mark Price

Note：

After connected WebSocket API server, send data as follow:

{

"req": "market.$contract_code.mark_price.$period",

"id": "id generated by client",

"from": " type: long, unit: second "

"to": "type: long, unit: second, must greater than from "

}

Example：


    {
    "req": "market.BTC-USDT.mark_price.5min",
    "id": "id4",
    "from": 1579247342,
    "to": 1579247342
    }

Request Parameter

Parameter Name Required Type Description Default Value
req true string topic, format as: market.$contract_code.mark_price.$period, too more detail to see req Request Parameter Rules
id false string optional; unique ID in client side
from true long start time
to true long end time

req Request Parameter Rules

Parameter Name Required Type Description Value Range
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ... or BTC-USDT-CW, BTC-USDT-NW, BTC-USDT-CQ, BTC-USDT-NQ
period true string period 1min, 5min, 15min, 30min, 60min,4hour,1day, 1week, 1mon

Note

Example of successful response:

{
 "rep": "market.BTC-USDT.mark_price.1min",
 "status": "ok",
 "id": "id4",
 "wsid": 1231323423,
 "ts": 1579489028884,
 "data": [
   {
      "vol": "0",
      "close": "9800.12",
      "count": "0",
      "high": "9800.12",
      "id": 1529898780,
      "low": "9800.12",
      "open": "9800.12",
      "trade_turnover": "0",
      "amount": "0"
   }
 ]
}

Returning Parameter

Parameter Name Required Type Description Default Value Value Range
req true string channel, format: market.period
status true string status "ok" , "error"
id true string id
wsid true long wsid
ts true number Time of Respond Generation, Unit: Millisecond
<data> true object array
id true long kline id
vol true string trade vol(cont), value is 0
count true string trade count, value is 0
open true string open price
close true string close price
low true string low price
high true string high price
amount true string trade amount, value is 0
trade_turnover true string trade turnover, value is 0
</data>

Orders and Accounts WebSocket Interfaces

[Isolated] Subscribe Order Data(sub)

Remarks

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.$contract_code”

}

Example of a successful subscribe request:


{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "orders.BTC-USDT"
}

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；format: orders.$contract_code; For parameter details please check req Subscribe Parameter

sub Subscribe Parameter Rules

Parameter Name Required Type Desc Value Range
contract_code true string contract code "*" all(it means to subscribe the all orders) "BTC-USDT","ETH-USDT"...

Illustration on detailed data format of orders Notification


{
    "op": "notify", 
    "topic": "orders.btc-usdt", 
    "ts": 1489474082831, 
    "uid": "123456789",
    "symbol": "BTC", 
    "contract_code": "BTC-USDT", 
    "volume": 111, 
    "price": 1111, 
    "order_price_type": "limit",
    "direction": "buy", 
    "offset": "open", 
    "status": 6,
    "lever_rate": 10, 
    "order_id":758684042347171840,
    "order_id_str":"758684042347171840", 
    "client_order_id": 10683, 
    "order_source": "web", 
    "order_type": 1, 
    "created_at": 1408076414000,
    "trade_volume": 1,
    "trade_turnover": 1200, 
    "fee": 0, 
    "liquidation_type": "0",
    "trade_avg_price": 10, 
    "margin_asset": "USDT",
    "margin_frozen": 10, 
    "profit": 2,
    "canceled_at": 1408076414000, 
    "fee_asset": "USDT",
    "margin_mode": "isolated",
    "margin_account": "BTC-USDT",
    "is_tpsl": 0,
    "real_profit": 0,
    "reduce_only": 0,
    "trade": [{
        "trade_id":14469,
        "id":"14469-758684042347171840-1",
        "trade_volume": 1, 
        "trade_price": 123.4555, 
        "trade_fee": 0.234,
        "fee_asset": "USDT", 
        "trade_turnover": 34.123, 
        "created_at": 1490759594752, 
        "real_profit": 0,
        "profit": 2,
        "role": "maker"
  }]
}

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 symbol
contract_code string Contract Code
volume decimal Order quantity
price decimal Order price
order_price_type string "market": Market Order，"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
direction string "buy" Long "sell": Short
offset string "open": Open "close": Close, "both"
status int Order status(1. Placing orders to order book; 2 Placing orders to order book; 3. Placed to order book 4. Partially filled; 5 partially filled but cancelled by client; 6. Fully filled; 7. Cancelled; 11Cancelling)
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、tpsl)
order_type int Order type 1Requested orders; 2. Cancelled orders; 3. Liquidated orders; 4. Delivered orders
created_at long order creation time
trade_volume decimal trade volume(coin))
trade_turnover decimal Turnover
fee decimal Fees
trade_avg_price decimal Average order price
margin_frozen decimal Frozen Margin
margin_asset string margin_asset
profit decimal total profit or loss of order when close position (calculated with the average price of position, exclude profit in history settlement.)
liquidation_type string Liquidation type, 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
canceled_at long Canceled time
fee_asset string the corresponding cryptocurrency to the given fee
margin_mode string margin mode isolated : "isolated"
margin_account string margin account "BTC-USDT"...
is_tpsl int whether to set take-profit and stop-loss order 1：yes；0：no
real_profit decimal total real profit of order (calculated with the opening average price, include profit in history settlement.)
reduce_only int reduce only 0: no, 1: yes
<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 linear-swap-api/v1/swap_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
real_profit decimal real profit of the transaction (calculated with the opening average price, include profit in history settlement.)
profit decimal profit or loss of the transaction (calculated with the average price of position, exclude profit in history settlement.)
fee_asset string the corresponding cryptocurrency to the given fee
</trade>

Note:

[Isolated] Unsubscribe Order Data（unsub）

Remarks

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.$contract_code”,

"cid": "id generated by client”,

}

Example of a successful unsubscribe request：


{
  "op": "unsub",
  "topic": "orders.BTC-USDT",
  "cid": "40sG903yz80oDFWr"
}

Format illustration of unsubscribe order data

Field Name Type Description
op string Required； Operator Name，value for unsubscribe is unsub;
cid string Optional; ID Client requests unique ID
topic string Required；Unsubscribe Topic Name, format: orders.$contract_code; For parameter details please check req Subscribe Parameter

sub Subscribe Parameter Rules

Parameter Name Required Type Desc Value Range
contract_code true string contract code "*" all(it means to unsubscribe the all orders) "BTC-USDT","ETH-USDT"...

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe( unsub ) Rule
orders.* orders.* Allowed
orders.contract_code1 orders.* Allowed
orders.contract_code1 orders.contract_code2 Allowed
orders.contract_code1 orders.contract_code2 Not Allowed
orders.* orders.contract_code1 Not Allowed

[Cross] Subscribe Order Data（sub）

Remarks

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": "orders_cross.$contract_code"

}

Example of a successful subscribe request:


{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "orders_cross.btc-usdt"
}

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；format: orders_cross.$contract_code; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code all: * (swap and future), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Illustration on detailed data format of orders Notification


{
    "contract_type":"swap",
    "pair":"BTC-USDT",
    "business_type":"swap",
    "op":"notify",
    "topic":"orders_cross.btc-usdt",
    "ts":1639107468139,
    "symbol":"BTC",
    "contract_code":"BTC-USDT",
    "volume":1,
    "price":48284.9,
    "order_price_type":"opponent",
    "direction":"buy",
    "offset":"open",
    "status":6,
    "lever_rate":5,
    "order_id":918828846806306816,
    "order_id_str":"918828846806306816",
    "client_order_id":null,
    "order_source":"api",
    "order_type":1,
    "created_at":1639107468086,
    "trade_volume":1,
    "trade_turnover":48.2849,
    "fee":-0.01931396,
    "trade_avg_price":48284.9,
    "margin_frozen":0,
    "profit":0,
    "trade":[
        {
            "trade_fee":-0.01931396,
            "fee_asset":"USDT",
            "real_profit":0,
            "profit":0,
            "trade_id":86875552122,
            "id":"86875552122-918828846806306816-1",
            "trade_volume":1,
            "trade_price":48284.9,
            "trade_turnover":48.2849,
            "created_at":1639107468102,
            "role":"taker"
        }
    ],
    "canceled_at":0,
    "fee_asset":"USDT",
    "margin_asset":"USDT",
    "uid":"123456789",
    "liquidation_type":"0",
    "margin_mode":"cross",
    "margin_account":"USDT",
    "is_tpsl":1,
    "real_profit":0,
    "reduce_only": 0
}

Pushed Data Parameter

Parameter Name Required Type Desc Value Range
op true string operation name, fixed as notify
topic true string topic
ts true long server response timestamp
uid true string uid
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
volume true decimal place volume
price true decimal place price
order_price_type true string type of order price "market": Market Order，"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
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
status true int order status 1. Placing orders to order book; 2 Placing orders to order book; 3. Placed to order book 4. Partially filled; 5 partially filled but cancelled by client; 6. Fully filled; 7. Cancelled; 11Cancelling
lever_rate true int leverage
order_id true long order ID
order_id_str true string order ID
client_order_id true long client order ID
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_type true int order type 1. Requested orders; 2. Cancelled orders; 3. Liquidated orders; 4. Delivered orders
created_at true long created time
trade_volume true decimal trade total amount
trade_turnover true decimal trade amount
fee true decimal service fee
trade_avg_price true decimal trade average price
margin_asset true string margin asset
margin_frozen true decimal frozen margin
profit true decimal total profit or loss of order when close position (calculated with the average price of position, exclude profit in history settlement.)
liquidation_type true decimal liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
canceled_at true long canceled time
fee_asset true string fee asset “USDT”
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
real_profit true decimal total real profit of order (calculated with the opening average price, include profit in history settlement.)
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
<trade> true object array
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 linear-swap-api/v1/swap_cross_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 true decimal trade quantity
trade_price true decimal trade price
trade_fee true decimal trade fee
trade_turnover true decimal trade amount
created_at true long trade time
role true string taker/maker
real_profit true decimal real profit of the transaction (calculated with the opening average price, include profit in history settlement.)
profit true decimal profit or loss of the transaction (calculated with the average price of position, exclude profit in history settlement.)
fee_asset true string fee asset “USDT”
</trade>

Note:

[Cross] Unsubscribe Order Data（unsub）

Remarks

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_cross.$contract_code",

"cid": "id generated by client",

}

Example of a successful unsubscribe request：


{                                
  "op": "unsub",                   
  "topic": "orders_cross.BTC-USDT",       
  "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，format: orders_cross.$contract_code; For parameter details please check req unsubscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code all: *(swap and future), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe( unsub ) Rule
orders_cross.* orders_cross.* Allowed
orders_cross.contract_code1 orders_cross.* Allowed
orders_cross.contract_code1 orders_cross.contract_code2 Allowed
orders_cross.contract_code1 orders_cross.contract_code2 Not Allowed
orders_cross.* orders_cross.contract_code1 Not Allowed

[Isolated] Subscribe Match Order Data（sub)

Remarks

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.$contract_code”

}

sub example:


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

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; subscribe Topic Name，format: matchOrders.$contract_code; For parameter details please check req unsubscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code "*" all(it means to subscribe the all match orders) "BTC-USDT"...

Note:

Illustration on detailed data format of orders Notification

response


{
    "op":"notify",
    "topic":"matchOrders.btc-usdt",
    "ts":1600926986125,
    "symbol":"BTC",
    "contract_code":"BTC-USDT",
    "status":6,
    "order_id":758688290195656704,
    "order_id_str":"758688290195656704",
    "client_order_id":null,
    "order_type":1,
    "created_at":1600926984112,
    "trade":[
        {
            "trade_id":14470,
            "id":"14470-758688290195656704-1",
            "trade_volume":1,
            "trade_price":10329.11,
            "trade_turnover":103.2911,
            "created_at":1600926986046,
            "role":"taker"
        }
    ],
    "uid":"123456789",
    "volume":1,
    "trade_volume":1,
    "direction":"buy",
    "offset":"open",
    "lever_rate":5,
    "price":10329.11,
    "order_source":"web",
    "order_price_type":"opponent",
    "margin_mode": "isolated",
    "margin_account": "BTC-USDT",
    "is_tpsl": 0,
    "reduce_only": 0
}

format of order data pushed

Parameter Name Required Type Desc Value Range
op true string notify
topic true string topic
ts true long server response timestamp
uid true string account uid
symbol true string symbol "BTC","ETH"...
contract_code true string contract code
status true 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 true long order id
order_id_str true string order id
client_order_id true long client order id
order_type true int order_type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
trade_volume true decimal trade volume
volume true decimal volume
direction true string direction "buy" : "sell"
offset true string offset "open", "close", "both"
lever_rate true int lever rate
price true decimal price
created_at true long created time
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true string order price type "market": Market Order，"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_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
reduce_only true int reduce only 0: no, 1: yes
<trade> true object array
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 linear-swap-api/v1/swap_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 trade price
trade_volume true decimal trade volume（cont）
trade_turnover true decimal trade turnover
created_at true long created time
role true string taker or maker
</trade>

[Isolated] Unsubscribe Match Order Data（unsub）

Remarks

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.$contract_code”,

"cid": "id generated by client”,

}

Example of a successful unsubscribe request：


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

Format illustration of unsubscribe order data

attr type desc
op string Required； Operator Name，value for unsubscribe is unsub;
cid string Optional; ID Client requests unique ID
topic string Required; Unsubscribe Topic Name，format: matchOrders.$contract_code; For parameter details please check req unsubscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code "*" all(it means to unsubscribe the all match orders) "BTC-USDT"...

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe( unsub) ) Rule
matchOrders.* matchOrders.* allowed
matchOrders.contract_code1 matchOrders.* Allowed
matchOrders.contract_code1 matchOrders.contract_code1 allowed
matchOrders.contract_code1 matchOrders.contract_code2 Not Allowed
matchOrders.* matchOrders.contract_code1 Not Allowed

[Cross] Subscribe Match Order Data（sub）

Remarks

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": "40sG903yz80oDFWr",

"topic": "matchOrders_cross.$contract_code"

}

Example of a successful ubscribe request：


{                                    
  "op": "sub",                     
  "topic": "matchOrders_cross.BTC-USDT",      
  "cid": "40sG903yz80oDFWr"          
}

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；format: matchOrders_cross.$contract_code; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code all: *(swap and future), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Note:

response


{
    "contract_type":"swap",
    "pair":"BTC-USDT",
    "business_type":"swap",
    "op":"notify",
    "topic":"matchOrders_cross.btc-usdt",
    "ts":1639705640671,
    "uid":"123456789",
    "symbol":"BTC",
    "contract_code":"BTC-USDT",
    "status":6,
    "order_id":921337601229725696,
    "order_id_str":"921337601229725696",
    "client_order_id":null,
    "order_type":1,
    "volume":1,
    "trade_volume":1,
    "created_at":1639705601752,
    "direction":"sell",
    "offset":"open",
    "lever_rate":5,
    "price":47800,
    "order_source":"web",
    "order_price_type":"limit",
    "trade":[
        {
            "trade_id":87890603387,
            "id":"87890603387-921337601229725696-1",
            "trade_volume":1,
            "trade_price":47800,
            "trade_turnover":47.8,
            "created_at":1639705640641,
            "role":"maker"
        }
    ],
    "margin_mode":"cross",
    "margin_account":"USDT",
    "is_tpsl":1,
    "reduce_only": 0
}

Pushed Data Parameter

Parameter Name Required Type Desc Value Range
op true string operaton name, fixed as notify;
topic true string topic
ts true long server response timestamp
uid true string uid
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
status true 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 true long order ID
order_id_str true string order ID
client_order_id true long client order ID
order_type true int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
trade_volume true decimal trade volume
volume true decimal order volume
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
lever_rate true int leverage
price true decimal place price
created_at true long created time
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true string type of order price "market": Market Order，"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
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
<trade> true object array
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 linear-swap-api/v1/swap_cross_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 trade price
trade_volume true decimal trade volume
trade_turnover true decimal trade amount
created_at true long created time
role true string taker/maker
</trade>

[Cross] Unsubscribe Match Order Data（unsub）

Remarks

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_cross.$contract_code",

"cid": "id generated by client",

}

Example of a successful unsubscribe request：


{                                    
  "op": "unsub",                     
  "topic": "matchOrders_cross.BTC-USDT",   
  "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, format: matchOrders_cross.$contract_code; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code all: *(swap and future), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe( unsub) ) Rule
matchOrders_cross.* matchOrders_cross.* allowed
matchOrders_cross.contract_code1 matchOrders_cross.* allowed
matchOrders_cross.contract_code1 matchOrders_cross.contract_code1 allowed
matchOrders_cross.contract_code1 matchOrders_cross.contract_code2 Not Allowed
matchOrders_cross.* matchOrders_cross.contract_code1 Not Allowed

[Isolated] Subscribe Account Equity Updates Data(sub)

Remarks

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.$contract_code”

}

Example of a successful subscribe request:


{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "accounts.BTC-USDT"
}

Format illustration on request subscribe account equity updates data

Filed Type Description
op string Required;Operator Name，Operator Name，Subscribe value is sub
cid string Optional; Client requests unique ID
topic string Required;subscribe Topic Name, format: accounts.$contract_code; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code "*" all(it means to subscribe the balance change of all coins), "BTC-USDT"...

Note:

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


{
    "op":"notify",
    "topic":"accounts.btc-usdt",
    "ts":1603711370689,
    "event":"order.open",
    "data":[
        {
            "symbol":"BTC",
            "contract_code":"BTC-USDT",
            "margin_balance":79.72434662,
            "margin_static":79.79484662,
            "margin_position":1.31303,
            "margin_frozen":4.0662,
            "margin_available":74.34511662,
            "profit_real":0.03405608,
            "profit_unreal":-0.0705,
            "withdraw_available":74.34511662,
            "risk_rate":14.745772976801512484,
            "liquidation_price":92163.420962779156327543,
            "lever_rate":10,
            "adjust_factor":0.075,
            "margin_asset":"USDT",
            "margin_mode": "isolated",
            "margin_account": "BTC-USDT",
            "position_mode": "dual_side"
        }
    ],
    "uid":"123456789"
}

Format Illustration of Notification

Field Name Type Description
op string Operator Name，Subscribe value is sub
topic string Subscribe Topic Name
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) (ncluding transfer with exchange accounts, transfer between main account and sub-account, and tranfer between different margin accounts.), system (contract.system), other asset change(other), switch leverage(switch_lever_rate), initial margin(init), ADL trade
<data>
symbol string Coins. "BTC","ETH"...
contract_code string Contract Code
margin_asset string margin asset
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 int Leverage
adjust_factor decimal Adjustment Factor
margin_mode string margin mode isolated : "isolated"
margin_account string margin account "BTC-USDT"...
position_mode string position mode single_side，dual_side
</data>

[Isolated] Unsubscribe Account Equity Updates Data (ubsub)

Remarks

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.$contract_code”,

"cid": "id generated by client”,

}

Example of a successful subscription request


{
  "op": "unsub",
  "topic": "accounts.BTC-USDT",
  "cid": "40sG903yz80oDFWr"
}

Format Illustration on Unsubscribe Account Equity Updates

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, format: accounts.$contract_code; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code "*" all(it means to unsubscribe the balance change of all coins), "BTC-USDT"...

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
accounts.* accounts.* Allowed
accounts.contract_code1 accounts.* Allowed
accounts.contract_code1 accounts.contract_code1 Allowed
accounts.contract_code1 accounts.contract_code2 Not Allowed
accounts.* accounts.contract_code1 Not Allowed

[Cross] Subscribe Account Equity Updates Data（sub）

Remarks

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",

"topic": "accounts_cross.$margin_account",

"cid": "id generated by client",

}

Example of a successful subscribe request: 


{                                   
  "op": "sub",                      
  "cid": "40sG903yz80oDFWr",        
  "topic": "accounts_cross.USDT"       
}

Subscribe Request Parameter

Filed Type Description
op string Required;Operator Name，Subscribe value is sub
cid string Optional; Client requests unique ID
topic string Required;subscribe Topic Name, format: accounts_cross.$margin_account; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
margin_account true string margin account "*" all(it means to subscribe the balance change of all coins), "USDT"...

Note:

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


{
    "op":"notify",
    "topic":"accounts_cross",
    "ts":1640756528985,
    "event":"snapshot",
    "data":[
        {
            "margin_mode":"cross",
            "margin_account":"USDT",
            "margin_asset":"USDT",
            "margin_balance":20.60340161555383535,
            "margin_static":20.47570161555383535,
            "margin_position":19.30352,
            "margin_frozen":0,
            "profit_real":-0.01911684,
            "profit_unreal":0.1277,
            "withdraw_available":1.17218161555383535,
            "risk_rate":25.683477437733940947,
            "position_mode": "dual_side",
            "contract_detail":[
                {
                    "symbol":"BTC",
                    "contract_code":"BTC-USDT",
                    "margin_position":9.55638,
                    "margin_frozen":0,
                    "margin_available":1.29988161555383535,
                    "profit_unreal":-0.0102,
                    "liquidation_price":27790.709661740085332661,
                    "lever_rate":5,
                    "adjust_factor":0.04,
                    "contract_type":"swap",
                    "pair":"BTC-USDT",
                    "business_type":"swap"
                }
            ],
            "futures_contract_detail":[
                {
                    "symbol":"BTC",
                    "contract_code":"BTC-USDT-220325",
                    "margin_position":9.74714,
                    "margin_frozen":0,
                    "margin_available":1.29988161555383535,
                    "profit_unreal":0.1379,
                    "liquidation_price":28744.509661740085332661,
                    "lever_rate":5,
                    "adjust_factor":0.04,
                    "contract_type":"quarter",
                    "pair":"BTC-USDT",
                    "business_type":"futures"
                }
            ]
        }
    ],
    "uid":"123456789"
}

Pushed Data Parameter

Parameter Name Required Type Desc Data Value
op true string operaton name, fixed as notify;
topic true string topic
ts true long server response timestamp
uid true string uid
event true string event of margin account update order.open 、order.match 、settlement、order.liquidation、order.cancel 、contract.transfer、ontract.system、other 、init、napshot 、ADL trade
<data> true object array
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
margin_asset true string margin asset
margin_balance true decimal account equity
margin_static true decimal static margin
margin_position true decimal position margin (the margin used by current positions)
margin_frozen true decimal frozen margin
profit_real true decimal realized profits and losses
profit_unreal true decimal unrealized profits and losses
withdraw_available true decimal available transfer amount
risk_rate true decimal margin rate
position_mode true string position mode single_side，dual_side
<contract_detail> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"...
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_unreal true decimal unrealized profits and losses
liquidation_price true decimal estimated liquidation price
lever_rate true decimal lever rate
adjust_factor true decimal adjustment factor
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</contract_detail>
<futures_contract_detail> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code future: "BTC-USDT-210625" ...
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_unreal true decimal unrealized profits and losses
liquidation_price true decimal estimated liquidation price
lever_rate true decimal lever rate
adjust_factor true decimal adjustment factor
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</futures_contract_detail>
</data>

[Cross] Unsubscribe Account Equity Updates Data（unsub）

Remarks

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_cross.$margin_account",

"cid": "id generated by client",

}

Example of a successful subscription request


{                                 
  "op": "unsub",                  
  "topic": "accounts_cross.USDT",    
  "cid": "40sG903yz80oDFWr"       
}

Unsubscribe Request Parameter

Filed Type Description
op string Required;Operator Name，Unsubscribe value is unsub
cid string Optional; Client requests unique ID
topic string Required;unsubscribe Topic Name, format: accounts_cross.$margin_account; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
margin_account true string margin account "*" all(it means to unsubscribe the balance change of all coins), "USDT"...

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
accounts_cross.* accounts_cross.* Allowed
accounts_cross.margin_account1 accounts_cross.* Allowed
accounts_cross.margin_account1 accounts_cross.margin_account1 Allowed
accounts_cross.margin_account1 accounts_cross.margin_account2 Not Allowed
accounts_cross.* accounts_cross.margin_account1 Not Allowed

[Isolated] Subscribe Position Updates(sub)

Remarks

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.$contract_code”

}

Example of a successful subscribe request:


{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "positions.BTC-USDT"
}

Format Illustration of Subscribe Position Updates

Filed Name type desc
op string Required； Operator Name，Subscribe value is sub;
cid string Optional; ID Client requests unique ID
topic string Required; subscribe Topic Name，format: positions.$contract_code; For parameter details please check req unsubscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code "*" all(it means to subscribe the all positions) "BTC-USDT"...

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



{
    "op":"notify",
    "topic":"positions",
    "ts":1603711371803,
    "event":"snapshot",
    "data":[
        {
            "symbol":"BTC",
            "contract_code":"BTC-USDT",
            "volume":1,
            "available":0,
            "frozen":1,
            "cost_open":13059.8,
            "cost_hold":13059.8,
            "profit_unreal":-0.0705,
            "profit_rate":-0.05398244996094886,
            "profit":-0.0705,
            "position_margin":1.31303,
            "lever_rate":10,
            "direction":"sell",
            "last_price":13130.3,
            "margin_asset":"USDT",
            "margin_mode": "isolated",
            "margin_account": "BTC-USDT",
            "position_mode": "dual_side"
        }
    ],
    "uid":"123456789"
}

Return Parameter Illustration

Filed Name Type Description
op string Required;Operator Name ;
topic string Required; 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). , ADL trade
<data>
symbol string Coin. "BTC","ETH"...
contract_code string Contract Code
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 int Leverage
direction string transaction direction of positions "buy":long "sell":short
last_price decimal Last Price
margin_asset string Margin Asset
margin_mode string margin mode isolated : "isolated"
margin_account string margin account "BTC-USDT"...
position_mode string position mode single_side，dual_side
</data>

Note:

[Isolated] Unsubscribe Position Updates Data(unsub)

Remarks

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.$contract_code”,

"cid": "id generated by client”,

}

Example of a successful unsubscribe request:


{
  "op": "unsub",
  "topic": "positions.BTC-USDT",
  "cid": "40sG903yz80oDFWr"
}

Format Illustration of Unsubscribe Position Updates

Filed Name type desc
op string Required； Operator Name，unsubscribe value is unsub;
cid string Optional; ID Client requests unique ID
topic string Required; unsubscribe Topic Name，format: positions.$contract_code; For parameter details please check req unsubscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code "*" all(it means to unsubscribe the all positions) "BTC-USDT"...

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(ubsub) Rule
positions.* positions.* Allowed
positions.contract_code1 positions.* Allowed
positions.contract_code1 positions.contract_code1 Allowed
positions.contract_code1 positions.contract_code2 Not Allowed
positions.* positions.symbol1 Not Allowed

[Cross] Subscribe Position Updates（sub）

Remarks

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",

"topic": "positions_cross.$contract_code",

"cid": "topic to sub"

}

Example of a successful subscribe request:


{                                 
  "op": "sub",                    
  "cid": "40sG903yz80oDFWr",      
  "topic": "positions_cross.BTC-USDT"    
}

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； Subscribe Topic, Subscribe (positions_cross.$contract_code) Required Subscribe/unsubscribe the position data of a single coin, For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code all: *(swap and future), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

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


{
    "op":"notify",
    "topic":"positions_cross.btc-usdt",
    "ts":1639107468139,
    "event":"order.match",
    "data":[
        {
            "contract_type":"swap",
            "pair":"BTC-USDT",
            "business_type":"swap",
            "symbol":"BTC",
            "contract_code":"BTC-USDT",
            "volume":1,
            "available":1,
            "frozen":0,
            "cost_open":48284.9,
            "cost_hold":48284.9,
            "profit_unreal":-0.0001,
            "profit_rate":-0.000010355204214985,
            "profit":-0.0001,
            "margin_asset":"USDT",
            "position_margin":9.65696,
            "lever_rate":5,
            "direction":"buy",
            "last_price":48284.8,
            "margin_mode":"cross",
            "margin_account":"USDT",
            "position_mode": "dual_side"
        }
    ],
    "uid":"123456789"
}

Pushed Data Parameter

Parameter Name Required Type Desc Data Value
op true string operaton name, fixed as notify;
topic true string topic
ts true long server response timestamp
uid true string uid
event true string event order.close 、order.match、settlement、order.liquidation、order.cancel、init、snapshot、ADL trade
<data> true object array
symbol true string symbol "BTC","ETH"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
volume true decimal position quantity
available true decimal positions available to close
frozen true decimal positions frozen
cost_open true decimal opening average price
cost_hold true decimal average price of position
profit_unreal true decimal unrealized profits and losses
profit_rate true decimal profit rate
profit true decimal profit
margin_asset true string margin asset
position_margin true decimal position margin
lever_rate true int leverage
direction true string transaction direction of positions "buy":long "sell":short
last_price true decimal latest trade price
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
position_mode true string position mode single_side，dual_side
</data>

Note:

[Cross] Unsubscribe Position Updates Data（unsub）

Remarks

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_cross.$contract_code",

"cid": "id generated by client",

}

Example of a successful unsubscribe request:


{                                    
  "op": "unsub",                     
  "topic": "positions_cross.BTC-USDT",      
  "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;Required；Required；Subscribe topic，Subscribe positions_cross.$contract_code required Subscribe or unsubscribe the position updates of a single coin; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code all: *(swap and future), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(ubsub) Rule
positions_cross.* positions_cross.* Allowed
positions_cross.contract_code1 positions_cross.* Allowed
positions_cross.contract_code1 positions_cross.contract_code1 Allowed
positions_cross.contract_code1 positions_cross.contract_code2 Not Allowed
positions_cross.* positions_cross.contract_code1 Not Allowed

[General] Subscribe Liquidation Orders (no authentication) (sub)

Remarks

Subscription Request Format of Liquidation order data

{

“op”: “sub”,

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

"cid": "id generated by client”,

}

Example of a successful subscription request:


{
  "op": "sub",
  "cid": "40sG903yz80oDFWr",
  "topic": "public.BTC-USDT.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.$contract_code.liquidation_orders. For parameter details please check req Subscribe Parameter
business_type string business type, default is swap: futures, swap, all

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code all: *(more see remarks), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Remarks

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


{
    "op":"notify",
    "topic":"public.O3-USDT.liquidation_orders",
    "ts":1639122193214,
    "data":[
        {
            "symbol":"O3",
            "contract_code":"O3-USDT",
            "direction":"sell",
            "offset":"close",
            "volume":432,
            "price":0.7858,
            "created_at":1639122193172,
            "amount":432,
            "trade_turnover":339.4656,
            "contract_type":"swap",
            "pair":"O3-USDT",
            "business_type":"swap"
        }
    ]
}

Return Parameter

Field Name Type Description
op string value: 'notify';
topic string topic subscribed
ts long Time of Respond Generation，Unit：Millisecond
<data> object array
symbol string symbol
contract_code string swap code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
direction string Long or short
offset string Open, close, both
volume decimal liquidation volume (Cont.)
amount decimal liquidation amount (token)
trade_turnover decimal liquidation amount (quotation token)
price decimal bankruptcy price
created_at long Order Creation Time
contract_type string contract type: swap, this_week, next_week, quarter, next_quarter
pair string pair, such as: “BTC-USDT”
business_type string business type: futures, swap
</data> object array

[General] Unsubscribe Liquidation Order Data (unsub)

Remarks

Unsubscribe Request Format

{

“op”: “unsub”,

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

"cid": "id generated by client”,

}

Example of a successful unsubscribe request :


{
  "op": "unsub",
  "topic": "public.BTC-USDT.liquidation_orders”",
  "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 Subscribe topic name，Require subscribe public.$contract_code.liquidation_orders Subscribe/unsubscribe the data of a given coin; For parameter details please check req Subscribe Parameter
business_type string business type, default swap: futures,swap,all

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code all: *(more see remarks), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Note

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
public.*.liquidation_orders public.*.liquidation_orders Allowed
public.contract_code1.liquidation_orders public.*.liquidation_orders Allowed
public.contract_code1.liquidation_orders public.contract_code1.liquidation_orders Allowed
public.contract_code1.liquidation_orders public.contract_code2. liquidation_orders Not Allowed
public.*.liquidation_orders public.contract_code1.liquidation_orders Not Allowed

[General] Subscribe funding rate (no authentication)（sub）

Remarks

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

{

"op": "sub",

"cid": "40sG903yz80oDFWr",

"topic": "public.$contract_code.funding_rate"

}

Request


{
  "op": "sub",
  "topic": "public.BTC-USDT.funding_rate",
  "cid": "40sG903yz80oDFWr"
}

Data format illustration of orders subscription

Filed Name type desc
op string Required； Operator Name，required subscribe value is sub
cid string Optional; ID Client requests unique ID
topic string Required; subscribe Topic Name，format: public.$contract_code.funding_rate; For parameter details please check req unsubscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code "*" all(it means to subscribe the all funding rate) "BTC-USDT"...

Response example when funding_rate is updated:


{
    "op":"notify",
    "topic":"public.BTC-USDT.funding_rate",
    "ts":1603778748166,
    "data":[
        {
            "symbol":"BTC",
            "contract_code":"BTC-USDT",
            "fee_asset":"USDT",
            "funding_time":"1603778700000",
            "funding_rate":"-0.000220068774978695",
            "estimated_rate":"-0.000684397270167616",
            "settlement_time":"1603785600000"
        }
    ]
}

Response data fields

Field Name Type Description
op string value: "notify";
topic string topic subscribed
ts long timestamp of server response.unit: millionseconds
<data> object array
symbol string symbol,"BTC","ETH"...
contract_code string contract_code,"BTC-USDT"
fee_asset string fee asset,"USDT"...
funding_time string current funding time
funding_rate string current funding rate
estimated_rate string estimated funding rate of next period
settlement_time string settlement timestamp.eg:"1490759594752"
</data>

[General] Unsubscribe Funding Rate Data(no authentication)(unsub)

Remarks

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

request format of unsubscribing funding rate

{

"op": "unsub",

"topic": "public.$contract_code.funding_rate",

"cid": "id generated by client",

}

example of unsubscribing funding rate::


{                                    
  "op": "unsub",                     
  "topic": "public.BTC-USDT.funding_rate",   
  "cid": "40sG903yz80oDFWr"          
}

request field desc of unsubscrbing funding rate

Filed Name type desc
op string Required； Operator Name，required unsubscribe value is unsub
cid string Optional; ID Client requests unique ID
topic string Required; unsubscribe Topic Name，format: public.$contract_code.funding_rate; For parameter details please check req unsubscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code "*" all(it means to unsubscribe the all funding rate) "BTC-USDT"...

Data format of subscription and unsubscription of funding rate

subscribe(sub) unsubscribe(unsub) rules
public.*.funding_rate pubic.*.funding_rate allowd
public.contract_code1.funding_rate public.*.funding_rate allowed
public.contract_code1.funding_rate public.contract_code1.funding_rate allowed
public.contract_code1.funding_rate public.contract_code2.funding_rate not allowed
public.*.funding_rate public.contract_code1.funding_rate not allowed

Note

[General] Subscribe Contract Info (no authentication)（sub）

Remarks

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

{

"op": "sub",

"cid": "40sG903yz80oDFWr",

"topic": "public.$contract_code.contract_info"

}

example of unsubscribing funding rate::


{                                    
  "op": "sub",                     
  "topic": "public.btc-usdt.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.$contract_code.contract_info. For parameter details please check req Subscribe Parameter
business_type string business type, default is swap , futures, swap, all

Request Parameter：

Parameter Name Mandotary Type Desc Default Value Range
contract_code true string contract code all: *(swap and future), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Remarks

Response example：


{
    "op":"notify",
    "topic":"public.*.contract_info",
    "ts":1639122053894,
    "event":"init",
    "data":[
        {
            "symbol":"MANA",
            "contract_code":"MANA-USDT",
            "contract_size":10,
            "price_tick":0.0001,
            "settlement_date":"1639123200000",
            "create_date":"20210129",
            "contract_status":1,
            "support_margin_mode":"all",
            "delivery_time":"",
            "contract_type":"swap",
            "business_type":"swap",
            "pair":"MANA-USDT",
            "delivery_date":""
        },
        {
            "symbol":"NKN",
            "contract_code":"NKN-USDT",
            "contract_size":10,
            "price_tick":0.00001,
            "settlement_date":"1639123200000",
            "create_date":"20210810",
            "contract_status":1,
            "support_margin_mode":"all",
            "delivery_time":"",
            "contract_type":"swap",
            "business_type":"swap",
            "pair":"NKN-USDT",
            "delivery_date":""
        }
    ]
}

Response data fields

Field Name Type Description
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, swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
contract_size decimal Contract Value (USDT of one contract). such as 10,100
price_tick decimal Minimum Variation of Contract Price
settlement_date string settlement date：such as "1490759594752"
create_date string Contract Listing Date ：such as "20180706"
delivery_time string delivery time（When the contract does not need to be delivered, the field value is an empty string），millesecond timestamp
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
support_margin_mode string support margin mode cross："cross"；isolated："isolated"；all："all"
contract_type string contract type swap, this_week, next_week, quarter, next_quarter
pair string pair such as: “BTC-USDT”
business_type string business type futures, swap
delivery_date string delivery date, empty string when swap , such as: "20180720"
</data> object array

Note：

[General] Unsubscribe Contract Info Data(no authentication)(unsub)

Remarks

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.$contract_code.contract_info",

"cid": "id generated by client",

}

example of unsubscribing contract info::


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

request field desc of unsubscrbing contract info

field datatype desc
op string Required; Operator Name，unsubscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Subscribe topic name，Require subscribe public.$contract_code.contract_info Subscribe/unsubscribe the data of a given contract code; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Default Value Range
contract_code true string contract code all: *(swap and future), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Note：

Data format of subscription and unsubscription of contract info

subscribe(sub) unsubscribe(unsub) rules
public.*.contract_info pubic.*.contract_info Allowed
public.contract_code1.contract_info public.*.contract_info Allowed
public.contract_code1.contract_info public.contract_code1.contract_info Allowed
public.contract_code1.contract_info public.contract_code2.contract_info Not Allowed
public.*.contract_info public.contract_code1.contract_info Not Allowed

[Isolated] Subscribe trigger orders updates(sub)

Remarks

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.$contract_code"

}

Example of a successful return data:


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

Request Parameter

Filed Name type desc
op string Required； Operator Name，required subscribe value is sub
cid string Optional; ID Client requests unique ID
topic string Required; subscribe Topic Name，format: trigger_order.$contract_code; For parameter details please check req unsubscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code "*" all(it means to subscribe the all trigger order) "BTC-USDT"...

Return example:


{
    "op":"notify",
    "topic":"trigger_order.btc-usdt",
    "ts":1603778055069,
    "event":"order",
    "uid":"123456789",
    "data":[
        {
            "symbol":"BTC-USDT",
            "contract_code":"BTC-USDT",
            "trigger_type":"ge",
            "volume":1,
            "order_type":1,
            "direction":"sell",
            "offset":"open",
            "lever_rate":10,
            "order_id":5,
            "order_id_str":"5",
            "relation_order_id":"-1",
            "order_price_type":"limit",
            "status":2,
            "order_source":"web",
            "trigger_price":15000,
            "triggered_price":null,
            "order_price":15000,
            "created_at":1603778055064,
            "triggered_at":0,
            "order_insert_at":0,
            "canceled_at":0,
            "fail_code":null,
            "fail_reason":null,
            "margin_mode": "isolated",
            "margin_account": "BTC-USDT",
            "reduce_only": 0
        }
    ]
}

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_code true string contract code "BTC-USDT" ...
trigger_type true string trigger type： ge great than or equal to；le less 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,both]
lever_rate true int Leverage
order_id true decimal 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 system、web、api、m、risk、settlement、ios、android、windows、mac、trigger
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
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
reduce_only true int reduce only 0: no, 1: yes
</data>

Rules:

[Isolated] Unsubscribe trigger orders updates（unsub）

Remarks

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.$contract_code",

"cid": "id generated by client",

}

Example of a successful unsubscribe request:


{                                    
  "op": "unsub",                     
  "topic": "trigger_order.BTC-USDT",   
  "cid": "40sG903yz80oDFWr"          
}

Format illustration of unsubscribe order data

Filed Name type desc
op string Required； Operator Name，required unsubscribe value is unsub
cid string Optional; ID Client requests unique ID
topic string Required; unsubscribe Topic Name，format: trigger_order.$contract_code; For parameter details please check req unsubscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Value Range
contract_code true string contract code "*" all(it means to unsubscribe the all trigger order) "BTC-USDT"...

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe( unsub) Rule
trigger_order.* trigger_order.* Allowed
trigger_order.contract_code1 trigger_order.* Allowed
trigger_order.contract_code1 trigger_order.contract_code1 Allowed
trigger_order.contract_code1 trigger_order.contract_code2 Not Allowed
trigger_order.* trigger_order.contract_code1 Not Allowed

[Cross] Subscribe trigger orders updates(sub)

Remarks

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_cross.$contract_code"

}

Example of a successful return data:


{
  "op": "sub",
  "topic": "trigger_order_cross.BTC-USDT",
  "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_cross.$contract_code; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Default Value Range
contract_code true string contract code all: *(swap and future), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Return example:


{
    "op":"notify",
    "topic":"trigger_order_cross.*",
    "ts":1639123353369,
    "event":"order",
    "uid":"123456789",
    "data":[
        {
            "contract_type":"swap",
            "pair":"BTC-USDT",
            "business_type":"swap",
            "symbol":"BTC",
            "contract_code":"BTC-USDT",
            "trigger_type":"le",
            "volume":1,
            "order_type":1,
            "direction":"buy",
            "offset":"open",
            "lever_rate":1,
            "order_id":918895474461802496,
            "order_id_str":"918895474461802496",
            "relation_order_id":"-1",
            "order_price_type":"limit",
            "status":2,
            "order_source":"api",
            "trigger_price":40000,
            "triggered_price":null,
            "order_price":40000,
            "created_at":1639123353364,
            "triggered_at":0,
            "order_insert_at":0,
            "canceled_at":0,
            "fail_code":null,
            "fail_reason":null,
            "margin_mode":"cross",
            "margin_account":"USDT",
            "reduce_only": 0
        }
    ]
}

Pushed Data Parameter

Parameter Name Required Type Desc Data Value
op true string operaton name, fixed as notify
topic true string topic
ts true long Time of Respond Generation, Unit: Millisecond
uid true string uid
event true string event order，cancel，trigger_success，trigger_fail
<data> true object array
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
trigger_type true string trigger type： ge great than or equal to；le less than or equal to
volume true decimal place volume
order_type true int order type 1. Place orders
direction true string direction "buy"/"sell"
offset true string "open", "close" "open","close",both
lever_rate true int leverage
order_id true decimal order ID
order_id_str true string order ID
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 type of order price "limit"，"optimal_5"，"optimal_10"，"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 system、web、api、m、risk、settlement、ios、android、windows、mac、trigger
trigger_price true decimal trigger price
triggered_price true decimal triggered price
order_price true decimal order price
created_at true long created time
triggered_at true long triggered time
order_insert_at true long insert time
canceled_at true long canceled time
fail_code true int fail code
fail_reason true string fail reason
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</data>

Rules:

[Cross] Unsubscribe trigger orders updates（unsub）

Remarks

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_cross.$contract_code",

"cid": "id generated by client",

}

Example of a successful unsubscribe request:


{                                    
  "op": "unsub",                     
  "topic": "trigger_order_cross.BTC-USDT",   
  "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 Optional; Unsubscribe Topic Name，format: trigger_order_cross.$contract_code; For parameter details please check req Subscribe Parameter

Request Parameter：

Parameter Name Mandotary Type Desc Default Value Range
contract_code true string contract code all: *(swap and future), swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe( unsub) Rule
trigger_order_cross.* trigger_order_cross.* Allowed
trigger_order_cross.contract_code1 trigger_order_cross.* Allowed
trigger_order_cross.contract_code1 trigger_order_cross.contract_code1 Allowed
trigger_order_cross.contract_code1 trigger_order_cross.contract_code2 Not Allowed
trigger_order_cross.* trigger_order_cross.contract_code1 Not Allowed

WebSocket interface for system status updates

[General]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.linear-swap.heartbeat"
}

Request Parameter:

Name Required 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 Required Type Desc Value Range
service true string Business Code linear-swap : USDT Margined Contracts

Return Parameter Example:


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

Return Parameter Rules：

Name Required 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(maintenance with service suspended)
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.$contract_code sub,ubsub Subscribe/unsubscribe the order data of a given pair; when the $contract_code 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.
2007 You don’t have access permission as you have not opened contracts trading.
2010 Topic error.
2011 Contract doesn't exist.
2012 Topic not subscribed.
2013 Authentication type doesn't exist.
2014 Repeated subscription.
2020 This contract does not support cross margin mode.
2021 Illegal parameter margin_account.
2030 Exceeds connection limit of single user.
2040 Missing required parameter.

Will be offline

[General] Query account financial records

Remarks

Request Parameters

Parameter name Must fill or not Type Description Value range
margin_account true string Margin currency "BTC-USDT","USDT"(in cross mode)...
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
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; 30:Funding fee-income; 31:Funding fee-expenditure; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master; 38:Transfer in from another margin account; 39:Transfer out to another margin account; 46:ADL close long; 47:ADL close short
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

Note:

Response:


{
    "status": "ok",
    "data": {
        "total_page": 1,
        "current_page": 1,
        "total_size": 2,
        "financial_record": [
            {
                "id": 117840,
                "type": 5,
                "amount": -0.024464850000000000,
                "ts": 1638758435635,
                "contract_code": "BTC-USDT-211210",
                "asset": "USDT",
                "margin_account": "USDT",
                "face_margin_account": ""
            },
            {
                "id": 10328,
                "type": 29,
                "amount": 10000.000000000000000000,
                "ts": 1638517931516,
                "contract_code": "",
                "asset": "USDT",
                "margin_account": "USDT",
                "face_margin_account": ""
            }
        ]
    },
    "ts": 1638759621932
}

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 Financial record ID (contract code unqiue)
ts true long create time
asset true string asset "USDT"...
contract_code true string contract type code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_account true string margin account "BTC-USDT","USDT"...
face_margin_account true string The counterparty margin account only has value when the type transaction type are 34, 35, 36, 37, 38, 39; for other types, the field values are empty strings. "BTC-USDT"...
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; 30:Funding fee-income; 31:Funding fee-expenditure; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master; 38:Transfer in from another margin account; 39:Transfer out to another margin account; 46:ADL close long; 47:ADL close short
amount true decimal amount
</financial_record>
total_page true int total page
current_page true int current page
total_size true int total size
</data>

[General]Query account financial records via Multiple Fields

Note：

Request Parameter

Parameter Name Required Type Description Value Range
margin_account true string margin account "BTC-USDT","USDT"(in cross mode)...
contract_code false string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
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; 30:Funding fee-income; 31:Funding fee-expenditure; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master; 38:transfer from other margin account; 39:transfer to another margin account; 46:ADL close long; 47:ADL close short
start_time false long start time(timestamp in millisecond) more detail sees the follow note
end_time false long end time(timestamp in millisecond) more detail sees the follow note
from_id false long from id(value from the query_id in return data)
size false int size default is 20, 50 at most
direct false string direct prev/next；default is 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": 117840,
                "type": 5,
                "amount": -0.024464850000000000,
                "ts": 1638758435635,
                "contract_code": "BTC-USDT-211210",
                "asset": "USDT",
                "margin_account": "USDT",
                "face_margin_account": ""
            },
            {
                "id": 10328,
                "type": 29,
                "amount": 10000.000000000000000000,
                "ts": 1638517931516,
                "contract_code": "USDT-USD",
                "asset": "USDT",
                "margin_account": "USDT",
                "face_margin_account": ""
            }
        ],
        "remain_size": 0,
        "next_id": null
    },
    "ts": 1638759705140
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string result of server handled request "ok" , "error"
ts true long Time of Respond Generation，Unit：Millisecond
<data> true object
<financial_record> true object array
id true long
ts true long create time
asset true string asset "USDT"...
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_account true string margin account "BTC-USDT","USDT"...
face_margin_account true string the counterparty margin account, only has value when the transaction Type is 34, 35, 36, 37, 38, 39, and the other types are empty strings "BTC-USDT"...
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; 30:Funding fee-income; 31:Funding fee-expenditure; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master; 38:transfer from other margin account; 39:transfer to another margin account; 46:ADL close long; 47:ADL close short
amount true decimal amount(quote currency)
</financial_record>
remain_size true int remain size(In the time range, the size that was not queried due to size restrictions)
next_id true long query_id for next data(It only has a value when the query result exceeds the size limit)
</data>

Note:

[Cross]Get History Match Results via Multiple Fields

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions, 17:buy(one-way mode), 18:sell(one-way mode)
start_time false long start time(timestamp in millisecond) more detail sees the follow note
end_time false long end time(timestamp in millisecond) more detail sees the follow note
from_id false long from id(value from the query_id in return data)
size false int size default is 20, 50 at most
direct false string direct prev/next；default is 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": [
            {
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures",
                "query_id": 136966,
                "match_id": 2902136,
                "order_id": 918800256249405440,
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "direction": "buy",
                "offset": "open",
                "trade_volume": 100.000000000000000000,
                "trade_price": 48555.600000000000000000,
                "trade_turnover": 4855.560000000000000000,
                "trade_fee": -2.427780000000000000,
                "offset_profitloss": 0E-18,
                "create_date": 1639100651577,
                "role": "Taker",
                "order_source": "api",
                "order_id_str": "918800256249405440",
                "id": "2902136-918800256249405440-1",
                "fee_asset": "USDT",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "real_profit": 0E-18,
                "reduce_only": 0
            }
        ],
        "remain_size": 0,
        "next_id": null
    },
    "ts": 1639102308193
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string result of server handled request
<data> true object
<trades> true object array
id true string unique id of the trade, and match_id is not unique id. The specific method of use is to use match_id and id as the joint primary key to form a unique transaction ID.
query_id true long Query id, which can be used as the from_id field for the next query request.
match_id true long matching result id, not unique, may be repeated
order_id true long order id
order_id_str true string order id in string
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross；
margin_account true string margin account such as:USDT”
direction true string direction向 "buy"/"sell"
offset true string offset "open","close","both"
trade_volume true decimal trade volume
trade_price true decimal trade price
trade_turnover true decimal trade turnover
create_date true long create date
offset_profitloss true decimal profit or loss when cloase position
real_profit true decimal real profit
trade_fee true decimal trade fee
role true string taker or maker
fee_asset true string fee asset ("USDT"...)
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</trades>
remain_size true int remain size(In the time range, the size that was not queried due to size restrictions)
next_id true long query_id for next data(It only has a value when the query result exceeds the size limit)
</data>
ts true long timestamp

Note：

[Cross] Get History Match Results

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions; 17.buy(one-way mode); 18.sell(one-way mode)
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 index, default 1st page
page_size false int default 20，no more than 50

Response


{
    "status": "ok",
    "data": {
        "trades": [
            {
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures",
                "match_id": 2902136,
                "order_id": 918800256249405440,
                "symbol": "BTC",
                "contract_code": "BTC-USDT-211210",
                "direction": "buy",
                "offset": "open",
                "trade_volume": 100.000000000000000000,
                "trade_price": 48555.600000000000000000,
                "trade_turnover": 4855.560000000000000000,
                "trade_fee": -2.427780000000000000,
                "offset_profitloss": 0E-18,
                "create_date": 1639100651577,
                "role": "Taker",
                "order_source": "api",
                "order_id_str": "918800256249405440",
                "id": "2902136-918800256249405440-1",
                "fee_asset": "USDT",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "real_profit": 0E-18,
                "reduce_only": 0
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 5
    },
    "ts": 1639102170045
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result
<data> true object
<trades> true object array
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
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_cross.$contract_code 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 symbol
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
trade_volume true decimal trade quantity
trade_price true decimal trade price
trade_turnover true decimal trade amount
create_date true long trade time
offset_profitloss true decimal profits and losses generated from closing positions(calculated with the average price of position, exclude profit in history settlement.)
trade_fee true decimal trade fee
role true string taker/maker
fee_asset true string fee asset （"USDT"...）
real_profit true decimal real profit (calculated with the opening average price, include profit in history settlement.)
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</trades>
current_page true int current page
total_page true int total page
total_size true int total size
</data>
ts true long timestamp

Note:

[Isolated]Get History Match Results via Multiple Fields

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code "BTC-USDT"...
trade_type true int trade type 0:All; 1: Open long; 2: Open short; 3: Close short; 4: Close long; 5: Liquidate long positions; 6: Liquidate short positions; 17.buy(one-way mode); 18.sell(one-way mode)
start_time false long start time(timestamp in millisecond) more detail sees the follow note
end_time false long end time(timestamp in millisecond) more detail sees the follow note
from_id false long from id(value from the query_id in return data)
size false int size default is 20, 50 at most
direct false string direct prev/next；default is 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": 138798248,
                "match_id": 13752484857,
                "order_id": 807038270541733888,
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "direction": "buy",
                "offset": "close",
                "trade_volume": 9,
                "trade_price": 36580,
                "trade_turnover": 329.22,
                "trade_fee": -0.131688,
                "offset_profitloss": 0.3636,
                "create_date": 1612454517757,
                "role": "Taker",
                "order_source": "android",
                "order_id_str": "807038270541733888",
                "id": "13752484857-807038270541733888-1",
                "fee_asset": "USDT",
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "real_profit": 0.2394,
                "reduce_only": 0
            }
        ],
        "remain_size": 0,
        "next_id": null
    },
    "ts": 1612503560490
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string result of server handled request
<data> true object
<trades> true object array
id true string unique id of the trade, and match_id is not unique id. The specific method of use is to use match_id and id as the joint primary key to form a unique transaction ID.
query_id true long Query id, which can be used as the from_id field for the next query request.
match_id true long matching result id, not unique, may be repeated
order_id true long order id
order_id_str true string order id in string
symbol true string symbol
contract_code true string contract code "BTC-USDT" ...
margin_mode true string margin mode isolated: isolated
margin_account true string margin account such as:BTC-USDT”
direction true string direction向 "buy"/"sell"
offset true string offset "open","close","both"
trade_volume true decimal trade volume
trade_price true decimal trade price
trade_turnover true decimal trade turnover
create_date true long create date
offset_profitloss true decimal profit or loss when close position
real_profit true decimal real profit
trade_fee true decimal trade fee
role true string taker or maker
fee_asset true string fee asset ("USDT"...)
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
reduce_only true int reduce only 0: no, 1: yes
</trades>
remain_size true int remain size(In the time range, the size that was not queried due to size restrictions)
next_id true long query_id for next data(It only has a value when the query result exceeds the size limit)
</data>
ts true long timestamp

Note：

[Isolated] Acquire History Match Results

Remarks

Request Parameter

Parameter Name Required Type Desc Default Value Range
contract_code true string Contract Code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT".
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, 17:buy(one-way mode), 18:sell(one-way mode)
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; 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": 131560927,
                "order_id": 770334322963152896,
                "symbol": "BTC",
                "contract_code": "BTC-USDT",
                "direction": "sell",
                "offset": "open",
                "trade_volume": 1.000000000000000000,
                "trade_price": 13059.800000000000000000,
                "trade_turnover": 13.059800000000000000,
                "trade_fee": -0.005223920000000000,
                "offset_profitloss": 0,
                "create_date": 1603703614715,
                "role": "Taker",
                "order_source": "api",
                "order_id_str": "770334322963152896",
                "id": "131560927-770334322963152896-1",
                "fee_asset": "USDT",
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "real_profit": 0,
                "reduce_only": 0
            }
        ],
        "total_page": 2,
        "current_page": 1,
        "total_size": 2
    },
    "ts": 1603704407235
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string request handling result
<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.$contract_code 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 system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
contract_code true string contract code "BTC-USDT" ...
direction true string "buy": to bid/ go long; "sell": to ask/ go short.
offset true string "open": open positions; "close": close positions , "both"
trade_volume true int the number of traded contract with unit of lot
trade_price true decimal the price at which orders get filled
trade_turnover true int the number of total traded amout with number of USDT
create_date true long the time when orders get filled
offset_profitloss true decimal profits and losses generated from closing positions(calculated with the average price of position, exclude profit in history settlement.)
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 "USDT"...
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
real_profit true decimal real profit (calculated with the opening average price, include profit in history settlement.)
reduce_only true int reduce only 0: no, 1: yes
</trades>
total_page true int total pages
current_page true int current page
total_size true int total size of the list
</data>
ts true long timestamp

Notice

[Cross] Get History Orders

Remarks

Request Parameter

Parameter Name Required Type Desc Data Value
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade 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, 17:buy(one-way mode), 18:sell(one-way mode)
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 index, default 1st page
page_size false int page size, default 20 no more than 50
sort_by false string sort fields(Default: “create_date” descending order) "create_date"：descending order by order create date , "update_time": descending order by order update time

Note:

Response

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures",
                "order_id": 918800256249405440,
                "contract_code": "BTC-USDT-211210",
                "symbol": "BTC",
                "lever_rate": 5,
                "direction": "buy",
                "offset": "open",
                "volume": 100.000000000000000000,
                "price": 48555.600000000000000000,
                "create_date": 1639100651569,
                "order_source": "api",
                "order_price_type": 3,
                "order_type": 1,
                "margin_frozen": 0E-18,
                "profit": 0E-18,
                "trade_volume": 100.000000000000000000,
                "trade_turnover": 4855.560000000000000000,
                "fee": -2.427780000000000000,
                "trade_avg_price": 48555.6000,
                "status": 6,
                "order_id_str": "918800256249405440",
                "fee_asset": "USDT",
                "liquidation_type": "0",
                "margin_asset": "USDT",
                "margin_mode": "cross",
                "margin_account": "USDT",
                "update_time": 1639100651000,
                "is_tpsl": 0,
                "real_profit": 0,
                "reduce_only": 0
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 4
    },
    "ts": 1639101888331
}

Returning Parameter

Parameter Name Required Type Desc Data Value
status true string Request Processing Result
<data> true object
<orders> true object array
order_id true long order ID
order_id_str true string order ID
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross: cross margin mode
margin_account true string margin account "USDT"...
lever_rate true int leverage
direction true string direction "buy"/"sell"
offset true string "open", "close" "open","close","both"
volume true decimal place volume
price true decimal place price
create_date true long created time
update_time true long order update time，millesecond timestamp
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true int type of order price 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_asset true string margin asset
margin_frozen true decimal frozen margin
profit true decimal profit when close position (calculated with the average price of position, exclude profit in history settlement.)
trade_volume true decimal trade quantity
trade_turnover true decimal trade amount
fee true decimal service fee
trade_avg_price true decimal trade average price
status true int order status
order_type true int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
fee_asset true string fee asset （"USDT"...）
liquidation_type true string liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
real_profit true decimal real profit (calculated with the opening average price, include profit in history settlement.)
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</orders>
current_page true int current page
total_page true int total page
total_size true int total size
</data>
ts true long timestamp

Note:

[Cross]Get History Orders via Multiple Fields

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code false(more see remarks) string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
trade_type true int trade 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, 17:buy(one-way mode), 18:sell(one-way mode)
type true int Type 1:All Orders,2:Order in Finished Status
status true string 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;
order_price_type false string order price type order price type, "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 in millisecond) more detail sees the follow note
end_time false long end time(timestamp in millisecond) more detail sees the follow note
from_id false long from id(value from the query_id in return data)
size false int size default is 20, 50 at most
direct false string direct prev/next；default is 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": 452057,
                "contract_type": "this_week",
                "pair": "BTC-USDT",
                "business_type": "futures",
                "order_id": 918800256249405440,
                "contract_code": "BTC-USDT-211210",
                "symbol": "BTC",
                "lever_rate": 5,
                "direction": "buy",
                "offset": "open",
                "volume": 100.000000000000000000,
                "price": 48555.600000000000000000,
                "create_date": 1639100651569,
                "order_source": "api",
                "order_price_type": "opponent",
                "order_type": 1,
                "margin_frozen": 0E-18,
                "profit": 0E-18,
                "trade_volume": 100.000000000000000000,
                "trade_turnover": 4855.560000000000000000,
                "fee": -2.427780000000000000,
                "trade_avg_price": 48555.6000,
                "status": 6,
                "order_id_str": "918800256249405440",
                "fee_asset": "USDT",
                "liquidation_type": "0",
                "is_tpsl": 0,
                "real_profit": 0,
                "margin_mode": "cross",
                "margin_account": "USDT",
                "reduce_only": 0
            }
        ],
        "remain_size": 0,
        "next_id": null
    },
    "ts": 1639102028275
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string result of server handled request
<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 in string
symbol true string symbol
contract_code true string contract code swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
margin_mode true string margin mode cross；
margin_account true string margin account such as:USDT”
lever_rate true int lever rate
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
volume true decimal volume
price true decimal price
create_date true long create date
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true string order price type order price type, "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 margin frozen
profit true decimal profit
real_profit true decimal real profit
trade_volume true decimal trade volume
trade_turnover true decimal trade turnover
fee true decimal fee
trade_avg_price true decimal trade avg 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; 10.Orders failed. 11. Orders cancelling.
order_type true int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
fee_asset true string fee asset ("USDT"...)
liquidation_type true string liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
is_tpsl true int is tpsl 1: yes; 0:no
contract_type true string contract type swap, this_week, next_week, quarter, next_quarter
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
reduce_only true int reduce only 0: no, 1: yes
</orders>
remain_size true int remain size(In the time range, the size that was not queried due to size restrictions)
next_id true long query_id for next data(It only has a value when the query result exceeds the size limit)
</data>
ts true long timestamp

Note：

[Isolated]Get History Orders via Multiple Fields

Note

Request Parameter

Parameter Name Required Type Description Value Range
contract_code true string contract code "BTC-USDT" ...
trade_type true int trade 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, 17:buy(one-way mode), 18:sell(one-way mode)
type true int Type 1:All Orders,2:Order in Finished Status
status true string 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;
order_price_type false string order price type order price type, "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 in millisecond) more detail sees the follow note
end_time false long end time(timestamp in millisecond) more detail sees the follow note
from_id false long from id(value from the query_id in return data)
size false int size default is 20, 50 at most
direct false string direct prev/next；default is 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": 13580806498,
                "order_id": 807038270541733888,
                "contract_code": "BTC-USDT",
                "symbol": "BTC",
                "lever_rate": 10,
                "direction": "buy",
                "offset": "close",
                "volume": 9,
                "price": 36580,
                "create_date": 1612454517740,
                "order_source": "android",
                "order_price_type": "opponent",
                "order_type": 1,
                "margin_frozen": 0,
                "profit": 0.3636,
                "trade_volume": 9,
                "trade_turnover": 329.22,
                "fee": -0.131688,
                "trade_avg_price": 36580,
                "status": 6,
                "order_id_str": "807038270541733888",
                "fee_asset": "BTC-USDT",
                "liquidation_type": "0",
                "is_tpsl": 0,
                "real_profit": 0.2394,
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "reduce_only": 0
            }
        ],
        "remain_size": 0,
        "next_id": null
    },
    "ts": 1612503332073
}

Returning Parameter

Parameter Name Required Type Description Value Range
status true string result of server handled request
<data> true object
<orders> true object array
query_id true long query id, can use as next request's from_id
order_id true long order id
order_id_str true string order id in string
symbol true string symbol
contract_code true string contract code "BTC-USDT" ...
margin_mode true string margin mode isolated: isolated
margin_account true string margin account such as:BTC-USDT”
lever_rate true int lever rate
direction true string direction "buy"/"sell"
offset true string offset "open","close","both"
volume true decimal volume
price true decimal price
create_date true long create date
order_source true string order source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
order_price_type true string order price type order price type, "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 margin frozen
profit true decimal profit
real_profit true decimal real profit
trade_volume true decimal trade volume
trade_turnover true decimal trade turnover
fee true decimal fee
trade_avg_price true decimal trade avg 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; 10.Orders failed. 11. Orders cancelling.
order_type true int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
fee_asset true string fee asset ("USDT"...)
liquidation_type true string liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
is_tpsl true int is tpsl 1: yes; 0:no
reduce_only true int reduce only 0: no, 1: yes
</orders>
remain_size true int remain size(In the time range, the size that was not queried due to size restrictions)
next_id true long query_id for next data(It only has a value when the query result exceeds the size limit)
</data>
ts true long timestamp

Note：

[Isolated] Get History Orders

Remarks

Request Parameter

Parameter Name Required Type Desc Default Value Range
contract_code true string Contract Code Case-Insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USDT".
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, 17:buy(one-way mode), 18:sell(one-way mode)
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
sort_by false string sort fields(descending) create_date "create_date"：descending order by order create date , "update_time": descending order by order update time

Note:

Response:


{
    "status": "ok",
    "data": {
        "orders": [
            {
                "order_id": 770336866451992576,
                "contract_code": "BTC-USDT",
                "symbol": "BTC",
                "lever_rate": 10,
                "direction": "sell",
                "offset": "close",
                "volume": 1.000000000000000000,
                "price": 13100.000000000000000000,
                "create_date": 1603704221118,
                "update_time": 1603704221118,
                "order_source": "web",
                "order_price_type": 6,
                "order_type": 1,
                "margin_frozen": 0,
                "profit": 0,
                "trade_volume": 0,
                "trade_turnover": 0,
                "fee": 0,
                "trade_avg_price": 0,
                "status": 3,
                "order_id_str": "770336866451992576",
                "fee_asset": "USDT",
                "liquidation_type": "0",
                "margin_asset": "USDT",
                "margin_mode": "isolated",
                "margin_account": "BTC-USDT",
                "is_tpsl": 0,
                "real_profit": 0,
                "reduce_only": 0
            }
        ],
        "total_page": 10,
        "current_page": 1,
        "total_size": 10
    },
    "ts": 1603704312847
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result
<data> object
<orders> array
order_id true long Order ID
order_id_str true string Order ID
symbol true string Variety code
contract_code true string Contract Code "BTC-USDT" ...
lever_rate true int Leverage Rate 1\5\10\20
direction true string Transaction direction
offset true string "open": "close" "open", "close", "both"
volume true int Number of Order
price true decimal Price committed
create_date true long Creation time
update_time true long order update time，millesecond timestamp
order_source true string Order Source system、web、api、m、risk、settlement、ios、android、windows、mac、trigger、tpsl
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 Frozen margin
margin_asset true string margin asset
profit true decimal profit when close position (calculated with the average price of position, exclude profit in history settlement.)
trade_volume true decimal Transaction quantity
trade_turnover true int Transaction aggregate amount
fee true decimal Service fee
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.
fee_asset true string the corresponding cryptocurrency to the given fee "USDT"...
order_type true int order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
liquidation_type true string Liquidation type 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
margin_mode true string margin mode isolated : "isolated"
margin_account true string margin account "BTC-USDT"...
is_tpsl true int whether to set take-profit and stop-loss order 1：yes；0：no
real_profit true decimal real profit (calculated with the opening average price, include profit in history settlement.)
reduce_only true int reduce only 0: no, 1: yes
</orders>
total_page true int Total Pages
current_page true int Current Page
total_size true int Total Size
</data>
ts true long Timestamp

Note

[General] Query Liquidation Orders

curl "https://api.hbdm.com/linear-swap-api/v1/swap_liquidation_orders?contract_code=BTC-USDT&trade_type=0&create_date=7"

Remarks

Request Parameter

Parameter Name Required Type Desc Value Range
contract_code false(more see remarks) string contract code Case-Insenstive.e.g. swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
pair false(more see remarks) string pair BTC-USDT
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": "BTC-USDT-211210",
                "symbol": "USDT",
                "direction": "sell",
                "offset": "close",
                "volume": 479.000000000000000000,
                "price": 51441.700000000000000000,
                "created_at": 1638593647864,
                "amount": 0.479000000000000000,
                "trade_turnover": 24640.574300000000000000,
                "business_type": "futures",
                "pair": "BTC-USDT"
            },
            {
                "contract_code": "BTC-USDT-211231",
                "symbol": "USDT",
                "direction": "sell",
                "offset": "close",
                "volume": 3999.000000000000000000,
                "price": 53457.900000000000000000,
                "created_at": 1638564308927,
                "amount": 3.999000000000000000,
                "trade_turnover": 213778.142100000000000000,
                "business_type": "futures",
                "pair": "BTC-USDT"
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 8
    },
    "ts": 1638756566302
}

Returning Parameter

Parameter Name Required Type Desc Value Range
status true string Request Processing Result
<data>
<orders>
symbol true string symbol
contract_code true string contract code e.g. swap: "BTC-USDT"... , future: "BTC-USDT-210625" ...
direction true string "buy":buy"sell": sell
offset true string "open":open "close": close, "both"
volume true decimal liquidation volume (cont)
amount true decimal liquidation amount (token)
trade_turnover true decimal liquidation amount (quotation token)
price true decimal bankruptcy price
created_at true long liquidation time
pair true string pair such as: “BTC-USDT”
business_type true string business type futures, swap
</orders>
total_page true int total page
current_page true int current page
total_size true int total size
</data>
ts true long timestamp






shell