关于API将新增两个Websocket订阅主题的公告

尊敬的用户:

自本通知生效之日起,火币Global将新增以下Websocket订阅主题 –

1)  清算后成交明细推送 trade.clearing#${symbol}

2)  账户变更推送 accounts.update#${mode}

此新增Websocket订阅主题基于全新URL“/ws/v2”以及v2.1版本签名方式。

 

生效日期:2019年12月4日(GMT+8)

具体变更细节及参数要求,请参考API文档:https://huobiapi.github.io/docs/spot/v1/cn/

火币全球站

2019年12月6日

 

以下为变更细节

接入URL

Websocket资产及订单(v2)

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

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

注:api-aws.huobi.pro域名对使用aws云服务的用户做了一定的链路延迟优化。

请使用中国大陆以外的服务器访问火币 API。

数据压缩

心跳消息

当用户的Websocket客户端连接到火币WebSocket服务器后,服务器会定期(当前设为20秒)向其发送Ping消息并包含一整数值如下:

{

               "action": "ping",

               "data": {

                               "ts": 1575537778295

               }

}

当用户的Websocket客户端接收到此心跳信息后,应返回Pong消息并包含同一整数值:

{

    "action": "ping",

    "data": {

          "ts": 1575537778295 // 使用Ping消息中的ts值

    }

}

action的有效取值

有效取值取值说明
sub订阅数据
req数据请求
ping、pong心跳数据
push推送数据,服务端发送至客户端数据类型

鉴权

鉴权请求格式如下:

{

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

    }

}

鉴权成功后返回数据格式如下:

{

               "action": "req",

               "code": 200,

               "ch": "auth",

               "data": {}

}

参数说明

字段是否必需数据类型描述
actiontruestringWebsocket数据操作类型,鉴权固定值为req
chtruestring请求主题,鉴权固定值为auth
authTypetruestring鉴权类型,鉴权固定值为api
accessKeytruestringAPI访问秘钥,您申请的API Key中的AccessKey
signatureMethodtruestring签名方法,用户计算签名寄语哈希的协议,固定值为HmacSHA256
signatureVersiontruestring签名协议版本,固定值为2.1
timestamptruestring时间戳,您发出请求的时间(UTC时间)在查询请求中包含此值有助于防止第三方截取您的请求。如:2017-05-11T16:22:06。再次强调是 (UTC 时区)
signaturetruestring签名, 计算得出的值,用于确保签名有效和未被篡改

签名步骤

v2.1版本签名与v2.0版本签名步骤相似,具体区别如下:

  1. 生成参与签名的字符串时,请求方法固定使用GET,请求地址固定为/ws/v2
  2. 生成参与签名的固定参数名替换为:accessKey,signatureMethod,signatureVersion,timestamp
  3. signatureVersion版本升级为2.1

v2版本签名步骤,您可以点击 这里 获取。

签名前最后生成的字符串如下:

GET\n

api.huobi.pro\n

/ws/v2\n

accessKey=0664b695-rfhfg2mkl3-abbf6c5d-49810&signatureMethod=HmacSHA256&signatureVersion=2.1&timestamp=2019-12-05T11%3A53%3A03

订阅主题

成功建立与Websocket服务器的连接后,Websocket客户端发送如下请求以订阅特定主题:

{

               "action": "sub",

               "ch": "accounts.update"

}

订阅成功Websocket客户端会接收到如下消息:

{

               "action": "sub",

               "code": 200,

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

               "data": {}

}

请求数据

成功建立Websocket服务器的连接后,Websocket客户端发送如下请求用以获取一次性数据:

{

    "action": "req",

    "ch": "topic",

}

请求成功后Websocket客户端会收到如下消息:

{

    "action": "req",

    "ch": "topic",

    "code": 200,

    "data": {} // 请求数据体

}

 

 

订阅清算后成交明细trade.clearing#${symbol}

 

清算后成交明细包含了交易手续费以及交易手续费抵扣等信息,仅当用户订单成交时推送。

 

请求参数数据类型描述
symbolstring交易代码(支持通配符”*”)

 

数据更新字段列表

字段名称数据类型描述
symbolstring交易代码
orderIdlong订单ID
tradePricestring成交价
tradeVolumestring成交量
orderSidestring订单方向,有效值: buy, sell
orderTypestring订单类型,有效值: buy-market, sell-market,buy-limit,sell-limit,buy-ioc,sell-ioc,buy-limit-maker,sell-limit-maker,buy-stop-limit,sell-stop-limit
aggressorbool是否交易主动方,有效值: true, false
tradeIdlong交易ID
tradeTimelong成交时间,unix time in millisecond
transactFeestring交易手续费
feeDeductstring交易手续费抵扣
feeDeductTypestring交易手续费抵扣类型,有效值: ht,point

 

订阅

{

       "action": "sub",

       "ch": "trade.clearing#btcusdt"

}

 

订阅响应:

{

       "action": "sub",

       "code": 200,

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

       "data": {}

}

 

数据推送:

{

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

    }

}

 

订阅账户资产变更accounts.update#${mode}

 

用户可选择以下任一账户变更推送的触发方式 –

  • 仅在账户余额发生变动时推送;
  • 在账户余额发生变动或可用余额发生变动时均推送,且分别推送。

 

请求参数数据类型描述
modeinteger推送方式,有效值:0, 1,默认值:00:仅当账户余额变动时推送1:在账户余额发生变动或可用余额发生变动时均推送且分别推送

 

订阅示例 –

  • 不填mode:

accounts.update

仅当账户余额变动时推送;

  • 填写mode=0:

accounts.update#0

仅当账户余额变动时推送;

  • 填写mode=1:

accounts.update#1

在账户余额发生变动或可用余额发生变动时均推送且分别推送。

 

数据更新字段列表

字段名称数据类型描述
currencystring币种
accountIdlong账户ID
balancestring账户余额(仅当账户余额发生变动时推送)
availablestring可用余额(仅当可用余额发生变动时推送)
changeTypestring余额变动类型,有效值:order-place(订单创建),order-match(订单成交),order-refund(订单成交退款),order-cancle(订单撤销),order-fee-refund(点卡抵扣交易手续费),margin-transfer(杠杆账户划转),margin-loan(借贷本金),margin-interest(借贷计息),margin-repay(归还借贷本金利息),other(其他资产变化)
accountTypestring账户类型,有效值:trade, frozen, loan, interest
changeTimelong余额变动时间,unix time in millisecond

 

订阅

{

       "action": "sub",

       "ch": "accounts.update"

}

 

订阅响应:

{

       "action": "sub",

       "code": 200,

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

       "data": {}

}

 

数据推送:

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

       }

}