更新日志
| 生效时间(UTC +8) | 接口 | 变化 | 摘要 |
|---|---|---|---|
| 2021.9.9 | - | 新增 | 新增WebSocket行情数据推送 |
| 2021.8.19 | /v1/order/matchresults | 优化 | 新增startTimestamp,endTimestamp字段 |
| 2018.6.10 | - | 初始化 | 初始化当前版本接口 |
json
- Change Log # Change Log Release Time(UTC +8)|API|Initialize / Update|Description | ------------- | ------------- | ------------- | ------------- | 2021.9.9|- |add|Added WebSocket market data push 2021.8.19|/v1/order/matchresults |update|add startTimestamp fields, endTimestamp fields 2018.6.10|- |Initialize|Initializes the current version of the interface
- Introduction
Introduction
Welcome to Hotcoin Global API.
This is the official Hotcoin API document, and will be continue updating. Hotcoin will also publish API announcement in advance for any API change. Please subscribe to our announcements so that you can get the latest updates.
Below is the content for Spot API document:
Access Instructions
Before you use API, you need to login the website to create API Key with proper permissions. The API key is shared for all instruments in Hotcoin including spot, futures, swap, options.
The permissions are described as follows:
- Read permission:It is used to query the data, such as order query, trade query.
- Trade permission:It is used to create order, cancel order and transfer, etc.
- Withdraw permission:It is used to create withdraw order, cancel withdraw order, etc.
Security Authentication
AccessKey is the access key to API, SecretKey is the secret key of user signature for requests. Important note: These two keys are closely related to account security, and should not be disclosed to others at any time
Demo
Java Python3 Php Dart Legal request structure
Based on the consideration of security, all API request must be calculated by signature algorithm except market API. A legel request consists of below parts:
-
Request-URI Method, i.e. the address access to server: api.hotcoinfin.com followed by method name, take api.hotcoinfin.com/v1/order/place for instance.
-
API AccessKeyId is the The AccessKey in the APIKEY you requested.
-
Signature Method is the hash-based protocol of calculating signatures by users, HmacSHA256 is applied here.
-
SignatureVersion is the version of the signature protocol, 2 is applied here.
-
Timestamp is the time you made the request (UTC Time Zone). Including the value in query request helps preventing third parties from interception of your request. For example：2017-05-11T16:22:06.123Z.Again,(UTC Time Zone) is stressed here. For required parameters and optional parameters, these parameters and their meanings can be viewed in the description of each method.
-
Signature the value calculated by signature is used for ensuring that the signature is valid and not tampered.
https://api.hotcoinfin.com/v1/order/place?
AccessKeyId=AccessKeyHotcoin123456789
&symbol=btc_usdt
&type=buy
&tradePrice=40000
&tradeAmount=0.1
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z
&Signature=calculated valueSignature Algorithm
API request can be tempered at great risk while it is sent through the Internet. To ensure that the request is not tempered, we will require users to sign in every request (except market API) for verifying the authticity of parameters or the values of parameters.
Sign Steps:
Standards for Requests of Calculating Signatures:
Establish a standard for requests of calculating signatures because when using HMAC to calculate signature, total different results will be achieved as different contents are calculated. So before calculating signatures, please make a standard. Examples of the request of order placement will be given as follows.
https://api.hotcoinfin.com/v1/order/place?
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z
&symbol=btc_usdt
&type=buy
&tradePrice=40000
&tradeAmount=0.1The request Method (GET or POST, WebSocket use GET), append line break “\n”
GET\n
The host with lower case, append line break \n.
api.hotcoinfin.com\n.
The path, append line break “\n”
/v1/order/place\n
Sorting parameters by order of ASCII code (Encoding by UTF-8 format and URI format, hexadecimal characters must be capitalized, for example ‘:’ will be encoded as ‘%3A’, space key will be encoded as ‘%20’).
For example, here is the original order of the request parameters after encoded.
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z
&symbol=btc_usdt
&type=buy
&tradePrice=40000
&tradeAmount=0.1Above parameter should be ordered like below:
AccessKeyId=AccessKeyHotcoin123456789
SignatureMethod=HmacSHA256
SignatureVersion=2
Timestamp=2017-05-11T16%3A22%3A06.123Z&
symbol=btc_usdt
tradeAmount=0.01
tradePrice=40000
type=buyUse char ‘&’ to concatenate all parameters.
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&symbol=btc_usdt
&tradeAmount=0.1
&tradePrice=40000
&type=buyThe final strings for signature calculation is as follows:
GET\n
api.hotcoinfin.com\n
/v1/order/place\n
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&symbol=btc_usdt
&tradeAmount=0.1
&tradePrice=40000
&type=buyCalculation of signature algorithm, transfer the following two parameters to the cryptographic hash function:
Strings for signature calculation
GET\n
api.hotcoinfin.com\n
/v1/order/place\n
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&symbol=btc_usdt
&tradeAmount=0.1
&tradePrice=40000
&type=buySecretKey for execute signature
SecretKeyHotcoin123456789
Obtained result of signature calculation and encoded with Base64
2oEC+yhkHTsNkgPUq4ZB/5mlY7EZAtUDWOQ5EO01D+I=
Add the above values as the value of parameter Signature to the API request. The value must be encoded with URI when this parameter is added to the request.
symbol rules：base currency + quote currency.In BTC/USDT, symbol is btc_usdt；While in ETH/BTC, symbol is eth_btc, and so on.
Finally, the API request sent to the server should be：
https://api.hotcoinfin.com/v1/order/place
?AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&symbol=btc_usdt
&tradeAmount=0.1
&tradePrice=40000&type=buy
&Signature=2oEC%2ByhkHTsNkgPUq4ZB%2F5mlY7EZAtUDWOQ5EO01D%2BI%3D - Reference Data
Reference Data
Get all trade pairs
Signature Authentication: No
Rate Limit: 10 times/shttps://api.hotcoinfin.com/v1/common/symbols curl "https://api.hotcoinfin.com/v1/common/symbols"- GET /v1/common/symbols
Request parameters:
No parameter is available for this endpoint.Response data:
Parameter Mandatory Data Type Description Default Value Range code y int Status code success：200 msg y string message time y long Current millisseconds data y array symbols list data:
Response
{ "code":"200", "time":1567045034, "data":[ { "baseCurrency":"etc", "quoteCurrency":"usdt", "pricePrecision":6, "amountPrecision":4, "symbolPartition":"main", "symbol":"etc_usdt", "state":"online", "minOrderCount":0.001, "maxOrderCount":10000, "minOrderPrice":0.0001, "maxOrderPrice":10000 }, { "baseCurrency":"ltc", "quoteCurrency":"usdt", "pricePrecision":6, "amountPrecision":4, "symbolPartition":"innovation", "symbol":"ltc_usdt", "state":"online", "minOrderCount":0.001, "maxOrderCount":10000, "minOrderPrice":0.0001, "maxOrderPrice":10000 } ] }Field Type Data Type description baseCurrency string baseCurrency code quoteCurrency string quoteCurrency code pricePrecision integer price precision amountPrecision integer quantity precision symbolPartition string symbol Partition, example:[main,innovation] symbol string trade pair code state string trade pair status [enable,disable] minOrderCount decimal min order count maxOrderCount decimal max order count minOrderPrice decimal min order price maxOrderPrice decimal max order price - Market Data # Market Data ### Real-time Ticker data Signature Authentication: No Rate Limit: 10 times/s - GET /v1/market/ticker ```json https://api.hotcoinfin.com/v1/market/ticker curl "https://api.hotcoinfin.com/v1/market/ticker" ``` **Response data:** Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- status|y|string|Status code||success：ok，failed：error timestamp|y|long|Current millisseconds|| ticker|y|list|data||
Response
```json { "status":"ok", "timestamp":1567045034, "ticker":[ { "symbol":"btc_usdt", "last":"10000.00000000", "buy":"9999.00000000", "sell":"10001.00000000", "high":"11000.00000000", "low":"9000.00000000", "vol":"10000000.0000", "change":"10.10" } ] } ``` Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|string|Trading pair||sellShortName_buyShortName，eg：btc_usdt last|y|number|latest price|| buy|y|number|buy|| sell|y|number|sell|| high|y|number|high || low|y|number|low|| vol|y|number|vol|| change|y|number|change|| ### Obtain kline data Signature Authentication: No Rate Limit: 20 times/s - GET /v1/ticker ```json https://api.hotcoinfin.com/v1/ticker?symbol=btc_usdt&step=60 curl "https://api.hotcoinfin.com/v1/ticker?symbol=btc_usdt&step=60" ``` **Request parameters:** Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- step|y|int|Time：Sec||60（1min）,300（5mins）,900（15mins）,1800（30mins）,3600（1h）,86400（1d）,604800（1w）,2592000（1mon） symbol|y|string|pairs||btc_usdt **Response data:**Response
```json { "code":200, "msg":"success", "time":1527838104874, "data":[ [ 1527820200000, 54598.5, 54598.5, 54598.5, 54598.5, 0 ], [ 1527820200000, 54598.5, 54598.5, 54598.5, 54598.5, 0 ] ] } ``` Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code msg|n|string|return message time|y|long|Current millisseconds data|y|array(array(number))|Kline data **data:**
[[
1527820200000, //int time
54598.5, //number O
54598.5, //number H
54598.5, //number L
54598.5, //number C
0.0000 //number Vol
],
......
]
### Obtain Deep Data Signature Authentication: No Rate Limit: 20 times/s - GET /v1/depth ```json https://api.hotcoinfin.com/v1/depth?symbol=btc_usdt&step=60 curl "https://api.hotcoinfin.com/v1/depth?symbol=btc_usdt&step=60" ``` **Request parameters:** Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|string|Trading pair||Example：btc_usdt step|n|int|Add the Parameter to check latest Kline data,Data Type is time,unit is sec.||60,3*60,5*60,15*60,30*60,60*60（1h）,24*60*60（1d）,7*24*60*60（1w）,30*24*60*60（1mon） **Response data:**Response
```json { "code":200, "msg":"success", "time":1527837164605, "data":{ "period":{ "data":[ [ 1527837120000, 54598.5, 54598.5, 54598.5, 54598.5, 0 ] ], "marketFrom":"btc_usdt", "type":60, "coinVol":"btc_usdt" }, "depth":{ "date":1527837163, "asks":[ [ 57373.8, 0.0387 ], [ 57751.26, 0.0128 ], [ 57751.26, 0.0128 ] ], "bids":[ [ 57373.8, 0.0387 ], [ 57751.26, 0.0128 ], [ 57751.26, 0.0128 ] ], "lastPrice":54598.5 } } } ``` Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code msg|n|string|return message time|y|long|Current millisseconds data|y|object|Trading deep date **data:** Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- depth|y|object period|n|object|Vaule only displayed when uploading step **depth:** Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- bids|y|array(array(long))|buy,[price(transaction price), amount(transaction vol)] asks|y|array(array(long))|sell,[price(transaction price), amount(transaction vol)] date|y|long|Timestamp lastPrice|y|number|Latest price **period:** Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- marketFrom|y|string|Input symbol coinVol|y|string|Input symbol type|y|long|Input step,time data|y|array（array）|Last kline data,same with format above by only one ### Obtain real-time trade data Signature Authentication: No Rate Limit: 20 times/s - GET /v1/trade ```json https://api.hotcoinfin.com/v1/trade?symbol=btc_usdt&count=60 curl "https://api.hotcoinfin.com/v1/trade?symbol=btc_usdt&count=60" ``` **Request parameters:** Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Access key SignatureVersion|y|string|Version SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|ApiSecret Timestamp|y|string|Timestamp count|y|int|Trades items||0 symbol|y|string|Trading pair||example：btc_usdt **Response data:**Response
```json { "code":200, "msg":"success", "time":1536315868962, "data":{ "sellSymbol":"BTC", "buySymbol":"USDT", "trades":[ { "price":0.007, "amount":66491.04, "id":1, "time":"02:45:08", "en_type":"ask", "type":"sell" }, { "price":0.007, "amount":66491.04, "id":1, "time":"02:45:08", "en_type":"ask", "type":"sell" } ] } } ``` Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code msg|n|string|return message time|y|long|Current millisseconds data|y|object|Real-time transactions **data:** Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- trades|y|array(object)|trades data sellSymbol|y|string|sellSymbol buySymbol|y|string|buySymbol **trades:** Parameter|Mandatory| Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- price|y|long|transaction price amount|y|string|transaction amount id|y|string|transaction id time|y|string|transaction time en_type|y|string|direction||"bid"(buy),"ask"(sell) type|y|string|transaction Data Type||"buy","sell" - Account
Account
Obtain User Balance
Signature Authentication: Yes
Rate Limit: 10 times/s- GET /v1/balance
https://api.hotcoinfin.com/v1/balance?AccessKeyId="" curl "https://api.hotcoinfin.com/v1/balance?AccessKeyId=''"Request parameters:
Parameter Mandatory Data Type Description Default Value Range AccessKeyId y string Access key Response data:
Response
{ "code": 200, "msg": "success", "time": 1527835756743, "data": { "netassets": 0, "wallet": [ { "uid":1100011, "coinId":1, "symbol":"BTC", "total":1000.0000000000, "frozen":1000.0000000000, "coinName":"BTC", "shortName":"BTC" }, { "uid":1100011, "coinId":2, "symbol":"LTC", "total":1000.0000000000, "frozen":1000.0000000000, "coinName":"LTC", "shortName":"LTC" }, { "uid":1100011, "coinId":4, "symbol":"ETH", "total":1000.0000000000, "frozen":0E-10, "coinName":"ETH", "shortName":"ETH" } ], "totalassets": 0 } }Parameter Mandatory Data Type Description Default Value Range code y int Status code msg n string Return message time y long Current millisseconds data y object Transaction deep data data:
Parameter Mandatory Data Type Description Default Value Range netassets y number net assets，unit: usdt totalassets y number total assets，unit:usdt wallet y array(object) wallet list wallet:
Parameter Mandatory Data Type Description Default Value Range coinName y long Currency uid y int User ID coinId y int Currency ID total y number Available frozen y number On orders symbol y string Currency symbol shortName y string Abbreviation - Trading # Trading ### Place order Signature Authentication: Yes Rate Limit: 10 times/s - POST /v1/order/place **Request parameters:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|string|Trading pair| |example：btc_usdt type|y|string|Type| | "buy" ,”sell" tradeAmount|y|number|amount|| tradePrice|y|number |price(Only for limit orders)|| matchType|n|integer |Match Type|0|0-limit 1-market marketUnit|n|string |Market Unit(Required for market orders, the amount or funds is tradeAmount)||amount-Amount funds-Funds **Response data:**
Response
```json { "code":200, "msg":"order success", "time":1536306331399, "data":{ "ID":18194813 } } ``` Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code||success：200，failed：300 msg|y|string|message|| time|y|long|Current millisseconds|| data|y|object|data|| **msg range** English | | ------------ |Illegal request | Illegal tradeAmount value | Illegal tradePrice value | Illegal symbol format **data:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- ID|y|bigint|order id|| ### Order Cancel Note: Cancel order requests is under asynchronous pattern, call interface /v1/order/detailById is required for order status query. Signature Authentication: Yes Rate Limit: 10 times/s - POST /v1/order/cancel **Request parameters:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|bigint |Order id | | **Response data:**Response
```json { "code": 200, "msg": "Cancel Success", "time": 1536306495984, "data": null } ``` Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code||success：200，failed：300 msg|y|string|message|| time|y|long|Current millisseconds|| ### Order Details Signature Authentication: Yes Rate Limit: 10 times/s - GET /v1/order/detailById ```json https://api.hotcoinfin.com/v1/order/detailById curl "https://api.hotcoinfin.com/v1/order/detailById" ``` **Request parameters:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|bigint |order id | | leverAcctid |n|string |Fields not required innon-leverorder,Sub-account id,clientId in line with API| | **Response data:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code|| msg|n|string|message|| time|y|long|Current millisseconds|| data|y|object|order details|| **data:**Response
```json { "code": 200, "msg": "success", "time": 1536306896294, "data": { "types": "bug", "leftcount": 0.01, "fees": 0, "last": 0, "count": 0.01, "successamount": 0, "source": "API", "type": 0, "price": 40000, "buysymbol": "", "id": 18194814, "time": "2018-09-07 15:48:44", "sellsymbol": "", "statusCode":1, "status": "unsettled" } } ``` Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- types|y|string|order type| |Buy 、Sell leftcount|y|number|Unfill|| fees|y|number|Fee|| last|y|number|Current order latest price|| count|y|number|amount|| successamount|y|number|Total transaction|| source|y|string|Source | |API、WEB、APP type|y|int|Data Type code| |0（Buy），1（Sell） price|y|number|Price || buysymbol|n|string|Buy symbol|| sellsymbol|n|string|Sell symbol|| time|y|string|Establish time|| statusCode|y|int|Status code| |1 Unfilled 2 Partial filled 3 Filled 4 Revoking 5 Cancelled status|y|int|Status| |Unfill,Partial filled,Filled,Revoking,Cancelled ### Transaction details Signature Authentication: Yes Rate Limit: 10 times/s - GET /v1/order/counterpartiesById ```json https://api.hotcoinfin.com/v1/order/counterpartiesById curl "https://api.hotcoinfin.com/v1/order/counterpartiesById" ``` **Request parameters:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|bigint |order id | | **Response data:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code|| msg|n|string|message|| time|y|long|Current millisseconds|| data|y|object|Order detail|| **data:**Response
```json { "code":200, "data":{ "entrusts":[ { "amount":1.2042000000, "count":2.2300000000, "createTime":"2019-05-27 18:15:12", "entrustId":431879850, "entrustType":0, "id":101192723, "isSelfTrade":1, "matchId":431879852, "prize":0.5400000000, "sysmbol":"btc_usdt" } ] }, "msg":"success", "time":1568690580787 } ``` Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- entrusts|y|array(object)|BBO list|| **wallet:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|bigint|Primary key ID|| isSelfTrade|y|int|Self-trade Option 0 n 1 y|| sysmbol|y|string|Trading pairs|| entrustType|y|int|orderData Type 0 Buy 1 Sell|| entrustId|y|bigint|order id|| matchId|y|bigint|Transaction ID|| amount|y|number|Total Transaction|| prize|y|number|Price|| count|y|number|Amount|| createTime|y|string|Create time|| ### Obtain order list Signature Authentication: Yes Rate Limit: 10 times/s - GET /v1/order/entrust ```json https://api.hotcoinfin.com/v1/order/entrust curl "https://api.hotcoinfin.com/v1/order/entrust" ``` **Request parameters:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|string |Trading pairs| |example：btc_usdt type|n|int|Data Type|0|0 is all 1 iscurrent 2 is history page|n|int|page|1| count|y|int|items|7|[1-100] max 100 items **Response data:**Response
```json { "code": 200, "msg": "Obtain success！", "time": 1527841588334, "data":{ "entrutsHis": [ { "types": "Buy", "leftcount": 1.0E-4, "fees": 0, "last": 0, "count": 1.0E-4, "successamount": 0, "source": "WEB", "type": 1, "price": 1.0E7, "buysymbol": "USDT", "id": 947644, "time": "2018-06-27 17:45:14", "sellsymbol": "BTC", "status": "Cancelled" }, { "types": "Buy", "leftcount": 1.0E-4, "fees": 0, "last": 0, "count": 1.0E-4, "successamount": 0, "source": "WEB", "type": 1, "price": 1.0E7, "buysymbol": "USDT", "id": 947645, "time": "2018-06-27 17:45:14", "sellsymbol": "BTC", "status": "Cancelled" } ], "entrutsCur": [ { "types": "Buy", "leftcount": 0.01, "fees": 0, "last": 0, "count": 0.01, "successamount": 0, "source": "API", "type": 0, "price": 40000, "buysymbol": "USDT", "id": 18194814, "time": "2018-09-07 15:48:44", "sellsymbol": "BTC", "status": "Unfill" }, { "types": "Sell", "leftcount": 0.01, "fees": 0, "last": 0, "count": 0.01, "successamount": 0, "source": "API", "type": 0, "price": 40000, "buysymbol": "USDT", "id": 18194814, "time": "2018-09-07 15:48:44", "sellsymbol": "BTC", "status": "Unfill" } ] } } ``` Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code|| msg|n|string|Return message|| time|y|long|Current millisseconds|| data|y|object|Order details|| **data:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- entrutsCur|n|array(object)|Current order|| entrutsHis|n|array(object)|History order|| **entrutsCur 及 entrutsHis Data Type is the same:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|bigint|Order id time|y|string|Order time types|y|string|Order Type|| Buy、Sell source|y|string|Order source||"WEB"，"APP"，"API" price|y|number|Order price count|y|number|Order amount leftcount|y|number|Unfill amount last|y|number|Transaction price successamount|y|number|Total Transaction fees|y|number|fee status|y|string|Order Status||Unfill,Partial filled,Filled,Revoking,Cancelled type|y|int|Order Data Type|| 0( "Buy"),1( "Sell") buysymbol|y|string|Currency Data Type symbol sellsymbol|y|string|Currency Data Type symbol ### Current&History Transaction Record Signature Authentication: Yes Rate Limit: 10 times/s - GET /v1/order/matchresults ```json https://api.hotcoinfin.com/v1/order/matchresults curl "https://api.hotcoinfin.com/v1/order/matchresults" ``` **Request parameters:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|string|Trading pairs||example：btc_usdt types|n|string|query order Data Type compositio，separate by','||0：buy, 1：sell startDate|n|string|Inquire start date, date form yyyy-mm-dd|-1d Inquire the day before end data|Value Range [((endDate) – 1), (endDate)] ，Max inquery date is 2 days in query window, inquery ranges of nearly 61 days endDate|n|string|Inqery end date, date form yyyy-mm-dd|today|Value Range [(today-60), today] ，Max inquery date is 2 days in query window, inquery ranges of nearly 61 days startTimestamp|n|Long|Inquire start time, Unix timestamp, in milliseconds. You are advised to use startDate, which can be queried in milliseconds|required when querying by timestamp|Value Range [((endTimestamp) – 1), (endTimestamp)] ，Max inquery date is 2 days in query window, inquery ranges of nearly 61 days endTimestamp|n|Long|Inquire end time, Unix timestamp, in milliseconds. You are advised to use endDate, which can be queried in milliseconds|required when querying by timestamp|Value Range [(today-60), today] ，Max inquery date is 2 days in query window, inquery ranges of nearly 61 days from|n|string|Inquire start&end ID|order history record ID（max）| direct|n|string|Direction|default next， transaction record ID orders from big to small|prev forward，time（or ID）positive sequence；next backward，time（or ID）reverse） size|n|string| query record scope|100|[1，100] **Response data:**Response
```json { "code":200, "data":{ "entrustdetail":[ { "createdAt":1623134000577, "filledAmount":"1.20", "filledFees":"2.2300", "id":43187, "matchId":123456, "orderId":431879852, "type":"1", "price":"0.5400000000", "role":"taker" } ] }, "msg":"success", "time":1568690580787 } ``` Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code msg|n|string|return message time|y|long|Current millisseconds data|y|object|Real-time transactions **data:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- entrustdetail|n|array(object)|Transaction Record **entrustdetail:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- createdAt|y|long|Transaction time filledAmount|y|string|Transaction amount filledFees|y|string|Transaction fee id|y|long|Transaction record id matchId|y|long|Matchmaking id orderId|y|long|Order id price|y|string|Transaction price type|y|string|Order Data Type||0：buy, 1：sell role|y|string|Transaction role||taker,maker ### Batch Cancels Signature Authentication: Yes Rate Limit: 10 times/s - POST /v1/order/batchCancelOrders `Note： The API only for submit cancel request,actual result need to confirm by order Status,matchmaking Status.` **Request parameters:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- orderIds|y|String|Revoke order ID list||Shall not exceeds 100 order ID each time Example"2232,1232,2321" **Response data:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code msg|n|string|Return message data|y|object| ### Batch Cancels(OpenOrders) Signature Authentication: Yes Rate Limit: 10 times/s - POST /v1/order/batchCancelOpenOrders `Note： The API only for submit cancel request,actual result need to confirm by order Status,matchmaking Status.` **Request parameters:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|String|Transaction code list( Max 10 symbols,separate by commas between various trade codes)，btc_usdt, eth_btc...|| side|n|String|Direction||when buy -buy direction sell -sell direction is empty，obtain orders of all directions to revoke. **Response data:**Response
```json { "code":200, "data":{ "successCount": 1, "failCount": 1 }, "msg":"success" } ``` Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code msg|n|string|Return message data|y|object| **data:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- {successCount|y|int|Success cancel amount failCount}|y|int|Cancelled failed amount ### Batch Orders API Key Access: Trading, Maximum 10 orders for a single batch Signature Authentication: Yes Rate Limit: 10 times/s - POST /v1/order/batchOrders **Request parameters:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- orders|y|object|Order list|| **orders:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- [{symbol|y|string|Trading pairs||example：btc_usdt type|y|string|Data Type||"buy" ,”sell" tradeAmount|y|number|Amount|| tradePrice|y|number|Price(Only for limit orders)|| matchType|n|integer |Match Type|0|0-limit 1-market marketUnit}]|n|string |Market Unit(Required for market orders, the amount or funds is tradeAmount)||amount-Amount funds-Funds **Response data:**Response
```json { "code": 200, "msg": "success", "time": 1527841588334, "data":{ "list": [ { "ID":123456, "errcode": "", "errmsg": "" }, { "ID":1234567, "errcode": "", "errmsg": "" } ] } } ``` Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status code msg|n|string|Return message data|y|object| **data:** Parameter|Mandatory|Data Type|Description|Default|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- [{ID|y|bigint|Order id|| errcode|n|string|return error code errmsg}]|n|string|Return error Description - WebSocket Market Data # WebSocket Market Data ### Access instructions #### WebSocket domain name ##### wss://wss.hotcoinfin.com/trade/multiple #### Data compression All data returned by the WebSocket quotation interface is GZIP compressed, and the client needs to decompress the data after receiving it. #### The heartbeat message After the user's Websocket client connects to the hot coin server, the hot coin server will send ping messages to the user periodically (currently set to 5 seconds), as follows: ```{"ping": "ping"}``` When the user's Websocket client receives this heartbeat message, it should return a PONG message as follows: ```{"pong": "pong"}``` #### Subscribe to the topic After successfully establishing a connection to the Websocket server, the Websocket client sends a request to subscribe to a specific topic: ```{"sub": "topic to subscribe"}``` for example：```{"sub": "market.btc_usdt.trade.depth"}``` After a successful subscription, the Websocket client will receive a confirmation message:
Response
```json { "ch": "market.btc_usdt.trade.depth", "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1632878832006 } ``` After that, once the subscribed topic has data update, the hot coin server will push the update message to the Websocket client. #### unsubscribe The unsubscribe format is as follows:```{"unsub": "topic to unsubscribe"}``` Unsubscription confirmed successfully. ### Kline data Request data:```{"sub":"market.$symbol$.kline.$period$"}``` Unsubscribe:```{"unsub":"market.$symbol$.kline.$period$"}``` > **Parameters** | Parameter | Data Type | Mandatory | Description | remark | | ------ | -------- | -------- | -------- | ----------------------------- | | symbol | String | y | symbol | btc_usdt | | period | String | y | Kline cycle| 1m,5m,15m,30m,1h,2h,4h,6h,12h,1d,3d,5d,1w,1mo | * After the subscription is successful or unsubscribed, the server returns data:Response
```json { "ch": "market.btc_usdt.kline.1m", "code": 200, "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1489474081631 } ``` Field description: ###### [timestamp,open,high,low,close,volume] ###### [ts, open, high, low, close, vol] | Parameter | Data Type | Mandatory | Description | remark | | ----- | -------- | -------- | ------ | --------------------------------------- | | ts | String | y | timestamp | Time range[1501174800000, 2556115200000] | | open | String | y | open | 995.37 | | high | String | y | high | 996.75 | | low | String | y | low | 995.36 | | close | String | y | close | 996.75 | | vol | String | y | volume | 9.112 | ### Market depth data Request data:```{"sub":"market.$symbol$.trade.depth"}``` Unsubscribe:```{"unsub":"market.$symbol$.trade.depth"}``` > **Parameters** | Parameter | Data Type | Mandatory | Description | remark | | ------ | -------- | -------- | -------- | -------- | | symbol | String | y | symbol | btc_usdt | * After the subscription is successful or unsubscribed, the server returns data:Response
```json { "ch": "market.btc_usdt.trade.depth", "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1489474081631 } ``` Field description: | Parameter | Data Type | Mandatory | Description | Default | | ----------------- | --------------- | -------- | ---------------------------- | --------------------- | | bids | [String,String] | y | 【Buyer's price, buyer's depth】 | ["9999.39","0.0098"] | | asks | [String,String] | y | 【Seller price, seller depth measure】 | ["10010.98","0.0099"] | | last | String | y | last | 0 | | open | String | y | open | 0 | | cny | String | y | cny | 0 | | netValue | String | y | ETF net| 0 | | buyOrSellCnyPrice | String | y | Used when buying or selling RMB valuation| 0 | ### Buy and sell every price Request data: ```{"sub":"market.$symbol$.trade.bbo"}``` Unsubscribe:```{"unsub":"market.$symbol$.trade.bbo"}``` > **Parameters** | Parameter | Data Type | Mandatory | Description | remark | | ------ | -------- | -------- | -------- | -------- | | symbol | String | y | symbol | btc_usdt | * After the subscription is successful or unsubscribed, the server returns data:Response
```json { "ch": "market.btc_usdt.trade.bbo", "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1489474081631 } ``` Field description: | Parameter | Data Type | Mandatory | Description | Default | | ----------------- | --------------- | -------- | ---------------------------- | --------------------- | | symbol | String | y | symbol | btc_usdt | | bid | String | y | Buy a price | 0 | | bidSize | String | y | Buy a quantity | 0 | | ask | String | y | Sold for a price | 0 | | askSize | String | y | Sell a quantity of | 0 | | last | String | y | last | 0 | ### 24H aggregate market data Request data:```{"sub":"market.$symbol$.24h.tickers"}``` Unsubscribe:```{"unsub":"market.$symbol$.24h.tickers"}``` > **Parameters** | Parameter | Data Type | Mandatory | Description | remark | | ------ | -------- | -------- | -------- | -------- | | symbol | String | y | symbol | btc_usdt | * After the subscription is successful or unsubscribed, the server returns data:Response
```json { "ch": "market.btc_usdt.24h.tickers", "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1489474081631 } ``` Field description: | Parameter | Data Type | Mandatory | Description | remark | | ------------- | -------- | -------- | ------------------------ | ---- | | sellShortName | String | y | sellShortName:BTC | | | sellSymbol | String | y | sellSymbol:bitcoin | | | buyShortName | String | y | buyShortName:ETH | | | buySymbol | String | y | buySymbol:ethereum | | | high | String | y | high | | | open | String | y | open | | | low | String | y | low | | | close | String | y | close | | | volume | String | y | volume | | | change | String | y | change | | | cny | String | y | cny | | | tradeId | Integer | y | tradeId | | | last | String | y | last | | | imageUrl | String | y | | | | netValue | String | y | ETF net | | ### Real-time transaction details Request data:```{"sub":"market.$symbol$.trade.detail"}``` Unsubscribe:```{"unsub":"market.$symbol$.trade.detail"}``` > **Parameters** | Parameter | Data Type | Mandatory | Description | remark | | ------ | -------- | -------- | -------- | -------- | | symbol | String | y | symbol | btc_usdt | * After the subscription is successful or unsubscribed, the server returns data:Response
```json { "ch": "market.btc_usdt.trade.detail", "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1489474081631 } ``` Field description: | Parameter | Data Type | Mandatory | Default | Description | remark | | --------- | -------- | -------- | ------------------------- | ------------------------------------------ | ---- | | amount | String | y | amount | 0.0099 | | | ts | String | y | time | time range[1501174800000, 2556115200000] | | | tradeId | Integer | y | tradeId | tradeId | | | price | String | y | price | 401.74 | | | direction | String | y | buy/sell | [buy/sell] | |
- sort: 3 # follow a certain sequence of letters or numbers # Market API ### Available Futures List #### GET /api/v1/perpetual/public #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|status，200：success|| msg|y|string|Tips|| data|y|object|Derivatives Info||
Response
```json { "code": 200, "msg": "success", "data": [ { "amount24": "3848", "base": "btc", "code": "btcusd", "direction": 1, "env": 1, "fluctuation": "-10.04", "fund": "0.00375", "high": "9100", "indexPrice": "7913.84", "low": "8100", "markPrice": "7918.29", "maxLever": 100, "minQuoteDigit": 2, "minTradeDigit": 8, "price": "8100", "quote": "usd", "size24": "4.39717319", "totalPosition": "1830", "unitAmount": 10 } ], } ``` ##### Derivatives InfoReturn： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|string|Contractcode|| base|y|string|base currency name,如btc、usdt|| quote|y|string|quote currency name，usd,usdt|| direction|y|string|Side 0:Linear Contract,1:Inverse Contract|| minTradeDigit|y|string|Min. transaction decimal places of base currency|| minQuoteDigit|y|string|Min. transaction decimal places of quote currency|| price|y|string|Latest Price|| quote|y|string|quote change|| fluctuation|y|string|quote change|| high|y|string|Highest price|| low|y|string|Lowest price|| amount24|y|string|24H Vol.(Cont)|| size24|y|string|24H Vol.(Cont)|| totalPosition|y|string|Holdings of lowest price|| fund|y|string|Fee rate|| markPrice|y|string|Mark price|| indexPrice|y|string|Index price|| unitAmount|y|string|quoteFace value of a contract, Default1|| env|y|string|Test or not 0:listing,1:testing|| maxLever|y|string|Max.Leverage|| ### Kline #### GET /api/v1/perpetual/public/{contractCode}/candles #### Request Parameter: ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- kline|y|string|klineType||1min,3min,5min,15min,30min,1hour,2hour,4hour,6hour,12hour,day,week since|n|int|Timestamp,Default Value0|| size|n|int|Klineamount|| klineType|n|int|KlineType|1|1-Latest Price 2-Mark Price 3-Index Price #### Return：Response
```json { "code":0, "data":[ [ 1543405500000,//time "100",//Lowest "100",//Highest "100",//Open price "100",//Close price "0",//Transaction Vol. "0"//Transaction value ] ], "msg":"success" } ``` Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|status，200：success|| msg|y|string|Tips|| data|y|object||| ### Depth Info #### GET /api/v1/perpetual/public/products/{contractCode}/orderbook ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode||Response
```json { "asks": [ //asks [ "9721.47", //price "225", //(Cont) "225" //Total(Cont) ] ], "bids": [ //bids [ "9720", "480", "480" ] ] } ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- asks|y|object|ask|| bids|y|object|bid|| ### Latest transaction data #### GET /api/v1/perpetual/public/{contractCode}/fills #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode||Response
```json { "code": 200, "data": [ [ "9695.28", //Deal price "496", //(Cont) "long", //Side 1582269058972, //time 9916897 //transactionid ] ], "msg": "success" } ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|string|statuscode|| data|y|object|Returnresult|| msg|y|string|Info|| ### Index Price Info #### GET /api/v1/perpetual/public/{contractCode}/indexInfo #### Request Parameter： ##### Path Parameter | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ------------ | --------- | ------ | ----------- | ------------- | ----------- | | contractCode | y | string | Futurescode | | |Response
```json { "code": 200, "data": { "components": [ { "name": "binance_contract", "price": "38983.69999999", "symbol": "BTC/USDT", "wgt": "1" } ], "index": "btc", "indexPrice": "38983.69999999", "time": 1650269513885 }, "msg": "success" } ``` #### Return： | Parameter | Type | Description | Default Value | Value Range | | ---------- | ------ | ------------------------------ | ------------------------------------------------------------ | ----------- | | components | obejct | Individual Exchange Index Info | | | | >name | string | Exchange Name | binance_contract-Binance Futures，binance-Binance，huobi-Huobi，okex-OK | | | >price | string | Price | | | | >symbol | string | Trade Pairs | | | | >wgt | number | Weight | | | | index | object | Index currency | | | | indexPrice | string | Index price | | | | time | number | Time | | | ### 资金费用历史 #### GET /api/v1/perpetual/public/{contractCode}/fee-rate ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| page|n|int|Page|| pageSize|n|int|Size|| #### Return：Response
```json { "code":200, "data": { "amount24":830768400, "contractCode":"etcusd", "createdDate":1546603201000, "feeRate":-0.00375, "id":5, "insuranceSize":0, "modifyDate":1546603201000, "size24":8307684, "timeIndex":1546603201000, "userPositionAmount":198000000 }, "msg":"success" } ``` Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- amount24|y|string|24H Vol.|| contractCode|y|string|Futurescode|| createdDate|y|string|Creation Time|| feeRate|y|string|Fee rate|| id|y|string|PRIMARY KEYid|| insuranceSize|y|string|Risk Reserves|| modifyDate|y|string|Modify time|| size24|y|string|24H Vol.(Cont)|| timeIndex|y|string|Time to generate current data|| userPositionAmount|y|string|Total Holdings|| ### Latest Mark price and Fee rate #### GET /api/v1/perpetual/public/{contractode}/premiumIndex ##### Path Parameter | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ------------ | --------- | ------ | ----------- | ------------- | ----------- | | contractCode | y | string | Futurescode | | | #### Return：Response
```json { "code": 200, "data": { "baseCurrency": "usdt", "contractCode": "btcusdt", "estimateFeeRate": "0.00375", "indexPrice": "39008.4", "lastFeeRate": "0.00375", "lastPrice": "41500", "markPrice": "39008.4", "quoteCurrency": "usdt", "time": 1650270347001, "totalPosition": "19193" }, "msg": "success" } ``` | Parameter | Type | Description | Default Value | Value Range | | --------------- | ------ | ------------------------ | ------------- | ----------- | | baseCurrency | string | Base currency | | | | contractCode | string | Contractcode | | | | estimateFeeRate | string | EstimateFee rate | | | | indexPrice | string | Index price | | | | lastFeeRate | string | Last updatedFee rate | | | | lastPrice | string | Latest transaction price | | | | markPrice | string | Mark price | | | | quoteCurrency | string | Quote currency | | | | time | string | Update time | | | | totalPosition | string | Total Positions | | | - Change Log # Change Log Release Time (UTC +8)| API |New/Update|Description ------------- | ------------- | ------------- | ------------- 2022.02.21|- |Add|Add perpetual api doc.
- Introduction
Introduction
API Document
Preparation
Before you use API, you need to login the website to create API Key with proper permissions. The API key is shared for all instruments in Hotcoin including spot, futures, swap, options.
Permissions are listed below：
- Read permission: It is used to query the data, such as order query, trade query.
- Trade permission：It is used to create order, cancel order and transfer, etc.
- Withdraw permission：It is used to create withdraw order, cancel withdraw order, etc.
Authentication
AccessKey is the access key of API ，SecretKey is used to generate the signature for user’s request.Important Note: These two keys are closely related to account security. Please do not disclose them to others at any time.
Legal Request Structure
For security reasons, all API requests other than market API shall be carrying out the Signing Algorithm. A valid request consists of below parts：
- Method request address,which is also the server access address：api-ct.hotcoin.fit following by the method name，for example: api-ct.hotcoin.fit/api/v1/perpetual/account/assets/btcusdt.
- API Access Key（AccessKeyId） The ‘AccessKey’ in your APIKEY.
- Signature Method（SignatureMethod） The Hash method that is used to sign, it uses HmacSHA256。
- Signature Version（SignatureVersion） The version for the signature protocol, it uses 2.
- Timestamp（Timestamp）The UTC time when the request is sent, e.g. 2017-05-11T16:22:06. 123Z. It is useful to prevent the request to be intercepted by third-party.Again, the time zone is (UTC )
- Parameters: Each API Method has a group of parameters, you can refer to detailed document for each of them.The value after signed, it is guarantee the signature is valid and the request is not be tempered. Example：
https://api-ct.hotcoin.fit/api/v1/perpetual/account/assets/btcusdt?
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z
&Signature=calculated valueSignature Method
The API request may be tampered during Internet, therefore all private API must be signed by your API Key (Secrete Key).
Signing and Verifying ： The signature may be different if the request text is different, therefore the request should be normalized before signing. Below signing steps take the order query as an example:
https://api-ct.hotcoin.fit/api/v1/perpetual/account/assets/btcusdt?
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123ZThe request Method（GET or POST , DELETE），append line break “\n”
GET\n
The host with lower case, append line break “\n”.
api.hotcoin.top\n
The path, append line break “\n”.
/api/v1/perpetual/account/assets/btcusdt\n
The parameters are URL encoded, and ordered based on ASCII(Use UTF-8 encoding and URL encoded, the hex must be upper case. For example, The semicolon ‘:’ should be encoded as ‘%3A’, The space should be encoded as ‘%20’.).
For example below is the original parameters:
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123ZThen above parameter should be ordered like below:
AccessKeyId=AccessKeyHotcoin123456789
SignatureMethod=HmacSHA256
SignatureVersion=2
Timestamp=2017-05-11T16%3A22%3A06.123Z&Use char “&” to concatenate all parameters.
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123ZFinally, the string for signature algorithm should be :
GET\n
api.hotcoin.top\n
/api/v1/perpetual/account/assets/btcusdt\n
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123ZSignature is generated by passing the following two parameters into the hash code：
String to be used for signature algorithm
GET\n
api.hotcoin.top\n
/api/v1/perpetual/account/assets/btcusdt\n
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123ZSecret Key（SecretKey）
SecretKeyHotcoin123456789
Encode the hash code with base-64 to generate the signature
ND/9e/TW6pqNSeDKkBYnXHaKye7Wfivu2Vk3EYRl2W8=
Put the signature into request API. Encode signature by URI encoding and append in the URI with parameter name “Signature”.
Finally, the request sent to API should be:
https://api-ct.hotcoin.fit/api/v1/perpetual/account/assets/btcusdt
?AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&Signature=ND/9e/TW6pqNSeDKkBYnXHaKye7Wfivu2Vk3EYRl2W8= - Asset API
Asset API
My Assets
GET /api/v1/perpetual/account/assets/{contractCode}
Request Parameters：
Path Parameter
Parameter Mandatory Type Description Default Value Range contractCode y string Contractcode Query
Parameter Mandatory Type Description Default Value Range AccessKeyId y string Accesskey SignatureVersion y string Version SignatureMethod y string Signature Method HmacSHA256 Signature y string Signature Timestamp y string Timestamp { "nextRewardTimestamp": 86400000, "accountRights": "211.73425366", "realizedSurplus": "-1996.67028101", "unRealizedSurplus": "0", "orderMargin": "111.32734888", "positionMargin": "55.30721388", "env": 0, "currencyCode": "usdt", "availableMargin": "45.09969088" }Return：
Parameter Mandatory Type Description Default Value Range currencyCode y string Currency env y int testing coin or not 0:listing coin,1:testing coin availableMargin y string Avail.margin realizedSurplus y string Realized P/L orderMargin y string Order margin positionMargin y string Position margin unRealizedSurplus y string Unrealized P/L accountRights y string Equity 资产列表
GET /api/v1/perpetual/account/assets
Request Parameters：
Query
Parameter|Mandatory|Type|Description|Default|Value Range ————- | ————- | ————- | ————- | ————- | ————- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp||
Response
[ { "availableBalance": "9875.254090", "currencyCode": "USDT", "env": "0", "frozenBalance": "0.000000", "orderMargin": "15.823570", "positionMargin": "89.352729", "positionAccountRights": "10456.925390", "realizedSurplus": "583.993103", "unRealizedSurplus": "-15.505000" } ]Return：
Parameter Mandatory Type Description Default Value Range availableBalance y string Available balance currencyCode y string Currency env y int testing coin or not 0:listing coin,1:testing coin frozenBalance y string frozen balance（in transfer audit） orderMargin y string Order margin positionMargin y string Position margin positionAccountRights y string Equity realizedSurplus y string Realized P/L unRealizedSurplus y string Unrealized P/L Transaction History
GET /api/v1/perpetual/bills/deal-record
Request Parameters：
Query
Parameter Mandatory Type Description Default Value Range AccessKeyId y string Accesskey SignatureVersion y string Version SignatureMethod y string Signature Method HmacSHA256 Signature y string Signature Timestamp y string Timestamp startDate n long Start Date endDate n long End Date contractCode n string Contractcode page n integer Page 1 pageSize n integer PageSize 20 startId n long Startid endId n long Endid Response
{ "code": 200, "data": { "data": [ { "amount": "6", "contractCode": "btcusdt", "createDate": "2021-11-14 20:52:03", "currencyCode": "usdt", "dealType": 1, "detailSide": "close_long", "fee": "1.3579752900000000", "id": "666746374653476864", "makerTaker": "maker", "orderId": 125090120907072, "price": "64665.4900000000000000", "profit": "0.9555748956901509", "refOrderId": 125090122965326, "size": "3879.9294000000000000", "userId": "2000011" } ], "pageNum": 1, "pageSize": 20, "totalCount": 112677 }, "msg": "success" }Return：
Parameter Mandatory Type Description Default Value Range amount y string Transaction amount contractCode y string Contractcode createDate y string Creation time currencyCode y string Currency dealType y string TransactionType，1：Self-match，2：Deal with other users detailSide y string Side fee y string Fee id y long TransactionHistoryid makerTaker y string maker or taker orderId y long Orderid price y string Transaction price profit y string Profit refOrderId y long ReferOrderid size y string Transaction Value userId y long uid - Trading API # Trading API ### Place a New Order #### POST /api/v1/perpetual/products/{contractCode}/order #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp|| ##### Body(json) Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- type|y|string|Type||10 Limit or Conditional 11 Market price triggerBy|n|string|triggerType||Conditional option, if not conditional order this field must be NULL，IndexPrice：index，MarkPrice：mark，LastPrice：last triggerPrice|n|string|Conditional option trigger price|| side|y|string|Side||open_long Open Long open_short Open Short close_long Close Long close_short Close Short price|y|string|Price|| ioc|n|int|if orders cannot be immediately traded , the untranslated part will be cancelled immediately|0|0: Disable，1: Enable amount|y|int|Amount|| beMaker|n|int|Timestamp|0|Post-only：0:Not Post-only 1:Post-only
Response
```json { "id": "1237893454356" } ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|long|Orderid|| ### Place a New Conditional Order #### POST /api/v1/perpetual/products/{contractCode}/order #### Request Parameter： ##### Path Parameter | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ------------ | --------- | ------ | ----------- | ------------- | ----------- | | contractCode | y | string | Futurescode | | | ##### Query | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ---------------- | --------- | ------ | ---------------- | ------------- | ----------- | | AccessKeyId | y | string | Accesskey | | | | SignatureVersion | y | string | Version | | | | SignatureMethod | y | string | Signature Method | | HmacSHA256 | | Signature | y | string | Signature | | | | Timestamp | y | string | Timestamp | | | ##### Body(json) | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ------------ | --------- | ------ | -------------------------------- | ------------- | ------------------------------------------------------------ | | type | y | string | Type | | 12 :conditional order | | triggerBy | n | string | triggerType | | default "mark"，MarkPrice：mark，LastPrice：last | | triggerPrice | n | string | Conditional option trigger price | | Conditional option trigger price | | side | y | string | Side | | open_long Open Long, open_short Open Short ,close_long Close Long, close_short Close Short | | price | y | string | Price | | Price | | amount | y | int | Amount | | Amount | | algoType | y | int | Order type | | 10 Limit price , 11 Market price | | currentPrice | y | string | Current contract price | | The current contract price, to determine the direction of profit and loss | ```json //Plan to place orders { "type": 12, //type: order type, 12: condition order "side": "open_long", //side: open position direction after triggering "triggerBy": "last", //Trigger type: index price: index, mark price: mark, last price: last "triggerPrice": "500", //Trigger price "price": "600.000000", // After triggering the order price (limit order price must be posted) "amount": "10", // Number of orders placed after triggerin "algoType": 10 // Conditional order Type 10: limit order 11: market order } ``` ```json //Stop profit stop loss order { "type": 12, //type: order type, 12: condition order "amount": 12, //Number of orders placed after triggering "side": "close_long", //side: open position after triggering "triggerBy": "last", // Trigger type: index price: index, mark price: mark, last price: last "triggerPrice": "12", // Trigger price "currentPrice": "600.000000", // Current contract price, determine the direction of stop profit and stop loss "algoType": 10, // Conditional order Type 10: limit order 11: market orde "price": "600.000000", // After triggering the order price (limit order price must be posted) } ``` #### Return： | Parameter | Mandatory | Type | Description | Default Value | Value Range | | --------- | --------- | ---- | ----------- | ------------- | ----------- | | id | y | long | Orderid | | |Response
```json { "id": "1237893454356" } ``` ### Place a Batch of Orders #### POST /api/v1/perpetual/products/{contractCode}/batch-order #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Contractcode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp|| ```json [ { "amount": 1, "lang": "zh_CN", "platform": 1, "price": "2.94", "side": "open_long", "type": 10, "tag": 1 } ] ``` ##### Body(list-json) Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- type|y|string|Type||10 Limit or Conditional 11 Market price side|y|string|Side||open_long Open Long open_short Open Short close_long Close Long close_short Close Short price|y|string|Price|| amount|y|int|Amount|| beMaker|n|int|Timestamp|0|Post-only：0:Not Post-only 1:Post-only ioc|n|int|if orders cannot be immediately traded , the untranslated part will be cancelled immediately|0|0: Disable，1: Enable tag|n|string|Tag||tags defined by the user at the time of order placing and returned after the order is placedResponse
```json [ { "orderId": 80742077438016, "tag": "1" } ] ``` #### Return(list-json)： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|long|Orderid|| ### Order List #### GET /api/v1/perpetual/products/{contractCode}/list #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Contractcode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp||Response
```json [ { "amount": "300.0000000000000000", "avgPrice": "0E-16", "base": "", "contractCode": "fbtcusd", "contractDirection": 0, "createdDate": 1582225542000, "dealAmount": "0E-16", "detailSide": "open_long", "direction": "", "fee": "0E-16", "id": 69109290623152, "orderSize": "0.32258064", "price": "9300.0000000000000000", "profit": "0E-16", "quote": "", "reason": 0, "refConditionOrderId": 0, "refOrderCondition": null, "side": "long", "source": "", "status": 0, "systemType": 10, "triggerBy": "", "triggerPrice": "" } ] ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- amount|y|string|Amount|| avgPrice|y|string|Avg. Filled Price|| base|y|string|Base curreny,such as btc、fbtc|| contractCode|y|string|A combination between Base and Quote P_BTC_USDT，R_BTC_USDT|| contractDirection|y|int|FuturesSide 0: Linear,1: Inverse|| createdDate|y|string|Creation Time|| dealAmount|y|string|Filled Amount|| detailSide|y|string|OrderSide 1.Open Longopen_long 2.Open Shortopen_short 3.Close Longclose_long 4.Close Shortclose_short|| direction|y|string|Conditional：triggerSide，greater Greater，less Less|| fee|y|string|The handling fee paid after the order is filled: Positive means fee obtained, negative means fee paid|| id|y|long|Orderid|| orderSize|y|string|Ordervalue|| price|y|string|OrderPrice|| profit|y|string|The P/L corresponding to the order after being filled: Positive means profit, negative means loss|| quote|y|string|Quote currency name，usd,cny,usdt|| reason|y|int|Reasons for cancellation of this order，0 is Default Value，no reasons|| refConditionOrderId|y|long|ConditionalOrderid|| refOrderCondition|y|object|ConditionalOrderDetails|| side|y|string|OrderSide，longLong，shortShort|| source|y|string|Source|| status|y|int|Status 0:Waiting to fill 1:Partial filled 2:Filled -1:Cancelled|| systemType|y|int|10:Limit 11:Market 13:Forced Liquidation 14: Liquidation 15：Over loss 16：ADL|| triggerBy|y|string|ConditionaltriggerType，IndexPrice：index，MarkPrice：mark，LastPrice：last|| triggerPrice|y|string|ConditionaltriggerPrice|| ### Cancel Order #### DELETE /api/v1/perpetual/products/{contractCode}/order/{id} #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| id|y|long|Orderid|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp||Response
```json { "code": 200, "msg": "success", "data": null } ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status，200：Success|| msg|y|string|Tips|| data|y|object||| ### 批量Cancel Order #### DELETE /api/v1/perpetual/products/{contractCode}/orders #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp||Response
```json { "code": 200, "msg": "success", "data": null } ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status，200：Success|| msg|y|string|Tips|| data|y|object||| ### Batch Cancel According to Order No. #### DELETE /api/v1/perpetual/products/{contractCode}/batch-delete-order #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp|| ```json [ 80581909355536, 80581909355537 ] ``` ##### Body(list) Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|string|OrderNo.||Response
```json { "code": 200, "msg": "success", "data": null } ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|Status，200：Success|| msg|y|string|Tips|| data|y|object||| ### OrderDetails #### GET /api/v1/perpetual/products/{contractCode}/{id} #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| id|y|long|Orderid|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp||Response
```json { "amount": "300.0000000000000000", "avgPrice": "0E-16", "base": "", "contractCode": "fbtcusd", "contractDirection": 0, "createdDate": 1582225542000, "dealAmount": "0E-16", "detailSide": "open_long", "direction": "", "fee": "0E-16", "id": 69109290623152, "orderSize": "0.32258064", "price": "9300.0000000000000000", "profit": "0E-16", "quote": "", "reason": 0, "refConditionOrderId": 0, "refOrderCondition": null, "side": "long", "source": "", "status": 0, "systemType": 10, "triggerBy": "", "triggerPrice": "" } ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- amount|y|string|Amount|| avgPrice|y|string|Avg. Filled Price|| base|y|string|Base currency name,such asbtc、fbtc|| contractCode|y|string|A combination between Base and Quote P_BTC_USDT，R_BTC_USDT|| contractDirection|y|int|FuturesSide 0: Linear,1: Inverse|| createdDate|y|string|Creation Time|| dealAmount|y|string|Filled Amount|| detailSide|y|string|OrderSide 1.Open Longopen_long 2.Open Shortopen_short 3.Close Longclose_long 4.Close Shortclose_short|| direction|y|string|ConditionalOrder：triggerSide，greaterGreater，lessLess|| fee|y|string|The handling fee paid after the order is filled: Positive means fee obtained, negative means fee paid|| id|y|long|Orderid|| orderSize|y|string|Ordervalue|| price|y|string|OrderPrice|| profit|y|string|The P/L corresponding to the order after being filled: Positive means profit, negative means loss|| quote|y|string|Quote currency name，usd,cny,usdt|| reason|y|int|Reasons for cancellation of this order，0 is Default Value，no reasons|| refConditionOrderId|y|long|Conditional orderid|| refOrderCondition|y|object|Conditional order details|| side|y|string|OrderSide，longLong，shortShort|| source|y|string|Source|| status|y|int|Status 0:Waiting to fill 1:Partial filled 2:Filled -1:Cancelled|| systemType|y|int|10:Limit 11:Market 13:Forced Liquidation 14: Liquidation 15：Over loss 16：ADL|| triggerBy|y|string|ConditionalOrdertriggerType，IndexPrice：index，MarkPrice：mark，LastPrice：last|| triggerPrice|y|string|ConditionalOrdertriggerPrice|| ### Market Close All #### POST /api/v1/perpetual/products/{contract_code}/{side}/closePosition #### Request Parameter： ##### Path Parameter | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ------------ | --------- | ------ | ----------- | ------------- | --------------------- | | contractCode | y | string | Futurescode | | | | side | y | string | Side | | long Long short Short | ##### Query | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ---------------- | --------- | ------ | ---------------- | ------------- | ----------- | | AccessKeyId | y | string | Accesskey | | | | SignatureVersion | y | string | Version | | | | SignatureMethod | y | string | Signature Method | | HmacSHA256 | | Signature | y | string | Signature | | | | Timestamp | y | string | Timestamp | | |Response
```json { "code": 200, "msg": "success", "data": null } ``` #### Return： | Parameter | Mandatory | Type | Description | Default Value | Value Range | | --------- | --------- | ------ | -------------------- | ------------- | ----------- | | code | y | int | Status，200：Success | | | | msg | y | string | Tips | | | | data | y | object | | | | ### History Order #### GET /api/v1/perpetual/products/{contractCode}/history-list #### Request Parameter： ##### Path Parameter | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ------------ | --------- | ------ | ----------- | ------------- | ----------- | | contractCode | y | string | Futurescode | | | ##### Query | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ---------------- | --------- | ------ | ------------------------------------------------------------ | ------------- | ----------- | | AccessKeyId | y | string | Accesskey | | | | SignatureVersion | y | string | Version | | | | SignatureMethod | y | string | Signature Method | | HmacSHA256 | | Signature | y | string | Signature | | | | Timestamp | y | string | Timestamp | | | | base | n | string | Base currency | | | | detailSide | n | string | PositionSide 1.Open Longopen_long 2.Open Shortopen_short 3.Close Longclose_long 4.Close Shortclose_short | | | | status | n | int | Status：1 Filled 2 Partial filledCancelled 3 Cancelled Order；Multiple conditions filters separated by “,” | | | | type | n | int | FuturesSide 0: Linear,1: Inverse | | | | systemType | n | string | OrderingType：10:Limit 11:Market 13:Forced Liquidation 14: Liquidation 15：Over loss 16：ADL;Multiple conditions filters separated by “,” | | | | startDate | n | int | Start Time | | | | endTime | n | int | End Time | | | | page | n | int | Page | 1 | | | pageSize | n | int | Page size | 20 | | | stopLimitType | n | int | TriggerType：0 -Stop-profit 1-Stop-loss 2-Trigger Order | | | ##### ReturnResponse
```json { "code": 0, "msg": "", "data": { "total": 0, "rows": [ { "id": 0, "contractCode": "", "base": "", "quote": "", "indexBase": "", "contractDirection": 0, "side": "", "detailSide": "", "amount": "", "dealAmount": "", "avgPrice": "", "price": "", "orderSize": "", "status": 0, "systemType": 0, "direction": "", "profit": "", "fee": "", "reason": 0, "triggerBy": "", "triggerPrice": "", "triggerDate": 0, "modifyDate": 0, "createdDate": "2022-04-18 16:07:49", "source": "", "refConditionOrderId": 0, "refOrderCondition": { "id": 0, "contractCode": "", "base": "", "quote": "", "indexBase": "", "contractDirection": 0, "type": "", "direction": "", "triggerPrice": "", "triggerBy": "", "price": "", "side": "", "detailSide": "", "amount": "", "avgPrice": "", "dealAmount": "", "orderSize": "", "dealSize": "", "status": 0, "reason": 0, "systemType": 0, "createdDate": "2022-04-18 16:07:49", "source": "", "orderPriceType": 0, "positionType": 0, "stopLimitType": 0, "refOrderId": 0, "lever": 0, "unitAmount": "", "marginDigit": 0, "marketPriceDigit": 0, "triggerDate": 0, "modifyDate": 0, "tiggerOrderDetail": { "id": 0, "price": "" } }, "stopLimitType": "", "lever": "", "orderPriceType": 0, "positionType": 0, "unitAmount": "", "marginDigit": 0, "marketPriceDigit": 0, "stopLoss": { "id": 0, "contractCode": "", "base": "", "quote": "", "indexBase": "", "contractDirection": 0, "type": "", "direction": "", "triggerPrice": "", "triggerBy": "", "price": "", "side": "", "detailSide": "", "amount": "", "avgPrice": "", "dealAmount": "", "orderSize": "", "dealSize": "", "status": 0, "reason": 0, "systemType": 0, "createdDate": "2022-04-18 16:07:49", "source": "", "orderPriceType": 0, "positionType": 0, "stopLimitType": 0, "refOrderId": 0, "lever": 0, "unitAmount": "", "marginDigit": 0, "marketPriceDigit": 0, "triggerDate": 0, "modifyDate": 0, "tiggerOrderDetail": { "id": 0, "price": "" } }, "stopProfit": { "id": 0, "contractCode": "", "base": "", "quote": "", "indexBase": "", "contractDirection": 0, "type": "", "direction": "", "triggerPrice": "", "triggerBy": "", "price": "", "side": "", "detailSide": "", "amount": "", "avgPrice": "", "dealAmount": "", "orderSize": "", "dealSize": "", "status": 0, "reason": 0, "systemType": 0, "createdDate": "2022-04-18 16:07:49", "source": "", "orderPriceType": 0, "positionType": 0, "stopLimitType": 0, "refOrderId": 0, "lever": 0, "unitAmount": "", "marginDigit": 0, "marketPriceDigit": 0, "triggerDate": 0, "modifyDate": 0, "tiggerOrderDetail": { "id": 0, "price": "" } } } ] } } ``` ###### Object-data | Name | Type | Description | Default Value | Remarks | | :------------------ | :------------- | ------------------------------------------------------------ | :------------ | :------ | | id | number | ID | | | | contractCode | string | FuturesCode | | | | base | string | Base currency name,such asbtc | | | | quote | string | Quote currency name，usd,cny,usdt | | | | indexBase | string | Indexcurrency | | | | contractDirection | number | Side 0: Linear,1: Inverse | | | | side | string | PositionSide，longLong，shortShort | | | | detailSide | string | PositionSide 1.Open Longopen_long 2.Open Shortopen_short 3.Close Longclose_long 4.Close Shortclose_short | | | | amount | string | Order Amount | | | | dealAmount | string | Filled Amount | | | | avgPrice | string | Avg. filledPrice | | | | price | string | OrderPrice | | | | orderSize | string | Ordervalue | | | | status | number | 0 Waiting to fill 1 Partial filled 2 Filled -1 Cancelled | | | | systemType | number | 10:Limit 11:Market 13:Forced Liquidation 14: Liquidation 15：Over loss 16：ADL | | | | direction | string | triggerSide，greaterGreater，lessLess | | | | profit | string | The P/L corresponding to the order after being filled: Positive means profit, negative means loss | | | | fee | string | The handling fee paid after the order is filled: Positive means fee obtained, negative means fee paid | | | | reason | number | Reasons for cancellation of this order，0isDefault Value，1 Cancelled by system，2 Cancelled by users Others-Order failed | | | | triggerBy | string | Trigger OrderType: index-IndexPricemarket/mark-MarkPricemark/last-LastPricelast | | | | triggerPrice | string | triggerPrice | | | | triggerDate | number | triggertime | | | | modifyDate | number | Last operation time | | | | createdDate | string | Creation Time | | | | source | string | Source | | | | refConditionOrderId | number | Associated conditionsOrderid | | | | refOrderCondition | OrderCondition | AssociateConditionalOrder #Object-OrderCondition | | | | stopLimitType | string | ConditionalOrderType 0 -Stop-profit 1-Stop-loss 2-Trigger Order | | | | lever | string | Leverages | | | | orderPriceType | number | 20 Optimal20/10 Optimal10/5 Optimal5/1 BBO | | | | positionType | number | HoldingType | | | | unitAmount | string | quote face value corresponding to a Futures,default1 | | | | marginDigit | number | Margin demical | | | | marketPriceDigit | number | MarkPricedemical | | | | stopLoss | object | AssociateStop-lossorder #Object-OrderCondition | | | | stopProfit | object | AssociateStop-profitorder #Object-OrderCondition | | | ###### Object-OrderCondition | Name | Type | Description | Default Value | Remarks | | :---------------- | :----- | :----------------------------------------------------------- | :------------ | :------ | | id | number | ConditionalOrderid | | | | contractCode | string | Futurescode：A combination between Base and Quote | | | | base | string | Base currency name | | | | quote | string | Quote currency name | | | | indexBase | string | Indexcurrency | | | | contractDirection | number | Side 0: Linear,1: Inverse | | | | type | string | triggerType：IndexPrice，MarkPrice，LastPrice | | | | direction | string | triggerSide，greaterGreater，lessLess | | | | triggerPrice | string | triggerPrice | | | | triggerBy | string | Trigger OrderType: index-IndexPricemarket/mark-MarkPricemark/last-LastPricelast | | | | price | string | User OrderingOrder or BankruptcyPrice | | | | side | string | PositionSide，longLong，shortShort | | | | detailSide | string | 1.Open Longopen_long 2.Open Shortopen_short 3.Close Longclose_long 4.Close Shortclose_short | | | | amount | string | Order Amount | | | | avgPrice | string | Avg. filledPrice | | | | dealAmount | string | Filled Amount | | | | orderSize | string | Ordervalue | | | | dealSize | string | Filledvalue | | | | status | number | Status 1:Triggered 0、2：Untrigger 3：Pre-ConditionalOrder -1：Cancelled | | | | reason | number | Reasons for Orderbeing cancelled 1：Cancelled by system 2：Cancelled by users 3、4、5：Failed after trigger Order Separated by comma | | | | systemType | number | 10:Limit 11:Market 13:Forced Liquidation 14: Liquidation | | | | createdDate | string | Creation Time | | | | source | string | Source | | | | orderPriceType | number | OrderingPriceType，BBO：opponent，Optimal20：optimal_20，Optimal10：optimal_10，Optimal5：optimal_5 | | | | positionType | number | PositionPattern | | | | stopLimitType | number | ConditionalType | | | | refOrderId | number | AssociateOrderid | | | | lever | number | Leverages | | | | unitAmount | string | Unit | | | | marginDigit | number | Margindecimal | | | | marketPriceDigit | number | Pricedecimal | | | | triggerDate | number | triggertime | | | | modifyDate | number | Modify time | | | | tiggerOrderDetail | object | | | | ### Order Transaction Details #### GET /api/v1/perpetual/products/{contractCode}/orderDetail #### Request Parameter： ##### Path Parameter | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ------------ | --------- | ------ | ----------- | ------------- | ----------- | | contractCode | y | string | Futurescode | | | ##### Query | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ---------------- | --------- | ------ | ---------------- | ------------- | ----------- | | AccessKeyId | y | string | Accesskey | | | | SignatureVersion | y | string | Version | | | | SignatureMethod | y | string | Signature Method | | HmacSHA256 | | Signature | y | string | Signature | | | | Timestamp | y | string | Timestamp | | | | orderId | y | number | OrderID | | | ##### Return ###### bodyResponse
```json { "code": 200, "data": { "amount": "4", "avgPrice": "342.150000", "canceledDate": 0, "contract": { "amount24": "", "base": "usdt", "code": "bchusdt", "countDownTimeInterval": "", "direction": 0, "env": 0, "fluctuation": "", "fund": "", "high": "", "indexBase": "bch", "indexPrice": "", "lastCny": "", "low": "", "makerRate": "", "marginDigit": 6, "markPrice": "", "marketPriceDigit": 6, "maxLever": 0, "minQuoteDigit": 0, "minTradeDigit": 0, "minTradeUnit": 0, "nextLiquidationInterval": 0, "openTradeTime": "", "price": "", "quote": "usdt", "size24": "", "sort": 0, "takerRate": "", "totalPosition": "", "tradeStatus": 0, "unitAmount": 0.1, "unitAmountStr": "0.1" }, "createdDate": 1649925906000, "currencyCode": "usdt", "dealAmount": "4", "dealDetails": [ { "dealAmount": "4", "dealDate": 1649925907000, "fee": "-0.088959", "markerTaker": 2 } ], "detailSide": "close_long", "fee": "-0.088959", "historyOrderFlag": true, "lever": "20", "liquidateExplosionDetail": null, "orderId": 138434463977680, "orderPriceType": 0, "orderSystemType": 11, "positionType": 1, "price": "341.686700", "profit": "-0.560000", "refConditionOrderId": 0, "refOrderId": 0, "refType": 1, "settingDate": 0, "side": "short", "status": 2, "stopLimitType": 0, "systemType": 11, "triggerDate": 0, "triggerPrice": "", "unitAmount": "0.1", "userId": 20600095 }, "msg": "success" } ``` ###### data | Name | Type | Description | Default Value | Remarks | | ------------------------ | --------- | ------------------------------------------------------------ | ------------- | ------------------------------ | | amount | string | Order Amount | | | | avgPrice | string | Average transaction price | | | | canceledDate | number | Revoke time | | | | contract | object | Futuresdetails | | ContractNavigation | | createdDate | number | Creation Time | | | | currencyCode | string | Currency | | | | dealAmount | string | Transaction Amount | | | | dealDetails | object [] | TransactionDetails | | **item Type:** OrderDealDetail | | detailSide | string | DetailPositionSide：1.Open Longopen_long 2.Open Shortopen_short 3.Close Longclose_long 4.Close Shortclose_short | | | | fee | string | Fee | | | | historyOrderFlag | boolean | HistoryOrder or not | | | | lever | string | Leverages | | | | liquidateExplosionDetail | object | Forced liquidation Details | | LiquidateExplosionDetail | | orderId | number | OrderID | | | | orderPriceType | number | OrderType | | | | positionType | number | PositionType | | | | price | string | Order价 | | | | profit | string | Yield | | | | refConditionOrderId | number | ConditionalOrderid | | | | settingDate | number | Setting time | | | | side | string | Side | | | | status | number | 1 Partial filled 2 Filled -1 Cancelled 0 NotTransaction（when the system type is not equal to 12） 0 is not trigger（when the system type is equal to 12ConditionalOrder） | | | | stopLimitType | number | ConditionalOrderType 0 -Stop-profit 1-Stop-loss 2-Trigger Order | | | | systemType | number | SystemType 10:Limit 11:Market12:ConditionalOrder 13:Forced Liquidation 14: Liquidation 15：Liquidation 16：ADL | | | | triggerDate | number | triggertime | | | | triggerPrice | string | triggerprice | | | ###### ContractNavigation | Name | Mandatory | Type | Description | Default Value | Remarks | | ----------------------- | ------- | ------ | --------------------- | --------------------- | --------------------- | | amount24 | y | string | 24H Transaction (Cont) | | | | base | y | string | Base currency name | | | | code | y | string | Futurescode | | | | contractType | y | string | FuturesType，Swap-perpetual、 Delivery-deliver 、current weekDelivery-week、next weekDelivery-nextWeek、current quarterlyDelivery-quarter、next quarterlyDelivery-nextQuarter | | | | countDownTimeInterval | y | string | Countdown interval | | | | direction | y | integer | Side 0: Linear,1: Inverse | | **format:** int32 | | env | y | integer | testing or not 0:launched,1:test | | **format:** int32 | | fluctuation | y | string | Change | | | | fund | y | string | Funding rate | | | | high | y | string | Highest price | | | | indexBase | y | string | Indexcurrency | | | | indexPrice | y | string | IndexPrice | | | | lastCny | y | string | Last price equivalent to | | | | liquidationDate | y | string | Liquidation time | | **format:** date-time | | low | y | string | Lowest price | | | | makerRate | y | string | maker exchange rate | | | | marginDigit | y | integer | margin precision | | **format:** int32 | | markPrice | y | string | MarkPrice | | | | marketPriceDigit | y | integer | MarkPrice Min.Unit（precision） | | **format:** int32 | | maxLever | y | number | Max.Leverages | | | | minQuoteDigit | y | integer | QuotecurrencyMin. transactiondemical | | **format:** int32 | | minTradeDigit | y | integer | basecurrencyMin. transactiondemical | | **format:** int32 | | minTradeUnit | y | number | Min. transactionUnit | | | | nextLiquidationInterval | y | integer | Next liquidate time gap | | **format:** int64 | | openTradeTime | y | string | Opening Time | | | | price | y | string | Lastprice | | | | quote | y | string | Quote currency name | | | | size24 | y | string | 24H Transactionvalue | | | | sort | y | integer | Sort | | **format:** int32 | | takerRate | y | string | taker Exchange Rate | | | | totalPosition | y | string | HoldingVol. | | | | tradeStatus | y | integer | PublishStatus:1*pre*-publish,2Within 7 days after the launch,3.7 days after the launch | | **format:** int32 | | unitAmount | y | number | quote face value corresponding to a Futures,default1 | | | ###### OrderDealDetail | Name | Type | Description | Default Value | Remarks | | ---------- | ------ | ------------------ | ------------- | ------- | | dealAmount | string | Transaction Amount | | | | dealDate | string | Transaction Time | | | | fee | string | Fee | | | ###### LiquidateExplosionDetail | Name | Type | Description | Default Value | Remarks | | -------------- | ------ | ------------------------ | ------------- | ------- | | contractCode | string | Futurescode | | | | explosionPrice | string | Bankruptcy price | | | | feeRate | string | Feerate | | | | lever | string | Leverages | | | | liquidatePrice | string | Forced liquidation price | | | | maintainRate | string | Maintenance margin rate | | | | price | string | OrderPrice | | | | side | string | Side | | | - Position API # Position API ### Position List #### GET /api/v1/perpetual/position/{contractCode}/list #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp||
Response
```json [ { "amount": "4867", "base": "fbtc", "closingAmount": "0", "contractCode": "fbtcusd", "lever": "100", "liqudatePrice": "3237.43", "maintenanceMargin": "0.02527905", "markPrice": "9659.25", "minQuoteDigit": 2, "minTradeDigit": 8, "openMargin": "0.14863957", "price": "9626.54", "quote": "usd", "realizedSurplus": "0.00413503", "side": "long", "size": "5.05581019", "type": 0 } ] ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- amount|y|string|Amount|| base|y|string|base currency name,example:BTC、ETH|| closingAmount|y|int|Transaction Vol.|| contractCode|y|string|Futures|| gear|y|string|Risk limit|| lever|y|string|Leverage|| liqudatePrice|y|string|Liquidation price|| maintenanceMargin|y|string|Maintenance margin|| markPrice|y|string|Mark price|| minQuoteDigit|y|string|Min. transaction decimal places of quote currency|| minTradeDigit|y|string|Min. transaction decimal places of base currency|| openMargin|y|string|Open margin|| price|y|string|Avg.price|| quote|y|string|quote currency name，USD,CNY,USDT|| realizedSurplus|y|Realized P/L||| side|y|string|PositionType，longLong，shortShort|| size|y|string|PositionValue|| type|y|string|0：Cross，1：Isolated|| ### Obtain Margin Rate and Levers of All Tiers #### GET /v1/perpetual/public/{contractCode}/lever-gears #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp||Response
```json { "code": 200, "data": [ { "entryRate": "0.008", "gear": 1, "lever": "125", "maintainRate": "0.004", "maxOpenAmount": "100" } ] "msg": "success" } ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- entryRate|y|string|Open margin rate|| gear|y|int|tiers|| lever|y|string|Leverage|| maintainRate|y|string|Maintenance margin rate|| maxOpenAmount|y|string|Max.Avail|| ### Position and Limit Settings #### GET /api/v1/perpetual/position/{contractCode}/configs #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp||Response
```json { "contractCode": "btcusdt", "feeRate": "0.00065", "fundRate": "0.00375", "indexPrice": "37591.04", "longPositionConfigDetails": { "initOpenMarginRate": "0.008", "lever": "125", "maintainRate": "0.004", "maxOpenAmount": "100", "side": "long" }, "makerFeeRate": "0.00035", "markPrice": "37704.1", "shortPositionConfigDetails": { "initOpenMarginRate": "0.008", "lever": "125", "maintainRate": "0.004", "maxOpenAmount": "100", "side": "short" }, "takerFeeRate": "0.00065", "type": 0, "unitAmount": "0.01" } ``` #### Return： **main** Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| feeRate|y|int|Handling Fee Rate|| fundRate|y|string|Fee Rate|| indexPrice|y|string|Index price|| markPrice|y|string|Mark price|| type|y|string|0：Cross，1：Isolated|| unitAmount|y|string|(Conts)：Number of quote face values for Futures (One cont)|| makerFeeRate|y|string|maker Fee Rate|| takerFeeRate|y|string|taker Fee Rate|| **|longPositionConfigDetails||shortPositionConfigDetails|Position详情** Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- lever|y|string|Leverage|| side|y|string|Side|| maxOpenAmount|y|string|Max.Avail|| lever|y|string|Leverage|| initOpenMarginRate|y|string|Initial margin rate|| ### Set-up Leverage #### POST /api/v1/perpetual/position/{contractCode}/lever #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp|| ##### Body(json) Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- type|y|int|LeverageType||Cross:0,Isolated:1 shortLever|y|int|ShortLeverage|| longLever|y|string|LongLeverage||Response
```json { "code":200, "data": { "shortLever":26, "type":1, "longLever": 10 }, "msg":"success" } ``` #### Return： Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- lever|y|string|Leverage|| ### 修改保证金 #### POST /api/v1/perpetual/position/{contract_code}/change-margin #### Request Parameter： ##### Path Parameter Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|Futurescode|| ##### Query Parameter|Mandatory|Type|Description|Default Value|Value Range ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|Accesskey|| SignatureVersion|y|string|Version|| SignatureMethod|y|string|Signature Method||HmacSHA256 Signature|y|string|Signature|| Timestamp|y|string|Timestamp|| margin|y|string|Margin amount（A positive number indicates a margin increase, a negative number indicates a margin decrease）|| side|y|string|Side||long Long short Short ##### Body(json) ```json { } ``` #### Return：Response
```json { "code": 200, "data": null, "msg": "success" } ``` | Parameter | Mandatory | Type | Description | Default Value | Value Range | | --------- | --------- | ------ | -------------------- | ------------- | ----------- | | code | y | int | Status，200：Success | | | | msg | y | string | Tips | | | | data | y | object | | | | ### 设置自动追加保证金 #### POST /api/v1/perpetual/position/{contractCode}/setting #### Request Parameter： ##### Path Parameter | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ------------ | --------- | ------ | ----------- | ------------- | ----------- | | contractCode | y | string | Futurescode | | | ##### Query | Parameter | Mandatory | Type | Description | Default Value | Value Range | | ---------------- | --------- | ------ | ----------------------------------------------------- | ------------- | ----------- | | AccessKeyId | y | string | Accesskey | | | | SignatureVersion | y | string | Version | | | | SignatureMethod | y | string | Signature Method | | HmacSHA256 | | Signature | y | string | Signature | | | | Timestamp | y | string | Timestamp | | | | value | y | string | 1 Enable Auto-margin call；0-Disable Auto-margin call | | | ##### Body(json) ```json { } ``` #### Return：Response
```json { "code": 200, "data": null, "msg": "success" } ``` | Parameter | Mandatory | Type | Description | Default Value | Value Range | | --------- | --------- | ------ | -------------------- | ------------- | ----------- | | code | y | int | Status，200：Success | | | | msg | y | string | Tips | | | | data | y | object | | | |
- 更新日志
更新日志
生效时间(UTC +8) 接口 变化 摘要 2021.9.9 - 新增 新增WebSocket行情数据推送 2021.8.19 /v1/order/matchresults 优化 新增startTimestamp,endTimestamp字段 2018.6.10 - 初始化 初始化当前版本接口 - 简介
简介
欢迎使用Hotcoin Global API。
此文档是Hotcoin API的唯一官方文档，Hotcoin API提供的功能和服务会在此文档持续更新，并会发布公告进行通知，建议您关注和订阅我们的公告，及时获取相关信息。以下是现货API文档各章节主要内容:
接入准备
如需使用API ，请先登录网页端，完成API key的申请和权限配置，再据此文档详情进行开发和交易。
权限说明如下：
- 读取权限：读取权限用于对数据的查询接口，例如：订单查询、成交查询等。
- 交易权限：交易权限用于下单、撤单、划转类接口。
- 提现权限：提现权限用于创建提现订单、取消提现订单操作。
安全认证
AccessKey为API 访问密钥，SecretKey为用户对请求进行签名的密钥。 重要提示：这两个密钥与账号安全紧密相关，无论何时都请勿向其它人透露
示例
Java Python3 Php Dart 合法请求结构
基于安全考虑，除行情API 外的 API 请求都必须进行签名运算。一个合法的请求由以下几部分组成：
-
方法请求地址,即访问服务器地址：api.hotcoinfin.com后面跟上方法名，比如api.hotcoinfin.com/v1/order/place。
-
API 访问密钥（AccessKeyId） 您申请的 APIKEY 中的AccessKey。
-
签名方法（SignatureMethod） 用户计算签名的基于哈希的协议，此处使用 HmacSHA256。
-
签名版本（SignatureVersion） 签名协议的版本，此处使用2。
-
时间戳（Timestamp） 您发出请求的时间 (UTC 时区)。在查询请求中包含此值有助于防止第三方截取您的请求。如：2017-05-11T16:22:06.123Z。再次强调是 (UTC 时区) 调用的必需参数和可选参数。可以在每个方法的说明中查看这些参数及其含义。
-
签名计算得出的值，用于确保签名有效和未被篡改。
https://api.hotcoinfin.com/v1/order/place?
AccessKeyId=AccessKeyHotcoin123456789
&symbol=btc_usdt
&type=buy
&tradePrice=40000
&tradeAmount=0.1
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z
&Signature=calculated value签名运算
API 请求在通过 Internet 发送的过程中极有可能被篡改。为了确保请求未被更改，我们会要求用户在每个请求中带上签名，来校验参数或参数值在传输途中是否发生了更改。
计算签名所需的步骤： 规范要计算签名的请求 因为使用 HMAC 进行签名计算时，使用不同内容计算得到的结果会完全不同。所以在进行签名计算前，请先对请求进行规范化处理。下面以下单请求为例进行说明
https://api.hotcoinfin.com/v1/order/place?
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z
&symbol=btc_usdt
&type=buy
&tradePrice=40000
&tradeAmount=0.1请求方法（GET 或 POST），后面添加换行符\n。
GET\n
添加小写的访问地址，后面添加换行符\n。
api.hotcoinfin.com\n
访问方法的路径，后面添加换行符\n。
/v1/order/place\n
按照ASCII码的顺序对参数名进行排序(使用 UTF-8 编码，且进行了 URI 编码，十六进制字符必须大写，如‘:’会被编码为’%3A’，空格被编码为’%20’)。
例如，下面是请求参数的原始顺序，进行过编码后。
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z
&symbol=btc_usdt
&type=buy
&tradePrice=40000
&tradeAmount=0.1这些参数会被排序为：
AccessKeyId=AccessKeyHotcoin123456789
SignatureMethod=HmacSHA256
SignatureVersion=2
Timestamp=2017-05-11T16%3A22%3A06.123Z&
symbol=btc_usdt
tradeAmount=0.01
tradePrice=40000
type=buy按照以上顺序，将各参数使用字符’&’连接。
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&symbol=btc_usdt
&tradeAmount=0.1
&tradePrice=40000
&type=buy组成最终的要进行签名计算的字符串如下：
GET\n
api.hotcoinfin.com\n
/v1/order/place\n
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&symbol=btc_usdt
&tradeAmount=0.1
&tradePrice=40000
&type=buy计算签名，将以下两个参数传入加密哈希函数：
要进行签名计算的字符串
GET\n
api.hotcoinfin.com\n
/v1/order/place\n
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&symbol=btc_usdt
&tradeAmount=0.1
&tradePrice=40000
&type=buy进行签名的密钥（SecretKey）
SecretKeyHotcoin123456789
得到签名计算结果并进行 Base64编码
2oEC+yhkHTsNkgPUq4ZB/5mlY7EZAtUDWOQ5EO01D+I=
将上述值作为参数Signature的取值添加到 API 请求中。 将此参数添加到请求时，必须将该值进行 URI 编码。
symbol 规则： 基础币种+计价币种。如BTC/USDT，symbol为btc_usdt；ETH/BTC， symbol为eth_btc。以此类推。
最终，发送到服务器的 API 请求应该为：
https://api.hotcoinfin.com/v1/order/place
?AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&symbol=btc_usdt
&tradeAmount=0.1
&tradePrice=40000&type=buy
&Signature=2oEC%2ByhkHTsNkgPUq4ZB%2F5mlY7EZAtUDWOQ5EO01D%2BI%3D - 基础信息
基础信息
获取所有交易对
签名认证：否
限频值：10次/shttps://api.hotcoinfin.com/v1/common/symbols curl "https://api.hotcoinfin.com/v1/common/symbols"- GET /v1/common/symbols
请求参数:
此接口不接受任何参数。 响应数据:参数名称 是否必须 类型 描述 默认值 取值范围 code y int 状态码 成功：200 msg y string 消息 time y long 当前毫秒数 data y array symbols列表 data:
Response
{ "code": "200", "time": 1567045034, "data": [ {"baseCurrency":"etc", "quoteCurrency":"usdt", "pricePrecision":6, "amountPrecision":4, "symbolPartition":"main", "symbol":"etc_usdt", "state":"online", "minOrderCount":0.001, "maxOrderCount":10000, "minOrderPrice":0.0001, "maxOrderPrice":10000 }, { "baseCurrency":"ltc", "quoteCurrency":"usdt", "pricePrecision":6, "amountPrecision":4, "symbolPartition":"innovation", "symbol":"ltc_usdt", "state":"online", "minOrderCount":0.001, "maxOrderCount":10000, "minOrderPrice":0.0001, "maxOrderPrice":10000 } ] }字段类型 数据类型 描述 description（英文） baseCurrency string 交易中的基础币种 baseCurrency code quoteCurrency string 交易中的报价币种 quoteCurrency code pricePrecision integer 交易对报价的精度（小数点后位数） price precision amountPrecision integer 交易对基础币种计数精度（小数点) quantity precision symbolPartition string 交易区，可能值: [main,innovation] symbol Partition, example:[main,innovation] symbol string 交易对 trade pair code state string 交易对状态 enable - 正常；disable-禁用 trade pair status [enable,disable] minOrderCount decimal 交易对最小下单量 (下单量指当订单类型为限价单时，下单接口传的’tradeAmount’) min order count maxOrderCount decimal 交易对最大下单量 (下单量指当订单类型为限价单时，下单接口传的’tradeAmount’) max order count minOrderPrice decimal 最小下单价格（下单金额指当订单类型为限价单时，下单接口传入的‘price’） min order price maxOrderPrice decimal 最大下单价格（下单金额指当订单类型为限价单时，下单接口传入的‘price’） max order price - 行情数据 # 行情数据 ### 实时ticker数据 签名认证：否 限频值：10次/s - GET /v1/market/ticker ```json https://api.hotcoinfin.com/v1/market/ticker curl "https://api.hotcoinfin.com/v1/market/ticker" ``` **响应数据:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- status|y|string|状态码||成功：ok，失败：error timestamp|y|long|当前毫秒数|| ticker|y|list|数据||
Response
```json { "status":"ok", "timestamp":1567045034, "ticker":[ { "symbol":"btc_usdt", "last":"10000.00000000", "buy":"9999.00000000", "sell":"10001.00000000", "high":"11000.00000000", "low":"9000.00000000", "vol":"10000000.0000", "change":"10.10" } ] } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|string|交易对symbol||卖币种简称_买币种简称简称，eg：btc_usdt last|y|number|最新价|| buy|y|number|买一价|| sell|y|number|卖一价|| high|y|number|24小时最高价 || low|y|number|24小时最低价|| vol|y|number|24小时成交量|| change|y|number|24小时涨跌幅|| ### 获取k线数据 签名认证：否 限频值：20次/s - GET /v1/ticker ```json https://api.hotcoinfin.com/v1/ticker?symbol=btc_usdt&step=60 curl "https://api.hotcoinfin.com/v1/ticker?symbol=btc_usdt&step=60" ``` **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- step|y|int|时间：秒||60（1分钟）,300（5分钟）,900（15分钟）,1800（30分钟）,3600（1小时）,86400（1天）,604800（1周）,2592000（1月） symbol|y|string|交易对||例：btc_usdt **响应数据:**Response
```json { "code":200, "msg":"成功", "time":1527838104874, "data":[ [ 1527820200000, 54598.5, 54598.5, 54598.5, 54598.5, 0 ], [ 1527820200000, 54598.5, 54598.5, 54598.5, 54598.5, 0 ] ] } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码 msg|n|string|返回消息 time|y|long|当前毫秒数 data|y|array(array(number))|K线数据 **data:**
[[
1527820200000, //int 时间
54598.5, //number 开
54598.5, //number 高
54598.5, //number 低
54598.5, //number 收
0.0000 //number 量
],
......
]
### 获取深度数据 签名认证：否 限频值：20次/s - GET /v1/depth ```json https://api.hotcoinfin.com/v1/depth?symbol=btc_usdt&step=60 curl "https://api.hotcoinfin.com/v1/depth?symbol=btc_usdt&step=60" ``` **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|string|交易对||例：btc_usdt step|n|int|加上此参数可查最新一个k线数据，类型为时间，单位秒||60,3*60,5*60,15*60,30*60,60*60（1小时）,24*60*60（1天）,7*24*60*60（1周）,30*24*60*60（1月） **响应数据:**Response
```json { "code":200, "msg":"成功", "time":1527837164605, "data":{ "period":{ "data":[ [ 1527837120000, 54598.5, 54598.5, 54598.5, 54598.5, 0 ] ], "marketFrom":"btc_usdt", "type":60, "coinVol":"btc_usdt" }, "depth":{ "date":1527837163, "asks":[ [ 57373.8, 0.0387 ], [ 57751.26, 0.0128 ], [ 57751.26, 0.0128 ] ], "bids":[ [ 57373.8, 0.0387 ], [ 57751.26, 0.0128 ], [ 57751.26, 0.0128 ] ], "lastPrice":54598.5 } } } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码 msg|n|string|返回消息 time|y|long|当前毫秒数 data|y|object|交易深度数据 **data:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- depth|y|object period|n|object|传step时才有值 **depth:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- bids|y|array(array(long))|买盘,[price(成交价), amount(成交量)] asks|y|array(array(long))|卖盘,[price(成交价), amount(成交量)] date|y|long|时间戳 lastPrice|y|number|最新成交价 **period:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- marketFrom|y|string|入参symbol coinVol|y|string|入参symbol type|y|long|入参step,时间 data|y|array（array）|最后一个k线数据，格式同上，但只有一个 ### 获取实时成交数据 签名认证：否 限频值：20次/s - GET /v1/trade ```json https://api.hotcoinfin.com/v1/trade?symbol=btc_usdt&count=60 curl "https://api.hotcoinfin.com/v1/trade?symbol=btc_usdt&count=60" ``` **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- count|y|int|Trades条数||0 symbol|y|string|交易对||例：btc_usdt **响应数据:**Response
```json { "code":200, "msg":"成功", "time":1536315868962, "data":{ "sellSymbol":"BTC", "buySymbol":"USDT", "trades":[ { "price":0.007, "amount":66491.04, "id":1, "time":"02:45:08", "en_type":"ask", "type":"卖出" }, { "price":0.007, "amount":66491.04, "id":1, "time":"02:45:08", "en_type":"ask", "type":"卖出" } ] } } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码 msg|n|string|返回消息 time|y|long|当前毫秒数 data|y|object|实时成交数据 **data:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- trades|y|array(object)|trades数据 sellSymbol|y|string|sellSymbol buySymbol|y|string|buySymbol **trades:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- price|y|long|成交价钱 amount|y|string|成交数量 id|y|string|成交id time|y|string|成交时间 en_type|y|string|成交方向||"bid"(买入),"ask"(卖出) type|y|string|成交类型||"买入","卖出" - 账户相关
账户相关
获取用户余额
签名认证：是
限频值：10次/s- GET /v1/balance
https://api.hotcoinfin.com/v1/balance?AccessKeyId="" curl "https://api.hotcoinfin.com/v1/balance?AccessKeyId=''"请求参数:
参数名称 是否必须 类型 描述 默认值 取值范围 AccessKeyId y string 访问key 响应数据:
Response
{ "code": 200, "msg": "成功", "time": 1527835756743, "data": { "netassets": 0, "wallet": [ { "uid":1100011, "coinId":1, "symbol":"BTC", "total":1000.0000000000, "frozen":1000.0000000000, "coinName":"比特币", "shortName":"BTC" }, { "uid":1100011, "coinId":2, "symbol":"LTC", "total":1000.0000000000, "frozen":1000.0000000000, "coinName":"莱特币", "shortName":"LTC" }, { "uid":1100011, "coinId":4, "symbol":"ETH", "total":1000.0000000000, "frozen":0E-10, "coinName":"以太坊", "shortName":"ETH" } ], "totalassets": 0 } }参数名称 是否必须 类型 描述 默认值 取值范围 code y int 状态码 msg n string 返回消息 time y long 当前毫秒数 data y object 交易深度数据 data:
参数名称 是否必须 类型 描述 默认值 取值范围 netassets y number 净资产，单位为usdt totalassets y number 总资产，单位为usdt wallet y array(object) 钱包列表 wallet:
参数名称 是否必须 类型 描述 默认值 取值范围 coinName y long 币种名称 uid y int 用户ID coinId y int 币种ID total y number 可用 frozen y number 冻结 symbol y string 币种symbol shortName y string 币种简称 - 现货/杠杆交易 # 现货/杠杆交易 ### 下单 签名认证：是 限频值：10次/s - POST /v1/order/place **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|string|交易对| |例：btc_usdt type|y|string|类型| | "buy" ,”sell" tradeAmount|y|number|数量|| tradePrice|n|number |价格(仅当限价单时传入)|| matchType|n|integer |撮合类型|0|0-限价单 1-市价单 marketUnit|n|string |市价单下单单位(市价下单时必须，数量或金额为tradeAmount)||amount-数量 funds-金额 **响应数据:**
Response
```json { "code":200, "msg":"委托成功", "time":1536306331399, "data":{ "ID":18194813 } } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码||成功：200，失败：300 msg|y|string|消息|| time|y|long|当前毫秒数|| data|y|object|数据|| **msg 范围** 中文 | English | ------------ | ------------ 非法请求 |Illegal request 请使用正确的数量| Illegal tradeAmount value 请使用正确的价格| Illegal tradePrice value 币种ID错误| Illegal symbol format **data:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- ID|y|bigint|订单id|| ### 订单取消 注：撤销订单请求为异步报单模式，需要调用/v1/order/detailById接口查询订单状态进行确认。 签名认证：是 限频值：10次/s - POST /v1/order/cancel **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|bigint |委单id | | **响应数据:**Response
```json { "code": 200, "msg": "取消成功", "time": 1536306495984, "data": null } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码||成功：200，失败：300 msg|y|string|消息|| time|y|long|当前毫秒数|| ### 委单详情 签名认证：是 限频值：10次/s - GET /v1/order/detailById ```json https://api.hotcoinfin.com/v1/order/detailById curl "https://api.hotcoinfin.com/v1/order/detailById" ``` **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|bigint |委单id | | leverAcctid |n|string |非杠杆下单无需传词字段，杠杆子账户id，对应开户接口的clientId| | **响应数据:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码|| msg|n|string|消息|| time|y|long|当前毫秒数|| data|y|object|委单详情|| **data:**Response
```json { "code": 200, "msg": "成功", "time": 1536306896294, "data": { "types": "买单", "leftcount": 0.01, "fees": 0, "last": 0, "count": 0.01, "successamount": 0, "source": "API", "type": 0, "price": 40000, "buysymbol": "", "id": 18194814, "time": "2018-09-07 15:48:44", "sellsymbol": "", "statusCode":1, "status": "未成交" } } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- types|y|string|委单类型| |买单 、卖单 leftcount|y|number|未成交|| fees|y|number|手续费|| last|y|number|当前委单最新成交价|| count|y|number|数量|| successamount|y|number|已成交总价 || source|y|string|来源 | |API、WEB、APP type|y|int|类型代码| |0（买单），1（卖单） price|y|number|价钱 || buysymbol|n|string|买符号|| sellsymbol|n|string|卖符号|| time|y|string|创建时间|| statusCode|y|int|状态码| |1 未成交 2 部分成交 3 完全成交 4 撤单处理中 5 已撤销 status|y|int|状态| |未成交、部分成交、完全成交、撤单处理中、已撤销 ### 成交详情 签名认证：是 限频值：10次/s - GET /v1/order/counterpartiesById ```json https://api.hotcoinfin.com/v1/order/counterpartiesById curl "https://api.hotcoinfin.com/v1/order/counterpartiesById" ``` **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|bigint |委单id | | **响应数据:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码|| msg|n|string|消息|| time|y|long|当前毫秒数|| data|y|object|委单详情|| **data:**Response
```json { "code":200, "data":{ "entrusts":[ { "amount":1.2042000000, "count":2.2300000000, "createTime":"2019-05-27 18:15:12", "entrustId":431879850, "entrustType":0, "id":101192723, "isSelfTrade":1, "matchId":431879852, "prize":0.5400000000, "sysmbol":"btc_usdt" } ] }, "msg":"成功", "time":1568690580787 } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- entrusts|y|array(object)|对手单列表|| **wallet:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|bigint|主键ID|| isSelfTrade|y|int|是否自成交 0 否 1 是|| sysmbol|y|string|交易对|| entrustType|y|int|委单类型 0 买单 1 卖单|| entrustId|y|bigint|委单ID|| matchId|y|bigint|成交ID|| amount|y|number|成交总价|| prize|y|number|价格|| count|y|number|数量|| createTime|y|string|创建时间|| ### 获取委单列表 签名认证：是 限频值：10次/s - GET /v1/order/entrust ```json https://api.hotcoinfin.com/v1/order/entrust curl "https://api.hotcoinfin.com/v1/order/entrust" ``` **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|string |交易对| |例：btc_usdt type|n|int|类型|0|0表示全部 1表示当前 2表示历史 page|n|int|页码|1| count|y|int|条数|7|[1-100] 最大100条 **响应数据:**Response
```json { "code": 200, "msg": "获取成功！", "time": 1527841588334, "data":{ "entrutsHis": [ { "types": "买单", "leftcount": 1.0E-4, "fees": 0, "last": 0, "count": 1.0E-4, "successamount": 0, "source": "WEB", "type": 1, "price": 1.0E7, "buysymbol": "USDT", "id": 947644, "time": "2018-06-27 17:45:14", "sellsymbol": "BTC", "status": "已撤销" }, { "types": "买单", "leftcount": 1.0E-4, "fees": 0, "last": 0, "count": 1.0E-4, "successamount": 0, "source": "WEB", "type": 1, "price": 1.0E7, "buysymbol": "USDT", "id": 947645, "time": "2018-06-27 17:45:14", "sellsymbol": "BTC", "status": "已撤销" } ], "entrutsCur": [ { "types": "买单", "leftcount": 0.01, "fees": 0, "last": 0, "count": 0.01, "successamount": 0, "source": "API", "type": 0, "price": 40000, "buysymbol": "USDT", "id": 18194814, "time": "2018-09-07 15:48:44", "sellsymbol": "BTC", "status": "未成交" }, { "types": "卖单", "leftcount": 0.01, "fees": 0, "last": 0, "count": 0.01, "successamount": 0, "source": "API", "type": 0, "price": 40000, "buysymbol": "USDT", "id": 18194814, "time": "2018-09-07 15:48:44", "sellsymbol": "BTC", "status": "未成交" } ] } } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码|| msg|n|string|消息|| time|y|long|当前毫秒数|| data|y|object|委单详情|| **data:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- entrutsCur|n|array(object)|当前委单|| entrutsHis|n|array(object)|历史委单|| **entrutsCur 及 entrutsHis类型相同:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|bigint|委单id time|y|string|下单时间 types|y|string|委单类型|| 买单、卖单 source|y|string|委单来源||"WEB"，"APP"，"API" price|y|number|下单价格 count|y|number|下单数量 leftcount|y|number|未成交数量 last|y|number|成交价格 successamount|y|number|成交总价 fees|y|number|手续费 status|y|string|委单状态||未成交、部分成交、完全成交、撤单处理中、已撤销 type|y|int|委单类型|| 0( "买单"),1( "卖单") buysymbol|y|string|币种类型符号 sellsymbol|y|string|币种类型符号 ### 当前和历史成交记录 签名认证：是 限频值：10次/s - GET /v1/order/matchresults ```json https://api.hotcoinfin.com/v1/order/matchresults curl "https://api.hotcoinfin.com/v1/order/matchresults" ``` **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|string|交易对||例：btc_usdt types|n|string|查询的订单类型组合，使用','分割||0：买, 1：卖 startDate|n|string|查询开始日期, 日期格式yyyy-mm-dd|-1d 查询结束日期的前1天|取值范围 [((endDate) – 1), (endDate)] ，查询窗口最大为2天，窗口平移范围为最近61天 endDate|n|string|查询结束日期, 日期格式yyyy-mm-dd|today|取值范围 [(today-60), today] ，查询窗口最大为2天，窗口平移范围为最近61天 startTimestamp|n|Long|查询开始时间，Unix时间戳, 单位毫秒。替代startDate，支持按毫秒查询，无时区问题，建议使用|按时间戳查询时必填|取值范围 [((endTimestamp) – 1), (endTimestamp)] ，查询窗口最大为2天，窗口平移范围为最近61天 endTimestamp|n|Long|查询结束时间，Unix时间戳, 单位毫秒。替代endDate，支持按毫秒查询，无时区问题，建议使用|按时间戳查询时必填|取值范围 [(today-60), today] ，查询窗口最大为2天，窗口平移范围为最近61天 from|n|string|查询起始 ID|订单成交记录ID（最大值）| direct|n|string|查询方向|默认 next， 成交记录 ID 由大到小排序|prev 向前，时间（或 ID）正序；next 向后，时间（或 ID）倒序） size|n|string| 查询记录大小|100|[1，100] **响应数据:**Response
```json { "code":200, "data":{ "entrustdetail":[ { "createdAt":1623134000577, "filledAmount":"1.20", "filledFees":"2.2300", "id":43187, "matchId":123456, "orderId":431879852, "type":"1", "price":"0.5400000000", "role":"taker" } ] }, "msg":"成功", "time":1568690580787 } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码 msg|n|string|返回消息 time|y|long|当前毫秒数 data|y|object|实时成交数据 **data:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- entrustdetail|n|array(object)|成交记录 **entrustdetail:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- createdAt|y|long|成交时间 filledAmount|y|string|成交数量 filledFees|y|string|成交手续费 id|y|long|订单成交记录id matchId|y|long|撮合id orderId|y|long|订单id price|y|string|成交价格 type|y|string|订单类型||0：买, 1：卖 role|y|string|成交角色||taker,maker ### 批量撤单 签名认证：是 限频值：10次/s - POST /v1/order/batchCancelOrders `注意：此接口只提交取消请求，实际取消结果需要通过订单状态，撮合状态等接口来确认。` **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- orderIds|y|String|撤销订单ID列表||单次不超过100个订单id 例如 "2232,1232,2321" **响应数据:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码 msg|n|string|返回消息 data|y|object| ### 批量撤单(OpenOrders) 签名认证：是 限频值：10次/s - POST /v1/order/batchCancelOpenOrders `注意：此接口只提交取消请求，实际取消结果需要通过订单状态，撮合状态等接口来确认。` **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- symbol|y|String|交易代码列表（最多10 个symbols，多个交易代码间以逗号分隔），btc_usdt, eth_btc...（|| side|n|String|交易方向||buy -买方向 sell -卖方向 为空时，则获取所有方向的委单进行撤销。 **响应数据:**Response
```json { "code":200, "data":{ "successCount": 1, "failCount": 1 }, "msg":"成功" } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码 msg|n|string|返回消息 data|y|object| **data:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- {successCount|y|int|成功撤销数量 failCount}|y|int|撤销失败数量 ### 批量下单 API Key 权限：交易，一个批量最多10张订单 签名认证：是 限频值：10次/s - POST /v1/order/batchOrders **请求参数:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- orders|y|object|订单列表|| **orders:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- [{symbol|y|string|交易对||例：btc_usdt type|y|string|类型||"buy" ,”sell" tradeAmount|y|number|数量|| tradePrice|y|number|价格(仅当限价单时传入)|| matchType|n|integer |撮合类型|0|0-限价单 1-市价单 marketUnit}]|n|string |市价单下单单位(市价下单时必须，数量或金额为tradeAmount)||amount-数量 funds-金额 **响应数据:**Response
```json { "code": 200, "msg": "成功", "time": 1527841588334, "data":{ "list": [ { "ID":123456, "errcode": "", "errmsg": "" }, { "ID":1234567, "errcode": "", "errmsg": "" } ] } } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态码 msg|n|string|返回消息 data|y|object| **data:** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- [{ID|y|bigint|订单id|| errcode|n|string|返回错误码 errmsg}]|n|string|返回错误描述 - WebSocket行情数据 # WebSocket行情数据 ### 接入说明 #### WebSocket域名 ##### wss://wss.hotcoinfin.com/trade/multiple #### 数据压缩 WebSocket行情接口返回的所有数据进行了GZIP压缩，客户端在收到数据之后需要解压。 #### 心跳消息 当用户的Websocket客户端连接到热币服务器后，热币服务器会定期（当前设为5秒）向其发送ping消息，如下： ```{"ping": "ping"}``` 当用户的Websocket客户端接收到此心跳消息后，应返回pong消息，如下： ```{"pong": "pong"}``` #### 订阅主题 成功建立与Websocket服务器的连接后，Websocket客户端发送请求以订阅特定主题： ```{"sub": "topic to subscribe"}``` 比如：```{"sub": "market.btc_usdt.trade.depth"}``` 成功订阅后，Websocket客户端将收到确认消息：
Response
```json { "ch": "market.btc_usdt.trade.depth", "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1632878832006 } ``` 之后, 一旦所订阅的主题有数据更新，热币服务器将向Websocket客户端推送更新消息。 #### 取消订阅 取消订阅的格式如下：```{"unsub": "topic to unsubscribe"}``` 取消订阅成功确认。 ### K线数据 请求数据：```{"sub":"market.$symbol$.kline.$period$"}``` 取消订阅：```{"unsub":"market.$symbol$.kline.$period$"}``` > **参数说明** | 参数 | 数据类型 | 是否必须 | 描述 | 备注 | | ------ | -------- | -------- | -------- | ----------------------------- | | symbol | String | 是 | 交易代码 | btc_usdt | | period | String | 是 | k线周期 | 1m,5m,15m,30m,1h,2h,4h,6h,12h,1d,3d,5d,1w,1mo | * 订阅成功或者取消订阅后，服务器返回数据:Response
```json { "ch": "market.btc_usdt.kline.1m", "code": 200, "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1489474081631 } ``` 返回字段说明: ###### [时间,开盘价,最高价,最低价,收盘价,成交量] ###### [ts, open, high, low, close, vol] | 参数 | 数据类型 | 是否必填 | 描述 | 备注 | | ----- | -------- | -------- | ------ | --------------------------------------- | | ts | String | 是 | 时间 | 时间有效范围[1501174800000, 2556115200000] | | open | String | 是 | 开盘价 | 995.37 | | high | String | 是 | 最高价 | 996.75 | | low | String | 是 | 最低价 | 995.36 | | close | String | 是 | 收盘价 | 996.75 | | vol | String | 是 | 交易量 | 9.112 | ### 市场深度数据 请求数据：```{"sub":"market.$symbol$.trade.depth"}``` 取消订阅：```{"unsub":"market.$symbol$.trade.depth"}``` > **参数说明** | 参数 | 数据类型 | 是否必须 | 描述 | 备注 | | ------ | -------- | -------- | -------- | -------- | | symbol | String | 是 | 交易代码 | btc_usdt | * 订阅成功或者取消订阅后，服务器返回数据:Response
```json { "ch": "market.btc_usdt.trade.depth", "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1489474081631 } ``` 返回字段说明: | 参数 | 数据类型 | 是否必填 | 描述 | 默认值 | | ----------------- | --------------- | -------- | ---------------------------- | --------------------- | | bids | [String,String] | 是 | 【买方价格,买方深度量】 | ["9999.39","0.0098"] | | asks | [String,String] | 是 | 【卖方价格,卖方深度度量】 | ["10010.98","0.0099"] | | last | String | 是 | 最新价 | 0 | | open | String | 是 | 开盘价 | 0 | | cny | String | 是 | 折合人民币价格 | 0 | | netValue | String | 是 | ETF净值 | 0 | | buyOrSellCnyPrice | String | 是 | 买入或者卖出人民币估值时使用 | 0 | ### 买一卖一逐笔行情 请求数据： ```{"sub":"market.$symbol$.trade.bbo"}``` 取消订阅：```{"unsub":"market.$symbol$.trade.bbo"}``` > **参数说明** | 参数 | 数据类型 | 是否必须 | 描述 | 备注 | | ------ | -------- | -------- | -------- | -------- | | symbol | String | 是 | 交易代码 | btc_usdt | * 订阅成功或者取消订阅后，服务器返回数据:Response
```json { "ch": "market.btc_usdt.trade.bbo", "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1489474081631 } ``` 返回字段说明: | 参数 | 数据类型 | 是否必填 | 描述 | 默认值 | | ----------------- | --------------- | -------- | ---------------------------- | --------------------- | | symbol | String | 是 | 交易代码 | btc_usdt | | bid | String | 是 | 买一价 | 0 | | bidSize | String | 是 | 买一量 | 0 | | ask | String | 是 | 卖一价 | 0 | | askSize | String | 是 | 卖一量 | 0 | | last | String | 是 | 最新价 | 0 | ### 24H聚合行情数据 请求数据：```{"sub":"market.$symbol$.24h.tickers"}``` 取消订阅：```{"unsub":"market.$symbol$.24h.tickers"}``` > **参数说明** | 参数 | 数据类型 | 是否必须 | 描述 | 备注 | | ------ | -------- | -------- | -------- | -------- | | symbol | String | 是 | 交易代码 | btc_usdt | * 订阅成功或者取消订阅后，服务器返回数据:Response
```json { "ch": "market.btc_usdt.24h.tickers", "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1489474081631 } ``` 返回字段说明: | 参数 | 数据类型 | 是否必填 | 描述 | 备注 | | ------------- | -------- | -------- | ------------------------ | ---- | | sellShortName | String | 是 | 卖方币种简称:BTC | | | sellSymbol | String | 是 | 卖方币种全称:bitcoin | | | buyShortName | String | 是 | 买方币种简称:ETH | | | buySymbol | String | 是 | 买方币种全称:ethereum | | | high | String | 是 | 最高价 | | | open | String | 是 | 开盘价 | | | low | String | 是 | 最低价 | | | close | String | 是 | 收盘价 | | | volume | String | 是 | 交易量 | | | change | String | 是 | 涨跌幅 | | | cny | String | 是 | 折合人民币的最新价 | | | tradeId | Integer | 是 | 交易代码ID | | | last | String | 是 | 最新价(原始价格) | | | imageUrl | String | 是 | | | | netValue | String | 否 | ETF净值 | | ### 实时成交明细 请求数据：```{"sub":"market.$symbol$.trade.detail"}``` 取消订阅：```{"unsub":"market.$symbol$.trade.detail"}``` > **参数说明** | 参数 | 数据类型 | 是否必须 | 描述 | 备注 | | ------ | -------- | -------- | -------- | -------- | | symbol | String | 是 | 交易代码 | btc_usdt | * 订阅成功或者取消订阅后，服务器返回数据:Response
```json { "ch": "market.btc_usdt.trade.detail", "code": 200, "msg": "SUCCESS", "status": "ok", "ts": 1489474081631 } ``` 返回字段说明: | 参数 | 数据类型 | 是否必填 | 默认值 | 描述 | 备注 | | --------- | -------- | -------- | ------------------------- | ------------------------------------------ | ---- | | amount | String | 是 | 成交量 | 0.0099 | | | ts | String | 是 | 成交时间 | 有效时间范围[1501174800000, 2556115200000] | | | tradeId | Integer | 是 | 交易代码ID | 交易代码ID | | | price | String | 是 | 成交价格 | 401.74 | | | direction | String | 是 | 买单【buy】或卖单【sell】 | [buy/sell] | |
- 更新日志
更新日志
生效时间(UTC +8) 接口 变化 摘要 2022.02.21 - 新增 新增永续api接口文档 2022.05.26 - 新增 新增行情/订单/持仓相关接口 - 简介
简介
API文档
接入准备
如需使用API ，请先登录网页端，完成API key的申请和权限配置，再据此文档详情进行开发和交易。
权限说明如下：
- 读取权限：读取权限用于对数据的查询接口，例如：订单查询、成交查询等。
- 交易权限：交易权限用于下单、撤单、划转类接口。
- 提币权限：提币权限用于创建提币订单、取消提币订单操作。
安全认证
AccessKey为API 访问密钥，SecretKey为用户对请求进行签名的密钥。 重要提示：这两个密钥与账号安全紧密相关，无论何时都请勿向其它人透露
合法请求结构
基于安全考虑，除行情API 外的 API 请求都必须进行签名运算。一个合法的请求由以下几部分组成：
-
方法请求地址,即访问服务器地址：api-ct.hotcoin.fit后面跟上方法名，比如api-ct.hotcoin.fit/api/v1/perpetual/account/assets/btcusdt。
-
API 访问密钥（AccessKeyId） 您申请的 APIKEY 中的AccessKey。
-
签名方法（SignatureMethod） 用户计算签名的基于哈希的协议，此处使用 HmacSHA256。
-
签名版本（SignatureVersion） 签名协议的版本，此处使用2。
-
时间戳（Timestamp） 您发出请求的时间 (UTC 时区)。在查询请求中包含此值有助于防止第三方截取您的请求。如：2017-05-11T16:22:06.123Z。再次强调是 (UTC 时区) 调用的必需参数和可选参数。可以在每个方法的说明中查看这些参数及其含义。
-
签名计算得出的值，用于确保签名有效和未被篡改。
https://api-ct.hotcoin.fit/api/v1/perpetual/account/assets/btcusdt?
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z
&Signature=calculated value签名运算
API 请求在通过 Internet 发送的过程中极有可能被篡改。为了确保请求未被更改，我们会要求用户在每个请求中带上签名，来校验参数或参数值在传输途中是否发生了更改。
计算签名所需的步骤： 规范要计算签名的请求 因为使用 HMAC 进行签名计算时，使用不同内容计算得到的结果会完全不同。所以在进行签名计算前，请先对请求进行规范化处理。下面以下单请求为例进行说明
https://api-ct.hotcoin.fit/api/v1/perpetual/account/assets/btcusdt?
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z请求方法（GET 或 POST 或 DELETE），后面添加换行符\n。
GET\n
添加小写的固定的字符串，后面添加换行符\n。
api.hotcoin.top\n
访问方法的路径，后面添加换行符\n。
/api/v1/perpetual/account/assets/btcusdt\n
按照ASCII码的顺序对参数名进行排序(使用 UTF-8 编码，且进行了 URI 编码，十六进制字符必须大写，如‘:’会被编码为’%3A’，空格被编码为’%20’)。
例如，下面是请求参数的原始顺序，进行过编码后。
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16:22:06.123Z这些参数会被排序为：
AccessKeyId=AccessKeyHotcoin123456789
SignatureMethod=HmacSHA256
SignatureVersion=2
Timestamp=2017-05-11T16%3A22%3A06.123Z&按照以上顺序，将各参数使用字符’&’连接。
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z组成最终的要进行签名计算的字符串如下：
GET\n
api.hotcoin.top\n
/api/v1/perpetual/account/assets/btcusdt\n
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z计算签名，将以下两个参数传入加密哈希函数：
要进行签名计算的字符串
GET\n
api.hotcoin.top\n
/api/v1/perpetual/account/assets/btcusdt\n
AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z进行签名的密钥（SecretKey）
SecretKeyHotcoin123456789
得到签名计算结果并进行 Base64编码
ND/9e/TW6pqNSeDKkBYnXHaKye7Wfivu2Vk3EYRl2W8=
将上述值作为参数Signature的取值添加到 API 请求中。 将此参数添加到请求时，必须将该值进行 URI 编码。
最终，发送到服务器的 API 请求应该为：
https://api-ct.hotcoin.fit/api/v1/perpetual/account/assets/btcusdt
?AccessKeyId=AccessKeyHotcoin123456789
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T16%3A22%3A06.123Z
&Signature=ND/9e/TW6pqNSeDKkBYnXHaKye7Wfivu2Vk3EYRl2W8= - 行情接口 # 行情接口 ### 可用合约列表 #### GET /api/v1/perpetual/public #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态，200：成功|| msg|y|string|提示|| data|y|object|合约信息||
Response
```json { "code": 200, "msg": "success", "data": [ { "amount24": "3848", "base": "btc", "code": "btcusd", "direction": 1, "env": 1, "fluctuation": "-10.04", "fund": "0.00375", "high": "9100", "indexPrice": "7913.84", "low": "8100", "markPrice": "7918.29", "maxLever": 100, "minQuoteDigit": 2, "minTradeDigit": 8, "price": "8100", "quote": "usd", "size24": "4.39717319", "totalPosition": "1830", "unitAmount": 10 } ], } ``` ##### 合约信息返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|string|合约code|| base|y|string|基础货币名,如btc、usdt|| quote|y|string|计价货币名，usd,usdt|| direction|y|string|方向 0:正向合约,1:反向合约|| minTradeDigit|y|string|基础货币最小交易小数位|| minQuoteDigit|y|string|计价货币最小交易小数位|| price|y|string|最新价|| quote|y|string|涨跌幅|| fluctuation|y|string|涨跌幅|| high|y|string|最高价|| low|y|string|最低价|| amount24|y|string|24小时成交张数|| size24|y|string|24小时成交价值|| totalPosition|y|string|最低价持仓量|| fund|y|string|资金费率|| markPrice|y|string|标记价格|| indexPrice|y|string|指数价格|| unitAmount|y|string|一张合约对应的quote面值,默认1|| env|y|string|是否测试盘 0:线上盘,1:测试盘|| maxLever|y|string|最大杠杆|| ### K线 #### GET /api/v1/perpetual/public/{contractCode}/candles #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- kline|y|string|k线类型||1min,3min,5min,15min,30min,1hour,2hour,4hour,6hour,12hour,day,week since|n|int|时间戳,默认值0|| size|n|int|k线数量|| klineType|n|int|K线类型|1|1-最新价 2-标记价 3-指数价 #### 返回：Response
```json { "code":0, "data":[ [ 1543405500000,//时间 "100",//最低 "100",//最高 "100",//开盘价 "100",//收盘价 "0",//成交量 "0"//成交价值 ] ], "msg":"success" } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态，200：成功|| msg|y|string|提示|| data|y|object||| ### 深度信息 #### GET /api/v1/perpetual/public/products/{contractCode}/orderbook ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code||Response
```json { "asks": [ //卖一 [ "9721.47", //价格 "225", //张数 "225" //总张数 ] ], "bids": [ //买一 [ "9720", "480", "480" ] ] } ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- asks|y|object|卖盘|| bids|y|object|买盘|| ### 最新交易数据 #### GET /api/v1/perpetual/public/{contractCode}/fills #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code||Response
```json { "code": 200, "data": [ [ "9695.28", //成交价格 "496", //张数 "long", //方向 1582269058972, //时间 9916897 //成交id ] ], "msg": "success" } ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|string|状态码|| data|y|object|返回结果|| msg|y|string|消息|| ### 指数价成分信息 #### GET /api/v1/perpetual/public/{contractCode}/indexInfo #### 请求参数： ##### 路径参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------ | -------- | ------ | -------- | | contractCode | y | string | 合约code | | |Response
```json { "code": 200, "data": { "components": [ { "name": "binance_contract", "price": "38983.69999999", "symbol": "BTC/USDT", "wgt": "1" } ], "index": "btc", "indexPrice": "38983.69999999", "time": 1650269513885 }, "msg": "success" } ``` #### 返回： | 参数名称 | 类型 | 描述 | 默认值 | 取值范围 | | ---------- | ------ | ------------------ | ------------------------------------------------------------ | -------- | | components | obejct | 单个交易所指数信息 | | | | >name | string | 交易所名称 | binance_contract-币安合约，binance-币安，huobi-火币，okex-OK | | | >price | string | 价格 | | | | >symbol | string | 交易对 | | | | >wgt | number | 权重 | | | | index | object | 指数货币 | | | | indexPrice | string | 指数价 | | | | time | number | 时间 | | | ### 资金费用历史 #### GET /api/v1/perpetual/public/{contractCode}/fee-rate ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| page|n|int|页码|| pageSize|n|int|大小|| #### 返回：Response
```json { "code":200, "data": { "amount24":830768400, "contractCode":"etcusd", "createdDate":1546603201000, "feeRate":-0.00375, "id":5, "insuranceSize":0, "modifyDate":1546603201000, "size24":8307684, "timeIndex":1546603201000, "userPositionAmount":198000000 }, "msg":"success" } ``` 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- amount24|y|string|24小时成交量|| contractCode|y|string|合约code|| createdDate|y|string|创建时间|| feeRate|y|string|资金费率|| id|y|string|主键id|| insuranceSize|y|string|风险准备金|| modifyDate|y|string|修改时间|| size24|y|string|24小时成交价值|| timeIndex|y|string|生成当前数据的时间|| userPositionAmount|y|string|持仓总量|| ### 最新标记价格和资金费率 #### GET /api/v1/perpetual/public/{contractode}/premiumIndex ##### 路径参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------ | -------- | ------ | -------- | | contractCode | y | string | 合约code | | | #### 返回：Response
```json { "code": 200, "data": { "baseCurrency": "usdt", "contractCode": "btcusdt", "estimateFeeRate": "0.00375", "indexPrice": "39008.4", "lastFeeRate": "0.00375", "lastPrice": "41500", "markPrice": "39008.4", "quoteCurrency": "usdt", "time": 1650270347001, "totalPosition": "19193" }, "msg": "success" } ``` | 参数名称 | 类型 | 描述 | 默认值 | 取值范围 | | --------------- | ------ | ------------------ | ------ | -------- | | baseCurrency | string | 交易货币 | | | | contractCode | string | 合约code | | | | estimateFeeRate | string | 预估的资金费率 | | | | indexPrice | string | 指数价 | | | | lastFeeRate | string | 最近更新的资金费率 | | | | lastPrice | string | 最新交易价格 | | | | markPrice | string | 标记价 | | | | quoteCurrency | string | 计价货币 | | | | time | string | 更新时间 | | | | totalPosition | string | 总持仓量 | | | - 资产接口
资产接口
我的资产
GET /api/v1/perpetual/account/assets/{contractCode}
请求参数：
路径参数
参数名称 是否必须 类型 描述 默认值 取值范围 contractCode y string 合约code Query
参数名称 是否必须 类型 描述 默认值 取值范围 AccessKeyId y string 访问key SignatureVersion y string 版本 SignatureMethod y string 签名方法 HmacSHA256 Signature y string 签名 Timestamp y string 时间戳 Response
{ "nextRewardTimestamp": 86400000, "accountRights": "211.73425366", "realizedSurplus": "-1996.67028101", "unRealizedSurplus": "0", "orderMargin": "111.32734888", "positionMargin": "55.30721388", "env": 0, "currencyCode": "usdt", "availableMargin": "45.09969088" }返回：
参数名称 是否必须 类型 描述 默认值 取值范围 currencyCode y string 币种 env y int 是否测试币 0:线上币,1:测试币 availableMargin y string 可用保证金 realizedSurplus y string 已实现盈亏 orderMargin y string 委托保证金 positionMargin y string 仓位保证金 unRealizedSurplus y string 未实现盈亏 accountRights y string 账户权益 资产列表
GET /api/v1/perpetual/account/assets
请求参数：
Query
参数名称 是否必须 类型 描述 默认值 取值范围 AccessKeyId y string 访问key SignatureVersion y string 版本 SignatureMethod y string 签名方法 HmacSHA256 Signature y string 签名 Timestamp y string 时间戳 Response
[ { "availableBalance": "9875.254090", "currencyCode": "USDT", "env": "0", "frozenBalance": "0.000000", "orderMargin": "15.823570", "positionMargin": "89.352729", "positionAccountRights": "10456.925390", "realizedSurplus": "583.993103", "unRealizedSurplus": "-15.505000" } ]返回：
参数名称 是否必须 类型 描述 默认值 取值范围 availableBalance y string 可用余额 currencyCode y string 币种 env y int 是否测试币 0:线上币,1:测试币 frozenBalance y string 可用冻结（出现在划转审核） orderMargin y string 订单保证金 positionMargin y string 仓位保证金 positionAccountRights y string 账户权益 realizedSurplus y string 已实现盈亏 unRealizedSurplus y string 未实现盈亏 成交记录
GET /api/v1/perpetual/bills/deal-record
请求参数：
Query
参数名称 是否必须 类型 描述 默认值 取值范围 AccessKeyId y string 访问key SignatureVersion y string 版本 SignatureMethod y string 签名方法 HmacSHA256 Signature y string 签名 Timestamp y string 时间戳 startDate n long 开始时间 endDate n long 结束时间 contractCode n string 合约code page n integer 页数 1 pageSize n integer 每页数量 20 startId n long 开始id endId n long 结束id Response
{ "code": 200, "data": { "data": [ { "amount": "6", "contractCode": "btcusdt", "createDate": "2021-11-14 20:52:03", "currencyCode": "usdt", "dealType": 1, "detailSide": "close_long", "fee": "1.3579752900000000", "id": "666746374653476864", "makerTaker": "maker", "orderId": 125090120907072, "price": "64665.4900000000000000", "profit": "0.9555748956901509", "refOrderId": 125090122965326, "size": "3879.9294000000000000", "userId": "2000011" } ], "pageNum": 1, "pageSize": 20, "totalCount": 112677 }, "msg": "success" }返回：
参数名称 是否必须 类型 描述 默认值 取值范围 amount y string 成交数量 contractCode y string 合约code createDate y string 创建时间 currencyCode y string 币种 dealType y string 成交类型，1：自成交，2：与其他用户成交 detailSide y string 开平方向 fee y string 手续费 id y long 成交记录id makerTaker y string maker or taker orderId y long 订单id price y string 成交价格 profit y string 收益 refOrderId y long 关联订单id size y string 成交价值 userId y long uid - 下单接口 # 下单接口 ### 普通单下单 #### POST /api/v1/perpetual/products/{contractCode}/order #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳|| ##### Body(json) 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- type|y|string|类型||10 限价 11 市价 side|y|string|方向||open_long 开多 open_short 开空 close_long 平多 close_short 平空 price|n|string|价格|| amount|y|int|数量|| beMaker|n|int|时间戳|0|被动委托：0:不被动委托 1:被动委托
Response
```json { "id": "1237893454356" } ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|long|订单id|| ### 条件单下单 #### POST /api/v1/perpetual/products/{contractCode}/order #### 请求参数： ##### 路径参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------ | -------- | ------ | -------- | | contractCode | y | string | 合约code | | | ##### Query | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ---------------- | -------- | ------ | -------- | ------ | ---------- | | AccessKeyId | y | string | 访问key | | | | SignatureVersion | y | string | 版本 | | | | SignatureMethod | y | string | 签名方法 | | HmacSHA256 | | Signature | y | string | 签名 | | | | Timestamp | y | string | 时间戳 | | | ##### Body(json) | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------ | ------------ | ------ | ------------------------------------------------------------ | | type | y | string | 订单类型 | | 12： 条件单 | | triggerBy | y | string | 触发类型 | | 默认mark，标记价格：mark，最新价格：last | | triggerPrice | y | string | 触发价 | | 触发价格 | | side | y | string | 方向 | | open_long 开多 open_short 开空 close_long 平多 close_short 平空 | | price | n | string | 委托价格 | | 触发后下单价格（限价单price必传） | | currentPrice | n | string | 当前标记价格 | | 计划委托时不传；止盈止损时传当前合约价格, 用于判断止盈止损方向 | | algoType | y | int | 委托类型 | | 10-限价，11-市价 | | amount | y | int | 数量 | | 委托数量 | ```json //计划委托下单 { "type": 12, //type：订单类型，12：条件单 "side": "open_long", //side：触发后开仓方向 "triggerBy": "last", //触发类型：指数价格：index，标记价格：mark，最新价格：last "triggerPrice": "500", //触发价格 "price": "600.000000", //触发后下单价格（限价单price必传） "amount": "10", //触发后下单数量 "algoType": 10 //条件单下单类型 10：限价单 11：市价单 } ``` ```json //止盈止损下单 { "type": 12, //type：订单类型，12：条件单 "amount": 12, //触发后下单数量 "side": "close_long", //side：触发后开仓方向 "triggerBy": "last", //触发类型：指数价格：index，标记价格：mark，最新价格：last "triggerPrice": "12", //触发价格 "currentPrice": "600.000000", //当前合约价格, 判断止盈止损方向 "algoType": 10, //条件单下单类型 10：限价单 11：市价单 "price": "600.000000", //触发后下单价格（限价单price必传） } ``` #### 返回： | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | -------- | -------- | ---- | ------ | ------ | -------- | | id | y | long | 订单id | | |Response
```json { "id": "1237893454356" } ``` ### 批量下单 #### POST /api/v1/perpetual/products/{contractCode}/batch-order #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳|| ```json [ { "amount": 1, "lang": "zh_CN", "platform": 1, "price": "2.94", "side": "open_long", "type": 10, "tag": 1 } ] ``` ##### Body(list-json) 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- type|y|string|类型||10 限价或条件单 11 市价 side|y|string|方向||open_long 开多 open_short 开空 close_long 平多 close_short 平空 price|y|string|价格|| amount|y|int|数量|| beMaker|n|int|时间戳|0|被动委托：0:不被动委托 1:被动委托 ioc|n|int|订单若不能立即成交则未成交的部分立即取消|0|0: 关闭，1: 开启 tag|n|string|标签||下单时用户所定义的标签，下单后返回Response
```json [ { "orderId": 80742077438016, "tag": "1" } ] ``` #### 返回(list-json)： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|long|订单id|| ### 订单列表 #### GET /api/v1/perpetual/products/{contractCode}/list #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳||Response
```json [ { "amount": "300.0000000000000000", "avgPrice": "0E-16", "base": "", "contractCode": "fbtcusd", "contractDirection": 0, "createdDate": 1582225542000, "dealAmount": "0E-16", "detailSide": "open_long", "direction": "", "fee": "0E-16", "id": 69109290623152, "orderSize": "0.32258064", "price": "9300.0000000000000000", "profit": "0E-16", "quote": "", "reason": 0, "refConditionOrderId": 0, "refOrderCondition": null, "side": "long", "source": "", "status": 0, "systemType": 10, "triggerBy": "", "triggerPrice": "" } ] ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- amount|y|string|数量|| avgPrice|y|string|平均成交价|| base|y|string|基础货币名,如btc、fbtc|| contractCode|y|string|是Base和Quote之间的组合 P_BTC_USDT，R_BTC_USDT|| contractDirection|y|int|合约方向 0:正向,1:反向|| createdDate|y|string|创建时间|| dealAmount|y|string|已成交数量|| detailSide|y|string|订单方向 1.开多open_long 2.开空open_short 3.平多close_long 4.平空close_short|| direction|y|string|条件单：触发方向，greater大于，less小于|| fee|y|string|该笔订单成交后交的手续费: 正表示得手续费,负表示付手续费|| id|y|long|订单id|| orderSize|y|string|订单价值|| price|y|string|委托价格|| profit|y|string|该笔订单成交后对应的盈亏: 正表示盈利,负表示亏损|| quote|y|string|计价货币名，usd,cny,usdt|| reason|y|int|该笔订单取消的理由，0是默认值，没有理由|| refConditionOrderId|y|long|条件单id|| refOrderCondition|y|object|条件单详情|| side|y|string|订单方向，long多，short空|| source|y|string|来源|| status|y|int|状态 0:等待成交 1:部分成交 2:已经成交 -1:已经撤销|| systemType|y|int|10:限价 11:市价 13:强平单 14:爆仓单 15：穿仓 16：强减|| triggerBy|y|string|条件单触发类型，指数价格：index，标记价格：mark，最新价格：last|| triggerPrice|y|string|条件单触发价格|| ### 撤单 #### DELETE /api/v1/perpetual/products/{contractCode}/order/{id} #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| id|y|long|订单id|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳||Response
```json { "code": 200, "msg": "success", "data": null } ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态，200：成功|| msg|y|string|提示|| data|y|object||| ### 批量撤单 #### DELETE /api/v1/perpetual/products/{contractCode}/orders #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳||Response
```json { "code": 200, "msg": "success", "data": null } ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态，200：成功|| msg|y|string|提示|| data|y|object||| ### 根据订单号批量撤单 #### DELETE /api/v1/perpetual/products/{contractCode}/batch-delete-order #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳|| ```json [ 80581909355536, 80581909355537 ] ``` ##### Body(list) 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- id|y|string|订单号||Response
```json { "code": 200, "msg": "success", "data": null } ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- code|y|int|状态，200：成功|| msg|y|string|提示|| data|y|object||| ### 订单详情 #### GET /api/v1/perpetual/products/{contractCode}/{id} #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| id|y|long|订单id|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳||Response
```json { "amount": "300.0000000000000000", "avgPrice": "0E-16", "base": "", "contractCode": "fbtcusd", "contractDirection": 0, "createdDate": 1582225542000, "dealAmount": "0E-16", "detailSide": "open_long", "direction": "", "fee": "0E-16", "id": 69109290623152, "orderSize": "0.32258064", "price": "9300.0000000000000000", "profit": "0E-16", "quote": "", "reason": 0, "refConditionOrderId": 0, "refOrderCondition": null, "side": "long", "source": "", "status": 0, "systemType": 10, "triggerBy": "", "triggerPrice": "" } ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- amount|y|string|数量|| avgPrice|y|string|平均成交价|| base|y|string|基础货币名,如btc、fbtc|| contractCode|y|string|是Base和Quote之间的组合 P_BTC_USDT，R_BTC_USDT|| contractDirection|y|int|合约方向 0:正向,1:反向|| createdDate|y|string|创建时间|| dealAmount|y|string|已成交数量|| detailSide|y|string|订单方向 1.开多open_long 2.开空open_short 3.平多close_long 4.平空close_short|| direction|y|string|条件单：触发方向，greater大于，less小于|| fee|y|string|该笔订单成交后交的手续费: 正表示得手续费,负表示付手续费|| id|y|long|订单id|| orderSize|y|string|订单价值|| price|y|string|委托价格|| profit|y|string|该笔订单成交后对应的盈亏: 正表示盈利,负表示亏损|| quote|y|string|计价货币名，usd,cny,usdt|| reason|y|int|该笔订单取消的理由，0是默认值，没有理由|| refConditionOrderId|y|long|条件单id|| refOrderCondition|y|object|条件单详情|| side|y|string|订单方向，long多，short空|| source|y|string|来源|| status|y|int|状态 0:等待成交 1:部分成交 2:已经成交 -1:已经撤销|| systemType|y|int|10:限价 11:市价 13:强平单 14:爆仓单 15：穿仓 16：强减|| triggerBy|y|string|条件单触发类型，指数价格：index，标记价格：mark，最新价格：last|| triggerPrice|y|string|条件单触发价格|| ### 市价全平 #### POST /api/v1/perpetual/products/{contract_code}/{side}/closePosition #### 请求参数： ##### 路径参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------ | -------- | ------ | -------------------- | | contractCode | y | string | 合约code | | | | side | y | string | 方向 | | long 多仓 short 空仓 | ##### Query | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ---------------- | -------- | ------ | -------- | ------ | ---------- | | AccessKeyId | y | string | 访问key | | | | SignatureVersion | y | string | 版本 | | | | SignatureMethod | y | string | 签名方法 | | HmacSHA256 | | Signature | y | string | 签名 | | | | Timestamp | y | string | 时间戳 | | |Response
```json { "code": 200, "msg": "success", "data": null } ``` #### 返回： | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | -------- | -------- | ------ | --------------- | ------ | -------- | | code | y | int | 状态，200：成功 | | | | msg | y | string | 提示 | | | | data | y | object | | | | ### 历史委托 #### GET /api/v1/perpetual/products/{contractCode}/history-list #### 请求参数： ##### 路径参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------ | -------- | ------ | -------- | | contractCode | y | string | 合约code | | | ##### Query | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ---------------- | -------- | ------ | ------------------------------------------------------------ | ------ | ---------- | | AccessKeyId | y | string | 访问key | | | | SignatureVersion | y | string | 版本 | | | | SignatureMethod | y | string | 签名方法 | | HmacSHA256 | | Signature | y | string | 签名 | | | | Timestamp | y | string | 时间戳 | | | | base | n | string | 基础币 | | | | detailSide | n | string | 仓位方向 1.开多open_long 2.开空open_short 3.平多close_long 4.平空close_short | | | | status | n | int | 状态：1 已成交 2 部分成交已撤销 3 已撤单；多个条件过滤用“,”分隔 | | | | type | n | int | 合约方向 0:正向,1:反向 | | | | systemType | n | string | 下单类型：10:限价 11:市价 13:强平单 14:爆仓单 15：穿仓 16：强减;多个条件过滤用“,”分隔 | | | | startDate | n | int | 开始时间 | | | | endTime | n | int | 结束时间 | | | | page | n | int | 第几页 | 1 | | | pageSize | n | int | 页面大小 | 20 | | | stopLimitType | n | int | 计划类型：0 -止盈 1-止损 2-计划委托 | | |Response
##### 返回 ```json { "code": 0, "msg": "", "data": { "total": 0, "rows": [ { "id": 0, "contractCode": "", "base": "", "quote": "", "indexBase": "", "contractDirection": 0, "side": "", "detailSide": "", "amount": "", "dealAmount": "", "avgPrice": "", "price": "", "orderSize": "", "status": 0, "systemType": 0, "direction": "", "profit": "", "fee": "", "reason": 0, "triggerBy": "", "triggerPrice": "", "triggerDate": 0, "modifyDate": 0, "createdDate": "2022-04-18 16:07:49", "source": "", "refConditionOrderId": 0, "refOrderCondition": { "id": 0, "contractCode": "", "base": "", "quote": "", "indexBase": "", "contractDirection": 0, "type": "", "direction": "", "triggerPrice": "", "triggerBy": "", "price": "", "side": "", "detailSide": "", "amount": "", "avgPrice": "", "dealAmount": "", "orderSize": "", "dealSize": "", "status": 0, "reason": 0, "systemType": 0, "createdDate": "2022-04-18 16:07:49", "source": "", "orderPriceType": 0, "positionType": 0, "stopLimitType": 0, "refOrderId": 0, "lever": 0, "unitAmount": "", "marginDigit": 0, "marketPriceDigit": 0, "triggerDate": 0, "modifyDate": 0, "tiggerOrderDetail": { "id": 0, "price": "" } }, "stopLimitType": "", "lever": "", "orderPriceType": 0, "positionType": 0, "unitAmount": "", "marginDigit": 0, "marketPriceDigit": 0, "stopLoss": { "id": 0, "contractCode": "", "base": "", "quote": "", "indexBase": "", "contractDirection": 0, "type": "", "direction": "", "triggerPrice": "", "triggerBy": "", "price": "", "side": "", "detailSide": "", "amount": "", "avgPrice": "", "dealAmount": "", "orderSize": "", "dealSize": "", "status": 0, "reason": 0, "systemType": 0, "createdDate": "2022-04-18 16:07:49", "source": "", "orderPriceType": 0, "positionType": 0, "stopLimitType": 0, "refOrderId": 0, "lever": 0, "unitAmount": "", "marginDigit": 0, "marketPriceDigit": 0, "triggerDate": 0, "modifyDate": 0, "tiggerOrderDetail": { "id": 0, "price": "" } }, "stopProfit": { "id": 0, "contractCode": "", "base": "", "quote": "", "indexBase": "", "contractDirection": 0, "type": "", "direction": "", "triggerPrice": "", "triggerBy": "", "price": "", "side": "", "detailSide": "", "amount": "", "avgPrice": "", "dealAmount": "", "orderSize": "", "dealSize": "", "status": 0, "reason": 0, "systemType": 0, "createdDate": "2022-04-18 16:07:49", "source": "", "orderPriceType": 0, "positionType": 0, "stopLimitType": 0, "refOrderId": 0, "lever": 0, "unitAmount": "", "marginDigit": 0, "marketPriceDigit": 0, "triggerDate": 0, "modifyDate": 0, "tiggerOrderDetail": { "id": 0, "price": "" } } } ] } } ``` ###### Object-data | 名称 | 类型 | 描述 | 默认值 | 备注 | | :------------------ | :------------- | ------------------------------------------------------------ | :----- | :--- | | id | number | ID | | | | contractCode | string | 合约Code | | | | base | string | 基础货币名,如btc | | | | quote | string | 计价货币名，usd,cny,usdt | | | | indexBase | string | 指数货币 | | | | contractDirection | number | 方向 0:正向,1:反向 | | | | side | string | 仓位方向，long多，short空 | | | | detailSide | string | 仓位方向 1.开多open_long 2.开空open_short 3.平多close_long 4.平空close_short | | | | amount | string | 委托数量 | | | | dealAmount | string | 已成交数量 | | | | avgPrice | string | 平均成交价格 | | | | price | string | 委托价格 | | | | orderSize | string | 委托价值 | | | | status | number | 0 等待成交 1 部分成交 2 已经成交 -1 已经撤销 | | | | systemType | number | 10:限价 11:市价 13:强平单 14:爆仓单 15：穿仓 16：强减 | | | | direction | string | 触发方向，greater大于，less小于 | | | | profit | string | 该笔订单成交后对应的盈亏: 正表示盈利,负表示亏损 | | | | fee | string | 该笔订单成交后交的手续费: 正表示得手续费,负表示付手续费 | | | | reason | number | 该笔订单取消的理由，0是默认值，1 系统撤销，2 用户取消 其他-委托失败 | | | | triggerBy | string | 计划委托类型: index-指数价格market/mark-标记价格mark/last-最新价格last | | | | triggerPrice | string | 触发价格 | | | | triggerDate | number | 触发时间 | | | | modifyDate | number | 最后操作时间 | | | | createdDate | string | 创建时间 | | | | source | string | 来源 | | | | refConditionOrderId | number | 关联的条件订单id | | | | refOrderCondition | OrderCondition | 关联条件单 #Object-OrderCondition | | | | stopLimitType | string | 条件单类型 0 -止盈 1-止损 2-计划委托 | | | | lever | string | 杠杆 | | | | orderPriceType | number | 20 最优20档/10 最优10档/5 最优5档/1 对手价 | | | | positionType | number | 持仓类型 | | | | unitAmount | string | 一张合约对应的quote面值,默认1 | | | | marginDigit | number | 保证金小数位 | | | | marketPriceDigit | number | 标记价格小数位 | | | | stopLoss | object | 关联止损单 #Object-OrderCondition | | | | stopProfit | object | 关联止盈单 #Object-OrderCondition | | | ###### Object-OrderCondition | 名称 | 类型 | 描述 | 默认值 | 备注 | | :---------------- | :----- | :----------------------------------------------------------- | :----- | :--- | | id | number | 条件单id | | | | contractCode | string | 合约code：是Base和Quote之间的组合 | | | | base | string | 基础货币名 | | | | quote | string | 计价货币名 | | | | indexBase | string | 指数货币 | | | | contractDirection | number | 方向 0:正向,1:反向 | | | | type | string | 触发类型：指数价格，标记价格，最新价格 | | | | direction | string | 触发方向，greater大于，less小于 | | | | triggerPrice | string | 触发价格 | | | | triggerBy | string | 计划委托类型: index-指数价格market/mark-标记价格mark/last-最新价格last | | | | price | string | 用户订单委托或者破产价格 | | | | side | string | 仓位方向，long多，short空 | | | | detailSide | string | 1.开多open_long 2.开空open_short 3.平多close_long 4.平空close_short | | | | amount | string | 委托数量 | | | | avgPrice | string | 平均成交价格 | | | | dealAmount | string | 已成交数量 | | | | orderSize | string | 委托价值 | | | | dealSize | string | 已经成交价值 | | | | status | number | 状态 1:已触发 0、2：未触发 3：预条件单 -1：已撤销 | | | | reason | number | 订单被撤销原因 1：系统撤销 2：用户撤销 3、4、5：触发后委托失败 中间用逗号分割 | | | | systemType | number | 10:限价 11:市价 13:强平单 14:爆仓单 | | | | createdDate | string | 创建时间 | | | | source | string | 来源 | | | | orderPriceType | number | 下单价格类型，对手价：opponent，最优20档：optimal_20，最优10档：optimal_10，最优5档：optimal_5 | | | | positionType | number | 仓位模式 | | | | stopLimitType | number | 条件类型 | | | | refOrderId | number | 关联订单id | | | | lever | number | 杠杆 | | | | unitAmount | string | 单位 | | | | marginDigit | number | 保证金位数 | | | | marketPriceDigit | number | 价格位数 | | | | triggerDate | number | 触发时间 | | | | modifyDate | number | 修改时间 | | | | tiggerOrderDetail | object | | | | ### 订单交易详情 #### GET /api/v1/perpetual/products/{contractCode}/orderDetail #### 请求参数： ##### 路径参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------ | -------- | ------ | -------- | | contractCode | y | string | 合约code | | | ##### Query | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ---------------- | -------- | ------ | -------- | ------ | ---------- | | AccessKeyId | y | string | 访问key | | | | SignatureVersion | y | string | 版本 | | | | SignatureMethod | y | string | 签名方法 | | HmacSHA256 | | Signature | y | string | 签名 | | | | Timestamp | y | string | 时间戳 | | | | orderId | y | number | 订单ID | | |Response
##### 返回 ###### body ```json { "code": 200, "data": { "amount": "4", "avgPrice": "342.150000", "canceledDate": 0, "contract": { "amount24": "", "base": "usdt", "code": "bchusdt", "countDownTimeInterval": "", "direction": 0, "env": 0, "fluctuation": "", "fund": "", "high": "", "indexBase": "bch", "indexPrice": "", "lastCny": "", "low": "", "makerRate": "", "marginDigit": 6, "markPrice": "", "marketPriceDigit": 6, "maxLever": 0, "minQuoteDigit": 0, "minTradeDigit": 0, "minTradeUnit": 0, "nextLiquidationInterval": 0, "openTradeTime": "", "price": "", "quote": "usdt", "size24": "", "sort": 0, "takerRate": "", "totalPosition": "", "tradeStatus": 0, "unitAmount": 0.1, "unitAmountStr": "0.1" }, "createdDate": 1649925906000, "currencyCode": "usdt", "dealAmount": "4", "dealDetails": [ { "dealAmount": "4", "dealDate": 1649925907000, "fee": "-0.088959", "markerTaker": 2 } ], "detailSide": "close_long", "fee": "-0.088959", "historyOrderFlag": true, "lever": "20", "liquidateExplosionDetail": null, "orderId": 138434463977680, "orderPriceType": 0, "orderSystemType": 11, "positionType": 1, "price": "341.686700", "profit": "-0.560000", "refConditionOrderId": 0, "refOrderId": 0, "refType": 1, "settingDate": 0, "side": "short", "status": 2, "stopLimitType": 0, "systemType": 11, "triggerDate": 0, "triggerPrice": "", "unitAmount": "0.1", "userId": 20600095 }, "msg": "success" } ``` ###### data | 名称 | 类型 | 描述 | 默认值 | 备注 | | ------------------------ | --------- | ------------------------------------------------------------ | ------ | ------------------------------ | | amount | string | 委托数量 | | | | avgPrice | string | 成交均价 | | | | canceledDate | number | 撤销时间 | | | | contract | object | 合约明细 | | ContractNavigation | | createdDate | number | 创建时间 | | | | currencyCode | string | 币种 | | | | dealAmount | string | 成交数量 | | | | dealDetails | object [] | 成交详情 | | **item 类型:** OrderDealDetail | | detailSide | string | 详细仓位方向：1.开多open_long 2.开空open_short 3.平多close_long 4.平空close_short | | | | fee | string | 手续费 | | | | historyOrderFlag | boolean | 是否是历史订单 | | | | lever | string | 杠杆 | | | | liquidateExplosionDetail | object | 强平详情 | | LiquidateExplosionDetail | | orderId | number | 订单ID | | | | orderPriceType | number | 订单类型 | | | | positionType | number | 仓位类型 | | | | price | string | 委托价 | | | | profit | string | 收益 | | | | refConditionOrderId | number | 条件单id | | | | settingDate | number | 设置时间 | | | | side | string | 方向 | | | | status | number | 1 部分成交 2 完全成交 -1 已经撤销 0 未成交（当systemType不等于12时） 0 未触发（当systemType等于12时条件单） | | | | stopLimitType | number | 条件单类型 0 -止盈 1-止损 2-计划委托 | | | | systemType | number | 系统类型 10:限价 11:市价 12:条件单 13:强平单 14:爆仓单 15：爆仓 16：强减 | | | | triggerDate | number | 触发时间 | | | | triggerPrice | string | 触发价 | | | ###### ContractNavigation | 名称 | 是否必须 | 类型 | 描述 | 默认值 | 备注 | | ----------------------- | ------- | ------ | --------------------- | --------------------- | --------------------- | | amount24 | y | string | 24小时成交张数 | | | | base | y | string | 基础货币名 | | | | code | y | string | 合约code | | | | contractType | y | string | 合约类型，永续-perpetual、 交割-deliver 、当周交割-week、次周交割-nextWeek、当季交割-quarter、次季交割-nextQuarter | | | | countDownTimeInterval | y | string | 倒计时时间间隔 | | | | direction | y | integer | 方向 0:正向,1:反向 | | **format:** int32 | | env | y | integer | 是否测试盘 0:线上盘,1:测试盘 | | **format:** int32 | | fluctuation | y | string | 涨跌幅 | | | | fund | y | string | 资金费率 | | | | high | y | string | 最高价 | | | | indexBase | y | string | 指数货币 | | | | indexPrice | y | string | 指数价格 | | | | lastCny | y | string | 最新价折合人民币 | | | | liquidationDate | y | string | 清算时间 | | **format:** date-time | | low | y | string | 最低价 | | | | makerRate | y | string | maker 汇率 | | | | marginDigit | y | integer | 保证金精度 | | **format:** int32 | | markPrice | y | string | 标记价格 | | | | marketPriceDigit | y | integer | 标记价格最小单位（精度） | | **format:** int32 | | maxLever | y | number | 最大杠杆 | | | | minQuoteDigit | y | integer | 计价货币最小交易小数位 | | **format:** int32 | | minTradeDigit | y | integer | 基础货币最小交易小数位 | | **format:** int32 | | minTradeUnit | y | number | 最小交易单位 | | | | nextLiquidationInterval | y | integer | 下一次清算时间差 | | **format:** int64 | | openTradeTime | y | string | 开盘时间 | | | | price | y | string | 最新价 | | | | quote | y | string | 计价货币名 | | | | size24 | y | string | 24小时成交价值 | | | | sort | y | integer | 排序 | | **format:** int32 | | takerRate | y | string | taker 汇率 | | | | totalPosition | y | string | 持仓量 | | | | tradeStatus | y | integer | 发布状态:1预发,2上线后7天内,3.上线七天后 | | **format:** int32 | | unitAmount | y | number | 一张合约对应的quote面值,默认1 | | | ###### OrderDealDetail | 名称 | 类型 | 描述 | 默认值 | 备注 | | ---------- | ------ | -------- | ------ | ---- | | dealAmount | string | 成交数量 | | | | dealDate | string | 成交时间 | | | | fee | string | 手续费 | | | ###### LiquidateExplosionDetail | 名称 | 类型 | 描述 | 默认值 | 备注 | | -------------- | ------ | ------------ | ------ | ---- | | contractCode | string | 合约code | | | | explosionPrice | string | 破产价 | | | | feeRate | string | 手续费率 | | | | lever | string | 杠杠 | | | | liquidatePrice | string | 强平价 | | | | maintainRate | string | 维持保证金率 | | | | price | string | 委托价格 | | | | side | string | 方向 | | | - 持仓接口 # 持仓接口 ### 仓位列表 #### GET /api/v1/perpetual/position/{contractCode}/list #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳||
Response
```json [ { "amount": "4867", "base": "fbtc", "closingAmount": "0", "contractCode": "fbtcusd", "lever": "100", "liqudatePrice": "3237.43", "maintenanceMargin": "0.02527905", "markPrice": "9659.25", "minQuoteDigit": 2, "minTradeDigit": 8, "openMargin": "0.14863957", "price": "9626.54", "quote": "usd", "realizedSurplus": "0.00413503", "side": "long", "size": "5.05581019", "type": 0 } ] ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- amount|y|string|持仓数量|| base|y|string|基础货币名,如BTC、ETH|| closingAmount|y|int|成交数量|| contractCode|y|string|合约|| gear|y|string|风险限额|| lever|y|string|杠杆|| liqudatePrice|y|string|强平价|| maintenanceMargin|y|string|维持保证金|| markPrice|y|string|标记价格|| minQuoteDigit|y|string|计价货币最小交易小数位|| minTradeDigit|y|string|基础货币最小交易小数位|| openMargin|y|string|开仓保证金|| price|y|string|成交均价|| quote|y|string|计价货币名，USD,CNY,USDT|| realizedSurplus|y|已实现盈亏|| side|y|string|仓位类型，long多，short空|| size|y|string|仓位价值|| type|y|string|0：全仓，1：逐仓|| ### 获取所有档位对应的保证金率和杠杆 #### GET /v1/perpetual/public/{contractCode}/lever-gears #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳||Response
```json { "code": 200, "data": [ { "entryRate": "0.008", "gear": 1, "lever": "125", "maintainRate": "0.004", "maxOpenAmount": "100" } ] "msg": "success" } ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- entryRate|y|string|开仓保证金率|| gear|y|int|档位|| lever|y|string|杠杆|| maintainRate|y|string|维持保证金率|| maxOpenAmount|y|string|最大可开张数|| ### 仓位和限额设置 #### GET /api/v1/perpetual/position/{contractCode}/configs #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳||Response
```json { "contractCode": "btcusdt", "feeRate": "0.00065", "fundRate": "0.00375", "indexPrice": "37591.04", "longPositionConfigDetails": { "initOpenMarginRate": "0.008", "lever": "125", "maintainRate": "0.004", "maxOpenAmount": "100", "side": "long" }, "makerFeeRate": "0.00035", "markPrice": "37704.1", "shortPositionConfigDetails": { "initOpenMarginRate": "0.008", "lever": "125", "maintainRate": "0.004", "maxOpenAmount": "100", "side": "short" }, "takerFeeRate": "0.00065", "type": 0, "unitAmount": "0.01" } ``` #### 返回： **main** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| feeRate|y|int|手续费率|| fundRate|y|string|资金费率|| indexPrice|y|string|指数价格|| markPrice|y|string|标记价格|| type|y|string|0：全仓，1：逐仓|| unitAmount|y|string|张数：一张合约对应的quote面值|| makerFeeRate|y|string|maker手续费率|| takerFeeRate|y|string|taker手续费率|| **|longPositionConfigDetails||shortPositionConfigDetails|仓位详情** 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- lever|y|string|杠杆|| side|y|string|方向|| maxOpenAmount|y|string|最大可开张数|| lever|y|string|杠杆|| initOpenMarginRate|y|string|初始保证金率|| ### 设置杠杆 #### POST /api/v1/perpetual/position/{contractCode}/lever #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳|| ##### Body(json) 参数名称|是否必须|类型| 描述 | 默认值 |取值范围 ------------- | ------------- | ------------- |------|-----| ------------- type|y|int| 杠杆类型 | | 全仓:0,逐仓:1 lever|y|int| 杠杆 | |1~125 side|y|string| 方向 | |多仓:long，空仓:shortResponse
```json { "code":200, "data": { "shortLever":26, "type":1, "longLever": 10 }, "msg":"success" } ``` #### 返回： 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- lever|y|string|杠杆|| ### 修改保证金 #### POST /api/v1/perpetual/position/{contract_code}/change-margin #### 请求参数： ##### 路径参数 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- contractCode|y|string|合约code|| ##### Query 参数名称|是否必须|类型|描述|默认值|取值范围 ------------- | ------------- | ------------- | ------------- | ------------- | ------------- AccessKeyId|y|string|访问key|| SignatureVersion|y|string|版本|| SignatureMethod|y|string|签名方法||HmacSHA256 Signature|y|string|签名|| Timestamp|y|string|时间戳|| margin|y|string|保证金数量（正数表示添加保证金，负数表示减少保证金）|| side|y|string|方向||long 多仓 short 空仓 ##### Body(json) ```json { } ```Response
```json { "code": 200, "data": null, "msg": "success" } ``` #### 返回： | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | -------- | -------- | ------ | --------------- | ------ | -------- | | code | y | int | 状态，200：成功 | | | | msg | y | string | 提示 | | | | data | y | object | | | | ### 设置自动追加保证金 #### POST /api/v1/perpetual/position/{contractCode}/setting #### 请求参数： ##### 路径参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------ | -------- | ------ | -------- | | contractCode | y | string | 合约code | | | ##### Query | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ---------------- | -------- | ------ | ------------------------------ | ------ | ---------- | | AccessKeyId | y | string | 访问key | | | | SignatureVersion | y | string | 版本 | | | | SignatureMethod | y | string | 签名方法 | | HmacSHA256 | | Signature | y | string | 签名 | | | | Timestamp | y | string | 时间戳 | | | | value | y | string | 1 开启自动追加；0-关闭自动追加 | | | ##### Body(json) ```json { } ``` #### 返回： ```json { "code": 200, "data": null, "msg": "success" } ``` | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | -------- | -------- | ------ | --------------- | ------ | -------- | | code | y | int | 状态，200：成功 | | | | msg | y | string | 提示 | | | | data | y | object | | | | - 合约推送订阅 # 合约推送订阅 ### 接入说明 #### WebSocket域名 ##### wss://wss-ct.hotcoin.fit #### 订阅主题 成功建立与Websocket服务器的连接后，Websocket客户端发送请求以订阅特定主题： ``` { "event": "subscribe", "params": { "biz": "perpetual", //固定传参 "type": "topic to subscribe", //主题类型 "contractCode": "contractCode", //合约代号 "zip": false, //固定传参 "serialize": false //固定传参 } } ``` 比如：
Request
``` { "event": "subscribe", "params": { "biz": "perpetual", "type": "fund_rate", "contractCode": "ethusdt", "zip": false, "serialize": false } } ``` 成功订阅后，Websocket客户端将收到确认消息：Response
```json { "biz": "perpetual", "data": { "result": true }, "channel": "subscribe", "type": "fund_rate", "env": 0, "contractCode": "btcusdt" } ``` 之后, 一旦所订阅的主题有数据更新，热币服务器将向Websocket客户端推送更新消息。 #### 维持 当用户的Websocket客户端连接到热币服务器后，用户需要定期向服务器发送心跳信息，否则5分钟之后将接收不到任何推送，如下： ``` { "event": "ping" } ``` 成功发送后，Websocket客户端将收到确认消息，如下： ``` { "event": "pong" } ``` #### 取消订阅 取消订阅的格式如下： ``` { "event": "unsubscribe", "params": { "biz": "perpetual", "type": "topic to subscribe", "contractCode": "contractCode", "zip": false, "serialize": false } } ``` 比如： ``` { "event": "unsubscribe", "params": { "biz": "perpetual", "type": "fund_rate", "contractCode": "ethusdt", "zip": false, "serialize": false } } ``` 取消订阅成功确认。 ``` { "biz": "perpetual", "data": { "result": true }, "channel": "unsubscribe", "type": "fund_rate", "contractCode": "ethusdt", "env": 0 } ``` ### PING #### 请求参数Request
```json { "event": "ping" } ``` #### 返回结果 ```json { "event": "pong" } ``` ### ws 登录 #### 请求参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | --------- | -------- | ------ | ------------------------- | ------ | -------- | | apiKey | y | string | 访问key | | | | signature | y | string | 签名,签名方式请看签名示列 | | | | timestamp | y | string | 时间戳 | | |Request
```json { "event": "signin", "params": { "apiKey": "xxx", "timestamp": "1593683685313", "signature": "xxx" } } ``` #### 返回结果Response
```json { "data": { "result": true }, "channel": "signin" } ``` ### ws 深度 #### 请求参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------- | -------- | ------ | --------- | | biz | y | string | 业务 | | perpetual | | type | y | string | 类型 | | depth | | contractCode | y | string | 合约code | | | | zip | y | boolean | 是否压缩 | | | | serialize | y | boolean | 是否序列化| | |Request
```json { "event": "subscribe", "params": { "biz": "perpetual", "type": "depth", "contractCode": "ethusdt", "zip": false, "serialize": false } } ``` #### 返回结果Response
```json { "biz": "perpetual", "data": { "result": true }, "channel": "subscribe", "type": "depth", "contractCode": "ethusdt" } ``` #### 推送结果 ```json { "biz": "perpetual", "data": { "asks": [ "0",//[0]价格 "1",//[1]数量 "2"//[2]深度 ], "bids": [ "0",//[0]价格 "1",//[1]数量 "2"//[2]深度 ] }, "type": "depth", "contractCode": "ethusdt" } ``` ### ws K线 #### 请求参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------- | -------- | ------ | ------------------------------------------------------------ | | biz | y | string | 业务 | | perpetual | | type | y | string | 类型 | | mark_candles-指数标记价格K线，candles-最新价K线 | | contractCode | y | string | 合约code | | | | granularity | | string | K线类型 | | 1min,3min,5min,15min,30min,1hour,2hour,4hour,6hour,12hour,day,week | | | | | | | | | zip | y | boolean | 是否压缩 | | | | serialize | y | boolean | 是否序列化| | |Request
```json { "event": "subscribe", "params": { "biz": "perpetual", "type": "candles", "contractCode": "ethusdt", "granularity": "1min", "zip": false, "serialize": false } } ``` #### 返回结果Response
```json { "biz": "perpetual", "data": { "result": true }, "granularity": "1min", "channel": "subscribe", "type": "candles", "contractCode": "ethusdt" } ``` #### 推送结果 ##### 最新价K线 ```json { "biz": "perpetual", "data": [],//[0]毫秒时间戳,[1]低,[2]高,[3]开,[4]收,[5]成交量 "type": "candles", "contractCode": "ethusdt", "granularity": "1min" } ``` ##### 指数标记价格K线 ```json "biz": "perpetual", "data": [],//[0]毫秒时间戳,[1]指数价低,[2]指数价高,[3]指数价开,[4]指数价收,[5]标记价低,[6]标记价高,[7]标记价开,[8]标记价收 "type": "mark_candles", "contractCode": "ethusdt", "granularity": "1min" } ``` ### ws行情所有币对 #### 请求参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------- | -------- | ------ | --------- | | biz | y | string | 业务 | | perpetual | | type | y | string | 类型 | | tickers | | zip | y | boolean | 是否压缩 | | | | serialize | y | boolean | 是否序列化| | |Request
```json { "event": "subscribe", "params": { "biz": "perpetual", "type": "tickers", "zip": false, "serialize": false } } ``` #### 返回结果Response
```json { "biz": "perpetual", "data": { "result": true }, "channel": "subscribe", "type": "tickers", } ``` #### 推送结果 ```json { "biz": "perpetual", "data": [ [ 1597801773851,//时间戳 "432.50",//最高价 "415.00",//最低价 "75250152",//成交张数 "3200391170.386",//成交价值 "430.30",//原始成交价 "424.50",//最新成交价 "-5.85",//24小时价格涨跌幅 "-1.35",//24小时价格涨跌幅比例 "424.4",//盘口买一 "424.55",//盘口卖一 "ethusdt",//币对 "2954.17"//最新成交价(cny) ] ], "type": "tickers", "contractCode":"ethusdt" } ``` ### ws 资金费率和合理价格单个币对 #### 请求参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------- | ---------- | ------ | --------- | | biz | y | string | 业务 | | perpetual | | type | y | string | 类型 | | fund_rate | | contractCode | y | string | 合约code | | | | zip | y | boolean | 是否压缩 | | | | serialize | y | boolean | 是否序列化 | | |Request
```json { "event": "subscribe", "params": { "biz": "perpetual", "type": "fund_rate", "zip": false, "contractCode": "ethusdt", "serialize": true } } ``` #### 返回结果Response
```json { "biz": "perpetual", "data": { "result": true }, "channel": "subscribe", "type": "fund_rate", "contractCode": "btcusdt", } ``` #### 推送结果 ```json { "biz": "perpetual", "data": [],//[0]合约编码,[1]标记价格,[2]指数价格,[3]费率,[4]估算费率,[5]下次结算时间,[6]当前持仓量,[7]指数价折合人民币,[8]标记价折合人民币,[9]env,[10]基础币,[11]指数币,[12]计价币,[13]基础币显示名,[14]指数币显示名,[15]计价币显示名 "type": "fund_rate", "env": 0, "contractCode": "btcusdt" } ``` ### ws 资金费率和合理价格所有币对 #### 请求参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | --------- | -------- | ------- | ---------- | ------ | ---------- | | biz | y | string | 业务 | | perpetual | | type | y | string | 类型 | | fund_rates | | zip | y | boolean | 是否压缩 | | | | serialize | y | boolean | 是否序列化 | | |Request
```json { "event": "subscribe", "params": { "biz": "perpetual", "type": "fund_rates", "zip": false, "serialize": true } } ``` #### 返回结果Response
```json { "biz": "perpetual", "data": { "result": true }, "channel": "subscribe", "type": "fund_rates", } ``` #### 推送结果 ```json { "biz": "perpetual", "data": [ []//[0]合约编码,[1]标记价格,[2]指数价格,[3]费率,[4]估算费率,[5]下次结算时间,[6]当前持仓量,[7]指数价折合人民币,[8]标记价折合人民币,[9]env,[10]基础币,[11]指数币,[12]计价币,[13]基础币显示名,[14]指数币显示名,[15]计价币显示名 ], "type": "fund_rates", "env": 1 } ``` ### ws 最新成交 #### 请求参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------- | ---------- | ------ | --------- | | biz | y | string | 业务 | | perpetual | | type | y | string | 类型 | | fills | | contractCode | y | string | 合约code | | | | zip | y | boolean | 是否压缩 | | | | serialize | y | boolean | 是否序列化 | | |Request
```json { "event": "subscribe", "params": { "biz": "perpetual", "type": "fills", "contractCode": "btcusdt", "zip": false, "serialize": true } } ``` #### 返回结果Response
```json { "biz": "perpetual", "data": { "result": true }, "channel": "subscribe", "type": "fills", "contractCode": "btcusdt" } ``` #### 推送结果 ```json { "biz": "perpetual", "data": [ []//[0]价格,[1]数量,[2]方向,[3]时间戳毫秒 ], "type": "fills", "env": 0, "contractCode": "btcusdt" } ``` ### ws用户资产（需要登录） #### 请求参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------- | -------- | ------ | --------- | | biz | y | string | 业务 | | perpetual | | type | y | string | 类型 | | assets | | zip | y | boolean | 是否压缩 | | | | serialize | y | boolean | 是否序列化| | |Request
```json { "event": "subscribe", "params": { "biz": "perpetual", "type": "assets", "zip": false, "serialize": false } } ``` #### 返回结果Response
```json { "biz": "perpetual", "data": { "result": true }, "channel": "subscribe", "type": "assets" } ``` #### 推送结果 ```json { "biz": "perpetual", "data": { "totalCnyAccountRights": "3283806187.35",//总的账户权益CNY "totalBtcUnRealizedSurplus": "0",//总的为实现盈亏BTC "data": [ { "cnPrice": "7451165.96",//人民币价格 "appLogo": "https://hotcoin-hk-static.oss-accelerate.aliyuncs.com/hotcoin/upload/coin/a417aec2fc85428aafed802649e227caUSDT.png",//app logo "fee": "0.000000",//费率 "orderFee": "0.001674",//订单手续费 "realAvailableBalance": "1000156.504790",//真实可用余额 "realizedSurplus": "4.014119",//已实现盈余 "availableBalance": "1000156.504790",//可用余额 "positionAccountRights": "1000156.635250",//持仓账户权益(使用用户持仓算出) "maintenanceMargin": "0.000000",//维持保证金 "price": "1000156.50479026",//价格（美元,取的是指数价格） "realPositionAccountRights": "0.000000",//持仓账户权益(取AvailableBalance) "currencyCodeDisplayName": "USDT",//币种显示名 "unRealizedSurplusBtcValue": "0.000000",//未实现盈亏(btc) "unRealizedSurplusValue": "0.000000",//未实现盈亏USDT "accountRightsValue": "1000156.635250",//总账户权益(USDT) "openMargin": "0.000000",//开仓保证金 "frozenBalance": "0.000000",//冻结 "sort": 1,//排序 "env": 0,//是否测试币 0:线上币,1:测试币 "accountRightsBtcValue": "47.215127",//总账户权益(btc) "accountRightsCnValue": "7451166.93",//总账户权益(RNB) "decimalPlaces": 6,//精度 "currentOrderMargin": "0.130460",//当前委托保证金 "webLogo": "https://hotcoin-hk-static.oss-accelerate.aliyuncs.com/hotcoin/upload/coin/a417aec2fc85428aafed802649e227caUSDT.png",//web logo "unRealizedSurplus": "0.000000",//未实现盈亏 "orderMargin": "0.130460",//挂单保证金 "positionMargin": "0.000000",//开仓保证金 "currencyCode": "USDT",//币种 "availableMargin": "0.000000",//可用保证金 "btcValue": "47.21512161"//btc估值 } ], "totalBtcAccountRights": "20808.19422358",//总的账户权益BTC "totalBtcAvaliableMargins": "20808.19421819",//总的可用保证金BTC "userId": 10061//用户ID }, "type": "assets", "env": 0 } ``` ### ws用户订单（需要登录） #### 请求参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------- | -------- | ------ | --------- | | biz | y | string | 业务 | | perpetual | | type | y | string | 类型 | | orders-普通单，condition_orders-条件单 | | zip | y | boolean | 是否压缩 | | | | serialize | y | boolean | 是否序列化| | |Request
```json { "event": "subscribe", "params": { "biz": "perpetual", "type": "orders", "zip": false, "serialize": false } } ``` #### 返回结果Response
```json { "biz": "perpetual", "data": { "result": true }, "channel": "subscribe", "type": "orders" } ``` #### 推送数据 | 类型 | 字段名 | 说明 | | ------ | ------------------------ | ------------------------------------------------------------ | | int | id | 订单ID | | string | contractCode | 合约CODE | | int | contractDirection | 合约方向 0:正向,1:反向 | | string | base | 基础货币名 | | string | quote | 计价货币名 | | int | userId | 用户ID | | string | side | 仓位方向，long多，short空 | | string | detailSide | 1.开多open_long 2.开空open_short 3.平多close_long 4.平空close_short | | int | clazz | 0:下单 1:撤单 | | int | mustMaker | 被动委托：0:不care 1:只做maker，如何是taker就撤单 | | string | amount | 委托数量 | | string | price | 用户订单委托或者破产价格 | | string | avgPrice | 平均成交价格 | | string | dealAmount | 已成交数量 | | string | orderSize | 下单价值 | | string | dealSize | 已经成交价值 | | string | openMargin | 开仓保险金 | | string | extraMargin | 额外价格偏移保证金 | | string | avgMargin | 每张合约摊到的保证金 | | int | systemType | 10:限价 11:市价 13:强平单 14:爆仓单 | | string | profit | 该笔订单成交后对应的盈亏: 正表示盈利,负表示亏损 | | string | fee | 该笔订单成交后交的手续费: 正表示得手续费,负表示付手续费 | | int | reason | 该笔订单取消的理由，0是默认值，没有理由 | | int | createdDate | 创建时间 | | string | triggerPrice | 触发价 | | string | indexBase | 指数基础货币,如BTC、ETH | | int | direction | 触发方向，greater大于，less小于 | | int | stopLimitType | 0 -止损 1-止盈 2-计划 | | int | lever | 杠杆 | | int | orderPriceType | 下单价格类型，对手价：opponent，最优20档：optimal_20，最优10档：optimal_10，最优5档：optimal_5 | | string | triggerBy | 触发类型：指数价格，标记价格，最新价格 | | int | refConditionOrderId | 关联条件单ID | | int | marginDigit | 保证金精度 | | int | positionType | 账户模式 0：全仓，1：逐仓，2：未知（按产品要求不显示） | | int | status | 0 等待成交 1 部分成交 2 已经成交 -1 已经撤销 | | object | stopLoss | 止损对象 | | object | stopProfit | 止盈对象 | | int | modifyDate | 修改时间 | | int | marketPriceDigit | 价格精度 | | int | unitAmount | 面值 | | string | beforeClosePositionPrice | 之前平仓价 | | string | baseDisplayName | 基础币显示名 | | string | quoteDisplayName | 计价币显示名 | | string | contractCodeDisplayName | 合约code显示名 | | string | indexBaseDisplayName | 指数币显示名 | | int | env | env | | int | dualPosition | 单向持仓 0-单向持仓/1-双向持仓 | | int | reduceOnly | 是否只减仓 0-否/1-是 | | int | orderType | 0：普通单，1：止盈止损，2：计划委托 | ```json { "biz": "perpetual", "data": { "reason": 0, "orderType": 0, "extraMargin": "0", "positionType": 1, "avgPrice": "0.00000000", "marginDigit": 4, "orderSize": "2.5651281", "fee": "0.000000", "dualPosition": 0, "quoteDisplayName": "USDT", "quote": "usdt", "baseDisplayName": "USDT", "price": "0.22000000", "indexBase": "bat", "marketPriceDigit": 8, "contractCodeDisplayName": "BATUSDT", "systemType": 10, "id": 157016654939648, "profit": "0.000000", "side": "long", "amount": "1", "modifyDate": 1668072577089, "dealAmount": "0", "openMargin": "0.128256", "contractDirection": 0, "dealSize": "0", "lever": 20, "avgMargin": "0.128256", "userId": 10061, "mustMaker": 0, "indexBaseDisplayName": "BAT", "detailSide": "open_long", "createdDate": 1668072577089, "reduceOnly": 0, "unitAmount": "10", "contractCode": "batusdt", "clazz": 0, "base": "usdt", "status": 0 }, "type": "orders", "env": 0 } ``` ### ws用户仓位（需要登录） #### 请求参数 | 参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 | | ------------ | -------- | ------- | -------- | ------ | --------- | | biz | y | string | 业务 | | perpetual | | type | y | string | 类型 | | position | | contractCode | y | string | 合约code | | | | zip | y | boolean | 是否压缩 | | | | serialize | y | boolean | 是否序列化| | |Request
```json { "event": "subscribe", "params": { "biz": "perpetual", "type": "position", "zip": false, "serialize": false } } ``` #### 返回结果Response
```json { "biz": "perpetual", "data": { "result": true }, "channel": "subscribe", "type": "position" } ``` #### 推送结果 | 类型 | 字段名 | 说明 | | ------ | ---------------------------- | ---------------------------- | | string | closingProfitConditionAmount | 止盈中的数量 | | string | closingLossConditionAmount | 止损中的数量 | | string | closingConditionAmount | 止盈止损中的数量(取最大) | | string | closingAmount | 正在平仓的数量 | | string | amount | 持仓数量 | | string | orderAmount | 订单数量 | | string | orderSize | 挂单价值 | | string | orderFee | 挂单手续费 | | string | orderMargin | 订单保证金 | | string | fee | 手续费 | | string | liqudatePrice | 强平价 | | string | realizedSurplus | 已实现盈余 | | string | availableBalance | 可用余额(保证金) | | string | maintenanceMargin | 维持保证金 | | string | price | 持仓均价 | | string | entireLever | 全仓杠杆(before) | | string | openMargin | 开仓保证金 | | string | lever | 杠杆 | | string | partInLever | | | string | size | 杠杆 | | string | brokerPrice | 爆仓价 | | string | unRealizedSurplus | 未实现盈亏 | | int | createdDate | | | string | unitAmount | 一张合约对应的面值,默认1 | | int | marginDigit | 保证金精度 | | string | openMarginRate | 开仓保证金率 | | int | autoAddMargin | 是否开启自动追加保证金 | | string | base | 基础货币名 | | int | brokerId | 业务方ID | | string | contractCode | 合约Code | | int | env | 是否测试盘 0:线上盘,1:测试盘 | | string | feeRate | 手续费率 | | int | id | 主键id | | string | maintainRate | 维持保证金率 | | int | marketPriceDigit | 精度 | | string | maxLever | 最大杠杆 | | int | modifyDate | | | string | preLiqudatePrice | 预强平价 | | string | quote | 计价币 | | int | score | 计算强减指示灯值 | | string | side | 仓位类型，long多，short空 | | int | type | 0全仓，1逐仓 | | int | userId | 用户ID | | string | indexBase | 指数币 | | string | markPrice | 标记价 | | string | lastPrice | 最新价 | | string | baseDisplayName | 基础币显示名 | | string | quoteDisplayName | 计价币显示名 | | string | contractCodeDisplayName | 合约显示名 | | string | indexBaseDisplayName | 指数币显示名 | | int | dualPosition | //0-单向持仓/1-双向持仓 | ```json { "biz": "perpetual", "data": { "fee": "0", "liqudatePrice": "0.00000000", "realizedSurplus": "0.000000", "type": 1, "onlyPositionPartInLever": 20, "quoteDisplayName": "USDT", "score": 0, "quote": "usdt", "maintenanceMargin": "0", "price": "0.00000000", "indexBase": "band", "id": 230393, "entireLever": "20", "modifyDate": 1668072633091, "lever": "20", "indexBaseDisplayName": "BAND", "onlyPositionEntireLever": 20, "size": "0", "closingAmount": "0", "unitAmount": "1", "unRealizedSurplus": "0.000000", "openMarginRate": "0", "autoAddMargin": 0, "marginDigit": 6, "maxLever": "125", "orderSize": "0", "orderFee": "0", "dualPosition": 0, "feeRate": "0.00065", "availableBalance": "1000156.633050", "markPrice": "1.89923333", "orderAmount": "0", "baseDisplayName": "USDT", "marketPriceDigit": 8, "contractCodeDisplayName": "BANDUSDT", "amount": "0", "brokerId": 1, "side": "long", "openMargin": "0.000000", "partInLever": "20", "env": 0, "userId": 10061, "createdDate": 1668072633169, "maintainRate": "0.025", "brokerPrice": "0", "orderMargin": "0", "contractCode": "bandusdt", "base": "usdt", "lastPrice": "5.92100000" }, "type": "position", "env": 0 } ```