NAV Navbar
shell

Introduction

SWAP API INTRODUCTION

Welcome to use Digideriv SWAP API! You can use the API to get market data, trade, and manage your account.

It is example code on the right of documentation. So far, we only provide shell code example.

You can switch different api version in the top menu, and different language by clicking language button in the top right.

SWAP TRADING INTERFACE

Swap Trading Interface List

Interface List

Permission Type Content Type Context Request Type Description Authorization
Read Market Data /api/v1/contract_contract_info GET Get Contracts Information False
Read Market Data /api/v1/contract_index GET Get Contract Index Price Information False
Read Market Data /api/v1/contract_price_limit GET Get Contract Price Limits False
Read Market Data /api/v1/contract_open_interest GET Get Contract Open Interest Information False
Read Market Data /market/depth GET Get Market Depth False
Read Market Data /market/history/kline GET Get K-Line Data False
Read Market Data /market/trade GET The Last Trade of a Contract False
Read Market Data /market/history/trade GET Request a Batch of Trade Records of a Contract False
Read Account /api/v1/contract_account_info POST User’s Account Information True
Read Account /api/v1/contract_position_info POST User’s Position Information True
Trade Account /api/v1/contract_order POST Place an Order True
Trade Account /api/v1/contract_batchorder POST Place a Batch of Orders True
Trade Account /api/v1/contract_cancel POST Cancel an Order True
Trade Account /api/v1/contract_cancelall POST Cancel All Orders True
Trade Account /api/v1/contract_order_info POST Get Information of an Order True
Trade Account /api/v1/contract_order_detail POST Get Trade Details of an Order True
Trade Account /api/v1/contract_openorders POST Get Current Orders True
Trade Account /api/v1/contract_hisorders POST Get History Orders True

Address

Address Applicable Sites Applicable Functions Applicable Trading Pairs
https://openapi.digideriv.com/perp digideriv SWAP API digideriv SWAP's Trading pairs

Signature Authentication & Verification

You could create API Key in "Account - API setting".

API Key consists of the following two parts.

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

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

Both Access Key and Secret Key are closely related with account security, please do not disclose them to others for any reasons anytime.

Signature Guide

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

A legitimate request consists of following parts:

For example:

https://openapi.digideriv.com/perp/v1/order/orders?

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

&SignatureMethod=HmacSHA256

&SignatureVersion=2

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

&order-id=1234567890

&Signature=calculated value

Generate API Key

You can go to the website generate API Key。

API Key consists of the following two parts.

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

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

Steps for Signature

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

query details of one order:

https://openapi.digideriv.com/perp/v1/order/orders?

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

&SignatureMethod=HmacSHA256

&SignatureVersion=2

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

&order-id=1234567890

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

GET\n

  1. Text the visit address in lowercase, adding line breaker "\n"

openapi.digideriv.com\n

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

/perp/v1/order/orders\n

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

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

SignatureMethod=HmacSHA256

SignatureVersion=2

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

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

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

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

GET\n

openapi.digideriv.com\n

perp/v1/order/orders\n

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

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

GET\n

openapi.digideriv.com\n

perp/v1/order/orders\n

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

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

b0xxxxxx-c6xxxxxx-94xxxxxx-dxxxx

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

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

4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=

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

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

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

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

Details of Each Error Code

Error Code Error Details Description

Swap Market Data Interface

Query Swap Info

Example

Request Parameter

Parameter Name Type Mandatory Description
symbol string false "BTC", "ETH"

Response:


  {
    "status":"ok",
    "ts":1586315506917,
    "data":[
        {
            "symbol":"BTC",
            "contract_code":"BTCPERP",
            "contract_type": None,
            "contract_size":1,
            "price_tick": 0.0001,
            "delivery_date": "99991231",
            "create_date": "20200213", 
            "contract_status":1
        }
    ]
}

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" , "error"
symbol true string symbol "BTC","ETH"...
contract_code true string Contract Code "BTCPERP" ...
contract_size true decimal Contract Value (USD of one contract) 10, 100...
price_tick true decimal Minimum Variation of Contract Price 0.001, 0.01...
delivery_date true string Settlement Date eg"1490759594752"
create_date true string Listing Date eg"1490759594752"
contract_status true int Contract Status 1: Listing,3: Suspension,5: In Settlement,6: Delivering,7: Settlement Completed,8: Delivered
ts true long Time of Respond Generation,Unit:Millisecond

Query Swap Index Price Information

Example


curl "https://openapi.digideriv.com/perp/api/v1/contract_index?symbol=BTC"

Request Parameter

Parameter Name Parameter Type Mandatory Description
symbol string true "BTC","ETH"...

Response:


    {
      "status":"ok",
      "index_ts": 1490759594752,
      "data": [
         {
           "contract_code": "BTCPERP",
           "index_price":471.0817,
           "current_fund_rate": 0.0001, 
           "fair_price": 471, 
           "last_funds_rate": 0.0001
          }
        ],
    }

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" , "error"
index_ts true long Time of Respond Generation,Unit:Millisecond
contract_code true string contract_code "BTCPERP","ETHPERP"...
index_price true decimal Index Price

Query Swap Price Limitation

Example

Request Parameter

Parameter Name Parameter Type Mandatory Description
symbol string false "BTC","ETH"...

Response:


    {
      "status":"ok",
      "ts": 1490759594752,
      "data": 
       [{
          "contract_code":"BTCPERP",
          "high_limit":443.07,
          "low_limit":417.09,
         }],
    }

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" ,"error"
ts true long Time of Respond Generation, Unit: Millisecond
contract_code true string contract_code "BTCPERP", "ETHPERP"...
high_limit true decimal Highest Buying Price
low_limit true decimal Lowest Selling Price

Get Swap Open Interest Information

Example

Request Parameter

Parameter Name Parameter Type Mandatory Description
symbol string false "BTC","ETH"...

Response:


    {
      "status":"ok",
      "ts": 1490759594752,
      "data":
        [{
          "symbol":"BTC",
          "contract_code": "BTCPERP"
          "volume":123,
          "amount":106,
         }],
    }

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" , "error"
ts true long Time of Respond Generation, Unit: Millisecond
symbol true string Variety code "BTC", "ETH" ...
contract_code true string contract_code "BTCPERP", "ETHPERP"...
volume true decimal Position quantity(amount)
amount true decimal Position quantity(Currency)

Get Market Depth

Example

Request Parameter

Parameter Name Parameter Type Mandatory Description
symbol string true "BTC" ...
type string true Get depth data within step 150, use step0, step1, step2, step3, step4, step5(merged depth data 0-5);when step is 0,depth data will not be merged; Get depth data within step 20, use step6, step7, step8, step9, step10, step11(merged depth data 7-11); when step is 6, depth data will not be merged.

tick illustration:

    {
    "ch": "market.BTC.depth.step5", 
    "status": "ok",
    "ts": 1587547748827,
    "tick": {
        "mrid": Order Id,
        "id": Message id.
        "ts": Time of Message Generation, unit: millisecond.
        "version": version,
        "ch": channel,
        "bids": Buying, [price(hanging unit price), vol(this price represent single contract)], According to the descending order of Price.
        "asks": Selling, [price(hanging unit Price), vol(this price represent single contract)], According to the ascending order of Price  .
        }
    }

