Introduction

API Documentation Summary

Welcome to the Huobi Option 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 you have more than 3 BTC in your Huobi option account,or more than 30000 USDT in your Huobi USDT Margined swap account, please send the following information to [email protected]:

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

Changelog

1.0.2 2021-01-12 【Modified "Get Option Open Interest Information" Interface、Modified "Subscribe Market Detail Data" Interface、Modified "Query History Orders" Interface、Modified "Query Trigger Order History" Interface】

1. Modified "Get Option 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.)

• Interface Name: Get Option Open Interest Information
• Interface Type: public
• Interface URL: /option-api/v1/option_open_interest

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

• Interface Name: Subscribe Market Detail Data
• Interface Type: public
• Subscription Topic: market.$contract_code.detail

3. Modified "Query History Orders" Interface（Added paprameter "sort_by" to represent "sort fields" with optional values “create_date” and “update_time”). added "update_time" to indicate order's update time））

• Interface Name: Query History Orders
• Interface Type: private
• Interface URL: /option-api/v1/option_hisorders

4. Modified "Query Trigger Order History" Interface（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））

• Interface Name: Query Trigger Order History
  
• Interface Type: private
• Interface URL: /option-api/v1/option_trigger_hisorders

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

1. Added WS interface for subscribing system status updates push

• Interface name: subscribe system status updates
• Interface type: public
• Subscription topic：public.$service.heartbeat

1.0.0 2020-09-01 18:00(GMT+8)

Option API Access Guide

API List

permission type	Content Type	Context	Request Type	Desc	Signature Required
Read	Market Data	/option-api/v1/option_contract_info	GET	Query Option Info	No
Read	Market Data	/option-api/v1/option_index	GET	Query Option Index Price Information	No
Read	Market Data	/option-api/v1/option_price_limit	GET	Query Option Price Limitation	No
Read	Market Data	/option-api/v1/option_market_index	GET	Query Market Index	No
Read	Market Data	/option-api/v1/option_open_interest	GET	Get Option Open Interest Information	No
Read	Market Data	/option-api/v1/option_delivery_price	GET	Get Option Estimated Delivery Price	No
Read	Market Data	/option-api/v1/option_his_open_interest	GET	Query information on history open interest	No
Read	Market Data	/option-api/v1/option_api_state	GET	Query information on system status	No
Read	Market Data	/option-ex/market/depth	GET	Query Market Depth	No
Read	Market Data	/option-ex/market/history/kline	GET	Query KLine Data	No
Read	Market Data	/option-ex/market/detail/merged	GET	Query Market Data Overview	No
Read	Market Data	/option-ex/market/trade	GET	Query The Last Trade of a Contract	No
Read	Market Data	/option-ex/market/history/trade	GET	Query a Batch of Trade Records of a Contract	No
Read	Account	/option-api/v1/option_account_info	POST	Query User’s Account Information	Yes
Read	Account	/option-api/v1/option_position_info	POST	Query User’s position Information	Yes
Read	Account	/option-api/v1/option_sub_account_list	POST	Query assets information of all sub-accounts under the master account (Query by coins)	Yes
Read	Account	/option-api/v1/option_sub_account_info	POST	Query a single sub-account's assets information	Yes
Read	Account	/option-api/v1/option_sub_position_info	POST	Query a single sub-account's position information	Yes
Read	Account	/option-api/v1/option_financial_record	POST	Query account financial records	Yes
Read	Account	/option-api/v1/option_order_limit	POST	Query contract information on order limit	Yes
Read	Account	/option-api/v1/option_fee	POST	Query information on contract trading fee	Yes
Read	Account	/option-api/v1/option_transfer_limit	POST	Query information on Transfer Limit	Yes
Read	Account	/option-api/v1/option_position_limit	POST	Query information on position limit	Yes
Read	Account	/option-api/v1/option_master_sub_transfer_record	GET	Query transfer records of master account	No
Trade	Account	/option-api/v1/option_master_sub_transfer	POST	transfer between master account and sub-accounts	No
Read	Account	/option-api/v1/option_api_trading_status	POST	Query API trading status	Yes
Trade	Trade	/option-api/v1/option_order	POST	Place an Order	Yes
Trade	Trade	/option-api/v1/option_batchorder	POST	Place a Batch of Orders	Yes
Trade	Trade	/option-api/v1/option_cancel	POST	Cancel an Order	Yes
Trade	Trade	/option-api/v1/option_cancelall	POST	Cancel All Orders	Yes
Trade	Trade	/option-api/v1/option_lightning_close_position	POST	Place Lightning Close Order	Yes
Trade	Trade	/option-api/v1/option_trigger_order	POST	Place an Trigger Order	Yes
Trade	Trade	/option-api/v1/option_trigger_cancel	POST	Cancel a Trigger Order	Yes
Trade	Trade	/option-api/v1/option_trigger_cancelall	POST	Cancel all trigger Orders	Yes
Read	Trade	/option-api/v1/option_trigger_openorders	POST	Get all open trigger Orders	Yes
Read	Trade	/option-api/v1/option_trigger_hisorders	POST	Get all history trigger Orders	Yes
Read	Trade	/option-api/v1/option_order_info	POST	Get Information of an Order	Yes
Read	Trade	/option-api/v1/option_order_detail	POST	Get Trade Details of an Order	Yes
Read	Trade	/option-api/v1/option_openorders	POST	Get Current Orders	Yes
Read	Trade	/option-api/v1/option_hisorders	POST	Get History Orders	Yes
Read	Trade	/option-api/v1/option_matchresults	POST	Acquire History Match Results	Yes

Address

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

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：

• Request address of method, i.e. visit server address--api.hbdm.com, e.g.: api.hbdm.com/option-api/v1/option_order

• API Access Key ID (AccessKeyId): Access Key of the API Key that you apply.

• Method of Signature (SignatureMethod): Based on the Hash Aggrement, users calculate the signature via HmacSHA256.

• Signature Version (SignatureVersion): It adopts version 2 in terms of Signature Version.

• Timestamp (Timestamp): The time when you send the request (UTC time zone) : (UTC time zone) : (UTC time zone), e.g.: 2017-05-11T16:22:06

• Must-fill parameters & optional parameters: For each method, there are a group of must-fill parameters and optional parameters used to address the API request, which can be found in the illustration of each method as well as their meaning. Please note that, in terms of "Get" requests, it needs to do Signature calculation for all the original parameters in each method ; In terms of "Post" requests, no need to do Signature calculation for the original parameters in each method, which means only four parameters need to do Signature calculation in "Post" requests, i.e. AccessKeyId, SignatureMethod, SignatureVersion, Timestamp with other parameters placed in "body".

• Signature: The result of Signature calculation which is used to verify if signature is valid and not tampered.

Create API Key

You could create API Key at

API Key consists of the following two parts.

• "Access Key", the Key used to visit API.

• "Secret Key", the Key used to do Signature authentication and verification (visible during application period).

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/option-api/v1/option_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"

/option-api/v1/option_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

6. Following the sequence above, link parameters with "&"

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

/option-api/v1/option_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/option-api/v1/option_order?AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&order-id=1234567890&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30&Signature=4F65x5A2bLyMWVQj3Aqp%2BB4w%2BivaA7n5Oi2SuYtCJ9o%3D

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

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

API Rate Limit Illustration

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

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

• Generally, the private interface rate limit of API key is at most 48 times every 3 seconds for each UID (Trade Interface: at most 24 times every 3 seconds. Read Interface: at most 24 times every 3 seconds) (this rate limit is shared by all the altcoins contracts delivered by different date). API Interface List

• For public interface used to get information of index, price limit, settlement, delivery, open positions and so on, the rate limit is 60 times every 3 second at most for each IP (this 60 times every 3 second public interface rate limit is shared by all the requests from that IP of non-marketing information, like above).

• In terms of public interface used to get candle chart data, the latest transaction record and information of aggregate market, order book and so on, the rate limit is as below:

  (1) For restful interfaces：all products(futures, coin margined swap, usdt margined swap and option) 800 times/second for one IP at most

  （2）For websocket: The rate limit for “req” request is 50 times at once. No limit for “sub” request as the data will be pushed by sever voluntarily.

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

  Each UID can build at most create 30 WS connections for private order push at the same time. For each account, contracts of the same underlying coin only need to subscribe one WS order push, e.g. users only need to create one WS order push connection for BTC Contract which will automatically push orders of BTC-USDT contracts. Please note that the rate limit of WS order push and RESTFUL private interface are separated from each other, with no relations.

• Both read and trade interfaces will return the ratelimit info.You can refer to the following fields of "header" from api response. E.g.,you will get the total Read ratelimit("ratelimit-limit") and the remaining Read ratelimit("ratelimit-remaining") when you query the order info(/option-api/v1/option_account_info) , and you will get the total Trade ratelimit("ratelimit-limit") and the remaining Trade ratelimit("ratelimit-remaining") when you place an order(/option-api/v1/option_order)). API Interface List

• Will response following string for "header" via api

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

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

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

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

API Limitation on Order Cancellation Ratio【Not enabled yet】

• The system will calculate the order cancellation ratio automatically when the total number of orders placed via certain order price types by the API user goes equal to or larger than 2,500 within 10 minutes. If the order cancellation ratio is greater than 99%, the user will be prohibited for 5 minutes from placing orders via certain API order price types which will be listed below (The response of placing orders will return: 1084 Your contract API is disabled, please try again after {0} (GMT+8).).
• A 30-minute API order placement prohibition will be triggered if the user was prohibited for 3 times within an hour (The response of placing orders will return: 1084 Your contract API is disabled, please try again after {0} (GMT+8).). After resuming access, the total number of prohibited times will be cleared during the previous period and will not be counted into the total prohibited times in the new period.
• Please note that the prohibition from placing orders will cause no effect on order cancellation via API as well as order placement and cancellation via other terminals. We’ll keep you notified on each prohibition via SMS and email.
• Only four API order price types will be prohibited which are Limit order, Post_only, FOK and IOC. Please note that you can still use freely other order price types during the banned period, such as Lightning Close, BBO, Optimal 5, Optimal 10 and Optimal 20, opponent_ioc, lightning_ioc, optimal_5_ioc, optimal_10_ioc，optimal_20_ioc，opponent_fok，lightning_fok，optimal_5_fok，optimal_10_fok，optimal_20_fok,etc.
• When placing order by using the four prohibited order price types during the prohibition period, the message header returned by interface will include the field: "recovery-time: recovery timestamp" whose unit is millisecond, showing the end time of prohibition, or the access retrieval timestamp; if you are not in the prohibition period, the field is not included in returned header;
• Please note that our system calculates order cancellation ratio according to UID and therefore, the master account UID and sub-accounts UIDs will be counted separately. The calculation period is 10 min/time(The start time starts at 00:00 and the end time is 00:10. Every 10 minutes is a cycle.).

• Definition of Indicators：

  • Order Cancellation Ratio =Total number of invalid cancellation / Total number of placed orders (all types of orders placed via API)
  • Total number of placed order: Total number of placed orders refers to all orders placed via API which meet these requirements:
  • 1.the order type is placing orders (Order Type = 1),
  • 2.order price types include Limit Order, Post_only, FOK and IOC.
  • 3.order creating time should be within the interval between 3 seconds before the start time of the calculation period and the end time of the calculation period.
  • Total number of invalid cancellation:Total number of invalid cancellation refers to all cancellation orders placed via API which meet the requirements.
  • the order type is placing orders (order Type=1),
  • the order price types are Limit Order, post_only, FOK and IOC.
  • the order status is “Orders cancelled” (status=7).
  • order with 0 fulfilled.
  • the interval between order cancellation and placement should be less than or equal to 3 seconds.
  • the order cancellation time should be within the calculation period.

• In order to ensure stability and transaction performance of API, please try to reduce order cancellation rate and cancellation amount during peak periods to avoid frequent triggering of API restriction mechanism.Suggestions of reducing order cancellation rate are as below:

  • 1. Set orders’ price to BBO prices as close as possible;
  • 2. Prolong the interval properly between each order placement and cancellation;
  • 3. Try to increase your amount for each order and reduce the frequency of order;
  • 4. Try to improve your order fulfillment rate:
  • （1）Please try to use order prices types that help more on order fulfillment in preference such as BBO, Optimal 5, Optimal 10, Optimal 20, lightning Close, opponent_ioc, lightning_ioc, optimal_5_ioc, optimal_10_ioc，optimal_20_ioc，opponent_fok，lightning_fok，optimal_5_fok，optimal_10_fok，optimal_20_fok, etc.
  • （2）Try to use best bid/ask price when placing IOC orders, FOK orders and Post_only orders.
  • 5. Please try to extend your request polling cycle when implementing your strategy.

Maintenance with service suspended

During the maintenance of the business system, in addition to the below one interface(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"
}

The one interfaces is:

• Query whether the system is available: https://api.hbdm.com/heartbeat/

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

Query whether the system is available

• Interface https://api.hbdm.com/heartbeat/

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

Response:

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

• Notice: Heartbeat is 1 is available, 0 is not available.

Get current system timestamp

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

request

null

response

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

Returning Parameter

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

Note:

• It can be used for system time calibration.。

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 withdraw.
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	{0} contract is restricted of transfer. Please contact customer service.
1090	Margin rate is lower than 0. Order can’t be placed.
1091	Equity is less than 0. Order can’t be placed.
1092	The Flash Closing Order takes the {0}th price at the order book. After placing an order, the account equity will be less than 0. Please manually enter the price or place an order with the counterparty price.
1093	The Flash Closing Order takes the {0}th price at the order book. The margin rate will be less than 0 after placing an order. Please manually enter the price or place an order with the counterparty price.
1094	The leverage cannot be empty, please switch the leverage or contact customer service
1095	Non-trading state, unable to switch the leverage temporarily
1100	Unable to open a position currently. Please contact the customer service.
1101	Unable to close a position currently. Please contact the customer service.
1102	Unable to transfer in currently. Please contact customer service.
1103	Unable to transfer out currently. Please contact customer service.
1104	Trading is prohibited due to contracts trading constraints.
1105	Only Close is available due to contracts trading constraints.
1106	Abnormal contracts status. Can’t transfer.
1108	Abnormal service. Please try again later.
1109	Sub-account doesn't own the permissions to open positions. Please contact customer service.
1110	Sub-account doesn't own the permissions to close positions. Please contact customer service.
1111	Sub-account doesn't own the permissions to transfer in. Please contact customer service.
1112	Sub-account doesn't own the permissions to transfer out. Please contact customer service.
1113	The sub-account does not have transaction permissions. Please login main account to authorize.
1114	The sub-account does not have transfer permissions. Please login main account to authorize.
1115	You have no access permissions of this sub-account.
1200	Login error. Please try again.
1220	You don’t have access permission as you have not opened contracts trading.
1221	The total balances of Exchange Account can't meet the requirements for opening contracts.
1222	The days of opening account can't meet the requirements for opening contracts.
1223	The VIP level can't meet the requirements for opening contracts.
1224	Your country/region can't meet the requirements for opening contracts.
1225	Failed to open contracts.
1226	Repeated account.
1227	Huobi Contract does not support sub-accounts. Please log out sub-account and log in again with primary account.
1228	Account has not opened, cannot agree to agreement.
1229	Cannot agree twice.
1230	You haven't finished the risk verification.
1231	You haven't finished the ID Verification.
1232	The format/size of the image you uploaded does not meet the requirements. Please re-upload.
1233	High leverage is not enabled (Please sign in the APP or web with your main account to agree to the High-Leverage Agreement)
1234	{0} contract opening orders cannot exceed {1}
1235	{0} contract closing orders cannot exceed {1}
1250	Unable to get the HT_token.
1251	Unable to get BTC assets. Please try again later.
1252	Unable to get currency account assets. Please try again later.
1253	Error in signature verification.
1254	The sub-account has no permission to open futures, please go to the web side to log in the main account and open.
1300	Transfer failed.
1301	Insufficient amount available.
1302	Transfer failed.
1303	The single transfer-out amount must be no less than {0}{1}.
1304	The single transfer-out amount must be no more than {0}{1}.
1305	The single transfer-in amount must be no less than {0}{1}.
1306	The single transfer-in amount must be no more than {0}{1}.
1307	Your accumulative transfer-out amount is over the daily maximum, {0}{1}. You can't transfer out for the time being.
1308	Your accumulative transfer-in amount is over the daily maximum, {0}{1}. You can't transfer in for the time being.
1309	Your accumulative net transfer-out amount is over the daily maximum, {0}{1}. You can't transfer out for the time being.
1310	Your accumulative net transfer-in amount is over the daily maximum, {0}{1}. You can't transfer in for the time being.
1311	The platform's accumulative transfer-out amount is over the daily maximum. You can't transfer out for the time being.
1312	The platform's accumulative transfer-in amount is over the daily maximum. You can't transfer in for the time being.
1313	The platform's accumulative net transfer-out amount is over the daily maximum. You can't transfer out for the time being.
1314	The platform's accumulative net transfer-in amount is over the daily maximum. You can't transfer in for the time being.
1315	Wrong transfer type.
1316	Failed to freeze the transfer.
1317	Failed to unfreeze the transfer.
1318	Failed to confirm the transfer.
1319	Failed to acquire the available transfer amount.
1320	The contract status is abnormal. Transfer is unavailable temporarily.
1321	Transfer failed. Please try again later or contact customer service.
1322	Invalid amount. Must be more than 0.
1323	Abnormal service, transfer failed. Please try again later.
1325	Failed to set trading unit
1326	Failed to obtain trading units
1327	No transfer permission, transfer failed, please contact customer service
1328	No transfer permission, transfer failed, please contact customer service
1329	No transfer permission, transfer failed, please contact customer service
1330	No transfer permission, transfer failed, please contact customer service
1331	Exceeds limit of transfer accuracy (8 digits). Please modify it
1332	The contract doesn't exist.
1333	Failed to open the Maker&Taker agreement
1334	Failed to check the Maker&Taker agreement
1335	Failed to check the second confirmation setting of Maker&Taker
1336	Failed to update the second confirmation setting of Maker&Taker
1337	Failed to check the settings of Maker&Taker
1338	Failed to update the settings of Maker&Taker
1339	Nickname contains illegal words, please modify it
1340	Nickname has been used, please modify it
1341	The enrollment has ended
1342	You cannot set nickname for sub-account
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.
1401	order price shall be lower than the strike price.
12001	Invalid submission time.
12002	Incorrect signature version.
12003	Incorrect signature method.
12004	Private key is expired.
12005	Incorrect IP address.
12006	The submission time can't be empty.
12007	Incorrect public key.
12008	Verification failed.
12009	The user is locked or doesn't exist.

