Huobi Global will include two new subscription topics in existing Websocket API

Dear API user,

Since the effective day of this notification, Huobi Global will add following two new subscription topics into existing Websocket API –

1)    Trade details post clearing – trade.clearing#${symbol};

2)    Account change – accounts.update#${mode}.

The above two new Websocket topics are based on brand new URL “/ws/v2” and version 2.1 signature method.

Effective Date: December 4, 2019 (GMT+8)

All the changes will be updated on https://huobiapi.github.io/docs/spot/v1/en/

Huobi Global

December 6, 2019

The followings are change details:

Access URL

Websocket Asset and Order (v2)

wss://api.huobi.pro/ws/v2

wss://api-aws.huobi.pro/ws/v2

Note: By comparing to api.huobi.pro, the network latency to api-aws.huobi.pro is lower, for those client's servers locating at AWS.

Message Compression

None.

Heartbeat

Once the Websocket connection is established, Huobi server will periodically send "ping" message at 20s interval, with an integer inside.

{               "action": "ping",               "data": {                               "ts": 1575537778295               }}

Once client's server receives "ping", it should respond "pong" message back with the same integer.

{    "action": "ping",    "data": {          "ts": 1575537778295 // the same integer from "ping" message    }}

Valid Values of action

Valid Values	Description
sub	Subscribe
req	Request
ping,pong	Heartbeat
push	Push (from Huobi server to client's server)

Authentication

Authentication request:

{    "action": "req",     "ch": "auth",    "params": {         "authType":"api",        "accessKey": "sffd-ddfd-dfdsaf-dfdsafsd",        "signatureMethod": "HmacSHA256",        "signatureVersion": "2.1",        "timestamp": "2019-09-01T18:16:16",        "signature": "safsfdsjfljljdfsjfsjfsdfhsdkjfhklhsdlkfjhlksdfh"    }}

The response of success

{               "action": "req",               "code": 200,               "ch": "auth",               "data": {}}

Authentication request field list

Field	Mandatory	Data Type	Description
action	true	string	Action type, valid value: "req"
ch	true	string	Channel, valid value: "auth"
authType	true	string	Authentication type, valid value: "api"
accessKey	true	string	Access key
signatureMethod	true	string	Signature method, valid value: "HmacSHA256"
signatureVersion	true	string	Signature version, valid value: "2.1"
timestamp	true	string	Timestamp in UTC in format like 2017-05-11T16:22:06
signature	true	string	Signature

Generating Signature

The signature generation method v2.1 is similar with v2.0, with only following differences:

1. The request method should be "GET", to URL "/ws/v2".
2. The involved field names in v2 signature generation are: accessKey，signatureMethod，signatureVersion，timestamp
3. The valid value of signatureVersion is 2.1.

Please refer to detailed signature generation steps from: [https://huobiapi.github.io/docs/spot/v1/cn/#c64cd15fdc]

The final string involved in signature generation should be like below:

GET\napi.huobi.pro\n/ws/v2\naccessKey=0664b695-rfhfg2mkl3-abbf6c5d-49810&signatureMethod=HmacSHA256&signatureVersion=2.1&timestamp=2019-12-05T11%3A53%3A03

Subscribe a Topic to Continuously Receive Updates

Once the Websocket connection is established, Websocket client could send following request to subscribe a topic:

{               "action": "sub",               "ch": "accounts.update"}

Upon success, Websocket client should receive a response below:

{               "action": "sub",               "code": 200,               "ch": "accounts.update#0",               "data": {}}

Request an Update

Once the Websocket connection is established, Websocket client could send following request to acquire an update:

{    "action": "req",     "ch": "topic",}

Upon success, Websocket client should receive a response below:

{    "action": "req",    "ch": "topic",    "code": 200,    "data": {} // update contents}

Subscription topic – trade.clearing#${symbol}

The “trade details post clearing” topic should include transaction fee and transaction fee deduction details, which only updating while order matched.

Request Parameter	Data Type	Description
symbol	string	Trading symbol (Wildcard “*” acceptable)

Update Content

Field Name	Data Type	Description
symbol	string	Trading symbol
orderId	long	Order ID
tradePrice	string	Trade price
tradeVolume	string	Trade volume
orderSide	string	Order side, Enum values: buy, sell
orderType	string	Order type, Enum values: buy-market, sell-market,buy-limit,sell-limit,buy-ioc,sell-ioc,buy-limit-maker,sell-limit-maker,buy-stop-limit,sell-stop-limit
aggressor	bool	Aggressor or not, Enum values: true, false
tradeId	long	Trade ID
tradeTime	long	Trade time, unix time in millisecond
transactFee	string	Transaction fee
feeDeduct	string	Transaction fee deduction
feeDeductType	string	Transaction fee deduction type, Enum values: ht，point

Subscription:

{

       "action": "sub",

       "ch": "trade.clearing#btcusdt"

}

Response:

{

       "action": "sub",

       "code": 200,

       "ch": "trade.clearing#btcusdt",

       "data": {}

}

Updates:

{

    "ch": "trade.clearing#btcusdt",

    "data": {

         "symbol": "btcusdt",

         "orderId": 99998888,

         "tradePrice": "9999.99",

         "tradeVolume": "0.96",

         "orderSide": "buy",

         "aggressor": true,

         "tradeId": 919219323232,

         "tradeTime": 998787897878,

         "transactFee": "19.88",

         " feeDeduct ": "0",

         " feeDeductType": ""

    }

}

Subscription topic – accounts.update#${mode}

The “account change” topic will be updating while either of following scenarios occurs –

• Only when account balance being changed;
• When either account balance being changed or available balance being changed, and updating separately.

User can choose either of above update behavior while subscribing to the topic.

Reqeust Parameter	Data Type	Description
mode	integer	Update behavior, Valid value: 0, 1, Default value: 00: Update only when account balance changed1: Update when either account balance changed or available balance changed, and update separately

Subscription examples –

• Ignoring “mode”:

accounts.update

Update only when account balance changed;

• Filling “mode=0”:

accounts.update#0

Update only when account balance changed;

• Filling “mode=1”:

accounts.update#1

Update when either account balance changed or available balance changed, and update separately.

Update Content

Field Name	Data Type	Description
currency	string	Currency
accountId	long	Account ID
balance	string	Account balance (to be updated only when account balance changed)
available	string	Available balance (to be updated only when available balance changed)
changeType	string	Change type, Enum values: order-place, order-match, order-refund, order-cancle, order-fee-refund, margin-transfer, margin-loan, margin-interest, margin-repay, other
accountType	string	Account type, Enum values: trade, frozen, loan, interest
changeTime	long	Change time, unix time in millisecond

Subscription:

{

       "action": "sub",

       "ch": "accounts.update"

}

Response:

{

       "action": "sub",

       "code": 200,

       "ch": "accounts.update#0",

       "data": {}

}

Updates:

accounts.update#0：

{

       "action": "push",

       "ch": "accounts.update#0",

       "data": {

              "currency": "btc",

              "accountId": 123456,

              "balance": "23.111",

              "changeType": "transfer",

              "accountType":"trade",

              "changeTime": 1568601800000

       }

}

accounts.update#1：

{

       "action": "push",

       "ch": "accounts.update#1",

       "data": {

              "currency": "btc",

              "accountId": 33385,

              "available": "2028.699426619837209087",

              "changeType": " order.match ",

                  "accountType":"trade",

              "changeTime": 1574393385167

       }

}

{

"action": "push",

       "ch": "accounts.update#1",

       "data": {

              "currency": "btc",

              "accountId": 33385,

              "balance": "2065.100267619837209301",

              "changeType": " order.match ",

                 "accountType":"trade",

              "changeTime": 1574393385122

       }