Response:


    {
      "ch":"market.BTC.depth.step5",
      "status":"ok",
      "ts":1536980854585,
        "tick":{
          "mrid":6903717,
          "id":1536980854,
          "ts":1536980854171,
          "version":1536980854,
          "ch":"market.BTC.depth.step5",
          "bids":[
            [10,3],
            [2,1]
            ],
          "asks":[
            [6580,3000],
            [70000,100]
            ]
        }
    }

Returning Parameter

Parameter Name Mandatory Data Type Description Value Range
ch true string Data belonged channel,Format: market.period
status true string Request Processing Result "ok" , "error"
ts true number Time of Respond Generation, Unit: Millisecond
mrid true string Order Id
asks true object Sell,[price(Ask price), vol(Ask orders (cont.) )], price in ascending sequence
bids true object Buy,[price(Bid price), vol(Bid orders(Cont.))], Price in descending sequence

Note

Depth Type precision
step1、step7 0.00001
step2、step8 0.0001
step3、step9 0.001
step4、step10 0.01
step5、step11 0.1

Get K-Line Data

Example

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol true string contract_code Case-Senstive.Only uppercase is supported.e.g."BTC" ...
period true string K-Line Type 1min, 5min, 15min, 30min, 60min,4hour,1day, 1mon
size false integer Acquisition Quantity 150 [1,2000]

Note

Data Illustration:

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

Response:


    {
      "ch": "market.BTC.kline.1min",
      "status":"ok",
      "ts":1536980854585,
      "data": [
        {
          "id": 1529898120,
          "vol": 2446,
          "close": 5000,
          "count": 2446,
          "high": 5000,
          "low": 5000,
          "open": 5000,
          "amount": 48.92
         },
        {
          "id": 1529898780,
          "vol": 0,
          "close": 5000,
          "count": 0,
          "high": 5000,
          "low": 5000,
          "open": 5000,
          "amount": 0
         }
       ]
    }

Returning Parameter

Parameter Name Mandatory Data Type Description Value Range
ch true string Data belonged channel,Format: market.period
data true object K-Line Data
status true string Request Processing Result "ok" , "error"
ts true number Time of Respond Generation, Unit: Millisecond

The Last Trade of a Contract

Example

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol true string "BTC" ...

Tick Illustration:

    "tick": {
      "ch": "market.BTC.trade.detail",
      "id": Message id,
      "ts": Latest Transaction time,
      "data": [
        {
       "id": Transaction id,
        "price": Transaction price,
         "amount": transaction amount,
         "direction": active transaction direction,
         "ts": transaction time,
         "quoteVolume": transaction volume,
        }
      ]
    }

Response:


    {
      "ch": "market.BTC.trade.detail",
      "status": "ok",
      "ts": 1529388202797,
      "tick": {
        "data": [
          {
            "id": 6010881529486944176,
            "direction": "sell",
            "ts": 1529386945343,
            "price": "5000",
            "amount": "2",
            "quoteVolume":"14564"
           }
         ],
        "id": 1529388202797,
        "ts": 1529388202797
        }
    }

Returning Parameter

Parameter Name Mandatory Type Description Default Value Range
ch true string Data belonged channel,Format: market.$symbol.trade.detail
status true string "ok","error"
tick true object Transaction Data
ts true number Order Creation Time

Request a Batch of Trade Records of a Contract

Example

Request Parameter:

Parameter Name Mandatory Data Type Description Default Value Range
symbol true string "BTC" ...
size true number Number of Trading Records Acquisition 1 [1, 1000]

data Illustration:


    "data": {
      "id": Message id,
      "ts": Latest transaction time,
      "data": [
        {
          "id": Transaction id,
          "price": transaction price,
          "amount": transaction (amount),
          "direction": active transaction direction,
          "ts": transaction time,
         "quoteVolume": transaction volume
        }
      ]
    }

Response:


    {
      "ch": "market.BTC.trade.detail",
      "status": "ok",
      "ts": 1529388050915,
      "data": [
        {
          "id": 601088,
          "ts": 1529386945343,
          "data": [
            {
             "direction": "sell",
             "id": 6010881529486944176,
             "ts": 1529386945343,
             "price": 5000,
             "amount": 2,
             "quoteVolume":"14564"
             }
           ]
        }
       ]
    }

Returning Parameter

Parameter Name Mandatory Data Type Description Value Range
ch true string Data belonged channel,Format: market.$contract_code.trade.detail
data true object Transaction data
status true string "ok","error"
ts true number Time of Respond Generation, Unit: Millisecond

Swap Account Interface

User’s Account Information

Example

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol false string "BTC", "ETH"... Return all

Response:


    {
      "status": "ok",
      "data": [
        {
          "symbol": "BTC",
          "contract_code": "BTCPERP",
          "margin_balance": 1,
          "margin_static": 0.5,
          "margin_position": 0,
          "margin_frozen": 3.33,
          "margin_available": 0.34,
          "profit_real": 3.45,
          "profit_unreal": 7.45,
          "withdraw_available":4.0989898,
          "risk_rate": 100,
          "liquidation_price": 100,
          "adjust_factor": 0.1
         },
        {
          "symbol": "ETH",
          "contract_code": "ETHPERP",
          "margin_balance": 1,
          "margin_static": 0.5,
          "margin_position": 0,
          "margin_frozen": 3.33,
          "margin_available": 0.34,
          "profit_real": 3.45,
          "profit_unreal": 7.45,
          "withdraw_available":4.7389859,
          "risk_rate": 100,
          "liquidation_price": 100,
          "adjust_factor": 0.1
         }
       ],
      "ts":158797866555
    }

Returning Parameter

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

User’s position Information

Example

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol false string contract_code Return All "BTC", "ETH"...

Response:


    {
      "status": "ok",
      "data": [
        {
          "symbol": "BTC",
          "contract_code": "BTCPERP",
          "volume": 1,
          "available": 0,
          "frozen": 0.3,
          "cost_open": 422.78,
          "cost_hold": 422.78,
          "profit_unreal": 0.00007096,
          "profit_rate": 0.07,
          "profit": 0.97,
          "position_margin": 3.4,
          "lever_rate": 10,
          "direction":"buy",
          "last_price":7900.17
         }
        ],
     "ts": 158797866555
    }

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" , "error"
symbol true string Variety code "BTC","ETH"...
contract_code true string contract_code "BTC", "ETH"...
volume true decimal Position quantity
available true decimal Available position can be closed
frozen true decimal frozen
cost_open true decimal Opening average price
cost_hold true decimal Average price of position
profit_unreal true decimal Unrealized profit and loss
profit_rate true decimal Profit rate
profit true decimal profit
position_margin true decimal Position margin
lever_rate true int Leverage rate
direction true string Transaction direction
last_price true decimal Latest price
ts true long Time of Respond Generation, Unit: Millisecond

Swap Trade Interface

Place an Order

Example

Request Parameter

Parameter Name Parameter Type Mandatory Description
symbol string true "BTC", "ETH"...
client_order_id int false Clients fill and maintain themselves
price decimal true Price
volume long true Numbers of orders (amount)
direction string true Transaction direction
offset string true "open", "close"
lever_rate int true Leverage rate [if“Open”is multiple orders in 10 rate, there will be not multiple orders in 20 rate. After using main account to log in website and agree the high leverage contract, it can use high leverage interface(>20)]
order_price_type string true "limit”: Limit Order "opponent":BBO "post_only": Post-Only Order, No order limit but position limit for post-only orders.,optimal_5: Optimal , optimal_10: Optimal 10, optimal_20:Optimal 20,ioc: IOC Order,fok:FOK Order, "opponent_ioc":IOC order using the BBO price,"optimal_5_ioc":optimal_5 IOC,"optimal_10_ioc":optimal_10 IOC,"optimal_20_ioc":optimal_20 IOC, "opponent_fok":FOK order using the BBO price,"optimal_5_fok":optimal_5 FOK,"optimal_10_fok":optimal_10 FOK,"optimal_20_fok":optimal_20 FOK