API Best Practice

1. Query contract history orders interface: /option-api/v1/option_hisorders

• To ensure timelines and to reduce latency, users are highly recommended to get contract history orders information faster from server memory using interface “query contract order information” (URL: /option-api/v1/option_order_info).

• For users who use interface “query contract history orders” (URL: /option-api/v1/option_hisorders), please enter as many query conditions as possible (including contract_code, trade_type（recommended to send “0” to query all）, type, status, create_date). Besides, try not to enter a big integer in parameter “create_date”. You are kindly suggested to query one-day data at a time.

2. Query contract match results interface: /option-api/v1/option_matchresults

• To improve query performance and response speed, please enter as many querying conditions as possible (including contract_code, trade_type（recommended to send “0” to query all）, create_date). Besides, try not to enter a big integer in parameter “create_date”. You are kindly suggested to query one-day data at a time.

3. Query contract financial record interface: /option-api/v1/option_financial_record

• To improve query performance and response speed, please enter as many querying conditions as possible (including symbol, type(recommended to leave it blank to query all), create_date). Besides, try not to enter a big integer in parameter “create_date”. You are kindly suggested to query one-day data at a time.

4. Query contract order detail interface: /option-api/v1/option_order_detail

• When querying orders without parameter(such as the parameter: created_at), the query result data may be delayed. It is recommended to pass the two parameters of the interface: created_at (order timestamp) and order_type (order type, default 1), the database will be directly queried, and the query results data will be more timely.

• Querying condition “created_at” uses 13-bit long type time stamp (including milliseconds). Querying performance will be improved when accurate time stamps are entered.

• For example: the converted time stamp of "2019/10/18 10:26:22" is 1571365582123. The returned ts from interface “contract_order” can be used as time stamp to query corresponding order. 0 is not allowed in parameter “created_at”.

5. WebSocket subscription to Market Depth data:

• For acquiring market depth data within 150 steps, you are kindly suggested to use step0, step1, step2, step3, step4, step5, step14, step15；

• For acquiring market depth data within 20 steps, you are kindly suggested to use step6, step7, step8, step9, step10, step11, step12, step13；

• Since the large volume of pushing 150 steps data every 100ms, WebSocket disconnection may occur frequently if client’s network bandwidth is insufficient or the processing is not in time; therefore, we highly recommend users using step6, step7, step8, step9, step10, step11, step12, step13 to acquire 20 steps data. For instance, subscribing 20 steps data.

{

"sub": "market.BTC-USDT-200925-C-10000.depth.step6",

"id": "id5"

}

• We also suggest that you subscribe incremental market depth data.orderbook event will be checked every 30ms. If there is no orderbook event, you will not receive any orderbook data.you HAVE TO maintain local orderbook data,such as updating your local orderbook bids and asks data.You can subscribe 20 or 150 unmerged data.

{

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

"data_type":"incremental",

"id": "id1"

}

6. Place order interface (URL: /option-api/v1/option_order) and place a batch of orders interface (URL:/option-api/v1/option_batchorder):

• We recommend to fill in the parameter “client_order_id”(should be unique from user-side),which can help users to acquire order status and other order information according to the parameter “client_order_id" from

• query order information interface (URL: /option-api/v1/option_order_info ) when there is no returned information due to network or other problems.

Code Demo

PS: option api is similar to future and swap apis.

• Python

• Java

• Postman

Strategy Demo

• Python

Option API FAQ

Access and Authentication

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

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

Q2: Why are APIs disconnected or timeouted?

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 formats, 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: Why does signature verification return failure (403: Verification failure) ?

The signature process of option is similar to huobi future . In addition to the following precautions,please refer to the option or 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 option code demo is here. The USDT Margined Swap code demo is here.

1. Check if the API key is valid and copied correctly.
2. Check if the IP is in whitelist
3. Check if th timestamp is UTC time
4. Check if parameters are sorted alphabetically
5. Check if the encoding is UTF-8
6. Check if the signature has base64 encoding
7. Any method with parameters for GET requests should be signed.
8. Any method with parameters for POST requests don't need to be signed.
9. Check if whether the signature is URI encoded and Hexadecimal characters must be capitalized, such as ":" should be encoded as "%3A", and the space 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.

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

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?

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

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

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

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

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

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

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

The Subscription of MBP data: market.$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：

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

Example:

step4(0.01):

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

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

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

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

20 price level: step6 to step13;

More examples：

step1(0.00001):

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

step7(0.00001):

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

step6(0.000001)

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

step11(0.1):

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

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

Subscription of position event: "positions.BTC-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;

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 option-api/v1/option_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: 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.

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

Q5: 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 regularlyl ,which is different from the market heartbeat format . Please refer to the "websocket Heartbeat and Authentication Interface" . if the it is disconnected ,please try to reconnect.

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

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

No.

Q8. 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 option-api/v1/option_order_info.

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

Query the order status by option-api/v1/option_order_info.If the status is 10,the order is failed。

Q10. 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: option-api/v1/option_order_info

Error Codes

Q1: What is the reason for 1030 error code?

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

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 option-api/v1/option_position_info to get your available position.

Q3: What is the reason for 1032 error code?

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

How to solve problems more effectively?

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

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

Option Market Data interface

Query Option Info

Example

• GET /option-api/v1/option_contract_info

curl "https://api.hbdm.com/option-api/v1/option_contract_info?contract_code=BTC-USDT-201225-C-13000"      

Request Parameter

Parameter Name	Mandatory	Type	Description	Value Range
symbol	false	string	Coin Code	"BTC","ETH"，If default, all coins will be returned.
trade_partition	false	string	trade partition	"USDT", Default:"USDT"
contract_type	false	string	contract type	Weekly: "this_week", Bi-weekly: "next_week", Quarterly: "quarter"
contract_code	false	string	contract code	BTC-USDT-201225-C-13000

Note:

• If all input parameters are not filled, query all contracts info under the USDT trading zone by default. If contract_code is filled, query according to contract_code first. ;

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-201225-C-13000",
            "contract_type": "quarter",
            "contract_size": 0.001,
            "price_tick": 0.01,
            "delivery_date": "20201225",
            "create_date": "20200904",
            "contract_status": 1,
            "option_right_type": "C",
            "exercise_price": 13000,
            "delivery_asset": "BTC",
            "quote_asset": "USDT",
            "trade_partition": "USDT"
        }
    ],
    "ts": 1604641660310
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_code	true	string	Contract Code (If the strike price has a decimal point, "+" will be used to indicate the decimal point. eg, if the strike price of BTC Weekly call options is 9002.35, the contract code is BTC-USDT-200508-C-9002+35)	"BTC-USDT-201225-C-13000"
contract_type	true	string	Contract Type	"this_week", "next_week", "quarter"
contract_size	true	decimal	Contract Value (how many coins corresponding to one contract)	0.01...
price_tick	true	decimal	Minimum Variation of Contract Price	0.001, 0.01...
delivery_date	true	string	Contract Delivery Date	eg "20200626"
create_date	true	string	Contract Listing Date	eg "20200515"
contract_status	true	int	Contract Status	0: Delisting 1: Listing 2: Pending Listing 3: Suspension 4: Suspending of Listing 5: In Settlement 6: Delivering 7 Settlement Completed 8: Delivered 9: Trading Suspended
option_right_type	true	string	Options Type	C: call options P: put options
exercise_price	true	decimal	Strike Price	eg 6622
delivery_asset	true	string	Delivery Coin	eg "BTC"
quote_asset	true	string	Quote Coin	eg"USDT"
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Query Option Index Price Information

Example

• GET /option-api/v1/option_index

curl "https://api.hbdm.com/option-api/v1/option_index"" 

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Index Coin Code	"BTC","ETH"，If default, all coins will be returned.

Response

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC-USDT",
            "index_price": 15666.651003896666666666,
            "index_ts": 1604641743091
        }
    ],
    "ts": 1604641747077
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
<data>	true	object array
symbol	true	string	Index Coin Code	"BTC","ETH"...
index_price	true	decimal	Index Price
index_ts	true	long	Time of Response Generation, unit: millisecond
</data>
ts	true	long	Timestamp, unit: millisecond

Query Option Price Limitation

Example

• GET /option-api/v1/option_price_limit

curl "https://api.hbdm.com/option-api/v1/option_price_limit?contract_code=BTC-USDT-201225-C-13000

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	BTC-USDT-201225-C-13000

Response

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_type": "quarter",
            "contract_code": "BTC-USDT-201225-C-13000",
            "high_limit": 4619.82,
            "low_limit": 1484.26,
            "trade_partition": "USDT"
        }
    ],
    "ts": 1604641793095
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok"
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
contract_code	true	string	Contract Code	eg"BTC-USDT-201225-C-13000" ...
high_limit	true	decimal	Highest Buy Price
low_limit	true	decimal	Lowest Sell Price
<data>
ts	true	long	Time of Response Generation, unit: millisecond

Query Market Index

Example

• GET /option-api/v1/option_market_index

curl "https://api.hbdm.com/option-api/v1/option_market_index?contract_code=BTC-USDT-201225-C-13000

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH"
trade_partition	false	string	Trade Partition	"USDT", Default: "USDT"
contract_type	false	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
option_right_type	false	string	Options Type	C: Call options P: Put options
contract_code	false	string	Contract Code	BTC-USDT-201225-C-13000

Note:

• If contract_code is filled，use contract_code to query；

• If contract_code isn't filled，use symbol+trade_partition+contract_type+option_right_type to query.

Response:

{
    "status": "ok",
    "data": [
        {
            "contract_code": "BTC-USDT-201225-C-13000",
            "symbol": "BTC",
            "iv_last_price": 0.47379972,
            "iv_ask_one": 0.66771509,
            "iv_bid_one": 0.55960657,
            "iv_mark_price": 0.62272073,
            "delta": 0.8249273542423468,
            "gamma": 0.00007202,
            "theta": -9.40283094,
            "vega": 14.82486644,
            "ask_one": 3122.7,
            "bid_one": 2964.33,
            "last_price": 2855.11,
            "mark_price": 3054.4960937643172123041257590971717688,
            "trade_partition": "USDT",
            "contract_type": "quarter",
            "option_right_type": "C"
        }
    ],
    "ts": 1604641840724
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok"
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT", Default: "USDT"
contract_code	true	string	Contract Code	eg"BTC-USDT-201225-C-13000" ...
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
option_right_type	true	string	Options Type	C: Call options P: Put options
iv_last_price	true	decimal	Latest Price Implied Volatility
iv_ask_one	true	decimal	Sell_one Price Implied Volatility
iv_bid_one	true	decimal	Buy_one Price Implied Volatility
iv_mark_price	true	decimal	Mark Price Implied Volatility
delta	true	decimal	DELTA
gamma	true	decimal	GAMMA
theta	true	decimal	THETA
vega	true	decimal	VEGA
ask_one	true	decimal	Sell_one Price
bid_one	true	decimal	Buy_one Price
last_price	true	decimal	Latest Price
mark_price	true	decimal	Mark Price
<data>
ts	true	long	Time of Response Generation, unit: millisecond

Get Option Open Interest Information

Example

• GET /option-api/v1/option_open_interest

curl "https://api.hbdm.com/option-api/v1/option_open_interest?contract_code=BTC-USDT-201225-C-13000"

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT" Default: "USDT"
contract_type	false	string	Contract Type	this_week: Weekly next_week: Bi-weekly quarter: Quarterly
contract_code	false	string	Contract Code	BTC-USDT-201225-C-13000

Note:

• If all input parameters are not filled, query all contracts info under the USDT trading zone by default. If contract_code is filled, query according to contract_code first.

Response:

{
    "status": "ok",
    "data": [
        {
            "volume": 2947,
            "amount": 2.947,
            "symbol": "BTC",
            "contract_type": "quarter",
            "contract_code": "BTC-USDT-201225-C-13000",
            "trade_partition": "USDT",
            "trade_amount": 1.42,
            "trade_volume": 142,
            "trade_turnover": 7.847622
        }
    ],
    "ts": 1604641943451
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_code	true	string	Contract Code	eg"BTC-USDT-201225-C-13000"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
amount	true	decimal	Position Amount (coin)
volume	true	decimal	volume (volume)
trade_amount	true	decimal	trading volume within the last 24 hours (coin)
trade_volume	true	decimal	trading volume within the last 24 hours (cont)
trade_turnover	true	decimal	trading amount within the last 24 hours
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Get Option Estimated Delivery Price

Example

• GET /option-api/v1/option_delivery_price

curl "https://api.hbdm.com/option-api/v1/option_delivery_price?contract_code=BTC-USDT-201225-C-13000"

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"，Default: "USDT"

Response:

{
    "status": "ok",
    "data": {
        "symbol": "BTC",
        "trade_partition": "USDT",
        "delivery_price": 13203.1966277128547579298831
    },
    "ts": 1604642022058
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
delivery_price	true	decimal	Estimated Delivery Price
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Query information on history open interest

• GET /option-api/v1/option_his_open_interest

curl "https://api.hbdm.com/option-api/v1/option_his_open_interest?symbol=BTC&contract_type=this_week&period=60min&amount_type=1&option_right_type=C&trade_partition=USDT"

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
period	true	string	Period Type	1 hours:"60min"，4 hours:"4hour"，12 hours:"12hour"，1 day:"1day"
size	false	int	Acquisition Amount	Default: 48，Value Range [1, 200]
amount_type	true	int	Unit	1: cont，2: coin
option_right_type	true	string	Options Type	C: Call options P: Put options

Response:

{
    "status": "ok",
    "data": {
        "symbol": "BTC",
        "contract_type": "quarter",
        "option_right_type": "C",
        "trade_partition": "USDT",
        "tick": [
            {
                "volume": 22688,
                "amount_type": 1,
                "ts": 1604638800000
            },
            {
                "volume": 22633,
                "amount_type": 1,
                "ts": 1604635200000
            }
        ]
    },
    "ts": 1604642063718
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object	Dictionary Data
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
option_right_type	true	string	Options Type	C:Call options P:Put options
<tick>	true	object array
volume	true	decimal	Position volume
amount_type	true	int	Unit	1: cont，2: coin
ts	true	long	Recording Time
</tick>
</data>

Notice

• tick fields: data in the array is arranged in reverse chronological order；

• data fields: Dictionary Type

Query information on system status

• GET /option-api/v1/option_api_state

curl "https://api.hbdm.com/option-api/v1/option_api_state?symbol=BTC&trade_partition=USDT"

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH","USDT"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"

Note:

• When the symbol is USDT, the return parameter only presents the transfer permission of USDT asset, and the permission for opening/closing positions or cancelling orders could be ignored.

Response:

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

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
open	true	int	open position access:“1" represents available; "0" represents unvailable
close	true	int	close position access:“1" represents available; "0" represents unvailable
cancel	true	int	cancel order access:“1" represents available; "0" represents unvailable
transfer_in	true	int	Transfer in from exchange account access: 1" represents available; "0" represents unvailable
transfer_out	true	int	Transfer out to exchange account access: 1" represents available; "0" represents unvailable
master_transfer_sub	true	int	transfer from master account to sub-account access: 1" represents available; "0" represents unvailable
sub_transfer_master	true	int	transfer from sub-account to master account access: 1" represents available; "0" represents unvailable
</data>

Notice

• open refers to the corresponding "API-Open Positions-Ordinary Order" access in Trade Access, and is available when "On", unavailable when "Off";

• close refers to the corresponding "API-Close Positions-Ordinary Order" access in Trade Access, and is available when"On", unavailable when "Off";

• cancel refers to the corresponding "API-Cancel Orders-Ordinary Order" access in Trade Access, and is available when "On", unavailable when "Off";

• transfer_in refers to the corresponding "Other-Transfer-Transfer in from exchange account" access in Trade Access, and is available when "On", unavailable when "Off";

• transfer_out refers to the corresponding "Other-Transfer-Transfer out to exchange account" access in Trade Access, and is available when "On", unavailable when "Off";

• master_transfer_sub refers to the corresponding "API-Transfer-Transfer from master account to sub-account" access in Trade Access, and is available when "On", unavailable when "Off";

• sub_transfer_master refers to the corresponding "API-Transfer-Transfer from sub-account to master account" access in Trade Access, and is available when "On", unavailable when "Off";

Query Market Depth

Example

• GET /option-ex/market/depth

curl "https://api.hbdm.com/option-ex/market/depth?contract_code=BTC-USDT-201225-C-13000&type=step5"

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000" ...
type	true	string	Depth Type	(Data within Step150) step0, step1, step2, step3, step4, step5, step14, step15 (merged depth 1-5,14,15); when step is 0, depth will not be merged, (Data within Step20) step6, step7, step8, step9, step10, step11, step12, step13(merge depth 7-13); when step is 6, depth will not be merged

tick illustration:

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

Response:

{
    "ch": "market.BTC-USDT-201225-C-13000.depth.step6",
    "status": "ok",
    "ts": 1604642203490,
    "tick": {
        "mrid": 118879828,
        "id": 1604642202,
        "bids": [
            [
                2943.2,
                552
            ],
            [
                2919.87,
                748
            ]
        ],
        "asks": [
            [
                3094.55,
                381
            ],
            [
                3125.95,
                494
            ]
        ],
        "ts": 1604642202644,
        "version": 1604642202,
        "ch": "market.BTC-USDT-201225-C-13000.depth.step6"
    }
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
ch	true	string	Data belonged channel，Format: market.$contract_code.depth.type
status	true	string	Request Processing Result	"ok" , "error"
<tick>	true	object
asks	true	array	Sell order book,[price( ask price), vol (quantity (conts) of open orders at this price)], price in ascending order
bids	true	array	Buy order book,[price( bid price), vol (quantity (conts) of open orders at this price)], price in decending order
ch	true	string	Data belonged channel，Format: market.period
id	true	long	Message id
mrid	true	long	Order ID
ts	true	long	Message generation time, unit: millisecond
version	true	long	Version
</tick>
ts	true	long	Time of Response Generation, unit: millisecond

Query KLine Data

Example

• GET /option-ex/market/history/kline

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

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000" ...
period	true	string	kline Type	1min, 5min, 15min, 30min, 60min, 4hour,1day,1week,1mon
size	false	int	Request Amount, default 150	[1,2000]
from	false	long	Start Timestamp, 10 digits, seconds
to	false	long	End Timestamp, 10 digits, seconds

Note

• Either size or from&to shall be filled. If neither is filled, no data will be returned.

• If from is filled, to is also required to be filled. At most two consecutive years's data can be acuqired.

• If size, from and to are all filled, from and to parameter will be ignored.

Data Illustration：

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

Response:

{
    "ch": "market.BTC-USDT-201225-C-13000.kline.5min",
    "data": [
        {
            "amount": 0,
            "close": 2855.11,
            "count": 0,
            "high": 2855.11,
            "id": 1604641800,
            "low": 2855.11,
            "open": 2855.11,
            "trade_turnover": 0,
            "vol": 0
        },
        {
            "amount": 0,
            "close": 2855.11,
            "count": 0,
            "high": 2855.11,
            "id": 1604642100,
            "low": 2855.11,
            "open": 2855.11,
            "trade_turnover": 0,
            "vol": 0
        }
    ],
    "status": "ok",
    "ts": 1604642303996
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
ch	true	string	Data belonged channel，Format: market.period
<data>	true	object array
id	true	long	kline id,the same as kline timestamp, kline start timestamp
vol	true	decimal	Trading volume(conts)，the sum of bilateral (buy&sell) trading volume
count	true	decimal	Filled Order Quantity
open	true	decimal	Opening Price
close	true	decimal	Closing price, the price in the last kline is the latest price
low	true	decimal	Lowest Price
high	true	decimal	Highest Price
amount	true	decimal	Trading Amount(coin), that is (Trading volume(conts)*Contract face value)
trade_turnover	true	decimal	Trading Amount, that is the sum of（Filled conts of a single order *Contract Face value *Transaction Price）
</data>
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond

Query Market Data Overview

Example

• GET /option-ex/market/detail/merged

curl "https://api.hbdm.com/option-ex/market/detail/merged?contract_code=BTC-USDT-201225-C-13000"

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000" ...

tick Illustration:

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

  }

Response:

{
    "ch": "market.BTC-USDT-201225-C-13000.detail.merged",
    "status": "ok",
    "tick": {
        "amount": "1.69",
        "ask": [
            3099.36,
            381
        ],
        "bid": [
            2939.87,
            552
        ],
        "close": "2855.11",
        "count": 5,
        "high": "2855.11",
        "id": 1604642357,
        "low": "2821.97",
        "open": "2821.97",
        "trade_turnover": "4480.8195",
        "ts": 1604642358431,
        "vol": "1690"
    },
    "ts": 1604642358431
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
ch	true	string	Data belonged channel，Format: market.$contract_code.detail.merged
status	true	string	Request Processing Result	"ok" , "error"
<tick>	true	object	kline data (Start at 00:00(UTC+8) of the day)
id	true	long	kline id,the same as kline timestamp
amount	true	decimal	Trading Amount(coin), that is (Trading volume(conts)*Face value of a single contract)
ask	true	array	[Sell_1 price; Sell_1 quantity (conts)]
bid	true	array	[Buy_1 price; Buy_1 quantity (conts)]
open	true	string	Opening Price
close	true	string	Closing price, the price in the last kline is the latest price
count	true	decimal	Filled Order Quantity
high	true	string	Highest Price
low	true	string	Lowest Price
vol	true	string	Trading Volume (conts)，the sum of bilateral (buy & sell) trading volume.
trade_turnover	true	string	Tranding Amount，that is the sum of Filled conts of a single order *Contract Face value *Transaction Price
ts	true	long	Timestamp
</tick>
ts	true	long	Time of Response Generation, unit: millisecond

Query the Last Trade of a Contract

Example

• GET /option-ex/market/trade
  

curl "https://api.hbdm.com/option-ex/market/trade?contract_code=BTC-USDT-201225-C-13000"

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000" ...

Tick Illustration：

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

Response:

{
    "ch": "market.BTC-USDT-201225-C-13000.trade.detail",
    "status": "ok",
    "tick": {
        "data": [
            {
                "amount": "98",
                "direction": "buy",
                "id": 1182841000001,
                "price": "2855.11",
                "ts": 1604615035549
            }
        ],
        "id": 1604642413998,
        "ts": 1604642413998
    },
    "ts": 1604642413998
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
ch	true	string	Data belonged channel，Format: market.$contract_code.trade.detail
status	true	string		"ok","error"
<tick>	true	object
id	true	long	Unique Order Id(symbol level)
ts	true	long	Latest Transaction Time
<data>	true	object array
amount	true	string	Trading Amount (conts)，the sum of bilateral (buy & sell) trading Amount.
direction	true	string	Active Transaction Direction
id	true	long	Unique Transaction Id(symbol level)
price	true	string	Transaction Price
ts	true	long	Transaction Time
</data>
</tick>
ts	true	long	Time of Response Generation

Query a Batch of Trade Records of a Contract

Example

• GET /option-ex/market/history/trade

curl "https://api.hbdm.com/option-ex/market/history/trade?contract_code=BTC-USDT-201225-C-13000&size=100"

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000" ...
size	true	int	Quantity of trade records acquisition	[1, 2000]

data Illustration：

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

Response:

{
    "ch": "market.BTC-USDT-201225-C-13000.trade.detail",
    "data": [
        {
            "data": [
                {
                    "amount": 10,
                    "direction": "sell",
                    "id": 1174421220000,
                    "price": 2406.83,
                    "ts": 1604581920670
                }
            ],
            "id": 117442122,
            "ts": 1604581920670
        },
        {
            "data": [
                {
                    "amount": 970,
                    "direction": "buy",
                    "id": 1182841000000,
                    "price": 2821.97,
                    "ts": 1604615035549
                },
                {
                    "amount": 98,
                    "direction": "buy",
                    "id": 1182841000001,
                    "price": 2855.11,
                    "ts": 1604615035549
                }
            ],
            "id": 118284100,
            "ts": 1604615035549
        }
    ],
    "status": "ok",
    "ts": 1604642481841
}

Returning Parameter

Parameter Name	Mandatory	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	Trading Amount (conts)，the sum of bilateral (buy & sell) trading Amount.
direction	true	string	Active Transaction Direction
id	true	long	Unique Transaction Id(symbol level)
price	true	decimal	Transaction Price
ts	true	long	Transaction Time
</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 Response Generation, unit: millisecond

Option Account Interface

Query User’s Account Information

Example

• POST /option-api/v1/option_account_info
  

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Asset symbol	"BTC"，"ETH"，"USDT"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT".Default: USDT

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "USDT",
            "margin_balance": 10.45482,
            "margin_position": 0,
            "margin_frozen": 0,
            "margin_available": 10.45482,
            "profit_real": -0.09418,
            "profit_unreal": 0,
            "withdraw_available": 10.45482,
            "margin_static": 10.45482,
            "premium_frozen": 0,
            "fee_frozen": 0,
            "premium_in": 2.85101,
            "premium_out": 0.47879,
            "delta": null,
            "gamma": null,
            "theta": null,
            "vega": null,
            "option_value": 0,
            "trade_partition": "USDT",
            "fee_asset": "USDT",
            "margin_asset": "USDT"
        }
    ],
    "ts": 1604642578467
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	long	long	Time of Response Generation, unit: millisecond
<data>	true	object array
symbol	true	string	Asset symbol	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
margin_balance	true	decimal	Account Equity
margin_position	true	decimal	Performance Margin
margin_frozen	true	decimal	Frozen Margin
margin_available	true	decimal	Available Margin
profit_real	true	decimal	Realized PnL
profit_unreal	true	decimal	Unrealized PnL
withdraw_available	true	decimal	Transferable Amount
margin_static	true	decimal	Static Equity
premium_frozen	true	decimal	Frozen Premium
fee_frozen	true	decimal	Frozen Transaction Fee
fee_asset	true	string	Transaction Fee Coin
premium_in	true	decimal	Current week premium income
premium_out	true	decimal	Current week premium expense
delta	true	decimal	DELTA
gamma	true	decimal	GAMMA
theta	true	decimal	THETA
vega	true	decimal	VEGA
option_value	true	decimal	Option Market Value(unit:"USDT")
margin_asset	true	decimal	margin asset	"BTC","ETH","USDT"
</data>

Query User’s Position Information

Example

• POST /option-api/v1/option_position_info

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT",
  "contract_code": "BTC-USDT-201225-C-13000"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"
contract_code	false	string	Contract Code	"BTC-USDT-201225-C-13000" ...

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-201225-C-13000",
            "contract_type": "quarter",
            "volume": 1,
            "available": 1,
            "frozen": 0,
            "cost_open": 2897.25,
            "cost_hold": 2897.25,
            "profit_unreal": 0,
            "profit_rate": 0,
            "margin_position": 0,
            "position_value": 2.89725,
            "direction": "buy",
            "profit": -0.005,
            "last_price": 2897.25,
            "delivery_date": "20201225",
            "option_right_type": "C",
            "exercise_price": 13000,
            "quote_asset": "USDT",
            "trade_partition": "USDT",
            "margin_asset": "BTC"
        }
    ],
    "ts": 1604888304689
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000" ...
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
volume	true	decimal	Position Quantity
available	true	decimal	Available Close Quantiy
frozen	true	decimal	Frozen Quantity
cost_open	true	decimal	Average open price
cost_hold	true	decimal	Average position price
profit_unreal	true	decimal	Unrealized PnL
profit_rate	true	decimal	Profit Rate
profit	true	decimal	Profit
margin_position	true	decimal	Performance Margin
position_value	true	decimal	Position Value
direction	true	string	"buy": Buy "sell": Sell
last_price	true	decimal	Latest Price
delivery_date	true	string	Delivery Date	eg"20200508"
option_right_type	true	string	Options Type	C:Call options P:Put options
exercise_price	true	decimal	Strike Price
quote_asset	true	string	Quote Coin	"USDT"...
margin_asset	true	string	Margin Coin	"BTC"...
</data>

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

• POST /option-api/v1/option_sub_account_list

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT"
}

Request Parameters

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC"，"ETH"，“USDT，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"

Response:

{
    "status": "ok",
    "data": [
        {
            "sub_uid": 123456789,
            "list": [
                {
                    "symbol": "USDT",
                    "margin_balance": 10,
                    "trade_partition": "USDT"
                },
                {
                    "symbol": "BTC",
                    "margin_balance": 0,
                    "trade_partition": "USDT"
                },
                {
                    "symbol": "ETH",
                    "margin_balance": 0,
                    "trade_partition": "USDT"
                }
            ]
        }
    ],
    "ts": 1604888581799
}

Return parameters

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object array
sub_uid	true	long	Sub-account UID
<list>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
margin_balance	true	decimal	Account Equity
</list>
</data>

Note

• Only data of sub-accounts with contract trading opened will be returned.

Query a single sub-account's assets information

• POST /option-api/v1/option_sub_account_info

Request:

{
  "sub_uid": "123456789",
  "symbol": "BTC",
  "trade_partition": "USDT"
}

Request Parameters

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH","USDT"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"
sub_uid	true	string	Sub-account UID

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "USDT",
            "margin_balance": 10,
            "margin_position": 0,
            "margin_frozen": 0,
            "margin_available": 10,
            "profit_real": 0,
            "profit_unreal": 0,
            "withdraw_available": 10,
            "margin_static": 10,
            "premium_frozen": 0,
            "fee_frozen": 0,
            "premium_in": 0,
            "premium_out": 0,
            "delta": null,
            "gamma": null,
            "theta": null,
            "vega": null,
            "option_value": 0,
            "trade_partition": "USDT",
            "fee_asset": "USDT",
            "margin_asset": "USDT"
        }
    ],
    "ts": 1604888673495
}

Return parameters

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
margin_balance	true	decimal	Account Equity
margin_position	true	decimal	Performance Margin
margin_frozen	true	decimal	Frozen Margin
margin_available	true	decimal	Available Margin
profit_real	true	decimal	Realized PnL
profit_unreal	true	decimal	Unrealized PnL
withdraw_available	true	decimal	Transferable Amount
margin_static	true	decimal	Static Equity
premium_frozen	true	decimal	Frozen Premium
fee_frozen	true	decimal	Frozen Transaction Fee
fee_asset	true	string	Transaction Fee Coin
premium_in	true	decimal	Current week premium income
premium_out	true	decimal	Current week premium expense
delta	true	decimal	DELTA
gamma	true	decimal	GAMMA
theta	true	decimal	THETA
vega	true	decimal	VEGA
option_value	true	decimal	Option Market Value(unit:"USDT")
margin_asset	true	decimal	Margin Coin."BTC"
</data>

Notice

• Can only query information of sub-accounts with contract trading opened;

• The corresponding data will not be returned if the sub-account has visited the contract system but has not opened contract trading.

Query a single sub-account's position information

• POST /option-api/v1/option_sub_position_info

Request:

{
  "sub_uid": "123456789",
  "symbol": "BTC",
  "trade_partition": "USDT",
  "contract_code": "BTC-USDT-201225-C-13000"
}

Request Parameters

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"
contract_code	false	string	Contract Code	eg"BTC-USDT-201225-C-13000" ...
sub_uid	true	string	Sub-account UID

Response:

{
    "data":[
        {
            "symbol":"BTC",
            "trade_partition":"USDT",
            "contract_code":"BTC-USDT-201225-C-13000",
            "contract_type":"quarter",
            "volume":1,
            "available":1,
            "frozen":0,
            "cost_open":7503,
            "cost_hold":7503,
            "profit_unreal":-4.442,
            "profit_rate":-0.00666622225185016,
            "profit":-4.442,
            "margin_position":0.000666622225184987,
            "position_value":5.49,
            "direction":"buy",
            "last_price":7500.5,
            "delivery_date":"20200508",
            "option_right_type":"C",
            "exercise_price":3500,
            "quote_asset":"USDT",
            "margin_asset":"BTC"
        }
    ],
    "status":"ok",
    "ts":1590047279305
}

Return parameters

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000" ...
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
volume	true	decimal	Position Quantity
available	true	decimal	Available Close Quantity
frozen	true	decimal	Frozen Quantity
cost_open	true	decimal	Average open price
cost_hold	true	decimal	Average position price
profit_unreal	true	decimal	Unrealized PnL
profit_rate	true	decimal	Profit Rate
profit	true	decimal	Profit
margin_position	true	decimal	Performance Margin
position_value	true	decimal	Position Value
direction	true	string	Position Direction	"buy": long "sell": sell
last_price	true	decimal	Latest Price
delivery_date	true	string	Delivery Date	eg"20200508"
option_right_type	true	string	Options Type	C: Call options P: Put options
exercise_price	true	decimal	Strike Price
quote_asset	true	string	Quote Coin	"USDT"...
margin_asset	true	string	Margin Coin	"BTC"...
</data>

Query account financial records

• POST /option-api/v1/option_financial_record

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT"
}

Request Parameters

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"
type	false	string	Query all type if not filled,【Separate with commas if querying multiple types】	1:open long; 2:open short; 3:close long; 4:close short; 5:fees for open positions-taker; 6:fees for open positions-maker; 7:fees for close positions-taker; 8:fees for close positions-maker; 9:close long for delivery; 10:close short for delivery; 11:delivery fee; 12:close long for liquidation; 13:lose short for liquidation; 14:transfer from spot exchange to contract exchange; 15:tranfer from contract exchange to spot exchange; 16:settle unrealized PnL-long positions; 17:settle unrealized PnL-short positions; 19:clawback; 26:system; 28:activity prize rewards; 29:rebate; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master;
create_date	false	int	Enter a positive integer; if the parameter exceeds 90, a default 90 days' data will be queried.
page_index	false	int	Page number. Default page 1 if not filled
page_size	false	int	default 20 if not filled; no more than 50

Response:

{
    "status": "ok",
    "data": {
        "total_page": 1,
        "current_page": 1,
        "total_size": 9,
        "financial_record": [
            {
                "id": 321223,
                "symbol": "USDT",
                "contract_code": "",
                "type": 34,
                "amount": -10,
                "ts": 1604888539807,
                "trade_partition": "USDT"
            },
            {
                "id": 321222,
                "symbol": "USDT",
                "contract_code": "",
                "type": 14,
                "amount": 10,
                "ts": 1604888516515,
                "trade_partition": "USDT"
            }
        ]
    },
    "ts": 1604888841800
}

Return parameters

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object	Dictionary Type
<financial_record>	true	object array
id	true	long	Financial record ID (contract code unqiue)
ts	true	long	Create Time
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000"， ...
type	true	int	TradeType	1:open long; 2:open short; 3:close long; 4:close short; 5:fees for open positions-taker; 6:fees for open positions-maker; 7:fees for close positions-taker; 8:fees for close positions-maker; 9:close long for delivery; 10:close short for delivery; 11:delivery fee; 12:close long for liquidation; 13:lose short for liquidation; 14:transfer from spot exchange to contract exchange; 15:tranfer from contract exchange to spot exchange; 16:settle unrealized PnL-long positions; 17:settle unrealized PnL-short positions; 19:clawback; 26:system; 28:activity prize rewards; 29:rebate; 34:transfer to sub; 35:transfer from sub; 36:transfer to master; 37:transfer from master;
amount	true	decimal	Amount
</financial_record>
current_page	true	int	Current Page
total_page	true	int	Total Pages
total_size	true	int	Total Size
</data>

Query Option information on order limit

• POST /option-api/v1/option_order_limit

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT",
  "order_price_type": "ioc"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"
