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 ValuesDescription
subSubscribe
reqRequest
ping,pongHeartbeat
pushPush (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

FieldMandatoryData TypeDescription
actiontruestringAction type, valid value: "req"
chtruestringChannel, valid value: "auth"
authTypetruestringAuthentication type, valid value: "api"
accessKeytruestringAccess key
signatureMethodtruestringSignature method, valid value: "HmacSHA256"
signatureVersiontruestringSignature version, valid value: "2.1"
timestamptruestringTimestamp in UTC in format like 2017-05-11T16:22:06
signaturetruestringSignature

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 ParameterData TypeDescription
symbolstringTrading symbol (Wildcard “*” acceptable)

 

Update Content

Field NameData TypeDescription
symbolstringTrading symbol
orderIdlongOrder ID
tradePricestringTrade price
tradeVolumestringTrade volume
orderSidestringOrder side, Enum values: buy, sell
orderTypestringOrder 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
aggressorboolAggressor or not, Enum values: true, false
tradeIdlongTrade ID
tradeTimelongTrade time, unix time in millisecond
transactFeestringTransaction fee
feeDeductstringTransaction fee deduction
feeDeductTypestringTransaction 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 ParameterData TypeDescription
modeintegerUpdate 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 NameData TypeDescription
currencystringCurrency
accountIdlongAccount ID
balancestringAccount balance (to be updated only when account balance changed)
availablestringAvailable balance (to be updated only when available balance changed)
changeTypestringChange type, Enum values: order-place, order-match, order-refund, order-cancle, order-fee-refund, margin-transfer, margin-loan, margin-interest, margin-repay, other
accountTypestringAccount type, Enum values: trade, frozen, loan, interest
changeTimelongChange 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

       }