Note

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

Direction

open long: direction - buy、offset - open

close long: direction -sell、offset - close

open short: direction -sell、offset - open

close short: direction -buy、offset - close

Response:


    {
      "status": "ok",
      "data": {
            "order_id": 88,
            "order_id_str": "88"
          },
      "ts": 158797866555
    }

Returning Parameter

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

Place a Batch of Orders

Example

Request Parameter

Parameter Name Parameter Type Mandatory Description
orders_data List<Object>
Parameter Name Parameter Type Mandatory Description
symbol string true "BTC", "ETH"...
client_order_id int false Clients fill and maintain themselves
price decimal true Price
volume long true Numbers of orders (amount)
direction string true Transaction direction
offset string true "open": "close"
lever_rate int true Leverage rate [if“Open”is multiple orders in 10 rate, there will be not multiple orders in 20 rate. After using main account to log in website and agree the high leverage contract, it can use high leverage interface(>20)]
order_price_type string true "limit”: Limit Order "opponent":BBO "post_only": Post-Only Order, No order limit but position limit for post-only orders.,optimal_5: Optimal , optimal_10: Optimal 10, optimal_20:Optimal 20,ioc: IOC Order,fok:FOK Order, "opponent_ioc":IOC order using the BBO price,"optimal_5_ioc":optimal_5 IOC,"optimal_10_ioc":optimal_10 IOC,"optimal_20_ioc":optimal_20 IOC, "opponent_fok":FOK order using the BBO price,"optimal_5_fok":optimal_5 FOK,"optimal_10_fok":optimal_10 FOK,"optimal_20_fok":optimal_20 FOK

Note

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

10 orders at most.

Response:


    {
      "status": "ok",
      "data": {
        "errors":[
          {
            "index":0,
            "err_code": 200417,
            "err_msg": "invalid contract_code"
           },
          {
            "index":3,
            "err_code": 200415,
            "err_msg": "invalid contract_code"
           }
         ],
        "success":[
          {
            "index":1,
            "order_id":161256,
            "order_id_str": "88",
            "client_order_id":1344567
           },
          {
            "index":2,
            "order_id":161257,
            "order_id_str": "88",
            "client_order_id":1344569
           }
         ]
       },
      "ts": 1490759594752
    }

Returning Parameter

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

Cancel an Order

Example

Request Parameter

Parameter Name Mandatory Type Description
order_id false string Order ID(different IDs are separated by ",", maximum 10 orders can be withdrew at one time)
symbol true string "BTC", "ETH"...

Note:

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

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

Response:


{
  "status": "ok",
  "data": {
    "errors":[
      {
        "order_id":"161251",
        "err_code": 200417,
        "err_msg": "invalid contract_code"
       },
      {
        "order_id":161253,
        "err_code": 200415,
        "err_msg": "invalid contract_code"
       }
      ],
    "successes":[161256,1344567]
   },
  "ts": 1490759594752
}

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" , "error"
order_id true string Order Id
err_code true int Error code
err_msg true string Error information
successes true string Successfully withdrew list of order_id or client_order_id
ts true long Time of Respond Generation, Unit: Millisecond

Cancel All Orders

Example

Request Parameter

Parameter Name Mandatory Type Description
symbol true string "BTC", "ETH"...

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


    {
      "status": "ok",
      "data": {
        "errors":[
          {
            "order_id":"161251",
            "err_code": 200417,
            "err_msg": "invalid symbol"
           },
          {
            "order_id":161253,
            "err_code": 200415,
            "err_msg": "invalid symbol"
           }
          ],
        "successes":[161256,1344567]
       },
      "ts": 1490759594752
    }

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" , "error"
order_id true String Order Id
err_code true int failed order error message Error code
err_msg true int failed order information
successes true string Successful order
ts true long Time of Respond Generation, Unit: Millisecond

Get Information of an Order

Example

Request Parameter

Parameter Name Mandatory Type Description
order_id false string Order ID(different IDs are separated by ",", maximum 50 orders can be withdrew at one time)
symbol true string "BTC", "ETH"...

Note:

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

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

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

Response:


    {
      "status": "ok",
      "data":[
        {
          "symbol": "BTC",
          "contract_code": "BTCPERP",
          "volume": 111,
          "price": 1111,
          "order_price_type": "limit",
          "direction": "buy",
          "offset": "open",
          "lever_rate": 10,
          "order_id": 106837,
          "order_id_str": "88",
          "client_order_id": 10683,
          "order_source": "web",
          "order_type": "1",
          "created_at": 1408076414000,
          "trade_volume": 1,
          "trade_turnover": 1200,
          "fee": 0,
          "fee_asset": "BTC", 
          "trade_avg_price": 10,
          "margin_frozen": 10,
          "profit": 10,
          "status": 0
         },
        {
          "symbol": "ETH",
          "contract_code": "BTCPERP",
          "volume": 111,
          "price": 1111,
          "order_price_type": "limit",
          "direction": "buy",
          "offset": "open",
          "lever_rate": 10,
          "order_id": 106837,
          "order_id_str": "88",
          "client_order_id": 10683,
          "order_source": "web",
          "order_type": "1",
          "created_at": 1408076414000,
          "trade_volume": 1,
          "trade_turnover": 1200,
          "fee": 0,
          "fee_asset": "BTC", 
          "trade_avg_price": 10,
          "margin_frozen": 10,
          "profit ": 10,
          "status": 0
         }
        ],
      "ts": 1490759594752
    }

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" , "error"
symbol true string Variety code
contract_code true string contract_code "BTC", "ETH"...
volume true decimal Numbers of order
price true decimal Price committed
order_price_type true string Order Price Type "limit", "opponent","post_only" Position limit will be applied to post_only while order limit will not.
direction true string Transaction direction "buy", "sell"
offset true string Open, Close "open", "close"
lever_rate true int leverage rate 1\5\10\20
order_id true long Order Id
order_id_str true string Order Id
client_order_id true long Client Order Id
created_at true long Creation time
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction aggregate amount
fee true decimal Service fee
fee_asset true string the corresponding cryptocurrency to the given fee "BTC","ETH"...
trade_avg_price true decimal Transaction average price
margin_frozen true decimal Freeze margin
profit true decimal profit
status true int Order Status status: 1. Ready to submit the orders; 2. Ready to submit the orders; 3. Have sumbmitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled; 10.Orders failed. 11. Orders cancelling.
order_type true string Order type 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
order_source true string Order Source (1:system、2:web、3:api、4:m 5:risk、6:settlement)
ts true long Timestamp

Get Trade Details of an Order

Example

Request Parameter

Parameter Name Mandatory Type Description
symbol true string "BTC", "ETH"...
order_id true long Order Id
created_at false long Timestamp
order_type true int Order type: 1. Quotation; 2. Cancelled order; 3. Forced liquidation; 4. Delivery Order
page_index false int Page number, default 1st page
page_size false int Default 20,no more than 50

Note

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

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

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

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

Please note that created_at can't send "0".