order_price_type	true	string	Order Type	"limit":Limit，"opponent": BBO，"lightning": Flash close，"optimal_5": Optimal 5，"optimal_10": Optimal 10，"optimal_20": Optimal 20，"fok": FOK Order，"ioc": IOC Order, "opponent_ioc": BBO-IOC，"lightning_ioc": Flash close-IOC，"optimal_5_ioc": Optimal 5-IOC，"optimal_10_ioc": Optimal 10-IOC，"optimal_20_ioc": Optimal 20-IOC，"opponent_fok": FOK order using BBO price，"lightning_fok": Flash close-FOK，"optimal_5_fok": Optimal 5-FOK，"optimal_10_fok": Optimal 10-FOK，"optimal_20_fok": Optimal 20-FOK

Response:

{
    "status": "ok",
    "data": {
        "order_price_type": "limit",
        "list": [
            {
                "symbol": "BTC",
                "types": [
                    {
                        "contract_type": "this_week",
                        "option_right_type": "C",
                        "open_limit": 100000,
                        "close_limit": 200000
                    },
                    {
                        "contract_type": "this_week",
                        "option_right_type": "P",
                        "open_limit": 100000,
                        "close_limit": 200000
                    },
                    {
                        "contract_type": "next_week",
                        "option_right_type": "C",
                        "open_limit": 100000,
                        "close_limit": 200000
                    },
                    {
                        "contract_type": "next_week",
                        "option_right_type": "P",
                        "open_limit": 100000,
                        "close_limit": 200000
                    },
                    {
                        "contract_type": "quarter",
                        "option_right_type": "C",
                        "open_limit": 100000,
                        "close_limit": 200000
                    },
                    {
                        "contract_type": "quarter",
                        "option_right_type": "P",
                        "open_limit": 100000,
                        "close_limit": 200000
                    }
                ],
                "trade_partition": "USDT"
            }
        ]
    },
    "ts": 1604888933651
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object
order_price_type	true	string	OrderType	"limit": Limit Order，"opponent": BBO，"lightning": Flash close，"optimal_5": Optimal 5，"optimal_10": Optimal 10，"optimal_20": Optimal 20，"fok": FOKOrder，"ioc": IOC Order, "opponent_ioc": BBO-IOC，"lightning_ioc": Flash close-IOC，"optimal_5_ioc": Optimal 5-IOC，"optimal_10_ioc": Optimal 10-IOC，"optimal_20_ioc": Optimal 20-IOC，"opponent_fok": FOK order using BBO price，"lightning_fok": Flash close-FOK，"optimal_5_fok": Optimal 5-FOK，"optimal_10_fok": Optimal 10-FOK，"optimal_20_fok": Optimal 20-FOK
<list>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
<types>	true	object array
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
option_right_type	true	string	Options Type	C: Call options P: Put options
open_limit	true	long	Max positions to open for a single order
close_limit	true	long	Max positions to close for a single order
</types>
</list>
</data>

Query information on option trading fee

• POST /option-api/v1/option_fee

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "open_maker_fee": "0.002",
            "open_taker_fee": "0.005",
            "close_maker_fee": "0.002",
            "close_taker_fee": "0.005",
            "fee_rate_type": 2,
            "max_trade_in_fee_rate": "0.125",
            "max_trade_out_fee_rate": "0.08",
            "call_delivery_fee": "0.002",
            "put_delivery_fee": "0.002",
            "max_delivery_fee_rate": "0.125",
            "trade_partition": "USDT",
            "fee_asset": "USDT"
        }
    ],
    "ts": 1604888987136
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object array
symbol	true	string	Asset variety	"BTC","ETH"，"USDT"...
trade_partition	true	string	Trade Partition	"USDT"
fee_asset	true	string	Transaction Fee coin
open_maker_fee	true	string	Maker Transaction Fee/Fee Rate for opening positions, decimal format
open_taker_fee	true	string	Taker Transaction Fee/Fee Rate for opening positions, decimal format
close_maker_fee	true	string	Close Maker Transaction Fee/Fee Rate for closing positions, decimal format
close_taker_fee	true	string	Close Taker Transaction Fee/Fee Rate for closing positions, decimal format
call_delivery_fee	true	string	Call Option Delivery Transaction Fee/Fee Rate, decimal format
put_delivery_fee	true	string	Put Option Delivery Transaction Fee/Fee Rate, decimal format
fee_rate_type	true	int	Fee rate type 1: relative fee, 2: absolute fee（relative fee uses transaction fee rate; absolute fee uses transaction fee, unit: USDT）
max_trade_in_fee_rate	true	string	Platform transaction fee charging upper limit (ratio), decimal format
max_trade_out_fee_rate	true	string	Platform transaction fee expense upper limit (ratio), decimal format
max_deliv_fee_rate	true	string	Delivery transaction fee upper limit (ratio), decimal format
</data>

Query information on Transfer Limit

• POST /option-api/v1/option_transfer_limit

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "transfer_in_max_each": 8000,
            "transfer_in_min_each": 0.0001,
            "transfer_out_max_each": 800,
            "transfer_out_min_each": 0.000001,
            "transfer_in_max_daily": 80000,
            "transfer_out_max_daily": 16000,
            "net_transfer_in_max_daily": 40000,
            "net_transfer_out_max_daily": 8000,
            "trade_partition": "USDT"
        }
    ],
    "ts": 1604889046636
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
transfer_in_max_each	true	decimal	Max amount of a single transfer_in
transfer_in_min_each	true	decimal	Min amount of a single transfer_in
transfer_out_max_each	true	decimal	Max amount of a single transfer_out
transfer_out_min_each	true	decimal	Min amount of a single transfer_out
transfer_in_max_daily	true	decimal	Max amount of daily cumulative transfer_in
transfer_out_max_daily	true	decimal	Max amount of daily cumulative transfer_out
net_transfer_in_max_daily	true	decimal	Max amount of daily cumulative net transfer_in
net_transfer_out_max_daily	true	decimal	Max amount of daily cumulative net transfer_out
</data>

Query information on position limit

• POST /option-api/v1/option_position_limit

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "list": [
                {
                    "contract_type": "this_week",
                    "option_right_type": "C",
                    "buy_limit": 1000000,
                    "sell_limit": 1000000
                },
                {
                    "contract_type": "this_week",
                    "option_right_type": "P",
                    "buy_limit": 1000000,
                    "sell_limit": 1000000
                },
                {
                    "contract_type": "next_week",
                    "option_right_type": "C",
                    "buy_limit": 1000000,
                    "sell_limit": 1000000
                },
                {
                    "contract_type": "next_week",
                    "option_right_type": "P",
                    "buy_limit": 1000000,
                    "sell_limit": 1000000
                },
                {
                    "contract_type": "quarter",
                    "option_right_type": "C",
                    "buy_limit": 1000000,
                    "sell_limit": 1000000
                },
                {
                    "contract_type": "quarter",
                    "option_right_type": "P",
                    "buy_limit": 1000000,
                    "sell_limit": 1000000
                },
                {
                    "contract_type": "all",
                    "option_right_type": "C",
                    "buy_limit": 3000000,
                    "sell_limit": 3000000
                },
                {
                    "contract_type": "all",
                    "option_right_type": "P",
                    "buy_limit": 3000000,
                    "sell_limit": 3000000
                }
            ],
            "trade_partition": "USDT"
        }
    ],
    "ts": 1604889079265
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
<list>	true	object array
option_right_type	true	string	Options Type	C-Call，P-Put
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"，All Contracts:“all”
buy_limit	true	decimal	Max long position limit, unit: cont
sell_limit	true	decimal	Max short position limit, unit: cont
</list>
</data>

Query account and position info

• post option-api/v1/option_account_position_info

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"

Note：

• If request BTC asset, BTC asset info and all positions info of BTC options will be returned; if request USDT asset, only USDT asset info will be returned and no positions info will be returned.

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "USDT",
            "margin_balance": 10.44982,
            "margin_position": 0,
            "margin_frozen": 0,
            "margin_available": 7.55257,
            "profit_real": -0.005,
            "profit_unreal": 0,
            "withdraw_available": 7.55257,
            "margin_static": 7.55257,
            "premium_frozen": 0,
            "fee_frozen": 0,
            "premium_in": 0,
            "premium_out": 2.89725,
            "delta": null,
            "gamma": null,
            "theta": null,
            "vega": null,
            "option_value": 2.89725,
            "trade_partition": "USDT",
            "fee_asset": "USDT",
            "margin_asset": "USDT",
            "positions": [
                {
                    "symbol": "BTC",
                    "contract_code": "BTC-USDT-201225-C-13000",
                    "contract_type": "quarter",
                    "volume": 1,
                    "available": 1,
                    "frozen": 0,
                    "cost_open": 2897.25,
                    "cost_hold": 2897.25,
                    "profit_unreal": 0,
                    "profit_rate": 0,
                    "margin_position": 0,
                    "position_value": 2.89725,
                    "direction": "buy",
                    "profit": -0.005,
                    "last_price": 2897.25,
                    "delivery_date": "20201225",
                    "option_right_type": "C",
                    "exercise_price": 13000,
                    "quote_asset": "USDT",
                    "trade_partition": "USDT",
                    "margin_asset": "BTC"
                }
            ]
        }
    ],
    "ts": 1604889122270
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	long	long	Time of Response Generation, unit: millisecond
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
margin_balance	true	decimal	Account Equity
margin_position	true	decimal	Performance Margin
margin_frozen	true	decimal	Frozen Margin
margin_asset	true	decimal	Margin Asset
margin_available	true	decimal	Available Margin
profit_real	true	decimal	Realized PnL
profit_unreal	true	decimal	Unrealized PnL
withdraw_available	true	decimal	Transferable Amount
margin_static	true	decimal	Static Equity
premium_frozen	true	decimal	Frozen Premium
fee_frozen	true	decimal	Frozen Transaction Fee
fee_asset	true	string	Transaction Fee coin
premium_in	true	decimal	Current week premium income
premium_out	true	decimal	Current week premium expense
delta	true	decimal	DELTA
gamma	true	decimal	GAMMA
theta	true	decimal	THETA
vega	true	decimal	VEGA
option_value	true	decimal	Option Market Value(unit:"USDT")
<positions>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
volume	true	decimal	Position Quantity
available	true	decimal	Available Close Quantity
frozen	true	decimal	Frozen Quantity
cost_open	true	decimal	Average open price
cost_hold	true	decimal	Average position price
profit_unreal	true	decimal	Unrealized PnL
profit_rate	true	decimal	Profit Rate
profit	true	decimal	Profit
margin_position	true	decimal	Performance Margin
position_value	true	decimal	Position Value
direction	true	string	"buy":Buy "sell":Sell
last_price	true	decimal	Latest Price
delivery_date	true	string	Delivery Date	eg"20200508"
option_right_type	true	string	Options Type	C:Call options P:Put options
exercise_price	true	decimal	Strike Price
quote_asset	true	string	Quote Coin	"USDT"...
margin_asset	true	string	Margin Coin	"BTC"...
</positions>
</data>

Note：

• The market value of options under USDT assets is the value of all options held in the USDT partition;the market value of options under BTC assets is the value of positions of BTC options;the market value of options under ETH assets is the value of positions of ETH options.

Transfer between master and sub account

• post /option-api/v1/option_master_sub_transfer

Request:

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

请求参数

Parameter Name	Mandatory	Type	Desc	Value Range
sub_uid	true	long	Sub-accountuid
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
amount	true	decimal	Transfer Amount
type	true	string	Transfer Type	master_to_sub: transfer from master account to sub-account， sub_to_master: transfer from sub-account to master account

Note：

• the rate limit between the master account and each subaccount is 10 times/ minute

Response:

{
    "status": "ok",
    "data": {
        "order_id": "775309101143093248"
    },
    "ts": 1604889694272
}

response

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object
order_id	true	long	Transfer Order ID
</data>

Query transfer records between master and sub account

• post /option-api/v1/option_master_sub_transfer_record

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT",
  "transfer_type": "34",
  "create_date": 7
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"
transfer_type	false	string	Transfer Type. Query all types if not filled【seperate with comma if querying several types】	34: Transfer out to sub-account derivative account 35: Transfer in from sub-account derivative account
create_date	true	int	Date	Enter a positive integer; if the parameter exceeds 90, query 90 days' data by default.
page_index	false	int	Page number, default page 1 if not filled	1
page_size	false	int	Default 20 if not filled; no more than 50	20

Response:

{
    "status":"ok",
    "data":{
        "total_page":1,
        "current_page":1,
        "total_size":4,
        "transfer_record":[
            {
                "id":321255,
                "symbol":"USDT",
                "amount":10,
                "transfer_type":35,
                "ts":1604889694258,
                "sub_uid":"123456789",
                "sub_account_name":"tom",
                "trade_partition":"USDT"
            },
            {
                "id":321224,
                "symbol":"USDT",
                "amount":-10,
                "transfer_type":34,
                "ts":1604888539807,
                "sub_uid":"123456789",
                "sub_account_name":"tom",
                "trade_partition":"USDT"
            }
        ]
    },
    "ts":1604889988776
}

response

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object
<transfer_record>	true	object array
id	true	long	Tranfer Order ID
ts	true	long	Create Time
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
sub_uid	true	string	Sub-account UID
sub_account_name	true	string	Sub-account Login Name
transfer_type	true	int	Transfer Type	35:Transfer in from contract sub-account; 34:Transfer out to contract sub-account;
amount	true	decimal	Amount
</transfer_record>
total_page	true	int	Total Pages
current_page	true	int	Current Page
total_size	true	int	Total Size
</data>

Query user's API indicator disable information

• get /option-api/v1/option_api_trading_status

request body

null

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":159007866555
}

Response:

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object
is_disable	true	int	Disabled or not	1: Disabled，0: Not disabled
order_price_types	true	string	Order types that trigger DISABLE; separate multiple order types by commas. eg:“limit,post_only,FOK,IOC”
disable_reason	true	string	The reason for DISABLE triggered, indicating current DISABLE is triggered by which indicator.	"COR": Cancel order ratio（Cancel Order Ratio），“TDN”: Total disable number（Total Disable Number）
disable_interval	true	long	Disable time interval, unit: millisecond
recovery_time	true	long	Estimated recovery time, unit: millisecond
<COR>	true	object	Indicator of cancel order ratio
orders_threshold	true	long	Threshold of orders that can be placed
orders	true	long	User's actual number of orders
invalid_cancel_orders	true	long	Number of user's invalid order cancellation
cancel_ratio_threshold	true	decimal	Theshold of cancel order ratio
cancel_ratio	true	decimal	User's actual cancel order ratio
is_trigger	true	int	User triggered the indicator or not	1: triggered，0: not triggered
is_active	true	int	Indicator enabled or not
</COR>
<TDN>	true	object	Indicator of total disable number（Total Disable Number）
disables_threshold	true	long	Threshold of total distable number
disables	true	long	Acutal disable number
is_trigger	true	int	User triggered the indicator or not	1: triggered，0: not triggered
is_active	true	int	Indicator enabled or not
</TDN>
</data>

Option Trade Interface

Place an Order

Example

• POST /option-api/v1/option_order

Request:

{
  "contract_code": "BTC-USDT-201225-C-13000",
  "price": 4.4,
  "volume": 5,
  "direction": "buy",
  "offset": "open",
  "order_price_type": "limit"
}

Request Parameter

Parameter Name	Parameter Type	Mandatory	Desc	Value Range
contract_code	string	true	Contract Code	BTC-USDT-201225-C-13000
client_order_id	long	false	Shall be filled out and maintained by the client; must be numbers
price	decimal	false	Price
volume	long	true	Order Quantity (volume)
direction	string	true	Position Direction	"buy":Buy "sell":Sell
offset	string	true	Open/Close Direction	"open": open "close": close
order_price_type	string	true	Order Type	"limit": Limit Order "opponent": BBO "post_only": Post-only Order, placing a Post-only order is only limited by user's position quantity. optimal_5: Optimal 5, optimal_10: Optimal 10, optimal_20: Optimal 20，ioc: IOC Order，fok: FOK Order, "opponent_ioc": BBO-IOC，"optimal_5_ioc": Optimal 5-IOC，"optimal_10_ioc": Optimal 10-IOC，"optimal_20_ioc": Optimal 20-IOC，"opponent_fok": BBO-FOK，"optimal_5_fok": Optimal 5-FOK，"optimal_10_fok": Optimal 10-FOK，"optimal_20_fok": Optimal 20-FOK

Note ：

"limit": Limit Order, "post_only": Maker Order Only, ioc: IOC Order, fok: FOK Order, only these four types of orders require price parameter, others do not.

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

open long: Buy to open long(direction uses buy, offset uses open)

close long: Sell to close long(direction uses sell, offset uses close)

Open short: Sell to open short (direction uses sell, offset uses open)

close short: Buy to close short (direction uses buy, offset uses close)

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

Response:

{
    "status": "ok",
    "data": {
        "order_id": 775311792237785088,
        "order_id_str": "775311792237785088",
        "client_order_id": 563829342342342
    },
    "ts": 1604890335869
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
<data>	true	object
order_id	true	long	Order ID
order_id_str	true	string	StringType Order ID
client_order_id	false	long	Order ID filled in by the user when placing an order; no return if not filled
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Note

• order_id returns 18 digits. nodejs and javascript cannot parse 18 digits by default. In nodejs and javascript, JSON.parse defaults to int, and numbers with more than 18 digits are parsed using the json-bigint package.

Place a Batch of Orders

Example

• POST /option-api/v1/option_batchorder

Request:

{
  "orders_data": [
    {
      "contract_code": "BTC-USDT-201225-C-13000",
      "price": 1120,
      "volume": 1,
      "direction": "buy",
      "offset": "open",
      "order_price_type": "post_only",
      "client_order_id":563829342342343
    },
     {
      "contract_code": "BTC-USDT-201225-C-13000",
      "price": 1150,
      "volume": 1,
      "direction": "buy",
      "offset": "open",
      "order_price_type": "post_only",
      "client_order_id":563829342342345
    }
  ]
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
<orders_data>	true	object array
contract_code	true	string	Contract Code	BTC-USDT-201225-C-13000
client_order_id	false	long	Shall be filled out and maintained by the client; must be numbers
price	false	decimal	Price
volume	true	long	Order Quantity(volume)
direction	true	string	Position Direction	"buy":Buy "sell":Sell
offset	true	string	Open/Close Direction	"open":open "close":close
order_price_type	true	string	Order Type	"limit":Limit Order "opponent":BBO "post_only":Post-only Order, placing a Post-only order is only limited by user's position quantity, optimal_5: Optimal 5, optimal_10: Optimal 10, optimal_20: Optimal 20，ioc: IOCOrder，fok: FOK Order,"opponent_ioc": BBO-IOC，"optimal_5_ioc": Optimal 5-IOC，"optimal_10_ioc": Optimal 10-IOC，"optimal_20_ioc": Optimal 20-IOC，"opponent_fok": FOK order using BBO price，"optimal_5_fok": Optimal 5-FOK，"optimal_10_fok": Optimal 10-FOK，"optimal_20_fok": Optimal 20-FOK
</orders_data>

Note ：

• "limit": Limit Order, "post_only": Maker Order Only, ioc: IOC Order, fok: FOK Order, only these four types of orders require price parameter, others do not.

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

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

Response:

{
    "status": "ok",
    "data": {
        "errors": [
            {
                "index": 1,
                "err_code": 1050,
                "err_msg": "Customer's order number is repeated. Please try again later.",
                "errorParams": null
            }
        ],
        "success": [
            {
                "order_id": 775312478778372096,
                "order_id_str": "775312478778372096",
                "client_order_id": 563829342342345,
                "index": 2
            }
        ]
    },
    "ts": 1604890499553
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
<data>	true	object array
<errors>	true	object array
index	true	int	Order Index
err_code	true	int	Error Code
err_msg	true	string	Error Info
</errors>
<success>
index	true	int	Order Index
order_id	true	long	Order ID
order_id_str	true	string	Order ID in string format
client_order_id	true	long	Order ID filled in by the user when placing an order; no return if not filled
</success>
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Note

• order_id returns 18 digits. nodejs and javascript cannot parse 18 digits by default. In nodejs and javascript, JSON.parse defaults to int, and numbers with more than 18 digits are parsed using the json-bigint package.

Cancel an Order

Example

• POST /option-api/v1/option_cancel

Request:

{
  "order_id": "675016139515973632,675016139515973632,675016172537729024",
  "trade_partition": "USDT"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
order_id	false	string	Order ID (Seperate multiple Order IDs with commas; allow to cancel at most 10 orders at a time)
client_order_id	false	string	Client Order ID (Seperate multiple IDs with commas; allow to cancel at most 10 orders at a time)
trade_partition	false	string	Trade Partition	"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 24 hours; Otherwise, clients cannot check orders placed beyond 24 hours.

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

{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "771757367472893952",
                "err_code": 1061,
                "err_msg": "This order doesn't exist."
            }
        ],
        "successes": "775312478778372096"
    },
    "ts": 1604890627676
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
<data>	true	object array
<errors>	true	object array
order_id	true	string	Order ID
err_code	true	int	Error Code
err_msg	true	string	Error Info
</errors>
successes	true	string	order_id or client_order_id list of successfully canceled orders
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Cancel All Orders

Example

• POST /option-api/v1/option_cancelall

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"
contract_type	false	string	Contract Type	this_week: Weekly next_week: Bi-weekly quarter: Quarterly
contract_code	false	string	Contract Code	BTC-USDT-201225-C-13000

Note

• If there is "contract_code" parameter, canceling all contracts under this code.

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

{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "775311573278339072,775311792237785088,775312389775110144,775312389800275968"
    },
    "ts": 1604890694946
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
<data>	true	object array
<errors>	true	object array
order_id	true	string	Order ID
err_code	true	int	Order Failed Error Code
err_msg	true	string	Order Failed Info
</errors>
successes	true	string	Successful Orders
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Place Lightning Close Order

• POST /option-api/v1/option_lightning_close_position

Request:

{
  "contract_code": "BTC-USDT-201225-C-13000",
  "volume": 1,
  "direction": "sell"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	BTC-USDT-201225-C-13000
volume	true	long	Order Quantity (volume)
direction	true	string	Buy/Sell Direction	"buy": Buy，"sell": Sell
client_order_id	false	long	（API）shall be filled in and maintained by the client; shall be unique.
order_price_type	false	string	Order Type	if not filled, default"Flash close"，"lightning": Lightning close，"lightning_ioc": Lightning close-IOC，"lightning_fok": Lightning close-FOK

Note:

• Lightning close means that the order can be filled instantly at the price within BBO-Optimal30, and the unfilled part will be converted to a limit order automatically.

• The closing price of flash close orders has a predictable effect, which can avoid users' loss due to the orders cannot be filled when the market fluctuates violently.

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

Response:

{
    "status":"ok",
    "ts":1590024939929,
    "data":{
        "order_id":663049584884322304,
        "order_id_str":"663049584884322304"
    }
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" : successful, "error": failed
ts	true	long	Time of Response Generation, unit: millisecond
<data>	true	object
order_id	true	long	Order ID [at the user level, different users may have the same order_id.]
order_id_str	true	string	String Type Order ID
client_order_id	false	int	User's own Order ID
</data>

Error：

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

Query Order Information

Example

• POST /option-api/v1/option_order_info

Request:

{
  "order_id": "663044581377445880",
  "symbol": "BTC",
  "trade_partition": "USDT",
  "client_order_id": "663044581377445888"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
order_id	false	string	Order ID (Seperate multiple Order IDs with commas; allow to query at most 50 orders at a time.)
client_order_id	false	string	Client Order ID (Seperate multiple IDs with commas; allow to query at most 50 orders at a time.)
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"

Note：

• Either order_id or client_order_id can be used for querying. Only one of them and at least one of them is required at a time. If both of them are set, the order_id is used for querying by default. After the delivery on Friday, orders with status ended will be deleted. (5: partial filled orders have been deleted 6: all filled 7: deleted)

• The client_order_id is valid for 24 hours. Orders cannot be queried according to client_order_id if exceeding 24 hours.

Response:

{
    "status": "ok",
    "data": [
        {
            "symbol": "BTC",
            "contract_code": "BTC-USDT-201225-C-13000",
            "contract_type": "quarter",
            "volume": 1,
            "price": 2897.25,
            "order_price_type": "opponent",
            "order_type": 1,
            "direction": "buy",
            "offset": "open",
            "order_id": 775303174474293248,
            "order_id_str": "775303174474293248",
            "client_order_id": null,
            "created_at": 1604888281225,
            "trade_volume": 1,
            "trade_turnover": 2.89725,
            "fee": -0.005,
            "trade_avg_price": 2897.25,
            "margin_frozen": 0,
            "profit": 0,
            "status": 6,
            "order_source": "web",
            "delivery_date": "20201225",
            "option_right_type": "C",
            "exercise_price": 13000,
            "quote_asset": "USDT",
            "premium_frozen": 0,
            "fee_frozen": 0,
            "trade_partition": "USDT",
            "fee_asset": "USDT",
            "margin_asset": "BTC"
        }
    ],
    "ts": 1604890904670
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
<data>	true	object
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000"
volume	true	decimal	Order Quantity
price	true	decimal	Order Price
order_price_type	true	string	Order Type	"limit":Limit Order, "opponent":BBO, "post_only":Post-only Order, placing a Post-only order is only limited by user's position quantity, optimal_5: Optimal 5, optimal_10: Optimal 10, optimal_20: Optimal 20, ioc: IOC Order，fok: FOKOrder, "opponent_ioc": BBO-IOC，"optimal_5_ioc": Optimal 5-IOC，"optimal_10_ioc": Optimal 10-IOC，"optimal_20_ioc": Optimal 20-IOC，"opponent_fok": BBO-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:Place an order, 2: Cancel an order, 4:Delivery
direction	true	string	"buy": Buy "sell": Sell
offset	true	string	"open": open "close": close
order_id	true	long	Order ID
order_id_str	true	string	Order ID in string format
client_order_id	true	long	Client Order ID
created_at	true	long	Order Creation Time
trade_volume	true	decimal	Trading Volume
trade_turnover	true	decimal	Total trading amount
fee	true	decimal	Transaction Fee
fee_asset	true	string	Transaction Fee coin
trade_avg_price	true	decimal	AverageTransaction Price
margin_frozen	true	decimal	Frozen Margin
margin_asset	true	decimal	Margin Coin	"BTC"
profit	true	decimal	Profit
status	true	int	Order Status	(3 unfilled 4 partial filled 5partial filled and unfilled orders are cancelled 6 all filled 7 cancelled)
order_source	true	string	Order Source
delivery_date	true	string	Delivery Date	eg"20200508"
option_right_type	true	string	Options Type	C:Call options P:Put options
exercise_price	true	decimal	Strike Price
quote_asset	true	string	Quote Coin	eg"USDT"
premium_frozen	true	decimal	Frozen Premium
fee_frozen	true	decimal	Frozen Transaction Fee
</data>
ts	true	long	Timestamp

Query Order detail

Example

• POST /option-api/v1/option_order_detail

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT",
  "order_id": 663681892062679040,
  "order_type": 1
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"
order_id	true	long	Order ID
created_at	false	long	Order Create Timestamp
order_type	false	int	Order Type	1:Place an order, 2: cancel an order, 4:Delivery
page_index	false	int	Page Number, default page 1 if not filled
page_size	false	int	Default 20 if not filled; no more than 50

Note

• When querying order cancellation data from Order Details Acquisition interface, if there are parameters created_at and order_type, only 90 days data can be queried. If there are not parameters created_at or order_type, only 24 hours data can be queried.

• order_id returns 18 digits. nodejs and javascript cannot parse 18 digits by default. In nodejs and javascript, JSON.parse defaults to int, and numbers with more than 18 digits are parsed using the json-bigint package.

• created_at uses a 13-digit long type timestamp (including milliseconds). If an accurate timestamp is entered, query performance will improve. For example, "2019/10/18 10:26:22" is converted to timestamp 1571365582123. You can also get the timestamp directly from the TS returned by the contract_order Place an Order interface to query the corresponding order.

• The parameter of create_at cannot be 0.

Response:

{
    "status": "ok",
    "data": {
        "symbol": "BTC",
        "trade_partition": "USDT",
        "contract_code": "BTC-USDT-201225-C-13000",
        "contract_type": "quarter",
        "direction": "buy",
        "offset": "open",
        "volume": 1,
        "price": 2897.25,
        "created_at": 1604888281225,
        "canceled_at": 0,
        "order_source": "web",
        "order_price_type": "opponent",
        "margin_frozen": 0,
        "profit": 0,
        "option_right_type": "C",
        "exercise_price": 13000,
        "quote_asset": "USDT",
        "premium_frozen": 0,
        "fee_frozen": 0,
        "fee_asset": "USDT",
        "order_type": 1,
        "order_id": 775303174474293248,
        "order_id_str": "775303174474293248",
        "client_order_id": null,
        "trade_volume": 1,
        "trade_turnover": 2.89725,
        "fee": -0.005,
        "trade_avg_price": 2897.25,
        "status": 6,
        "delivery_date": "20201225",
        "margin_asset": "BTC",
        "trades": [
            {
                "trade_id": 125344032,
                "trade_price": 2897.25,
                "trade_volume": 1,
                "trade_turnover": 2.89725,
                "trade_fee": -0.005,
                "created_at": 1604888281258,
                "role": "taker",
                "id": "125344032-775303174474293248-1",
                "fee_asset": "USDT"
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1604890985365
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" , "error"
<data>	true	object
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000"
direction	true	string	Buy/Sell Direction	"buy":Buy "sell":Sell
offset	true	string	Open/Close Direction	"open": open "close": close
volume	true	decimal	Order Quantity
price	true	decimal	Order Price
created_at	true	long	Creation Time
canceled_at	true	long	Cancel Time
order_source	true	string	Order Source
order_price_type	true	string	Order Type	"limit": Limit Order "opponent": BBO "post_only": Post-only Order, placing a Post-only order is only limited by user's position quantity, optimal_5: Optimal 5、optimal_10: Optimal 10、optimal_20: Optimal 20，ioc: IOCOrder，fok: FOKOrder,"opponent_ioc": BBO-IOC，"optimal_5_ioc": Optimal 5-IOC，"optimal_10_ioc": Optimal 10-IOC，"optimal_20_ioc": Optimal 20-IOC，"opponent_fok": BBO-FOK，"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	decimal	Margin Coin
profit	true	decimal	Profit
order_type	true	int	Order Type，1:Place an order, 2: Cancel an order, 4:Delivery
order_id	true	long	Order ID
order_id_str	true	string	Order ID in string format
client_order_id	true	long	Client Order ID
trade_volume	true	decimal	Trading Volume
trade_turnover	true	decimal	Total trading amount
fee	true	decimal	Transaction Fee
fee_asset	true	string	Transaction Fee coin
trade_avg_price	true	decimal	AverageTransaction Price
status	true	int	Order Status	(3 unfilled 4 partial filled 5partial filled and unfilled orders are cancelled 6 all filled 7 cancelled)
delivery_date	true	string	Delivery Date	eg"20200508"
option_right_type	true	string	Options Type	C:Call options P:Put options
exercise_price	true	decimal	Strike Price
quote_asset	true	string	Quote Coin	eg"USDT"
premium_frozen	true	decimal	Frozen Premium
fee_frozen	true	decimal	Frozen Transaction Fee
total_page	true	int	Total Pages
current_page	true	int	Current Page
total_size	true	int	Total Size
<trades>	true	object array
id	true	string	Unique transaction id. Because trade_id is not unique, the specific method is to use trade_id and id as joint primary key and splice it into a unqiue transaction ID.
trade_id	true	long	Match result id. Because trade_id is not unique, the specific method is to use trade_id and id as joint primary key and splice it into a unqiue transaction ID.
trade_price	true	decimal	Match Price
trade_volume	true	decimal	Trading Volume
trade_turnover	true	decimal	Trading Amount
trade_fee	true	decimal	Transaction Fee
fee_asset	true	string	Transaction Fee coin
role	true	string	taker or maker
created_at	true	long	Creation Time
</trades>
</data>
ts	true	long	Timestamp

Query Open Orders

Example

• POST /option-api/v1/option_openorders

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT",
  "contract_code": "BTC-USDT-201225-C-13000",
  "page_index": 1,
  "page_size": 20
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	false	string	Coin Code	"BTC","ETH"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"
contract_code	false	string	Contract Code	"BTC-USDT-201225-C-13000" ...
page_index	false	int	Page number, default page1 if not filled
page_size	false	int	Page size, default 20 if not filled; no more than 50

Response:

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-201225-C-13000",
                "contract_type": "quarter",
                "volume": 1,
                "price": 1204.79,
                "order_price_type": "post_only",
                "order_type": 1,
                "direction": "buy",
                "offset": "open",
                "order_id": 775314891945996288,
                "order_id_str": "775314891945996288",
                "client_order_id": 563829342342349,
                "created_at": 1604891074887,
                "trade_volume": 0,
                "trade_turnover": 0,
                "fee": 0,
                "trade_avg_price": 0,
                "margin_frozen": 0,
                "profit": 0,
                "status": 3,
                "order_source": "api",
                "delivery_date": "20201225",
                "option_right_type": "C",
                "exercise_price": 13000,
                "quote_asset": "USDT",
                "premium_frozen": 1.20479,
                "fee_frozen": 0.005,
                "trade_partition": "USDT",
                "fee_asset": "USDT",
                "margin_asset": "BTC"
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1604891079443
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result
<data>	true	object
<orders>	true	object
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000"
volume	true	decimal	Order Quantity
price	true	decimal	Order Price
order_price_type	true	string	Order Type	"limit": Limit Order "opponent": BBO "post_only":Post-only Order, placing a Post-only order is only limited by user's position quantity, optimal_5: Optimal 5、optimal_10: Optimal 10, optimal_20: Optimal 20，ioc: IOC Order，fok: FOK Order,"opponent_ioc": BBO-IOC，"optimal_5_ioc": Optimal 5-IOC，"optimal_10_ioc": Optimal 10-IOC，"optimal_20_ioc": Optimal 20-IOC，"opponent_fok": BBO-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: Place an order, 2: Cancel an order, 4: Delivery
direction	true	string	"buy": Buy "sell": Sell
offset	true	string	"open": open "close": close
order_id	true	long	Order ID
order_id_str	true	string	Order ID in string format
client_order_id	true	long	Client Order ID
created_at	true	long	Order Creation Time
trade_volume	true	decimal	Trading Volume
trade_turnover	true	decimal	Total Trading Amount
fee	true	decimal	Transaction Fee
trade_avg_price	true	decimal	Average Transaction Price
margin_frozen	true	decimal	Frozen Margin
margin_asset	true	decimal	Margin Coin
profit	true	decimal	Profit
status	true	int	Order Status	(3: unfilled 4: partial filled 5: partial filled orders have been deleted 6: all filled 7:deleted)
order_source	true	string	Order Source
delivery_date	true	string	Delivery Date	eg"20200508"
option_right_type	true	string	Options Type	C: Call options P: Put options
exercise_price	true	decimal	Strike Price
quote_asset	true	string	Quote Coin	eg"USDT"
premium_frozen	true	decimal	Frozen Premium
fee_frozen	true	decimal	Frozen Transaction Fee
fee_asset	true	string	Transaction Fee coin
</orders>
total_page	true	int	Total Pages
current_page	true	int	Current Page
total_size	true	int	Total Size
</data>
ts	true	long	Timestamp

Query History Orders

Example

• POST /option-api/v1/option_hisorders

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT",
  "trade_type": 0,
  "type": 2,
  "status": 0,
  "create_date": 7
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"
trade_type	true	int	Trade Type	0: all, 1:Buy to open long, 2: Sell to open short, 3: Buy to close short, 4: Sell to close long, 7:Delivery to close long, 8: Delivery to close short
type	true	int	Type	1:all orders, 2:orders with status ended
status	true	int	Order Status	0:all, 3:unfilled, 4: partial filled, 5: partial filled and unfilled orders are cancelled, 6: all filled, 7:cancelled
create_date	true	int	Date	Enter a positive integer; if the parameter exceeds 90, a default 90 days'data will be queried.
page_index	false	int	Page number, default page 1 if not filled
page_size	false	int	page size, default 20	no more than 50
contract_code	false	string	Contract Code	BTC-USDT-201225-C-13000
sort_by	false	string	sort fields(descending)	"create_date"：descending order by order create date , "update_time": descending order by order update time

Note:

• The records of cancelled and unfilled limit orders are only kept for 24 hours.

Response:

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "order_id": 775314891945996288,
                "order_id_str": "775314891945996288",
                "contract_code": "BTC-USDT-201225-C-13000",
                "symbol": "BTC",
                "direction": "buy",
                "offset": "open",
                "volume": 1,
                "price": 1204.79,
                "create_date": 1604891074887,
                "update_time": 1604891074887,
                "order_source": "api",
                "order_price_type": "post_only",
                "order_type": 1,
                "margin_frozen": 0,
                "profit": 0,
                "contract_type": "quarter",
                "trade_volume": 0,
                "trade_turnover": 0,
                "fee": 0,
                "trade_avg_price": 0,
                "status": 3,
                "delivery_date": "20201225",
                "option_right_type": "C",
                "exercise_price": 13000,
                "quote_asset": "USDT",
                "trade_partition": "USDT",
                "fee_asset": "USDT",
                "margin_asset": "BTC"
            }
        ],
        "total_page": 22,
        "current_page": 1,
        "total_size": 22
    },
    "ts": 1604891148311
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
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 in string format
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000"
direction	true	string	Buy/Sell Direction	"buy":Buy "sell":Sell
offset	true	string	Open/Close Direction	"open": open "close": close
volume	true	decimal	Order Quantity
price	true	decimal	Order Price
create_date	true	long	Creation Time
update_time	true	long	order update time，millesecond timestamp
order_source	true	string	Order Source
order_price_type	true	string	Order 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	Frozen Margin
margin_asset	true	decimal	Margin Coin
profit	true	decimal	Profit
trade_volume	true	decimal	Trading Volume
trade_turnover	true	decimal	Total Trading Amount
fee	true	decimal	Transaction Fee
fee_asset	true	string	Transaction Fee coin
trade_avg_price	true	decimal	Average Transaction Price
status	true	int	Order Status
order_type	true	int	Order Type	1: Place an order, 2: Cancel an order, 4: Delivery
delivery_date	true	string	Delivery Date	eg"20200508"
option_right_type	true	string	Options Type	C: Call options P: Put options
exercise_price	true	decimal	Strike Price
quote_asset	true	string	Quote Coin	eg"USDT"
</orders>
current_page	true	int	Current Page
total_page	true	int	Total Pages
total_size	true	int	Total Size
</data>
ts	true	long	Time Stamp

Note

• order_id returns 18 digits. nodejs and javascript cannot parse 18 digits by default. In nodejs and javascript, JSON.parse defaults to int, and numbers with more than 18 digits are parsed using the json-bigint package.

Query History Match Results

Example

• POST /option-api/v1/option_matchresults

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT",
  "trade_type": 1,
  "create_date": 7
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"，If default, all coins will be returned.
trade_partition	false	string	Trade Partition	"USDT"
trade_type	true	int	Trade Type	0: all,1: Buy to open long, 2: Sell to open short, 3: Buy to close short, 4: Sell to close long
create_date	true	int	Date	Enter a positive integer; if the parameter exceeds 90, 90 days' data will be queried.
contract_code	false	string	Contract Code	BTC-USDT-201225-C-13000
role	false	string	taker or maker
page_index	false	int	Page number, default page 1
page_size	false	int	Default 20 if not filled; no more than 50

Note:

• Request parameter“create_date”changes from "can only enter 7 or 90" to " Enter a positive integer; if the parameter exceeds 90, 90 days' data will be queried."

Response:

{
    "status": "ok",
    "data": {
        "trades": [
            {
                "match_id": 125344032,
                "order_id": 775303174474293248,
                "order_id_str": "775303174474293248",
                "symbol": "BTC",
                "contract_type": "quarter",
                "contract_code": "BTC-USDT-201225-C-13000",
                "direction": "buy",
                "offset": "open",
                "trade_volume": 1,
                "trade_price": 2897.25,
                "trade_turnover": 2.89725,
                "trade_fee": -0.005,
                "offset_profitloss": 0,
                "create_date": 1604888281258,
                "role": "Taker",
                "order_source": "web",
                "id": "125344032-775303174474293248-1",
                "quote_asset": "USDT",
                "delivery_date": "20201225",
                "option_right_type": "C",
                "exercise_price": 13000,
                "trade_partition": "USDT",
                "fee_asset": "USDT"
            }
        ],
        "total_page": 7,
        "current_page": 1,
        "total_size": 7
    },
    "ts": 1604891293936
}  

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result
<data>	true	object
<trades>	true	object array
id	true	string	Unique transaction id. Because trade_id is not unique, the specific method is to use trade_id and id as joint primary key and splice it into a unqiue transaction ID.
match_id	true	long	Transaction ID, not unique
order_id	true	long	OrderID
order_id_str	true	string	Order ID in string format
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000"
direction	true	string	Buy/Sell Direction	"buy":Buy "sell":Sell
offset	true	string	Open/Close Direction	"open": open "close": close
trade_volume	true	decimal	Trading Volume
trade_price	true	decimal	Transaction Price
trade_turnover	true	decimal	Transaction Amount
create_date	true	long	Transaction Time
offset_profitloss	true	decimal	PnL after closing positions
traded_fee	true	decimal	Transaction Fee
fee_asset	true	string	Transaction Fee Coin
role	true	string	Transaction type	taker、maker、Otm delivery records、Itm delivery records
order_source	true	string	Order Source
delivery_date	true	string	Delivery Date	eg"20200508"
option_right_type	true	string	Options Type	C: Call options P: Put options
exercise_price	true	decimal	Strike Price
quote_asset	true	string	Denomination Coin	eg"USDT"
</trades>
current_page	true	int	Current Page
total_page	true	int	Total Pages
total_size	true	int	Total Size
</data>
ts	true	long	Timestamp

Notice

• If there are not parameters page_index and page_size, the system will query the top 20 data on the first page by default. For more details, plese check parameters illustration.

• order_id returns 18 digits. nodejs and javascript cannot parse 18 digits by default. In nodejs and javascript, JSON.parse defaults to int, and numbers with more than 18 digits are parsed using the json-bigint package.

Place Trigger Order

• POST option-api/v1/option_trigger_order

Request:

{
  "contract_code": "BTC-USDT-201225-C-13000",
  "trigger_type": "le",
  "trigger_price": "7900",
  "order_price": "7900",
  "order_price_type": "limit",
  "volume": "1",
  "direction": "buy",
  "offset": "close"
}

body

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	BTC-USDT-201225-C-13000
trigger_type	true	string	Trigger Type: ge equal to or greater than (Trigger Price is higher than Latest Price)；le less than (Trigger Price is lower than Latest Price)
trigger_price	true	decimal	Trigger Price，if the precision exceeds the minimum variation unit, an error will be reported
order_price	false	decimal	Order Price，if the precision exceeds the minimum variation unit, an error will be reported
order_price_type	false	string	Order Type: default limit if not filled;	Limit Order: limit ，Optimal 5: optimal_5，Optimal 10: optimal_10，Optimal 20: optimal_20
volume	true	long	Order Quantity(volume)
direction	true	string	Buy/Sell Direction	buy: Buy sell: Sell
offset	true	string	Open/Close Direction	open: open close: close

Note

• optimal_5: Optimal 5、optimal_10: Optimal 10、optimal_20: Optimal 20 order_price isn't required to be filled，"limit":Limit Order requires filling price。

Return:

{
    "status": "ok",
    "data": {
        "order_id": 775316559685038080,
        "order_id_str": "775316559685038080"
    },
    "ts": 1604891472516
}

Response Desc

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" :successful, "error": failed
ts	true	long	Time of Response Generation, unit: millisecond
err_code	long	false	error code
err_msg	string	false	error message
<data>	true	object		Dictionary
order_id	true	long	Order ID[at the user level, different users may have the same order_id.]
order_id_str	true	string	String Type Order ID
</data>

Error：

{
    "status": "error",
    "err_code": 1014,
    "err_msg": "This contract doesn't exist.",
    "ts": 1604891496965
}

Cancel Trigger Order

• POST /option-api/v1/option_trigger_cancel

Request:

{
  "symbol":"BTC",
  "trade_partition": "USDT",
  "order_id": "161251,161256,1344567"
}

request params

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH" ...
trade_partition	false	string	Trade Partition	"USDT"
order_id	true	string	User Order ID（Seperate multiple Order IDs with commas; allow to cancel at most 20 orders at a time. ）

Response:

{
    "status": "ok",
    "data": {
        "errors": [
            {
                "order_id": "775316816045150201",
                "err_code": 1061,
                "err_msg": "This order doesn't exist."
            }
        ],
        "successes": "775316816045150208"
    },
    "ts": 1604891550756
}

response

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok": successful, "error": failed
<data>	true	object
<errors>	true	object		Dictionary
order_id	true	string	Order ID [at the user level, different users may have the same order_id.]
err_code	false	long	Error Code
err_msg	false	string	Error Info
</errors>
successes	true	string	Successful Orders
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Cancel All Trigger Orders

• POST /option-api/v1/option_trigger_cancelall

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT"
}

Params

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"
contract_code	false	string	Contract Code	"BTC-USDT-201225-C-13000"
contract_type	false	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"

Note

• If there is "contract_code" parameter, canceling all contracts under this code.

Response:

{
    "status": "ok",
    "data": {
        "errors": [],
        "successes": "775316559685038080"
    },
    "ts": 1604891729726
}

response params

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok": succesfful, "error": failed
<data>	true	object
<errors>	true	object		Dictionary
order_id	true	string	Order ID [at the user level, different users may have the same order_id.]
err_code	false	long	Error Code
err_msg	false	string	Error Info
</errors>
successes	true	string	Successful Orders
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Query Trigger Order Open Orders

• POST option-api/v1/option_trigger_openorders

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT",
  "page_index": "1",
  "page_size": "50"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"
contract_code	false	string	Contract Code	"BTC-USDT-201225-C-13000"
page_index	false	int	Page number. Default page1 if not filled
page_size	false	int	Default 20 if not filled; no more than 50

Response:

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-201225-C-13000",
                "contract_type": "quarter",
                "trigger_type": "le",
                "volume": 1,
                "order_type": 1,
                "direction": "buy",
                "offset": "open",
                "order_id": 775317966815424512,
                "order_id_str": "775317966815424512",
                "status": 2,
                "order_source": "api",
                "trigger_price": 100,
                "order_price": 100,
                "order_price_type": "limit",
                "created_at": 1604891807992,
                "trade_partition": "USDT"
            }
        ],
        "total_page": 1,
        "current_page": 1,
        "total_size": 1
    },
    "ts": 1604891813788
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok": successful, "error": failed
<data>	true	object		Dictionary
total_page	true	int	Total Pages
total_size	true	int	Total Size
current_page	true	int	Current Page
<orders>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000"
trigger_type	true	string	Trigger Type: ge equals to or greater than；le eaquals to or less than
volume	true	decimal	Order Quantity
order_type	true	int	Order Type: 1, place an order 2, cancel an order
direction	true	string	Buy/Sell Direction	Buy: "buy",Sell: "sell"
offset	true	string	Open/Close Direction	open: "open", close: "close"
order_id	true	long	Trigger Order ID
order_id_str	true	string	String Type Order ID
order_source	true	string	Source	r
trigger_price	true	decimal	Trigger Price
order_price	true	decimal	Order Price
created_at	true	long	Order Creation Time
order_price_type	true	string	Order Type	"limit":Limit Order，"optimal_5":Optimal 5，"optimal_10":Optimal 10，"optimal_20":Optimal 20
status	true	int	Order Status:	1:To submit，2: Submitted, 3:Order placing in progress, 7:Wrong orders, 8: Cannot find the canceled orders, 9: Orders cancelling in progress, 10: Failed
</orders>
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Query Trigger Order History

• POST /option-api/v1/option_trigger_hisorders

Request:

{
  "symbol": "BTC",
  "trade_partition": "USDT",
  "trade_type": "0",
  "status": "0",
  "create_date": "100"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	false	string	Trade Partition	"USDT"
contract_code	false	string	Contract Code	"BTC-USDT-201225-C-13000"
trade_type	true	int	TradeType	0: all,1: Buy to open long,2: Sell to open short, 3: Buy to close short, 4: Sell to close long；the backstage queries by converting the value to offset and direction; cannot query by other values.
status	true	string	Order Status	Seperate multiple status with commas. Trigger order status: 0: all（represents all orders with status ended）, 4: trigger orders successfully submitted, 5: trigger orders failed being submitted、6: order canceled
create_date	true	long	Date	Enter a positive integer; if the parameter exceeds 90, a default 90 days' data will be queried.
page_index	false	int	Page number. Default page 1 if not filled
page_size	false	int	Default 20 if not filled; no more than 50
sort_by	false	string	sort fields(descending)	"created_at"：descending order by order creation time, "update_time": descending order by order update time

NOTE

• Querying the filled trigger orders by default (type corresponds to the status 4,5,6) ；

Response:

{
    "status": "ok",
    "data": {
        "orders": [
            {
                "symbol": "BTC",
                "contract_code": "BTC-USDT-201225-C-13000",
                "contract_type": "quarter",
                "trigger_type": "le",
                "volume": 1,
                "order_type": 1,
                "direction": "buy",
                "offset": "open",
                "order_id": 775316816045150208,
                "order_id_str": "775316816045150208",
                "relation_order_id": null,
                "status": 6,
                "order_source": "api",
                "trigger_price": 100,
                "triggered_price": null,
                "order_price": 100,
                "order_price_type": "limit",
                "created_at": 1604891533629,
                "update_time": 1604891533629,
                "triggered_at": null,
                "order_insert_at": 0,
                "canceled_at": 1604891551047,
                "fail_code": null,
                "fail_reason": null,
                "trade_partition": "USDT"
            }
        ],
        "total_page": 7,
        "current_page": 1,
        "total_size": 7
    },
    "ts": 1604891892449
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
status	true	string	Request Processing Result	"ok" :successful, "error": failed
<data>	true	object		Dictionary
total_page	true	int	Total Pages
current_page	true	int	Current Page
total_size	true	int	Total Size
<orders>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	Contract Type	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000"
trigger_type	true	string	Trigger Type	ge equals to or greater than；le equals to or lower than
volume	true	decimal	Order Quantity
order_type	true	int	Order Type	1: place an order 2: cancel an order
direction	true	string	Buy/Sell Direction	Buy: "buy",Sell: "sell"
offset	true	string	Open/Close Direction	open: "open", close: "close"
order_id	true	decimal	Trigger Order ID
order_id_str	true	string	String Type Order ID
relation_order_id	true	string	The field is the related field of the related limit orders. the value is -1 before the order is trigged.
order_price_type	true	string	OrderType	"limit":Limit Order，"optimal_5":Optimal 5，"optimal_10":Optimal 10，"optimal_20":Optimal 20
status	true	int	Order Status	4: order successfully placed, 5: order failed to be placed, 6: order cancelled
order_source	true	string	Source
trigger_price	true	decimal	Trigger Price
triggered_price	true	decimal	Price at the triggering
order_price	true	decimal	Order Price
created_at	true	long	Order Creation Time
update_time	true	long	order update time，millesecond timestamp
triggered_at	true	long	Trigger Time
order_insert_at	true	long	Order Placing Time
canceled_at	true	long	Cancel Time
fail_code	true	int	Error Code for failed to placing an order when triggered
fail_reason	true	string	The reason for failed to placing an order when triggered
</orders>
</data>
ts	true	long	Time of Response Generation, unit: millisecond

Option Transferring Interface

Transfer margin between Spot account and Option account

Example

• POST https://api.huobi.pro/v2/account/transfer

Notice

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

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

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

Request Parameter

Parameter Name	Mandatory	Type	Desc	Default	Value Range
from	true	string	source，value：spot、option	e.g. spot
to	true	string	destination，value：spot、option	e.g. option
currency	true	string	currency.Both uppercase and lowercase are supported.		e.g. btc
amount	true	Decimal	Transferring amount
tradePartition	true	string	Trade Partition (Currently only USDT available）	e.g. usdt

Response:

{
    "code": 200,
    "data": 182408686,
    "message": "Succeed",
    "success": true
}
    Error response

{
    "code": 1301,
    "data": null,
    "message": "Insufficient amount available.",
    "success": false
}

Returning Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
code	true	long	response code
success	true	boolean	true/false
message	true	string	response messsage
data	true	long	Transfer ID ,If status="error", data will be null.

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.

Option WebSocket Reference

API List

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

WebSocket Subscription Address

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

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

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/option-ws;

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

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

Note:

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

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

• Generally, the private interface rate limit of API key is at most 48 times every 3 seconds for each UID (Trade Interface: at most 24 times every 3 seconds. Read Interface: at most 24 times every 3 seconds) (this rate limit is shared by all the altcoins contracts delivered by different date).

• For public interfaces used to get information of non-market data (such as request information of index, price limit, delivery and settlement, positions, etc.), the rate limit for each IP is 60 times every 3 seconds. (Please note that the 60 times/3s rate limit is shared by all the requests for non-market data under this UID)

• For public interface to get market data such as Get kline data, Get Market Data Overview, Get Contract Information, Get the last Trade of a Contract and so on：

(1) For restful interfaces：all products(futures, coin margined swap, usdt margined swap and option) 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.

• The order push private WebSocket interface requires API Key for authentication.

  Each UID can create 30 WS connections at most for private order push at the same time. The user under this UID only need to subscribe one WS order push for the contracts of the same underlying coins. For example, users only need to create one WS order push connection for BTC Contract, which our system will automatically push orders of BTC weekly, BTC biweekly and BTC quarterly contracts via this connection.

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

• 40 subscriptions at most can be sent in one second in websocket connections.

Response the following strings for “Header” via API

• ratelimit-limit： the upper request limit per time, unit: time

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

• ratelimit-remaining： available request number left in this round, unit: time

• ratelimit-reset： upper limit of reset time used to request number， unit: ms

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.

• WebSocket Server sends heartbeat：

{"ping": 18212558000}

• WebSocket Client should respond:：

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

}

• WebSocket Client should return:

{

"op": "pong",

"ts": "1492420473058"

}

Note

• "ts" value in the return "pong" message is the "ts" value from "ping" push Once the WebSocket Client and WebSocket Server connected, Websocket Server will send a heartbeat every 5 seconds (the frequency might change) to Wesocket Client. If WebSocket Client ignores the heartbeat message for 3 times, it will get disconnected with Websocket Sever automatically. Under abnormal conditions, WebSocket Server will return error message like:

{

"op": "pong"

"ts": "1492420473027",

"err-code": 2011,

"err-msg": “detailed error message”

}

• Websocket Server disconnects automatically During period of building connection and authentication, Websocket Server will disconnect automatically if there is any error. The data structure before closing pushing are as below:

{

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

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

}

• Server return error but remain connection After successful authentication, Server will return error but not disconnect if Client provides illegal Op or there is any internal error.

{

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

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

}

Order Push Address

• Huobi Option uses one official address:

wss://api.hbdm.com/option-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

• Character Encoding：UTF-8

• Case sensitive，including parameter name and return parameter

• Data type： use JSON to transmit data

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

Request data format is laid out as below:

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

All responses push data will be returned in fixed format，Huobi Option 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 Option. 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：

• To decrease API access rate, the WebSocket server uses the same signature algorithm with that on REST API

• All data is case sensitive;

• When type is api, In API authentication, parameter op, type, cid, Signature do not participate in operation.

• The request method in signature's method is GET, the other parameter please refer to REST api document

Signature Illustration：

Example on Signature Computing Process:，

• Request code requirement for signature computing. Because it can return to total different data with different content when using HMAC for signature computing; Before signature computing, clients need to sign by following the standard format.

• Request Method (GET or POST), add newline character \n after URL

GET\n

• add visit address with lowercase letters, add newline characters \n after URL

api.hbdm.com\n

• Access path, adding newline character \n after URL

/option-notification\n

• Sequence the parameter name according to ASCII code (use UTF-8 and transfer into URI encoding, capital letters for hexadecimal characters. E.G.: ‘:’ will be encoded into '%3A', blank will be encoded into '%20'). Here is an encoding example below for request parameters

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

• Connect all parameters with ’&’ according to the sequence above.

• The final strings for signature computing created by following the steps as below:

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

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

Authentication Response Format Illustration

Field	type	description
op	string	required； Operator type， Authentication response type is auth
type	string	required； Return data according to the requested parameters
cid	string	optional； Return data when “cid” string requested
err-code	integer	0 means successfully response, others means response failure 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	long	client ID

Example of A Success Authentication Response

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

Example of Authentication Response with Error

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

WebSocket Market Interface

Subscribe Kline data

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

{

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

"id": "id generate by client"

}

Example of a successful subscription request：

    {
    "sub": "market.BTC-USDT-201225-C-13000.kline.1min",
    "id": "id1"
    }

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
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

subSubscribeParameter Rules

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000" ...
period	true	string	kline Type	1min, 5min, 15min, 30min, 60min,4hour,1day,1week, 1mon

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

Example for returning data after subscription successful

    {
    "id": "id1",
    "status": "ok",
    "subbed": "market.BTC-USDT-201225-C-13000.kline.1min",
    "ts": 1489474081631
    }

Then everytime when kline is updated, clients will receive data. Example:

{
    "ch":"market.BTC-USDT-201225-C-13000.kline.15min",
    "ts":1604900702590,
    "tick":{
        "id":1604900700,
        "mrid":125344032,
        "open":2897.25,
        "close":2897.25,
        "high":2897.25,
        "low":2897.25,
        "amount":0,
        "vol":0,
        "trade_turnover":0,
        "count":0
    }
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
ch	true	string	Data belonged channel	Format: market.period
ts	true	long	Time of Response Generation, unit: millisecond
<tick>	true	object
id	true	long	kline id,the same as kline timestamp, kline start timestamp
mrid	true	long	Order ID
vol	true	decimal	Trading Volume(cont)
count	true	decimal	Filled orders quantity
open	true	decimal	Opening Price
close	true	decimal	Closing price, the price in the last kline is the latest price
low	true	decimal	Lowest Price
high	true	decimal	Highest Price
amount	true	decimal	Trading Amount(cont), that is (Trading Volume(cont)* contract face value)
trade_turnover	true	decimal	Trading amount，that is the sum of (Filled conts of a single order *Contract Face value *Transaction Price)
</tick>

Request Kline data

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

{

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

"id": "id generated by client",

"from": " type: long, point-in-time from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00，unit: second",

"to": "type: long, point-in-time from 2017-07-28T00:00:00+08:00 to 2050-01-01T00:00:00+08:00，unit: second，shall greater than from"

}

Example of Kline Data Subscription Request：

`>Request kline Data & Request Parameter

{
  "id": "id1",
  "req": "market.BTC-USDT-201225-C-13000.kline.60min",
  "from": 1579247342,
  "to": 1579247342
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
req	true	string	Theme for Requesting Data; the interface is fixed at: market.$contract_code.kline.$period; for details of Parameter please check req Request Parameter Rules
id	false	string	id generated automatically by the business party
from	true	long	Start Time
to	true	long	End Time

req Request Parameter Rules

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000" ...
period	true	string	kline Type	1min, 5min, 15min, 30min, 60min,4hour,1day,1week, 1mon

Note

[t1, t5] assume there is kline from t1 to t5:

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.

At most 2000 at a time.

Return data as below:

{
    "id":"id1",
    "rep":"market.BTC-USDT-201225-C-13000.kline.60min",
    "wsid":4203781398,
    "status":"ok",
    "data":[
        {
            "id":1602691200,
            "open":630,
            "close":630,
            "low":630,
            "high":630,
            "amount":0,
            "vol":0,
            "trade_turnover":0,
            "count":0
        },
        {
            "id":1602694800,
            "open":630,
            "close":630,
            "low":630,
            "high":630,
            "amount":0,
            "vol":0,
            "trade_turnover":0,
            "count":0
        }
    ]
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
id	true	string	Request ID
rep	true	string	Request Parameter
status	true	string	Status
wsid	true	long	wsid
<data>	true	object array
id	true	long	kline id,the same as kline timestamp, kline start timestamp
open	true	decimal	Opening Price
close	true	decimal	Closing price, the price in the last kline is the latest price
low	true	decimal	Lowest Price
high	true	decimal	Highest Price
amount	true	decimal	Trading Amount (coin), that is (Trading Amount(cont)* contract face value)
trade_turnover	true	decimal	Trading amount，that is the sum of（Filled conts of a single order *Contract Face value *Transaction Price）
vol	true	decimal	Trading Volume (cont)
count	true	decimal	Filled order quantity
</data>

Subscribe Market Depth Data

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

{

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

"id": "id generated by client"

}

Example of Subscribe Request Parameter:

{
  "sub": "market.BTC-USDT-201225-C-13000.depth.step0",
  "id": "id5"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
sub	true	string	Theme for Requesting Data; the interface is fixed at: market.$contract_code.depth.$type; for details of Parameter please check subSubscribe Parameter Rules
id	false	string	id generated automatically by the business party

SubscribeParameter Rules

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	"BTC-USDT-201225-C-13000" ...
type	true	string	Depth Type	Get depth data within Step 150 using step0, step1, step2, step3, step4, step5，step14，step15（step1 to step5 and step14, step15 are the depth after depth merging），When the step is 0, get step150 data without depth merged; Get step 20 data using step6, step7, step8, step9, step10, step11, step12, step13（step7 to step13 are the depth after merging)，when using step 6，get step 20 data without depth merged

Note

• When users select "Merge Depth", open orders of a certain precision will be merged and displayed. "Merge Depth" only affects the display mode, not the actual transaction price.

• the precisions correspond to the Depth type fields are as below:

Step	Depth Type	Precision
Step 150	step0	Depth not merged
Step 150	step1	0.00001
Step 150	step2	0.0001
Step 150	step3	0.001
Step 150	step4	0.01
Step 150	step5	0.1
Step 150	step14	1
Step 150	step15	10
Step 20	step6	Depth not merged
Step 20	step7	0.00001
Step 20	step8	0.0001
Step 20	step9	0.001
Step 20	step10	0.01
Step 20	step11	0.1
Step 20	step12	1
Step 20	step13	10

Whenever depth is updated, the clients will receive data as following:

{
    "ch":"market.BTC-USDT-201225-C-13000.depth.step0",
    "ts":1604901962322,
    "tick":{
        "mrid":125686472,
        "id":1604901962,
        "bids":[
            [
                2746.4,
                535
            ],
            [
                2723.89,
                520
            ]
        ],
        "asks":[
            [
                2881.38,
                498
            ],
            [
                2911.03,
                499
            ]
        ],
        "ts":1604901962321,
        "version":1604901962,
        "ch":"market.BTC-USDT-201225-C-13000.depth.step0"
    }
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
ch	true	string	Data belonged channel	Format: market.period
ts	true	long	Time of Respond Generation, unit: millisecond
<tick>	true	object
mrid	true	long	OrderID
id	true	long	ID
asks	true	array	Sell order book,[price( maker price), vol (conts of open orders at this price)], price in ascending order
bids	true	array	Buy order book,[price( maker price), vol( conts of open orders at this price)], price in descending order
ts	true	long	Time of Respond Generation, unit: millisecond
version	true	long	Version Number
ch	true	string	Data belonged channel	Format: market.period
</tick>

Subscribe Incremental Market Depth Data

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

{

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

"data_type":"incremental",

"id": "id generated by client"

}

Example for subscribing Request Parameter::

{
  "data_type": "incremental",
  "sub": "market.BTC-USDT-201225-C-13000.depth.size_150.high_freq",
  "id": "id1"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
sub	true	string	Theme for Requesting Data，the interface is fixed at: market.$contract_code.depth.size_${size}.high_freq, for details of Parameter please check subSubscribe Parameter Rules
id	false	string	id generated automatically by the business party
data_type	false	string	Data Type	Default full data if not filled，"incremental": Incremental Data，"snapshot": Full Data

Subscribe Parameter Rules

Parameter Name	Mandatory	Type	Desc	Value Range
$contract_code	true	string	Contract Code	eg"BTC-USDT-201225-C-13000"。
size	true	string	step	20: represents depth within step 20 without merging, 150: represents depth within step 150 without merging,

Note

When users select "Merge Depth", open orders of a certain precision will be merged and displayed. "Merge Depth" only affects the display mode, not the actual transaction price.

Whenever depth has incremental updates, clients will receive data as below:

{
    "ch":"market.BTC-USDT-201225-C-13000.depth.size_20.high_freq",
    "tick":{
        "asks":[
            [
                2891.92,
                509
            ],
            [
                2922.58,
                499
            ]
        ],
        "bids":[
            [
                2732.53,
                535
            ],
            [
                2710.12,
                520
            ]
        ],
        "ch":"market.BTC-USDT-201225-C-13000.depth.size_20.high_freq",
        "event":"snapshot",
        "id":125696596,
        "mrid":125696596,
        "ts":1604902337523,
        "version":1511997
    },
    "ts":1604902337523
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
ch	true	string	Data belonged channel	Format: market.period
ts	true	long	Time of Respond Generation, unit: millisecond
<tick>	true	object
mrid	true	long	OrderID
id	true	long	ID
asks	true	array	Sell order book,[price( maker price), vol( conts of open orders at this price)], price in ascending order
bids	true	array	Buy order book,[price( maker price), vol(conts of open order at this price)], price in descending order
ts	true	long	Time of Respond Generation, unit: millisecond
version	true	long	Version Number
ch	true	string	Data belonged channel	Format: market.period
event	true	string	Event Type；	"update": update, push incremental data within step 20 or step 150 of Buy and sell order book respectively without depth merging; "snapshot": snapshot，push full data within step 20 or step 150 of Buy and sell order book respectively without merging;
</tick>

Note

1. when "data_type" is incremental, the "event" that first pushed is the data of "snapshot". And when resend subscription request, the data returned at the first time is "snapshot" data;

2. version（Version number）. It is a serial number in ascending order, which increases by 1 every time. No matter incremental data or full data, every connection is unique. The version connected may be different for multiple websocket.

3. Order book will be checked every 30 ms. If there is an update, the system will push to you; if not, you will not receive any push data.

4. If it is incremental data, you have to maintain local orderbook bids/ asks data.

Subscribe Market Detail Data

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

{

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

"id": "id generated by client"

}

Example for subscribing Request Parameter:

{
  "id": "111",
  "sub": "market.BTC-USDT-201225-C-13000.detail"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
sub	true	string	Theme for requesting data, the interface is fixed at: market.$contract_code.detail，for details of Parameter please check subSubscribe Parameter Rules
id	false	string	id generated automatically by the business party

subSubscribe Parameter Rules

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	eg"BTC-USDT-201225-C-13000".

Whenever Market Detail updates, clients will receive data as below:

{
    "ch":"market.BTC-USDT-201225-C-13000.detail",
    "ts":1604902200630,
    "tick":{
        "id":1604902200,
        "mrid":125693341,
        "open":2897.25,
        "close":2897.25,
        "high":2897.25,
        "low":2897.25,
        "amount":0.176,
        "vol":176,
        "trade_turnover":439.20704,
        "count":3,
        "bid":[
            13684.5,
            10615
        ],
        "ask":[
            13684.6,
            3440
        ]
    }
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
ch	true	string	Data belonged channel	Format: market.period
ts	true	long	Time of Respond Generation, unit: millisecond
<tick>	true	object
id	true	long	ID
mrid	true	long	Order ID
open	true	decimal	Opening Price
close	true	decimal	Closing price, the price in the last kline is the latest price
high	true	decimal	Highest Price
low	true	decimal	Lowest Price
amount	true	decimal	Trading Amount(coin)，that is (Trading Amount(conts)*Contract face value)
vol	true	decimal	Trading Volume (conts)，the sum of bilateral trading volume.
trade_turnover	true	decimal	Trading amount, that is the sum（Filled conts of a single order*Contract face value*Transaction Price）
count	true	decimal	Filled orders quantity
ask	true	array	Sell,[price(Ask price), vol(Ask orders (cont.) )]
bid	true	array	Buy,[price(Bid price), vol(Bid orders(Cont.))]
</tick>

Note:

• Bid price(p1) and ask price(p1) are not updated in real time, there will be some delay (about 500ms).

Request Trade Detail Data

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

{

"req": "market.$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 for subscribing Request Parameter:

{
  "id": "160943040012341",
  "size": 50,
  "req": "market.BTC-USDT-201225-C-13000.trade.detail"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
req	true	string	Theme for requesting data, the interface is fixed at:market.$contract_code.trade.detail，for details of parameter please check reqRequest Parameter Rules
id	false	string	id generated automatically by the business party
size	false	int	number of data; no more than 50; default 50 if not filled

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	eg"BTC-USDT-201225-C-13000".

Note

• Only return current Trade Detail.

Return data as below:

{
    "data":[
        {
            "amount":"6",
            "ts":1603869385244,
            "id":991487430000,
            "price":"1542.78",
            "direction":"sell"
        },
        {
            "amount":"40",
            "ts":1603889690205,
            "id":996663430000,
            "price":"1300",
            "direction":"sell"
        }
    ],
    "id":"160943040012341",
    "rep":"market.BTC-USDT-201225-C-13000.trade.detail",
    "status":"ok",
    "ts":1604902521584
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
rep	true	string	Data belonged channel	Format: market.$contract_code.trade.detail
status	true	string	Return Statu
id	true	string	Return ID
<data>	true	object array
id	true	long	Unique Transaction Id(symbol level)
price	true	string	Price
amount	true	string	Quantity (cont)
direction	true	string	Buy/Sell Direction
ts	true	long	OrderTransaction Time
</data>
ts	true	long	server response time

Subscribe Trade Detail Data

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

{

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

"id": "id generated by client"

}

Example for subscribing Request Parameter:

{
  "id": "160943040012341",
  "Sub": "market.BTC-USDT-201225-C-13000.trade.detail"
}

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
sub	true	string	Theme for requesting data, the interface is fixed at:market.$contract_code.trade.detail，for details of Parameter please check subSubscribe Parameter Rules
id	false	string	id generated automatically by the business party

subSubscribeParameter Rules

Parameter Name	Mandatory	Type	Desc	Value Range
contract_code	true	string	Contract Code	eg"BTC-USDT-201225-C-13000".

Whenever trade detail is updated, clients will receive data as below:

{
    "ch":"market.BTC-USDT-201225-C-13000.trade.detail",
    "ts":1604888281270,
    "tick":{
        "id":125344032,
        "ts":1604888281258,
        "data":[
            {
                "amount":2,
                "ts":1604888281258,
                "id":1253440320000,
                "price":2897.25,
                "direction":"buy"
            }
        ]
    }
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
ch	true	string	Data belonged channel	Form: market.period
ts	true	long	Time of Respond Generation, unit: millisecond
<tick>	true	object
id	true	long	Unique Order Id(symbol level)
ts	true	long	Server response time
<data>	true	object array
amount	true	decimal	Quantity (cont)
ts	true	long	Server response time
id	true	long	Unique Transaction Id(symbol level)
price	true	decimal	Price
direction	true	string	Buy/Sell Direction
</data>
</tick>

Orders and Accounts WebSocket Interfaces

Subscribe Order Data(sub)

After successfully connected with the WebSocket API, send the data in following format to the server to subscribe data:

Example

{

"op": "sub",

"topic": "orders.$symbol-$partition",

"cid": "id generated by client"

}

Example of Subscribe Request Parameter:

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

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Fixed value of subscription is sub
cid	false	string	Client Request Unique ID
topic	true	string	Subscribe Theme Name; must fill in (orders.$symbol-$partition) subscription, cancel order filled info subscription of a certian coin; $symbol-$partition is “Coin Code-Trade Partition”（BTC-USDT, ETH-USDT...），If the value is * , all options contracts will be subscribed;

Whenever there is an order filled, clients will receive data as below:

{
    "op":"notify",
    "topic":"orders.btc-usdt",
    "uid":"123456789",
    "ts":1604903121972,
    "symbol":"BTC",
    "contract_type":"quarter",
    "contract_code":"BTC-USDT-201225-C-13000",
    "volume":1,
    "price":2752.58,
    "order_price_type":"opponent",
    "direction":"sell",
    "offset":"close",
    "status":6,
    "order_id":775365420395126784,
    "order_id_str":"775365420395126784",
    "client_order_id":null,
    "order_source":"web",
    "order_type":1,
    "created_at":1604903121809,
    "canceled_at":0,
    "trade_volume":1,
    "trade_turnover":2.75258,
    "fee":-0.005,
    "trade_avg_price":2752.58,
    "margin_frozen":0,
    "profit":-0.14467,
    "trade_partition":"USDT",
    "delivery_date":"20201225",
    "option_right_type":"C",
    "exercise_price":13000,
    "quote_asset":"USDT",
    "premium_frozen":0,
    "fee_frozen":0,
    "fee_asset":"USDT",
    "margin_asset":"BTC",
    "trade":[
        {
            "id":"125715777-775365420395126784-1",
            "trade_id":125715777,
            "trade_volume":1,
            "trade_price":2752.58,
            "trade_fee":-0.005,
            "trade_turnover":2.75258,
            "created_at":1604903121857,
            "role":"taker",
            "fee_asset":"USDT"
        }
    ]
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Operation Name, fixed push value is notify;
topic	true	string	Push Theme
ts	true	long	Server responses timestamp
uid	true	string	User uid
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	ContractType
contract_code	true	string	Contract Code	BTC-USDT-201225-C-13000
volume	true	decimal	Order Quantity
price	true	decimal	Order Price
order_price_type	true	string	Order Type	"limit":Limit Order，"opponent":BBO，"lightning":Flash close，"optimal_5":Optimal 5，"optimal_10":Optimal 10，"optimal_20":Optimal 20，"fok": FOK Order，"ioc": IOC Order, "opponent_ioc": BBO-IOC，"lightning_ioc": Flash close-IOC，"optimal_5_ioc": Optimal 5-IOC，"optimal_10_ioc": Optimal 10-IOC，"optimal_20_ioc": Optimal 20-IOC，"opponent_fok": FOK order using BBO price，"lightning_fok": Flash close-FOK，"optimal_5_fok": Optimal 5-FOK，"optimal_10_fok": Optimal 10-FOK，"optimal_20_fok": Optimal 20-FOK
direction	true	string	Buy/Sell Direction	"buy":Buy "sell":Sell
offset	true	string	Open/Close Direction	"open":open "close": close
status	true	int	Order Status	1:To submit 2:To submit 3:Submitted 4:Partial filled 5:Partial filled orders have been deleted 6:All filled 7:Deleted
order_id	true	long	Order ID
order_id_str	true	string	Order ID in string format
client_order_id	true	long	User OrderID
order_source	true	string	Order Source	system、web、api、m、risk、settlement、ios、android、windows、mac、trigger
order_type	true	int	Order Type	1:Place an order, 2:Cancel an order, 4:Delivery
created_at	true	long	Order Create Time
trade_volume	true	decimal	Trading Volume
trade_turnover	true	decimal	Total Trading Amount
fee	true	decimal	Transaction Fee
trade_avg_price	true	decimal	Transaction Average Price
margin_frozen	true	decimal	Frozen Margin
margin_asset	true	decimal	Margin Coin
profit	true	decimal	Profit
canceled_at	true	long	Cancel Time
delivery_date	true	string	Delivery Date	eg"20200508"
option_right_type	true	string	Options Type	C:Call options P:Put options
exercise_price	true	decimal	Strike Price
quote_asset	true	string	Quote Coin	eg"USDT"
premium_frozen	true	decimal	Frozen Premium
fee_frozen	true	decimal	Frozen Transaction Fee
fee_asset	true	string	Transaction Fee coin
<trade>	true	object array
id	true	string	Unique transaction id, because match_id is not unique, the specific method is to use trade_id and id as joint primary key and splice it into a unqiue transaction ID.
trade_id	true	long	trade_id is not unique, note: a trade_id includes all transaction records of a taker order and N maker orders. If a taker order matches with N maker orders, the N transactions will share tha same trade_id.
trade_volume	true	decimal	Trading Volume
trade_price	true	decimal	Match Price
trade_fee	true	decimal	Transaction Fee
trade_turnover	true	decimal	Transaction Amount
created_at	true	long	Trade Creation Time
role	true	string	taker or maker
fee_asset	true	string	Transaction Fee coin
</trade>

Unsubscribe Order Data（unsub）

After successfully connected with the WebSocket API, sending the data in following format to the server to cancel data subscription:

Example

{

"op": "unsub",

"topic": "orders.$symbol-$partition",

"cid": "id generated by client"

}

Example for subscribing Request Parameter:

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

Cancel SubscriptionRequest Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Fixed value of cancel subscription is unsub
cid	false	string	Client Request Unique ID
topic	true	string	Subscribe Theme Name; must fill in (orders.$symbol-$partition) subscription, cancel order filled info subscription of a certian coin; $symbol-$partition is “Coin Code-Trade Partition”（BTC-USDT、ETH-USDT...），If the value is * , all options contracts will be subscribed;

Subscribe & Cancel Subscription Rules

Subscribe(sub)	Cancel Subscription(ubsub)	Rule
orders.*	orders.*	Allowed
orders.symbol1-partion1	orders.*	Allowed
orders.symbol1-partion1	orders.symbol1-partion1	Allowed
orders.symbol1-partion1	orders.symbol2-partion1	Not Allowed
orders.*	orders.symbol1-partion1	Not Allowed

Subscribe Match Order Data（sub)

After successfully connected with the WebSocket API, sending the data in following format to the server to subscribe data:

Example

{

"op": "sub",

"topic": "matchOrders.$symbol-$partition",

"cid": "id generated by client"

}

Example for subscribing request parameter:

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

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Fixed value of subscription is sub
cid	false	string	Client Request Unique ID
topic	true	string	Subscribe Theme Name; must fill in (matchOrders.$symbol-$partition) Subscription, cancel match order filled info subscription for a certain coin;$symbol-$partition is “Coin Code-Trade Partition”（BTC-USDT、ETH-USDT...），If the value is * , all options contracts will be subscribed;

Whenever filled orders change, the clients will receive the data as below:

{
    "op":"notify",
    "topic":"matchOrders.btc-usdt",
    "ts":1604903121879,
    "uid":"123456789",
    "symbol":"BTC",
    "trade_partition":"USDT",
    "contract_type":"quarter",
    "contract_code":"BTC-USDT-201225-C-13000",
    "status":6,
    "order_id":775365420395126784,
    "order_id_str":"775365420395126784",
    "order_type":1,
    "trade_volume":1,
    "volume":1,
    "trade":[
        {
            "id":"125715777-775365420395126784-1",
            "trade_id":125715777,
            "trade_volume":1,
            "trade_price":2752.58,
            "trade_turnover":2.75258,
            "created_at":1604903121857,
            "role":"taker"
        }
    ]
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Operator Name, fixed push value is notify;
topic	true	string	Push Theme
ts	true	long	Server responses Timestamp
uid	true	string	Useruid
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_type	true	string	ContractType	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
contract_code	true	string	Contract Code	BTC-USDT-201225-C-13000
status	true	int	OrderStatus (3unfilled 4partial filled 5partial filled orders have been deleted 6all filled7deleted)
order_id	true	long	Order ID, the field stored in the system is user_order_id
order_id_str	true	string	Order ID, String Type
order_type	true	int	Order Type	1:Place an order, 2:Cancel an order
trade_volume	true	decimal	quantity of order filled
volume	true	decimal	quantity of order placed
<trade>	true	object array
id	true	string	Unique transaction ID
trade_id	true	long	match result id
trade_price	true	decimal	Match Price
trade_volume	true	decimal	Trading Volume
trade_turnover	true	decimal	Trading Amount
created_at	true	long	Creation Time
role	true	string	taker or maker
</trade>

Unsubscribe Match Order Data（unsub）

After successfully connected with the WebSocket API, sending the data in following format to the server to cancel data subscription:

Example

{

"op": "unsub",

"topic": "matchOrders.$symbol-$partition",

"cid": "id generated by client"

}

Example for subscribing Request Parameter:

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

Cancel Subscription Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Fixed value of cancel subscription is unsub
cid	false	string	Client Request Unique ID
topic	true	string	Subscription Theme Name, must fill in(matchOrders.$symbol-$partition) subscription, cancel match order filled info subscription for a certain coin;$symbol-$partition is“Coin Code-Trade Partition”（BTC-USDT、ETH-USDT...）, If the value is * , all options contracts will be subscribed;
ts	true	long	Time of Respond Generation, unit: millisecond

Subscribe and Cancel Subscription Rules

Subscribe(sub)	Cancel Subscription(ubsub)	Rule
matchOrders.*	matchOrders.*	Allowed
matchOrders.symbol1-partion1	matchOrders.*	Allowed
matchOrders.symbol1-partion1	matchOrders.symbol1-partion1	Allowed
matchOrders.symbol1-partion1	matchOrders.symbol2-partion1	Not Allowed
matchOrders.*	matchOrders.symbol1-partion1	Not Allowed

Subscribe Account Equity Updates Data(sub)

After successfully connected with the WebSocket API, sending the data in following format to the server to subscribe data:

Example

{

"op": "sub",

"topic": "accounts.$symbol-$partition",

"cid": "id generated by client"

}

Example for subscribing Request Parameter:

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

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Fixed value of subscription is sub
cid	false	string	Client Request Unique ID
topic	true	string	Subscribe Theme Name; must fill in (accounts.$symbol-$partition) subscription, cancel asset change info subscription of a certain coin; $symbol-$partition is “Coin Code-Trade Partition”（BTC-USDT、ETH-USDT...）, If the value is * , all options contracts will be subscribed;

Whenever asset changes, clients will receive data as below:

{
    "op":"notify",
    "topic":"accounts",
    "ts":1604903471303,
    "uid":"123456789",
    "event":"init",
    "data":[
        {
            "symbol":"USDT",
            "margin_balance":10.30015,
            "margin_static":10.30015,
            "margin_position":0,
            "margin_frozen":0,
            "margin_available":9.09036,
            "profit_real":-0.15467,
            "profit_unreal":0,
            "withdraw_available":9.09036,
            "option_value":0,
            "premium_frozen":1.20479,
            "fee_frozen":0.005,
            "premium_in":2.75258,
            "premium_out":2.89725,
            "fee_asset":"USDT",
            "delta":null,
            "gamma":null,
            "theta":null,
            "vega":null,
            "margin_asset":"USDT",
            "trade_partition":"USDT"
        }
    ]
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Operator Name, push value is fixed at notify;
topic	true	string	Push Theme
ts	true	long	Server responses Timestamp
uid	true	string	User UID
event	true	string	Asset change notification related events illustration	for example, order created to open positions(order.open) , order filled(order.match)（excluding liquidation, settlement and delivery）, settlement and delivery (settlement), cancel orders (order.cancel) , close orders(order.close), contract account transfer（contract.transfer)（including deposits and withdrawals), system（contract.system), other assets change(other), initial assets(init), triggered by system regular push (snapshot）
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
margin_balance	true	decimal	Account Equity
margin_static	true	decimal	Static Equity
margin_position	true	decimal	Performance Margin
margin_frozen	true	decimal	Frozen Margin
margin_asset	true	decimal	Margin Coin
margin_available	true	decimal	Available Margin
profit_real	true	decimal	Realized PnL
profit_unreal	true	decimal	Unrealized PnL
withdraw_available	true	decimal	Transferable Quantity
premium_frozen	true	decimal	Frozen Premium
fee_frozen	true	decimal	Frozen Transaction Fee
fee_asset	true	string	Transaction Fee coin
premium_in	true	decimal	Current week premium income
premium_out	true	decimal	Current week premium expense
delta	true	decimal	DELTA
gamma	true	decimal	GAMMA
theta	true	decimal	THETA
vega	true	decimal	VEGA
option_value	true	decimal	Option Market Value(unit:"USDT")
</data>

Unsubscribe Account Equity Updates Data (unsub)

After successfully connected with the WebSocket API, sending the data in following format to the server to cancel data subscription:

Example

{

"op": "unsub",

"topic": "accounts.$symbol-$partition",

"cid": "id generated by client"

}

Example for subscribing Request Parameter:

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

Cancel Request Parameter Subscription

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Fixed value of cancel subscription is unsub
cid	false	string	Client Request Unique ID
topic	true	string	Subscribe Theme Name; must fill in (accounts.$symbol-$partition) Subscription, cancel asset change info subscription of a certain coin; $symbol-$partition is “Coin Code-Trade Partition”（BTC-USDT、ETH-USDT...），If the value is * , all options contracts will be subscribed;

Subscribe & cancel Subscription Rules

Subscribe(sub)	Cancel Subscription(ubsub)	Rule
accounts.*	accounts.*	Allowed
accounts.symbol1-partion1	accounts.*	Allowed
accounts.symbol1-partion1	accounts.symbol1-partion1	Allowed
accounts.symbol1-partion1	accounts.symbol2-partion1	Not Allowed
accounts.*	accounts.symbol1-partion1	Not Allowed

Subscribe Position Updates(sub)

After successfully connected with the WebSocket API, sending the data in following format to the server to subscribe data:

Example

{

"op": "sub",

"topic": "positions.$symbol-$partition",

"cid": "id generated by client"

}

Example for subscribing Request Parameter:

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

Request Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Fixed value of subscription is sub
cid	false	string	Client Request Unique ID
topic	true	string	Subscription Theme Name, must fill in(positions.$symbol-$partition) subscription, cancel position change info subscription if a certain coin, $symbol-$partition is “Coin Code-Trade Partition”（BTC-USDT、ETH-USDT...），If the value is * , all options contracts will be subscribed;

Whenever position changes, clients will receive data as below:

{
    "op":"notify",
    "topic":"positions",
    "ts":1604903117918,
    "uid":"123456789",
    "event":"snapshot",
    "data":[
        {
            "symbol":"BTC",
            "contract_code":"BTC-USDT-201225-C-13000",
            "contract_type":"quarter",
            "volume":1,
            "available":1,
            "frozen":0,
            "cost_open":2897.25,
            "cost_hold":2897.25,
            "profit_unreal":0,
            "profit_rate":0,
            "profit":0,
            "margin_position":0,
            "direction":"buy",
            "last_price":2897.25,
            "trade_partition":"USDT",
            "delivery_date":"20201225",
            "option_right_type":"C",
            "exercise_price":13000,
            "quote_asset":"USDT",
            "margin_asset":"BTC",
            "position_value":2.89725
        }
    ]
}

Return Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Operator Name, fixed push value isnotify;
topic	true	string	Push Theme
ts	true	long	Server responses Timestamp
uid	true	string	User uid
event	true	string	Related events illustration on position change notification	for example, create an order to close positions(order.close) 、order filled(order.match), settlement and delivery(settlement)、order liquidation filled (order.liquidation), cancel orders(order.cancel) , initial positions（init）, triggered by system regular push（snapshot）
<data>	true	object array
symbol	true	string	Coin Code	"BTC","ETH"...
trade_partition	true	string	Trade Partition	"USDT"
contract_code	true	string	Contract Code	BTC-USDT-201225-C-13000
contract_type	true	string	ContractType	Weekly:"this_week", Bi-weekly:"next_week", Quarterly:"quarter"
volume	true	decimal	Position Quantity
available	true	decimal	Available Close Amount
frozen	true	decimal	Frozen Quantity
cost_open	true	decimal	Average open price
cost_hold	true	decimal	Average position price
profit_unreal	true	decimal	Unrealized PnL
profit_rate	true	decimal	Profit Rate
profit	true	decimal	Profit
margin_position	true	decimal	Performance Margin
position_value	true	decimal	Position Value
direction	true	string	Position Direction	"buy":Buy "sell":Sell
last_price	true	decimal	Latest Price
delivery_date	true	string	Delivery Date	eg"20200508"
option_right_type	true	string	Options ExcerciseType	C:Call options P:Put options
exercise_price	true	decimal	Strike Price
quote_asset	true	string	Denomination Coin	"USDT"...
margin_asset	true	string	Margin Coin	"BTC"...
</data>

Unsubscribe Position Change Data

After successfully connected with the WebSocket API, sending the data in following format to the server to cancel data subscription:

Example

{

"op": "unsub",

"topic": "positions.$symbol-$partition",

"cid": "id generated by client"

}

Example for subscribing Request Parameter:

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

Cancel SubscriptionRequest Parameter

Parameter Name	Mandatory	Type	Desc	Value Range
op	true	string	Fixed value of cancel subscription is unsub
cid	false	string	Client Request Unique ID
topic	true	string	Subscribe Theme Name, must fill in (positions.$symbol-$partition) Subscription、Cancel asset change info subscription of a certain coin; $symbol-$partition is “Coin Code-Trade Partition”（BTC-USDT、ETH-USDT...），If the value is * , all options contracts will be subscribed;

Subscribe & Cancel Subscription Rules

Subscribe(sub)	Cancel Subscription(ubsub)	Rule
positions.*	positions.*	Allowed
positions.symbol1-partion1	positions.*	Allowed
positions.symbol1-partion1	positions.symbol1-partion1	Allowed
positions.symbol1-partion1	positions.symbol2-partion1	Not Allowed
positions.*	positions.symbol1-partion1	Not Allowed

WebSocket interface for system status updates

• The websocket url of system status updates is : wss://api.hbdm.com/center-notification

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.option.heartbeat"
}

Request Parameter:

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

Subscription parameter description:

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

Return Parameter Example:

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

Return Parameter Rules：

Name	Mandatory	Type	Desc	Value Range
op	true	string	Operation name, the fixed value of push is notify;
topic	true	string	Push topic
event	true	string	Description on notification related event	The initial system status information returned by a successful subscription (init), triggered by system status change (update)
ts	true	long	Server response timestamp
<data>
heartbeat	true	int	System Status	1 is available, 0 is not available(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

• Since this push is a poll query status, there may be a delay of 1-2 seconds.

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.