火币网API文档——Websocket 请求与订阅示例

1. 访问地址

  • Pro 站行情请求地址为:wss://api.huobipro.com/ws
  • HADAX 站行情请求地址为:wss://api.hadax.com/ws

 

2. 数据压缩

  WebSocket API 返回的所有数据都进行了 GZIP 压缩,需要 client 在收到数据之后解压,推荐使用pako。(【pako】 是一个支持压缩和解压 GZIP 的库)

 

3. WebSocket库

  【ws】 是 Node.js 下的 WebSocket 库。

 

4. 心跳

  WebSocket API 支持双向心跳,无论是 Server 还是 Client 都可以发起ping message,对方返回 pong message。

WebSocket Server 发送心跳:

{"ping": 18212558000}

WebSocket Client 应该返回:

 {"pong": 18212558000}

注:返回的数据里面的'pong' 的值为收到的'ping' 的值

注:WebSocket Client 和 WebSocket Server 建立连接之后,WebSocket Server 每隔5s(这个频率可能会变化) 会向 WebSocket Client 发起一次心跳,WebSocket Client 忽略心跳2次后,WebSocket Server 将会主动断开连接。

例如

WebSocket Client 发送心跳:

{"ping": 18212553000}

注:发送的 message 里面,"ping" 的值必须为 Long 类型,否则返回错误信息:

{
  "ts": 1492420473027,
  "status": "error",
  "err-code": "bad-request",
  "err-msg": "invalid ping"
}

 

WebSocket Server 会返回:

{"pong": 18212553000}

 

注:返回的数据里面的 'pong' 的值为收到的'ping' 的值

 

5. topic格式

订阅数据和请求数据都要使用topic,topic的语法如下:

topic 类型topic 语法描述
KLine market.$symbol.kline.$period $period 可选值:{ 1min, 5min, 15min, 30min, 60min, 1day, 1mon, 1week, 1year }
Market Depth market.$symbol.depth.$type $type 可选值:{ step0, step1, step2, step3, step4, step5 } (合并深度0-5);step0时,不合并深度
Trade Detail market.$symbol.trade.detail  
Market Detail market.$symbol.detail  
  • $symble是币种,可选值: { ethbtc, ltcbtc, etcbtc, bchbtc...... }
  • 用户选择“合并深度”时,一定报价精度内的市场挂单将予以合并显示。合并深度仅改变显示方式,不改变实际成交价格。

 

6. 请求数据(req/rep)

请求数据,仅返回一次数据

请求数据的格式

{
  "req": "topic to req",
  "id": "id generate by client"
}
  • 'req'的值为 topic 格式

正确请求数据的例子

{
  "req": "market.btcusdt.kline.1min",
  "id": "id10"
}
返回数据的例子:

{
  "status": "ok",
  "rep": "market.btcusdt.kline.1min",
  "tick": [
    {
      "amount": 1.6206,
      "count":  3,
      "id":     1494465840,
      "open":   9887.00,
      "close":  9885.00,
      "low":    9885.00,
      "high":   9887.00,
      "vol":    16021.632026
    },
    {
      "amount": 2.2124,
      "count":  6,
      "id":     1494465900,
      "open":   9885.00,
      "close":  9880.00,
      "low":    9880.00,
      "high":   9885.00,
      "vol":    21859.023500
    }
  ]
}

 

错误请求数据的例子

{
  "req": "market.invalidsymbo.kline.1min",
  "id": "id10"
}

 

返回的错误信息的例子:

{
  "status": "error",
  "id": "id10",
  "err-code": "bad-request",
  "err-msg": "invalid topic market.invalidsymbol.trade.detail",
  "ts": 1494483996521
}

 

7. 订阅数据(sub/pub)

订阅数据的格式

成功建立和 WebSocket API 的连接之后,向 Server 发送如下格式的数据来订阅数据:

{
  "sub": "topic to sub",
  "id": "id generate by client"
}

 

正确订阅的例子

正确订阅:

{
  "sub": "market.btcusdt.kline.1min",
  "id": "id1"
}
  • "sub"值为 topic 格式

订阅成功返回数据的例子:

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

之后每当 KLine 有更新时,client 会收到数据,例子:

{
  "ch": "market.btcusdt.kline.1min",
  "ts": 1489474082831,
  "tick": {
    "id": 1489464480,
    "amount": 0.0,
    "count": 0,
    "open": 7962.62,
    "close": 7962.62,
    "low": 7962.62,
    "high": 7962.62,
    "vol": 0.0
  }
}

tick 说明:

  "tick": {
    "id": K线id,
    "amount": 成交量,
    "count": 成交笔数,
    "open": 开盘价,
    "close": 收盘价,当K线为最晚的一根时,是最新成交价
    "low": 最低价,
    "high": 最高价,
    "vol": 成交额, 即 sum(每一笔成交价 * 该笔的成交量)
  }

 

错误订阅的例子

错误订阅(错误的 symbol):

{
  "sub": "market.invalidsymbol.kline.1min",
  "id": "id2"
}

订阅失败返回数据的例子:

{
  "id": "id2",
  "status": "error",
  "err-code": "bad-request",
  "err-msg": "invalid topic market.invalidsymbol.kline.1min",
  "ts": 1494301904959
}

错误订阅(错误的 topic):

{
  "sub": "market.btcusdt.kline.3min",
  "id": "id3"
}

 

订阅失败返回数据的例子:

{
  "id": "id3",
  "status": "error",
  "err-code": "bad-request",
  "err-msg": "invalid topic market.btcusdt.kline.3min",
  "ts": 1494310283622
}

 

8. 取消订阅(unsub)

取消订阅的格式

  WebSocket Client 订阅数据之后,可以取消订阅,取消订阅之后 WebSocket Server 将不会再发送该 topic 的数据,取消订阅的格式如下:

{
  "unsub": "topic to unsub",
  "id": "id generate by client"
}

 

正确取消订阅的例子:

{
  "unsub": "market.btcusdt.trade.detail",
  "id": "id4"
}

 

取消订阅成功返回信息的例子:

{
  "id": "id4",
  "status": "ok",
  "unsubbed": "market.btcusdt.trade.detail",
  "ts" 1494326028889
}

 

错误取消订阅的例子

错误取消订阅的例子(取消订阅一个尚未订阅的 topic):

{
  "unsub": "market.btcusdt.trade.detail",
  "id": "id5"
}

 

返回的错误信息的例子

{
  "id": "id5",
  "status": "error",
  "err-code": "bad-request",
  "err-msg": "unsub with not subbed topic market.btcusdt.trade.detail",
  "ts": 1494326217428
}

 

错误取消订阅的例子(取消订阅一个不存在的 topic):

{
  "unsub": "not-exists-topic",
  "id": "id5"
}

 

返回的错误信息的例子:

{
  "id": "id5",
  "status": "error",
  "err-code": "bad-request",
  "err-msg": "unsub with not subbed topic not-exists-topic",
  "ts": 1494326318809
}

 

 

 

 

                                       

posted @ 2018-04-25 20:46 ''竹先森゜ 阅读(...) 评论(...) 编辑 收藏