Response:


    {
      "status": "ok",
      "data":{
        "symbol": "BTC",
        "contract_code": "BTCPERP",
        "volume": 111,
        "price": 1111,
        "order_price_type": "limit",
        "direction": "buy",
        "offset": "open",
        "lever_rate": 10,
        "margin_frozen": 10,
        "profit": 10,
        "order_source": "web",
        "created_at": 1408076414000,
        "canceled_at": 1408076414000,
        "instrument_price" : 10000,
        "final_interest" : 0,
        "adjust_value" : 0,
        "trades":[
          {
            "trade_id":112,
            "id": "1232-213123-1231",
            "trade_volume":1,
            "trade_price":123.4555,
            "trade_fee":0.234,
            "fee_asset": "BTC", 
            "trade_turnover":34.123,
            "role": "maker",
            "created_at": 1490759594752
          }
        ],
        "total_page":15,
        "total_size":3,
        "current_page":3
        },
      "ts": 1490759594752
    }

Error:


    {
     "status":"error",
     "err_code":20029,
     "err_msg": "invalid contract_code",
     "ts": 1490759594752
    }

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result "ok" , "error"
symbol true string Variety code
contract_code true string contract_code "BTC", "ETH"...
lever_rate true int Leverage Rate 1\5\10\20
direction true string Transaction direction "buy", "sell"
offset true string "open": "close" "open": "close"
volume true decimal Number of Order
price true decimal Price committed
created_at true long Creation time
canceled_at true long Cancellation Time
order_source true string Order Source
order_price_type true string Order Price Type "limit", "opponent","post_only" Position limit will be applied to post_only while order limit will not.
margin_frozen true decimal Freeze margin
profit true decimal profit
total_page true int Page in total
current_page true int Current Page
total_size true int Total Size
instrument_price true decimal Liquidation price
final_interest true decimal Account Balance After Liquidation
adjust_value true decimal Adjustment Factor of Liquidating Order
fee true decimal total amount of fees
fee_asset true string The corresponding cryptocurrency to the given fee
liquidation_type true string 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
trade_id true long In this interface, trade_id is the same with match_id of swap-api/v1/swap_matchresults. trade_id is the result of sets of order execution and trade confirmation. NOTE: trade_id is not unique, which includes all trade records of a taker order and N maker orders. If the taker order matches with N maker orders, it will create N trades with same trade_id.
id true string the global unique ID of the trade.
trade_price true decimal Match Price
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction amount
trade_fee true decimal Transaction Service fee
role true string taker or maker
ts true long Timestamp

Get Current Orders

Example

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol true string contract_code "BTC", "ETH"...
page_index false int Page, default 1st page 1
page_size false int Default 20,no more than 50

Response:


    {
      "status": "ok",
      "data":{
        "orders":[
          {
             "symbol": "BTC",
             "contract_code": "BTCPERP",
             "volume": 111,
             "price": 1111,
             "order_price_type": "limit",
             "order_type": 1,
             "direction": "buy",
             "offset": "open",
             "lever_rate": 10,
             "order_id": 106837,
             "order_id_str": "88",
             "client_order_id": 10683,
             "order_source": "web",
             "created_at": 1408076414000,
             "trade_volume": 1,
             "trade_turnover": 1200,
             "fee": 0,
             "fee_asset": "BTC", 
             "trade_avg_price": 10,
             "margin_frozen": 10,
             "status": 1,
             "profit": 1.231
            }
           ],
        "total_page":15,
        "current_page":3,
        "total_size":3
       },
      "ts": 1490759594752
    }

Returning Parameter

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

Get History Orders

Example

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol true string contract_code "BTC", "ETH"...
trade_type true int TradeType 0:all,1: buy long,2: sell short,3: buy short,4: sell long,5: sell liquidation,6: buy liquidation,7:Delivery long,8: Delivery short,11:reduce positions to close long,12:reduce positions to close short
type true int Type 1:All Orders,2:Order in Finished Status
status true int Order Status 3. Have submitted the orders; 4. Orders partially matched; 5. Orders cancelled with partially matched; 6. Orders fully matched; 7. Orders cancelled;
create_date true int Date any positive integer available. Requesting data beyond 90 will not be supported, otherwise, system will return trigger history data within the last 90 days by default.
page_index false int Page, default 1st page 1
page_size false int Default 20 20 no more than 50

Note:

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

Response:


    {
      "status": "ok",
      "data":{
        "orders":[
          {
            "symbol": "BTC",
            "contract_code": "BTCPERP",
            "volume": 111,
            "price": 1111,
            "order_price_type": "1",
            "direction": "buy",
            "offset": "open",
            "lever_rate": 10,
            "order_id": 106837,
            "order_id_str": "88",
            "order_source": "web",
            "create_date": 1408076414000,
            "trade_volume": 1,
            "trade_turnover": 1200,
            "fee": 0,
            "fee_asset": "BTC", 
            "trade_avg_price": 10,
            "margin_frozen": 10,
            "profit": 10,
            "status": 1,
            "order_type": 1
          }
         ],
        "total_page":15,
        "current_page":3,
        "total_size":3
        },
      "ts": 1490759594752
    }

Returning Parameter

Parameter Name Mandatory Type Description Value Range
status true string Request Processing Result
order_id true long Order Id
order_id_str true string Order Id
symbol true string Variety code
contract_code true string contract_code "BTC", "ETH"...
lever_rate true int Leverage Rate 1\5\10\20
direction true string Transaction direction "buy", "sell"
offset true string "open": "close" "open": "close"
volume true decimal Number of Order
price true decimal Price committed
create_date true long Creation time
order_source true string Order Source
order_price_type true string Order Price Type 1:限价单,3:对手价,4:闪电平仓,5:计划委托,6:post_only
margin_frozen true decimal Freeze margin
profit true decimal profit
trade_volume true decimal Transaction quantity
trade_turnover true decimal Transaction aggregate amount
fee true decimal Service fee
fee_asset true string the corresponding cryptocurrency to the given fee "BTC","ETH"...
trade_avg_price true decimal Transaction average price
status true int Order Status
order_type true int Order type 1Requested orders; 2. Cancelled orders; 3. Liquidated orders; 4. Delivered orders
liquidation_type true string 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
total_page true int Total Pages
current_page true int Current Page
total_size true int Total Size
ts true long Timestamp

Swap WebSocket Reference

API List

Permission Category URL Path Type Description Authorization
Read Market Data market.$symbol.kline.$period sub Subscribe KLine data False
Read Market Data market.$symbol.kline.$period req Request Kline Data False
Read Market Data market.$symbol.depth.$type sub Subscribe Market Depth Data False
Read Market Data market.$symbol.detail sub Subscribe Market Detail Data False
Read Market Data market.$symbol.trade.detail req Request Trade Detail Data False
Read Market Data market.$symbol.trade.detail sub Subscribe Trade Detail Data False
Read Market Data indexs.$symbol sub Subscribe Index Price Data False
Trade Trade Interface matchorders.$symbol sub Subscribe Order Data True
Read Account Interface accounts.$symbol sub Subscribe asset change Information of a given coin True
Read Account Interface positions.$symbol sub Subscribe position change Information of a given coin True
Read Trade Interface liquidationOrders.$symbol sub Subscribe Liquidated Orders Information of a given coin True

WebSocket Subscription Address

Market Data Request and Subscription:wss://openapi.digideriv.com/perp/ws

WebSoket Heartbeat and Authentication Interface

Market Heartbeat

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

WebSocket Server sends heartbeat: {"ping": 18212558000} WebSocket Client should respond:: {"pong": 18212558000} Note: Once the WebSocket Client and WebSocket Server get connected, the server will send a heartbeat every 5 seconds (the frequency might change). The connection will get disconnected automatically if the WebSocket Client ignores the heartbeat message for 2 times.

┌────────┐                         ┌────────┐
│ Client │                         │ Server │
└───┬────┘                         └───┬────┘
    │         {"ping": 18212558000}  │
    │<─────────────────────────────────┤
    │                                  │ wait 5s
    │                                  ├───┐
    │                                  │<──┘
    │         {"ping": 18212558000}  │
    │<─────────────────────────────────┤
    │                                  │
    │ {"pong": 18212558000}          │
    ├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄>│
    │                                  │

Note: The server will remain connection if the WebSocket Client responds one “ping” value within the latest 2 heartbeat messages.

┌────────┐                         ┌────────┐
│ Client │                         │ Server │
└───┬────┘                         └───┬────┘
    │         {"ping": 1523778470416}  │
    │<─────────────────────────────────┤
    │                                  │ wait 5s
    │                                  ├───┐
    │                                  │<──┘
    │         {"ping": 1523778475416}  │
    │<─────────────────────────────────┤
    │                                  │ wait 5s
    │                                  ├───┐
    │                                  │<──┘
    │                                  │
    │                                  │ close WebSocket connection
    │                                  ├───┐
    │                                  │<──┘
    │                                  │

Data Compression

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

Illustration of Request(req and rep) Data

Request data format is laid out as below:

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

All responses push data will be returned in fixed format,Huobi DM API document will only focus on data illustration, Response data format is laid out as below;

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

Push Data Format is laid out as below:

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

Authentication

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

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

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

Authentication Format Example:

{

"op": "auth",

"type": "api",

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

"SignatureMethod": "HmacSHA256",

"SignatureVersion": "2",

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

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

}

Illustration on Authentication Format Data

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

Notice:

Authentication Response Format Illustration

名称 Type Description
op string required; Operator type, Authentication response type is auth
type string required; Return data according to the requested parameters
cid string optional; Return data when “cid” string requested
err-code integer 0 means successfully response, others means response failure return 0 if success , For detailed Response code(Err-Code), please refer to appendix
err-msg string optional, response detailed error code when error occurs
ts long server responds timestamp
user-id long client ID

Example of A Success Authentication Response

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

Example of Authentication Response with Error

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

WebSocket Market Interface

Subscribe K-line data

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

{

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

"id": "id generate by client"

}

Example of a successful subscription request:


  {
      "id": "id1",
      "status": "ok",
      "subbed": "market.BTC.kline.1min",
      "ts": 1489474081631
  }

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
contract_code true string contract_code "BTC", "ETH"...
period true string Kline Period 1min, 5min, 15min, 30min, 1hour,4hour,1day, 1mon

Example of a successful subscription request:

{

"sub": "market.BTC.kline.1min",

"id": "id1"

}

Returning Parameter

Parameter Name Mandatory Type Description
ch true string Request Parameter
ts true long Time of Respond Generation, Unit: Millisecond
id true number ID
mrid true number Order Id
vol true decimal Trade Volume(Cont.)
count true decimal Order Quantity
open true decimal Opening Price
close true decimal Closing Price, the price in the last kline is the latest order price
low true decimal Low
high true decimal High
amount true decimal Trade Volume(Coin), trade volume(coin)=sum(order quantity of a single order * face value of the coin/order price)

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


   {
    "ch": "market.BTC.kline.1min",
    "ts": 1489474082831,
    "tick": {
        "id": 1489464480,
        "mrid": 268168237,
        "vol": 100,
        "count": 0,
        "open": 7962.62,
        "close": 7962.62,
        "low": 7962.62,
        "high": 7962.62,
        "amount": 0.3
    }
   }

Request Kline Data

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

{

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

"id": "id generated by client",

"from": " type: long, 2017-07-28T00:00:00+08:00 至2050-01-01T00:00:00+08:00 之间的时间点,单位:秒",

"to": "type: long, 2017-07-28T00:00:00+08:00 至2050-01-01T00:00:00+08:00 之间的时间点,单位:秒,必须比 from 大"

}

Example of Kline Data Subscription Request:


    {
    "req": "market.BTC.kline.1min",
    "id": "id4"
    }

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol true string Trade对 e.g."BTC","ETH","EOS"...
period false string Kline Period 1min, 5min, 15min, 30min, 60min,4hour,1day,1week, 1mon
from true long Start Time
to true long End Time

Note

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

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

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

from: t5, return [t5].

from: t3, return [t3, t5].

to: t5, return [t1, t5].

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

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

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

Clients can request 2000 Klines at most in one request.

Returning Parameter

Parameter Name Mandatory Type Description
rep true string Request Parameter
status true string status
id true string Request ID
wsid true long wsid
id true long ID
vol true decimal Trade Volume(Cont.)
count true decimal Order Quantity
open true decimal Opening Price
close true decimal Closing Price, the price in the last kline is the latest order price
low true decimal Low
high true decimal High
amount true decimal Trade Volume(Coin), trade volume(coin)=sum(order quantity of a single order * face value of the coin/order price)

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


    {
     "rep": "market.BTC.kline.1min",
     "status": "ok",
     "id": "id4",
     "wsid": 3925737956,
     "data": [
       {
        "vol": 100,
        "count": 27,
        "id": 1494478080,
        "open": 10050.00,
        "close": 10058.00,
        "low": 10050.00,
        "high": 10058.00,
        "amount": 175798.757708
       },
       {
        "vol": 300,
        "count": 28,
        "id": 1494478140,
        "open": 10058.00,
        "close": 10060.00,
        "low": 10056.00,
        "high": 10065.00,
        "amount": 158331.348600
       }
     ]
    }

Subscribe Market Depth Data

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

{

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

"id": "id generated by client"

}

Example of a successful subscription request:


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

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol true string contract_code "BTC", "ETH"...
type true string Depth Type Get depth data within step 150, use step0, step1, step2, step3, step4, step5(merged depth data 0-5);when step is 0,depth data will not be merged; Get depth data within step 20, use step6, step7, step8, step9, step10, step11(merged depth data 7-11); when step is 6, depth data will not be merged.

Note

Depth Type precision
step1、step7 0.00001
step2、step8 0.0001
step3、step9 0.001
step4、step10 0.01
step5、step11 0.1

Return Parameter

Parameter Name Mandatory Data Type Description Value Range
ch true string Data channel, Format: market.period
ts true number Time of Respond Generation, Unit: Millisecond
mrid true number Order Id
id true number tick ID
asks true object Sell,[price(Ask price), vol(Ask orders (cont.) )], price in ascending sequence
bids true object Buy,[price(Bid price), vol(Bid orders(Cont.))], Price in descending sequence
ts true number Time of Respond Generation, Unit: Millisecond
version true number version ID
ch true string Data channel, Format: market.period

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

{ "ch": "market.BTC.depth.step0", "ts": 1489474082831, "tick": { "mrid": 269073229, "id": 1539843937, "bids": [ [9999.9101,1], [9992.3089,2] ], "asks": [ [10010.9800,10], [10011.3900,15] ], "ts": 1539843937417, "version": 1539843937, "ch": "market.BTC.depth.step0" } }



## Subscribe Market Detail Data

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

  `{ `

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

  ` "id": "id generated by client" `

  `} `

> Example of Subscribe Market Detail Data:

```json

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

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol true string contract_code "BTC", "ETH"...

Example of a successful return data:


  {
    "ch": "market.BTC.detail",
    "ts": 1539842340724,
    "tick": {
        "id": 1539842340,
        "mrid": 268041138,
        "open": 6740.47,
        "close": 7800,
        "high": 7800,
        "low": 6726.13,
        "amount": 477.1200312075244664773339914558562673572,
        "vol": 32414,
        "count": 1716
      }
  }

Returning Parameter

Parameter Name Mandatory Data Type Description
ch true string Data channel,Format: market.$symbol.detail.merged
ts true number Time of Respond Generation, Unit: Millisecond
<list>(属性名称: tick)
id true number ID
mrid true number Order Id
open true decimal Opening Price
close true decimal Closing Price, the price in the last kline is the latest order price
high true decimal High
low true decimal Low
amount true decimal Trade Volume(Coin), trade volume(coin)=sum(order quantity of a single order * face value of the coin/order price)
vol true decimal Trade volue(Cont.), the sum volume of both buy and sell sides
count true decimal Order Quantity

Request Trade Detail Data

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

{

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

"id": "id generated by client"

}

Return to the current trade detail data only

Example of requesting market detail data:


    {
     "req": "market.BTC.trade.detail",
     "id": "id8"
    }

Returning Parameter

Parameter Name Mandatory Type Description Default
rep true string Data Channel,Format: market.\$contract_code.trade.detail
status true string Request Status
id true number ID
id true number ID
price true decimal Price
amount true decimal Quantity(Cont.)
direction true string Transaction direction
ts true number Order Creation Time

Example of a successful return data:


    {
     "ch": "market.BTC.trade.detail",
     "ts": 1489474082831,
     "data": [
              {
               "id":601595424,
               "price":10195.64,
               "amount":100,
               "direction":"buy",
               "ts":1494495766000
               },
              {
              "id":601595423,
              "price":10195.64,
              "amount":200,
              "direction":"buy",
              "ts":1494495711000
              }
            ]
     }

Subscribe Trade Detail Data

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

{

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

"id": "id generated by client"

}

Note

Clients can only access the recent 300 trade detail data.

Request Parameter

Parameter Name Mandatory Type Description Default Value Range
symbol true string contract_code "BTC", "ETH"...

Example of a successful subscription request:


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

Returning Parameter

Parameter Name Mandatory Type Description Default
ch true string Data channel,format: market.$symbol.trade.detail
ts true number Request time
id true number ID
ts true number Request time
amount true decimal Quantity(Cont.)
ts true number Request time
id true number tick id
price true decimal Price
direction true string Transaction direction

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


  {
        "ch": "market.BTC.trade.detail",
        "ts": 1539831709042,
        "tick": {
            "id": 265842227,
            "ts": 1539831709001,
            "data": [{
                "amount": 20,
                "ts": 1539831709001,
                "id": 265842227259096443,
                "price": 6742.25,
                "direction": "buy"
            }]
    }
  }

WebSocket Orders and Accounts Interfaces

Subscribe Order Data(sub)

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

Subscribe Request Format

{

"op": "sub",

"cid": "id generated by client",

"topic": "topic to sub"

}

Data format illustration of orders subscription

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

Illustration on detailed data format of orders Notification


    {
    "op": "notify", 
    "topic": "orders.BTC", 
    "ts": 1489474082831, 
    "symbol": "BTC",
    "contract_code": "BTCPERP",
    "volume": 111, 
    "price": 1111, 
    "order_price_type": "limit", 
    "direction": "buy", 
    "offset": "open",
    "status": 6 ,
    "lever_rate": 10, 
    "order_id": 106837,
    "order_id_str": "88",
    "client_order_id": 10683, 
    "order_source": "web", 
    "order_type": 1, 
    "created_at": 1408076414000, 
    "trade_volume": 1, 
    "trade_turnover": 1200, 
    "fee": 0, 
    "trade_avg_price": 10, 
    "margin_frozen": 10, 
    "profit": 2, 
    "trade":[{
        "trade_id":112, 
        "id": "1232-213123-1231",
        "trade_volume":1, 
        "trade_price":123.4555,
        "trade_fee":0.234, 
        "fee_asset": "BTC", 
        "trade_turnover":34.123, 
        "created_at": 1490759594752, 
        "role": "maker" 
      }]
    }

Format Illustration on return data of order push

Field Name Type Description
op string Required;Operator Name,Order push value is notify ;
topic string Required; Order push topic
ts long Server responses timestamp
symbol string Coin
contract_code string contract_code
volume decimal Number of Order
price decimal Price committed
order_price_type string "limit", "opponent","post_only" Position limit will be applied to post_only while order limit will not.
direction string "buy", "sell"
offset string "open": "close"
status int Order status(1. Placing orders to order book; 2 Placing orders to order book; 3. Placed to order book 4. Partially fulfilled; 5 partially fulfilled but cancelled by client; 6. Fully fulfilled; 7. Cancelled; 11Cancelling)
lever_rate int Leverage Rate
order_id long Order Id
order_id_str string Order Id
client_order_id long Client order ID
order_source int Order source(system: System; Web: web; API: api; m:Mobile; risk: risk control system)
order_type int Order type 1Requested orders; 2. Cancelled orders; 3. Liquidated orders; 4. Delivered orders
created_at long Order Creation time
trade_volume decimal Transaction quantity
trade_turnover decimal Transaction aggregate amount
fee decimal Service fee
trade_avg_price decimal Transaction average price
margin_frozen decimal Freeze margin
profit decimal profit
liquidation_type string 0: Non-liquidated,1: Long and short netting,2: Partial liquidated,3: Full liquidated
(属性名称: trade)
trade_id long In this interface, trade_id is the same with match_id of swap-api/v1/swap_matchresults. trade_id is the result of sets of order execution and trade confirmation. NOTE: trade_id is not unique, which includes all trade records of a taker order and N maker orders. If the taker order matches with N maker orders, it will create N trades with same trade_id.
id string the global unique ID of the trade.
trade_volume decimal Transaction quantity
trade_price decimal Match Price
trade_fee decimal Transaction Service fee
fee_asset string the corresponding cryptocurrency to the given fee
trade_turnover decimal Transaction amount
created_at long trade creation time
role string taker or maker

Unsubscribe Order Data(unsub)

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

Format of Unsubscribe order data

{

"op": "unsub",

"topic": "topic to unsub",

"cid": "id generated by client",

}

Example of a successful unsubscribe request:


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

Format illustration of unsubscribe order data

Field Name Type Description
op string Required;Operator Name,value for unsubscribe is unsub;
cid string Optional; Client requests unique ID
topic string Optional; Unsubscribe Topic Name,format: orders.$contract_code; contract_code is case-insenstive.Both uppercase and lowercase are supported.e.g. "BTC-USD"

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe( unsub) ) Rule
orders.* orders.* Allowed
orders.contract_code1 orders.* Allowed
orders.contract_code1 orders.contract_code1 Allowed
orders.contract_code1 orders.contract_code2 Not Allowed
orders.* orders.contract_code1 Not Allowed

Subscribe Account Equity Updates Data(sub)

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

Request Format for Subscribe Account Equity Updates Data

{
  "op": "sub",
  "cid": "id generated by client",
  "topic": "topic to sub"
}

Example of a successful subscribe request:


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

Format illustration on request subscribe account equity updates data

Field Name Type Description
op string Required; Operator Name,Subscribe value is sub
cid string Optional; Client requests unique ID
topic string Required; Subscribe Topic Name,Required subscribe accounts.$contract_code Subscribe/unsubscribe the balance change of a given coin,when the value of $contract_code is “*”, it means to subscribe/unsubscribe the balance change of all coins; contract_code is case-insenstive.Both uppercase and lowercase are supported.

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


{
    "op": "notify",
    "topic": "accounts.BTCPERP",
    "ts": 1489474082831,
    "event": "order.match",
    "data": [{
        "symbol": "BTC",
        "contract_code": "BTCPERP",
        "margin_balance": 1,
        "margin_static": 1,
        "margin_position": 0,
        "margin_frozen": 3.33,
        "margin_available": 0.34,
        "profit_real": 3.45,
        "profit_unreal": 7.45,
        "withdraw_available": 4.0989898,
        "risk_rate": 100,
        "liquidation_price": 100,
        "lever_rate": 10,
        "adjust_factor": 0.1
    }]
}

Format Illustration of Notification

Field Name Type Description
ts long Time of Respond Generation, Unit: Millisecond
event string notification on account asset change such as commit order(order.open), fulfill order(order.match)(excluding liquidated order and settled orders), settlement and delivery(settlement), fulfill liquidation order(order.liquidation)(including voluntarily fulfilled liquidation order and the fulfilled liquidation order taken over by system ) , cancel order(order.cancel), asset transfer(contract.transfer) (including withdraw and deposit), system (contract.system), other asset change(other), initial margin(init)
symbol string Variety code,"BTC","ETH"...
contract_code string contract_code ,"BTC", "ETH"...,当 $symbol值为 * 时代表订阅所有contract_code
margin_balance decimal Account Equity
margin_static decimal Static Equity
margin_position decimal Position Margi(the margin for holding currenty positions)
margin_frozen decimal Freeze margin
margin_available decimal Available Margin
profit_real decimal Realized Profits&Losses
profit_unreal decimal Unrealized Profits&Losses
risk_rate decimal Margin Ratio
liquidation_price decimal Liquidation Price
withdraw_available decimal Assets available to withdraw
lever_rate decimal Leverage Rate
adjust_factor decimal Adjustment Factor

Unsubscribe Account Equity Updates Data (ubsub)

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

Request Format of Unsubscribe Account Equity Updates Data

{

"op": "unsub",

"topic": "accounts.BTCPERP",

"cid": "id generated by client",

}

Example of a successful subscription request


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

Format Illustration on Unsubscribe Account Equity Updates

Field Name Type Description
op string Required; Operator Name,Subscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Required;Required; Required; Subscribe Topic,Subscribe accounts.$contract_code required unsubscribe/unsubscribe account equity change of a given coin,when the $contract_code value is *

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
accounts.* accounts.* Allowed
accounts.contract_code1 accounts.* Allowed
accounts.contract_code1 accounts.contract_code1 Allowed
accounts.contract_code1 accounts.contract_code2 Not Allowed
accounts.* accounts.contract_code1 Not Allowed

Subscribe Position Updates(sub)

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

Subscribe Request Format

{

"op": "sub",

"cid": "positions.BTCPERP",

"topic": "topic to sub"

}

Example of a successful subscribe request:


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

Subscribe Request FormatDescription

Field Name Type Description
op string Required;Operator Name,Subscribe value is sub
cid string Optional; Client requests unique ID
topic string Required; Subscribe Topic, Subscribe (positions.$contract_code) Required Subscribe/unsubscribe the position data of a single coin, when the $contract_code value is *

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


{
    "op": "notify",
    "topic": "positions.BTCPERP",
    "ts": 1489474082831,
    "event": "order.match",
    "data": [{
        "symbol": "BTC",
        "contract_code": "BTCPERP",
        "volume": 1,
        "available": 0,
        "frozen": 1,
        "cost_open": 422.78,
        "cost_hold": 422.78,
        "profit_unreal": 0.00007096,
        "profit_rate": 0.07,
        "profit": 0.97,
        "position_margin": 3.4,
        "lever_rate": 10,
        "direction": "buy",
        "last_price": 2.97
    }]
}

Returning Parameter

Field Name Type Description
ts long Time of Respond Generation, Unit: Millisecond
event string Notification on position change such as commit order(order.open), fulfill order(order.match)(excluding liquidated order and settled orders), settlement and delivery(settlement), fulfill liquidation order(order.liquidation)(including voluntarily fulfilled liquidation order and the fulfilled liquidation order taken over by system ) , cancel order(order.cancel), asset transfer(contract.transfer) (including withdraw and deposit), system (contract.system), initial margin(init)
symbol string Variety code ,"BTC","ETH"...
contract_code decimal contract_code,"BTCPERP"
volume decimal Volume
available decimal Positions available to close
frozen decimal Frozen Margin
cost_open decimal Open price
cost_hold decimal Position Price
profit_unreal decimal Unrealized Profits&Losses
profit_rate decimal profit/Losses Ratio
profit decimal Profits/Losses
position_margin decimal Position Margin
lever_rate decimal Leverage Rate
direction decimal Position direction "buy":Long "sell":Short
last_price decimal Last Price

Unsubscribe Position Updates Data(unsub)

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

Request Format of Unsubscribe Position Updates

{

"op": "unsub",

"topic": "positions.BTCPERP",

"cid": "id generated by client",

}

Example of a successful subscription request

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

Format Illustration on Unsubscribe Account Equity Updates

Field Name Type Description
op string Required; Operator Name,Subscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Required;Required;Required;Subscribe topic,Subscribe positions.$contract_code required Subscribe or unsubscribe the position updates of a single coin;

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
positions.* positions.* Allowed
positions.contract_code1 positions.* Allowed
positions.contract_code1 positions.contract_code1 Allowed
positions.contract_code1 positions.contract_code2 Not Allowed
positions.* positions.contract_code1 Not Allowed

Subscribe Liquidation Orders (no authentication) (sub)

Subscription Request Format of Liquidation order data

{

“op”: “sub”,

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

"cid": "id generated by client”,

}

Example of a successful subscribe request:


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

Request Parameter

Parameter Name Mandatory Type Description Value Range
op true string Required; Operator Name,required subscribe value is sub
cid false string Optional; ID Client requests unique ID
topic true string Required;Topic name format:(public.$symbol.liquidation_orders) Subscribe Liquidated Orders Information of a given coin;$symbol is Variety code(BTCPERP、ETHPERP)

Returning ParameterDescription

Parameter Name Mandatory Data Type Description Value Range
op true string value: 'notify';
topic true string topic subscribed
ts true long Time of Respond Generation,Unit:Millisecond
symbol true string Variety code "BTC","ETH"...
contract_code true string contract_code
direction true string Direction "buy", "sell"
offset true string "open": "close" "open": "close"
volume true decimal Quantity(Cont.)
price true decimal Price
created_at true number Order Creation time

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

{
    "op":"notify",
    "topic":"public.BTC.liquidation_orders",
    "ts":1580815422403,
    "data":[
        {
            "symbol":"BTC",
            "contract_code":"BTCPERP",
            "direction":"buy",
            "offset":"close",
            "volume":7,
            "price":4.236,
            "created_at":1580815422296
        }
    ]
}

Unsubscribe Liquidation Order Data (unsub)

Unsubscribe Request Format

{

“op”: “unsub”,

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

"cid": "id generated by client”,

}

Example of a successful subscription request


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

Returning Parameter

Field Name Type Description
op string Required; Operator Name,Subscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Subscribe topic name,Require subscribe public.$contract_code.liquidationOrders Subscribe/unsubscribe the data of a given coin; when the $contract_code value is *, it stands for subscribing/unsubscribing the data of all coins,;
ts number Mandatory;Time of Respond Generation, Unit: Millisecond

Example of a successful unsubscribe request :


{
  "op": "unsub",
  "topic": "public.BTC.liquidation_orders",
  "cid": "id generated by client",
  "err-code": 0,
  "ts": 1489474081631
}

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
public.*.liquidationOrders public.*.liquidationOrders Allowed
public.$symbol.liquidationOrders public.*.liquidationOrders Allowed
public.contract_code1.liquidationOrders public.contract_code1.liquidationOrders Allowed
public.contract_code1.liquidationOrders public.contract_code2.liquidationOrders Not Allowed
public.*.liquidationOrders public.contract_code1.liquidationOrders Not Allowed

Subscribe funding rate (no authentication)(sub)

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

{

"op": "sub",

"cid": "40sG903yz80oDFWr",

"topic": "public.$symbol.funding_rate"

}

Response example when funding rate is updated:


{ 
      "op": "notify",            
      "topic": "public.BTC.funding_rate",    
      "ts": 1489474082831,   
      "data": [
        {
          "symbol": "BTC",
          "contract_code": "BTCPERP",
          "fee_asset": "BTC", 
          "funding_time": "1490759594752",
          "funding_rate": "-0.12000001",
          "estimated_rate": "-0.12000001",
          "settlement_time": "1490759594752"
        }
      ]
}

Returning Parameter

Parameter Name Mandatory Type Description Value Range
op true string value: 'notify';
topic true string topic subscribed
ts true long Time of Respond Generation,Unit:Millisecond
<data> true object array
symbol true string Variety code "BTC","ETH"...
contract_code true string contract_code
fee_asset true string fee asset "BTC","ETH"...
funding_time true string current funding time "open": "close"
funding_rate true string current funding rate
estimated_rate true string estimated funding rate of next period
settlement_time true string settlement timestamp eg:"1490759594752"
</data>

Unsubscribe Funding Rate Data(no authentication)(unsub)

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

request format of unsubscribing funding rate

{

"op": "unsub",

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

"cid": "id generated by client",

}

Example of a successful subscription request

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

Format Illustration on Unsubscribe Account Equity Updates

Field Name Type Description
op string Required; Operator Name,Subscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Subscribe topic name,Require subscribe public.$contract_code.funding_rate Subscribe/unsubscribe the data of a given contract code; when the $contract_code value is *, it stands for subscribing/unsubscribing all the funding rates of contract codes,;

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
public.*.funding_rate pubic.*.funding_rate Allowed
public.contract_code1.funding_rate public.*.funding_rate Allowed
public.contract_code1.funding_rate public.contract_code1.funding_rate Allowed
public.contract_code1.funding_rate public.contract_code2.funding_rate Not Allowed
public.*.funding_rate public.contract_code1.funding_rate Not Allowed

Note

Funding rate will be pushed every 60 seconds by default.Funding rate will not be calculated under conditions below:

Subscribe Liquidation order data(sub)

Subscribe Liquidation order data format

{

“op”: “sub”,

“topic": "topic to sub”,

"cid": "id generated by client”,

}

Example of a successful subscribe request:


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

Returning Parameter

Field Name Type Description
ts number Time of Respond Generation, Unit: Millisecond
symbol string symbol
contract_code string "BTCPERP","ETHPERP"...
direction string Transaction direction
offset string "open": "close"
volume decimal Quantity(Cont.)
price decimal Price
created_at number Order Creation time

Return Example:


{
    "op": "notify",             
    "topic": "liquidationOrders.btc",     
    "ts": 1489474082831,    
    "symbol": "BTC",
    "contract_code": "BTCPERP",     
    "direction": "buy",
    "offset": "close",
    "volume": 111,
    "price": 1111,
    "created_at": 1408076414000
}

Unsubscribe Liquidation order data(unsub)

Unsubscribe Liquidation order data format

{

“op”: “unsub”,

“topic": "topic to unsub”,

"cid": "id generated by client”,

}

Example of a successful subscription request


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

Returning Parameter

Field Name Type Description
op string Required; Operator Name,Subscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Subscribe topic name,Require (liquidationOrders.$symbol) Subscribe/unsubscribe the data of a given contract code; when the $contract_code value is *, it stands for subscribing/unsubscribing all the funding rates of contract codes,;
ts number Mandatory;Time of Respond Generation, Unit: Millisecond

Example of a successful unsubscribe request :


{
  "op": "unsub",
  "topic": "liquidationOrders.btc",
  "cid": "id generated by client",
  "err-code": 0,
  "ts": 1489474081631
}

Rules on Subscribe and Unsubscribe

Subscribe(sub) 取消订阅(ubsub) Rule
liquidationOrders.* liquidationOrders.* Allowed
liquidationOrders.contract_code1 liquidationOrders.* Allowed
liquidationOrders.contract_code1 liquidationOrders.contract_code1 Allowed
liquidationOrders.contract_code1 liquidationOrders.contract_code2 Not Allowed
liquidationOrders.* liquidationOrders.contract_code1 Not Allowed

Subscribe funding rate(sub)

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

{

"op": "sub",

"cid": "40sG903yz80oDFWr",

"topic": "funding_rate.BTCPERP"

}

Response example when funding_rate is updated:


{
 "op": "notify",
 "topic": "funding_rate", 
 "ts": 1585753005644, 
 "data": [
   {
 "symbol": "BTC", 
 "contractCode": "BTCPERP", 
 "feeAsset": "BTC", 
 "fundingTime": "1585752960000", 
 "fundingRate": "0.000100000000000000",
 "estimatedRate": "-0.000294693121917726",
 "settlementTime": "1585771200000"
  }
  ]
 }

Returning Parameter

Field Name Type Description
ts long Time of Respond Generation, Unit: Millisecond
symbol string Variety code,"BTC","ETH"...
contractCode string "BTC", "ETH"...
feeAsset string fee asset,"BTC","ETH"...
fundingTime string current funding time
fundingRate string current funding rate
estimatedRate string estimated funding rate of next period
settlementTime string settlement timestamp,eg:"1490759594752"

Unsubscribe Funding Rate Data(unsub)

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

Unsubscribe Request Format

{

"op": "unsub",

"topic": "topic to unsub",

"cid": "id generated by client",

}

Example of a successful subscription request

{                                    
  "op": "unsub",                     
  "topic": "funding_rate.BTCPERP",   
  "cid": "40sG903yz80oDFWr"          
}                                    

Format Illustration on Unsubscribe Account Equity Updates

Field Name Type Description
op string Required; Operator Name,Subscribe value is unsub;
cid string Optional; Client requests unique ID
topic string Subscribe topic name,Require (funding_rate.$symbol) Subscribe/unsubscribe the data of a given contract code; when the $contract_code value is *, it stands for subscribing/unsubscribing all the funding rates of contract codes,;

Rules on Subscribe and Unsubscribe

Subscribe(sub) Unsubscribe(unsub) Rule
funding_rate.* funding_rate.* Allowed
funding_rate.contract_code1 funding_rate.* Allowed
funding_rate.contract_code1 funding_rate.contract_code1 Allowed
funding_rate.contract_code1 funding_rate.contract_code2 Not Allowed
funding_rate.* funding_rate.contract_code1 Not Allowed

Note

Funding rate will be pushed every 60 seconds by default.Funding rate will not be calculated under conditions below: