本文介绍火币Huobi API Websocket
WebSocket API简介
WebSocket协议是基于TCP的一种新的网络协议。它实现了客户端与服务器之间在单个 tcp 连接上的全双工通信,由服务器主动发送信息给客户端,减少了频繁的身份验证等不必要的开销。其最大优点有两个:
-
两方请求的 header 数据很小,大概只有2 Bytes。
-
服务器不再是被动的接到客户端的请求后才返回数据,而是有了新数据后主动推送给客户端。
以上 WebSocket 协议带来的优点使得其十分适用于数字货币行情和交易这种实时性强的接口。
WebSocket 只支持行情查询、订单和资产推送,交易接口将在后续提供。在使用中如果遇到问题,请加技术讨论 QQ 群: 火币网API交流群(7) 794370631,我们将尽力帮您答疑解惑(加群时请注明uid和编程语言)。
请求与订阅说明
1. 访问地址
注意:HADAX和Pro是两个不同的交易站,所以行情信息也不一样,请通过 Pro symbols 和 HADAX symbols 查询相应的交易对信息
- Pro 站行情请求地址为:wss://api.huobi.pro/ws
- HADAX 站行情请求地址为:wss://api.hadax.com/ws
- Pro 站和 HADAX 站资产和订单推送统一服务地址为:wss://api.huobi.pro/ws/v1
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发送最近2次心跳message中的其中一个ping
的值,WebSocket Server都会保持WebSocket连接。
┌────────┐ ┌────────┐
│ Client │ │ Server │
└───┬────┘ └───┬────┘
│ {"ping": 18212558000} │
│<─────────────────────────────────┤
│ │ wait 5s
│ ├───┐
│ │<──┘
│ {"ping": 18212558000} │
│<─────────────────────────────────┤
│ │
│ {"pong": 18212558000} │
├┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄>│
│ │
注:WebSocket Client 发送最近2次心跳 message 中的其中一个 "ping"
的值,WebSocket Server 都会保持 WebSocket 连接
┌────────┐ ┌────────┐
│ Client │ │ Server │
└───┬────┘ └───┬────┘
│ {"ping": 1523778470416} │
│<─────────────────────────────────┤
│ │ wait 5s
│ ├───┐
│ │<──┘
│ {"ping": 1523778475416} │
│<─────────────────────────────────┤
│ │ wait 5s
│ ├───┐
│ │<──┘
│ │
│ │ close WebSocket connection
│ ├───┐
│ │<──┘
│ │
注: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"
的值
错误信息返回格式
{
"id": "id generate by client",
"status": "error",
"err-code": "err-code",
"err-msg": "err-message",
"ts": 1487152091345
}
注:ts
为错误信息生成的时间戳,单位:毫秒
5. topic格式
订阅数据和请求数据都要使用 topic
,topic
的语法如下:
topic 类型 | topic 语法 | sub/req | 描述 | 是否需要验签 |
---|---|---|---|---|
KLine | market.$symbol.kline.$period | sub/req | K线 数据,包含单位时间区间的开盘价、收盘价、最高价、最低价、成交量、成交额、成交笔数等数据 $period 可选值:{ 1min, 5min, 15min, 30min, 60min, 4hour,1day, 1mon, 1week, 1year } | N |
Market Depth | market.$symbol.depth.$type | sub/req | 盘口深度,按照不同 step 聚合的买一、买二、买三等和卖一、卖二、卖三等数据 $type 可选值:{ step0, step1, step2, step3, step4, step5, percent10 } (合并深度0-5);step0时,不合并深度 | N |
Trade Detail | market.$symbol.trade.detail | sub/req | 成交记录,包含成交价格、成交量、成交方向等信息 | N |
Market Detail | market.$symbol.detail | sub/req | 最近24小时成交量、成交额、开盘价、收盘价、最高价、最低价、成交笔数等 | N |
Market Tickers | market.tickers | sub | 所有对外公开交易对的 日K线、最近24小时成交量等信息 | N |
Accounts | accounts | sub, unsub | 订阅账户资产变更 | Y |
Orders | orders.$symbol | sub,unsub | 订阅订单变更 | Y |
Accounts list | accounts.list | req | 请求账户资产信息 | Y |
Order list | accounts.list | req | 请求订单信息 | Y |
order detail | orders.detail | req | 请求某个订单明细 | Y |
$symbol
为交易对,可选值: { ethbtc, ltcbtc, etcbtc, bchbtc...... }- 用户选择“合并深度”时,一定报价精度内的市场挂单将予以合并显示。合并深度仅改变显示方式,不改变实际成交价格。
6. 请求数据(req/rep)
请求数据,仅返回一次数据
请求数据的格式
{
"req": "topic to req",
"id": "id generate by client"
}
"req"
的值为 topic ,请参考"5. topic格式"
的 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)
订阅数据(sub)以及接收订阅数据的大致流程
┌────────┐ ┌────────┐
│ Client │ │ Server │
└───┬────┘ └───┬────┘
│ {"sub": "topic"} │
├─────────────────────────────────>│
│ │
│ {"subbed": "topic"} │
│<┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ │
│ {"tick": "data of topic"} │
│<┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ │
│ {"tick": "data of topic"} │
│<┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤
│ │
注:订阅 topic 成功之后,当 topic 对应的数据有更新时,Server 按一定的频率把 topic 对应的新数据推送给 Client
订阅数据的格式
成功建立和 WebSocket API 的连接之后,向 Server 发送如下格式的数据来订阅数据:
{
"id": "id generate by client",
"sub": "topic to sub",
"freq-ms": 1000
}
注:id
参数是可选的 注:freq-ms
参数是可选的,可选值为 { 1000
, 2000
, 3000
, 4000
, 5000
},不传 freq-ms
时默认为0
也就是有新的数据就马上推送到 Client,freq-ms
决定 Server 推送的频率 正确订阅的例子
正确订阅:
{
"sub": "market.btcusdt.kline.1min",
"id": "id1"
}
"sub"
的值为 topic ,请参考"5. topic格式"
的 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
}
9. 鉴权(Authentication)
用户自己在火币网生成Access Key和Secret Key,Secret Key由用户自己保存,用户需提供Access Key。目前关于 apikey 申请和修改,请在“账户 - API 管理 ” 创建新API Key 填写备注(可选择绑定ip)点击创建。其中 Access Key 为 API 访问密钥,Secret Key 为用户对请求进行签名的密钥(仅申请时可见)。用户按规则生成签名(Signature)。Pro 站和 HADAX 站 apikey 通用。
交易功能 websocket 版本接口建立连接时首先要做鉴权操作,具体格式如下,
重要提示:这两个密钥与账号安全紧密相关,无论何时都请勿向其它人透露。
鉴权请求数据格式
{
"op": "auth",
"AccessKeyId": "e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx",
"SignatureMethod": "HmacSHA256",
"SignatureVersion": "2",
"Timestamp": "2017-05-11T15:19:30",
"Signature": "4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=",
}
鉴权请求数据格式说明
字段名称 | 类型 | 说明 |
---|---|---|
op | string | 必填;操作名称,鉴权固定值为 auth; |
cid | string | 选填;Client 请求唯一 ID |
AccessKeyId | string | 必填;API 访问密钥, 您申请的 APIKEY 中的 AccessKey |
SignatureMethod | string | 必填;签名方法, 用户计算签名的基于哈希的协议,此处使用 HmacSHA256 |
SignatureVersion | string | 必填;签名协议的版本,此处使用 2 |
Timestamp | string | 必填;时间戳, 您发出请求的时间 (UTC 时区) (UTC 时区) (UTC 时区) 。在查询请求中包含此值有助于防止第三方截取您的请求。如:2017-05-11T16:22:06。再次强调是 (UTC 时区) |
Signature | string | 必填;签名, 计算得出的值,用于确保签名有效和未被篡改 |
注意:
- 为了减少已有用户的接入工作量,此处使用了与 REST 接口同样的签名算法进行鉴权,详细请参考 REST_authentication#签名运算。
- 请注意大小写
- 参数
op
,cid
,Signature
不参加签名计算- 此处签名计算中请求方法固定值为
GET
,其余值请参考 REST 接口签名算法文档
步骤:
示例参数签名(Signature)计算过程如下,
-
规范要计算签名的请求 因为使用 HMAC 进行签名计算时,使用不同内容计算得到的结果会完全不同。所以在进行签名计算前,请先对请求进行规范化处理。
-
请求方法,后面添加换行符
GET
- 添加小写的访问地址,后面添加换行符
api.huobipro.com
- 访问方法的路径,后面添加换行符
/ws/v1
- 按照ASCII码的顺序对参数名进行排序(使用 UTF-8 编码,且进行了 URI 编码,十六进制字符必须大写,如‘:’会被编码为'%3A',空格被编码为'%20')。 例如,下面是请求参数的原始顺序,进行过编码后。
AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&Signature
Method=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%
3A19%3A30
- 按照以上顺序,将各参数使用字符’&’连接。
- 组成最终的要进行签名计算的字符串如下:
- 计算签名,将以下两个参数传入加密哈希函数: 要进行签名计算的字符串,进行签名的密钥(SecretKey)
- 得到签名计算结果并进行 Base64编码
- 组成最终的要进行签名计算的字符串如下:
- 将上述值作为参数Signature的取值添加到 API 请求中。 将此参数添加到请求时,必须将该值进行 URI 编码。
鉴权应答数据格式说明
名称 | 类型 | 说明 |
---|---|---|
op | string | 必填;操作名称,鉴权固定值为 auth |
err-code | integer | 成功返回 0, 失败为其他值,详细响应码列表请参考附录 |
err-msg | string | 可选,若出错表示详细错误信息 |
ts | long | 服务端应答时间戳 |
user-id | long | 用户 id |
鉴权成功应答数据示例
{
"op": "auth",
"ts": 1489474081631,
"err-code": 0,
"data": {
"user-id": 1000
}
}
鉴权失败应答返回数据
{
"op": "auth",
"ts": 1489474081631,
"err-code": 1010,
"err-msg": ”详细的错误信息“
}
若用户上一次鉴权还未应答,用户连续发送鉴权请求,会返回重复鉴权的错误应答:
{
"op": "auth",
"ts": 1489474081631,
"err-code": 1022,
"err-msg": ”详细的错误信息“
}
WebSocket API Reference
订阅 KLine 数据 market.$symbol.kline.$period
成功建立和 WebSocket API 的连接之后,向 Server 发送如下格式的数据来订阅数据:
{
"sub": "market.$symbol.kline.$period",
"id": "id generate by client"
}
参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 |
---|---|---|---|---|---|
symbol | true | string | 交易对 | ethbtc, ltcbtc, etcbtc, bchbtc......以下新的symbol会在生效日当天可以请求:huobi10 - 指数,hb10 - ETF净值 | |
period | true | string | K线周期 | 1min, 5min, 15min, 30min, 60min, 1day, 1mon, 1week, 1year |
正确订阅的例子
正确订阅
{
"sub": "market.btcusdt.kline.1min",
"id": "id1"
}
订阅成功返回数据的例子
{
"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
}
请求 KLine 数据 market.$symbol.kline.$period
{
"req": "market.$symbol.kline.$period",
"id": "id generated by client",
"from": 1533536947, //optional, type: long, 2017-07-28T00:00:00+08:00 至 2050-01-01T00:00:00+08:00 之间的时间点,单位:秒
"to": 1533536947 //optional, type: long, 2017-07-28T00:00:00+08:00 至 2050-01-01T00:00:00+08:00 之间的时间点,单位:秒,必须比 from 大
}
参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 |
---|---|---|---|---|---|
symbol | true | string | 交易对 | btcusdt, ethusdt, ltcusdt, etcusdt, bchusdt, ethbtc, ltcbtc, etcbtc, bchbtc... 以下新的symbol会在生效日当天可以请求:huobi10 - 指数,hb10 - ETF净值 | |
period | true | string | K线周期 | 1min, 5min, 15min, 30min, 60min, 1day, 1mon, 1week, 1year |
关于ETF请求参数的说明
Symbol | 说明 |
---|---|
huobi10 | 指数 |
hb10 | ETF净值 |
其他请求参数period
,from
,to
保持不变。
- 响应结果
响应结果的结构保持不变,唯一的区别是响应结果中的amount, count 和 vol都是0,因为在这里的amount, count 和 vol是交易的相关的 值,而指数和ETF净值没有相应的数据。Houbi10 指数和 Hb10净值每15秒更新一次。
[t1, t5]
假设有 t1 ~ t5 的K线.
- 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 1501171200 < t1 < t2 < 2524579200.
一次最多300条
请求 KLine 数据的例子
{
"req": "market.btcusdt.kline.1min",
"id": "id10"
}
返回数据的例子
{
"rep": "market.btcusdt.kline.1min",
"status": "ok",
"id": "id10",
"tick": [
{
"amount": 17.4805,
"count": 27,
"id": 1494478080,
"open": 10050.00,
"close": 10058.00,
"low": 10050.00,
"high": 10058.00,
"vol": 175798.757708
},
{
"amount": 15.7389,
"count": 28,
"id": 1494478140,
"open": 10058.00,
"close": 10060.00,
"low": 10056.00,
"high": 10065.00,
"vol": 158331.348600
},
// more KLine data here
]
}
订阅 Market Depth 数据 market.$symbol.depth.$type
成功建立和 WebSocket API 的连接之后,向 Server 发送如下格式的数据来订阅数据:
{
"sub": "market.$symbol.depth.$type",
"id": "id generated by client"
}
参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 |
---|---|---|---|---|---|
symbol | true | string | 交易对 | btcusdt, ethusdt, ltcusdt, etcusdt, bchusdt, ethbtc, ltcbtc, etcbtc, bchbtc... | |
type | true | string | Depth 类型 | step0, step1, step2, step3, step4, step5(合并深度0-5);step0时,不合并深度 |
用户选择“合并深度”时,一定报价精度内的市场挂单将予以合并显示(具体合并规则见GET /market/symbols)。合并深度仅改变显示方式,不改变实际成交价。
正确订阅例子
{
"sub": "market.btcusdt.depth.step0",
"id": "id1"
}
订阅成功返回数据的例子
{
"id": "id1",
"status": "ok",
"subbed": "market.btcusdt.depth.step0",
"ts": 1489474081631
}
之后每当 depth 有更新时,client 会收到数据,例子
{
"ch": "market.btcusdt.depth.step0",
"ts": 1489474082831,
"tick": {
"bids": [
[9999.3900,0.0098], // [price, amount]
[9992.5947,0.0560],
// more Market Depth data here
]
"asks": [
[10010.9800,0.0099]
[10011.3900,2.0000]
//more data here
]
}
}
tick 说明
"tick": {
"bids": [
[买1价,买1量]
[买2价,买2量]
//more data here
]
"asks": [
[卖1价,卖1量]
[卖2价,卖2量]
//more data here
]
}
请求 Market Depth 数据 market.$symbol.depth.$type
{
"req": "market.$symbol.depth.$type",
"id": "id generated by client"
}
请求 Market Depth 数据的例子
{
"req": "market.btcusdt.depth.step0",
"id": "id10"
}
返回数据的例子:
{
"rep": "market.btcusdt.depth.step0",
"status": "ok",
"id": "id10",
"tick": {
"bids": [
[9999.3900,0.0098], // [price, amount]
[9992.5947,0.0560],
// more Market Depth data here
]
"asks": [
[10010.9800,0.0099]
[10011.3900,2.0000]
//more data here
]
}
}
订阅 Trade Detail 数据 market.$symbol.trade.detail
{
"sub": "market.$symbol.trade.detail",
"id": "id generated by client"
}
参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 |
---|---|---|---|---|---|
symbol | true | string | 交易对 | btcusdt, ethusdt, ltcusdt, etcusdt, bchusdt, ethbtc, ltcbtc, etcbtc, bchbtc... |
正确订阅例子:
{
"sub": "market.btcusdt.trade.detail",
"id": "id1"
}
订阅成功返回数据的例子:
{
"id": "id1",
"status": "ok",
"subbed": "market.btcusdt.trade.detail",
"ts": 1489474081631
}
之后每当 Trade Detail 有更新时,client 会收到数据,例子:
{
"ch": "market.btcusdt.trade.detail",
"ts": 1489474082831,
"tick": {
"id": 14650745135,
"ts": 1533265950234,
"data": [
{
"amount": 0.0099,
"ts": 1533265950234,
"id": 146507451359183894799,
"price": 401.74,
"direction": "buy"
},
// more Trade Detail data here
]
}
]
}
}
data 说明:
"data": [
{
"id": 消息ID,
"price": 成交价,
"time": 成交时间,
"amount": 成交量,
"direction": 成交方向,
"tradeId": 成交ID,
"ts": 时间戳
}
]
请求 Trade Detail 数据 market.$symbol.trade.detail
{
"req": "market.$symbol.trade.detail",
"id": "id generated by client"
}
- 仅能获取最近 300 个 Trade Detail 数据
请求 Trade Detail 数据的例子
{
"req": "market.btcusdt.trade.detail",
"id": "id11"
}
返回数据的例子:
{
"rep": "market.btcusdt.trade.detail",
"status": "ok",
"id": "id11",
"data": [
{
"id": 601595424,
"price": 10195.64,
"time": 1494495766,
"amount": 0.2943,
"direction": "buy",
"tradeId": 601595424,
"ts": 1494495766000
},
{
"id": 601595423,
"price": 10195.64,
"time": 1494495711,
"amount": 0.2430,
"direction": "buy",
"tradeId": 601595423,
"ts": 1494495711000
},
// more Trade Detail data here
]
}
请求 Market Detail 数据 market.$symbol.detail
{
"req": "market.$symbol.detail",
"id": "id generated by client"
}
- 仅返回当前 Market Detail
请求 Market Detail 数据的例子
{
"req": "market.btcusdt.detail",
"id": "id12"
}
返回数据的例子:
{
"rep": "market.btcusdt.detail",
"status": "ok",
"id": "id12",
"tick": {
"amount": 12224.2922,
"open": 9790.52,
"close": 10195.00,
"high": 10300.00,
"ts": 1494496390000,
"id": 1494496390,
"count": 15195,
"low": 9657.00,
"vol": 121906001.754751
}
}
订阅accounts
订阅accounts资产变动更新。
订阅请求数据格式说明
字段名称 | 类型 | 说明 |
---|---|---|
op | string | 必填;操作名称,订阅固定值为 sub; |
cid | string | 选填;Client 请求唯一 ID |
topic | string | 必填;订阅主题名称,详细主题列表请参考附录; |
订阅请求示例
正确的订阅请求
{
"op": "sub",
"cid": "40sG903yz80oDFWr",
"topic": "accounts"
}
订阅成功返回数据示例
{
"op": "sub",
"cid": "40sG903yz80oDFWr",
"err-code": 0,
"ts": 1489474081631,
"topic": "accounts"
}
之后每当 Account 有更新时,Client 会收到数据,比如,
{
"op": "notify",
"ts": 1522856623232,
"topic": "accounts",
"data": {
"event": "order.match|order.place|order.refund|order.cancel|order.fee-refund|margin.transfer|margin.loan|margin.interest|margin.repay|other",
"list": [
{
"account-id": 419013,
"currency": "usdt",
"type": "trade",
"balance": "500009195917.4362872650"
},
{
"account-id": 419013,
"currency": "btc",
"type": "frozen",
"balance": "9786.6783000000"
}
]
}
}
Accounts变化通知数据格式说明
名称 | 类型 | 说明 |
---|---|---|
event | string | 资产变化通知相关事件说明,比如订单创建(order.place) 、订单成交(order.match)、订单成交退款(order.refund)、订单撤销(order.cancel) 、点卡抵扣交易手续费(order.fee-refund)、杠杆账户划转(margin.transfer)、借贷本金(margin.loan)、借贷计息(margin.interest)、归还借贷本金利息(margin.repay)、其他资产变化(other) |
account-id | long | 账户 id |
currency | string | 币种 |
type | string | 账户类型, 比如交易可用账户(trade),交易冻结账户(frozen) |
balance | string | 账户余额 |
订阅orders.$symbol
订阅订单更新
订阅请求数据格式说明
字段名称 | 类型 | 说明 |
---|---|---|
op | string | 必填;操作名称,订阅固定值为 sub; |
cid | string | 选填;Client 请求唯一 ID |
topic | string | 必填;订阅主题名称,详细主题列表请参考附录; |
正确的订阅请求
{
"op": "sub",
"cid": "40sG903yz80oDFWr",
"topic": "orders.htusdt"
}
订阅成功返回数据示例
{
"op": "sub",
"cid": "40sG903yz80oDFWr",
"err-code": 0,
"ts": 1489474081631,
"topic": "orders.htusdt"
}
之后每当 Order 有更新时,Client 会收到数据,比如,
{
"op": "notify",
"topic": "orders.htusdt",
"ts": 1522856623232,
"data": {
"seq-id": 94984,
"order-id": 2039498445,
"symbol": "htusdt",
"account-id": 100077,
"order-amount": "5000.000000000000000000",
"order-price": "1.662100000000000000",
"created-at": 1522858623622,
"order-type": "buy-limit",
"order-source": "api",
"order-state": "filled",
"role": "taker|maker",
"price": "1.662100000000000000",
"filled-amount": "5000.000000000000000000",
"unfilled-amount": "0.000000000000000000",
"filled-cash-amount": "8301.357280000000000000",
"filled-fees": "8.000000000000000000"
}
}
订单变化通知数据格式说明
名称 | 类型 | 说明 |
---|---|---|
seq-id | long | 流水号(不连续) |
order-id | long | 订单 id |
symbol | string | 交易对 |
account-id | long | 账户 id |
order-amount | string | 订单数量 |
order-price | string | 订单价格 |
created-at | long | 订单创建时间 |
order-type | string | 订单类型,请参考订单类型说明 |
order-source | string | 订单来源,请参考订单来源说明 |
order-state | string | 订单状态,请参考订单状态说明 |
role | string | maker, taker |
price | string | 成交价格 |
filled-amount | string | 单次成交数量 |
unfilled-amount | string | 单次未成交数量 |
filled-cash-amount | string | 单次成交金额 |
filled-fees | string | 单次成交手续费(买入为币,卖出为钱) |
错误订阅请求示例(错误的 topic)
{
"op": "sub",
"topic": "foo.bar",
"cid": "40sG903yz80oDFWr"
}
订阅失败会返回下面示例数据
{
"op": "sub",
"topic": "foo.bar",
"cid": "40sG903yz80oDFWr",
"err-code": 1001, //具体编码请参考响应码表
"err-msg": “详细的错误信息”,
"ts": 1489474081631
}
取消订阅数据(unsub)
成功建立和 WebSocket API 的连接之后,向 Server 发送如下格式的数据来取消订阅数据:
取消订阅请求数据格式
{
“op”: “unsub”,
“topic": "topic to unsub”,
"cid": "id generated by client”,
}
取消订阅请求数据格式说明
字段名称 | 类型 | 说明 |
---|---|---|
op | string | 必填;操作名称,订阅固定值为 unsub; |
cid | string | 选填;Client 请求唯一 ID |
topic | string | 必填;待取消订阅主题名称,详细主题列表请参考附录; |
取消订阅请求示例
正确的取消订阅请求
{
"op": "unsub",
"topic": "accounts",
"cid": "40sG903yz80oDFWr"
}
取消订阅成功返回数据示例
{
"op": "unsub",
"topic": "accounts",
"cid": "id generated by client",
"err-code": 0,
"ts": 1489474081631
}
订阅与取消订阅规则说明
订阅(sub) | 取消订阅(unsub) | 规则 |
---|---|---|
accounts | accounts | 允许 |
orders.* | orders.* | 允许 |
orders.symbol1 | orders.* | 允许 |
orders.symbol1 | orders.symbol1 | 允许 |
orders.symbol1 | orders.symbol2 | 不允许 |
orders.* | orders.symbol1 | 不允许 |
请求用户资产 - accounts.list
查询当前用户的所有账户余额数据
成功建立和 WebSocket API 的连接之后,向 Server发送如下格式的数据来查询账户数据:
账户查询请求数据格式说明
字段名称 | 类型 | 说明 |
---|---|---|
op | string | 必填;操作名称,固定值为 req; |
cid | string | 选填;Client 请求唯一 ID |
topic | string | 必填;固定值为accounts.list,详细主题列表请参考附录; |
账户查询请求示例
请求内容
{
"op": "req",
"topic": "accounts.list",
"cid": "40sG903yz80oDFWr"
}
调用成功返回数据
{
"op": "req",
"topic": "accounts.list",
"cid": "40sG903yz80oDFWr"
"err-code": 0,
"ts": 1489474082831,
"data": [
{
"id": 419013,
"type": "spot",
"state": "working",
"list": [
{
"currency": "usdt",
"type": "trade",
"balance": "500009195917.4362872650"
},
{
"currency": "usdt",
"type": "frozen",
"balance": "9786.6783000000"
}
]
},
{
"id": 35535,
"type": "point",
"state": "working",
"list": [
{
"currency": "eth",
"type": "trade",
"balance": "499999894616.1302471000"
},
{
"currency": "eth",
"type": "frozen",
"balance": "9786.6783000000"
}
]
}
]
}
调用失败应答数据示例
{
"op": "req",
"topic": "foo.bar",
"cid": "40sG903yz80oDFWr"
"err-code": 12001, //具体编码需要参考响应码表
“err-msg": "详细的错误信息”,
"ts": 1489474081631
}
请求交易订单 - orders.list
查询当前委托、历史委托
成功建立和 WebSocket API 的连接之后,向 Server发送如下格式的数据来查询委托数据:
订单列表查询请求数据格式
{
"op": "req",
"topic": "orders.list",
"cid": "40sG903yz80oDFWr",
"account-id": "$account-id",
"symbol": "$symbol",
"types": "$order-type",
"start-date": "$start-date",
"end-date": "$end-date",
"states": "$order-state",
"from": "$from",
"direct": "$direct",
"size": "$size"
}
订单查询请求数据格式说明
参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 |
---|---|---|---|---|---|
op | true | string | 操作名称,固定值为 req | ||
cid | false | string | Client 请求唯一 ID | ||
topic | true | string | 固定值为 orders.list,详细主题列表请参考附录 | ||
account-id | true | long | 账户 id | ||
symbol | true | string | 交易对 | btcusdt, ltcbtc, etcbtc, htusdt...... | |
types | false | string | 查询的订单类型组合,使用','分割 | 参考订单类型说明 | |
start-date | false | string | 查询开始日期, 日期格式yyyy-mm-dd | ||
end-date | false | string | 查询结束日期, 日期格式yyyy-mm-dd | ||
states | true | string | 查询的订单状态组合,使用','分割 | ||
from | false | string | 查询起始 ID | ||
direct | false | string | 查询方向 | prev 向前,next 向后 | |
size | false | string | 查询记录大小 |
订单列表查询请求示例
{
"op": "req",
"topic": "orders.list",
"cid": "40sG903yz80oDFWr",
"symbol": "htusdt",
"states": "submitted,partial-filled"
}
调用成功返回数据
{
"op": "req",
"topic": "orders.list",
"cid": "40sG903yz80oDFWr",
"err-code": 0,
"ts": 1522856623232,
"data": [
{
"id": 2039498445,
"symbol": "htusdt",
"account-id": 100077,
"amount": "5000.000000000000000000",
"price": "1.662100000000000000",
"created-at": 1522858623622,
"type": "buy-limit",
"filled-amount": "5000.000000000000000000",
"filled-cash-amount": "8301.357280000000000000",
"filled-fees": "8.000000000000000000",
"finished-at": 1522858624796,
"source": "api",
"state": "filled",
"canceled-at": 0
}
]
}
应答数据格式说明,
名称 | 类型 | 说明 |
---|---|---|
id | long | 订单ID |
symbol | string | 交易对 |
account-id | long | 账户ID |
amount | string | 订单数量 |
price | string | 订单价格 |
created-at | long | 订单创建时间 |
type | string | 订单类型,请参考订单类型说明 |
filled-amount | string | 已成交数量 |
filled-cash-amount | string | 已成交总金额 |
filled-fees | string | 已成交手续费 |
finished-at | string | 最后成交时间 |
source | string | 订单来源,请参考订单来源说明 |
state | string | 订单状态,请参考订单状态说明 |
cancel-at | long | 撤单时间 |
请求某个订单详情 - orders.detail
查询某个订单详情
成功建立和 WebSocket API 的连接之后,向 Server发送如下格式的数据来查询某个订单详情数据:
订单详情查询请求数据格式
{
"op": "req",
"topic": "orders.detail",
"order-id": "$order-id"
"cid": "40sG903yz80oDFWr"
}
订单详情查询请求数据格式说明
参数名称 | 是否必须 | 类型 | 描述 | 默认值 | 取值范围 |
---|---|---|---|---|---|
op | true | string | 操作名称,固定值为 req | ||
cid | true | string | Client 请求唯一 ID | ||
topic | false | string | 固定值为 orders.detail,详细主题列表请参考附录 | ||
order-id | true | string | 订单ID |
订单详情查询请求示例
请求内容
{
"op": "req",
"topic": "orders.detail",
"order-id": "2039498445"
"cid": "40sG903yz80oDFWr"
}
调用成功返回数据示例
{
"op": "req",
"topic": "orders.detail",
"cid": "40sG903yz80oDFWr"
"err-code": 0,
"ts": 1522856623232,
"data": {
"id": 2039498445,
"symbol": "htusdt",
"account-id": 100077,
"amount": "5000.000000000000000000",
"price": "1.662100000000000000",
"created-at": 1522858623622,
"type": "buy-limit",
"filled-amount": "5000.000000000000000000",
"filled-cash-amount": "8301.357280000000000000",
"filled-fees": "8.000000000000000000",
"finished-at": 1522858624796,
"source": "api",
"state": "filled",
"canceled-at": 0
}
}
请求数据(req)限流策略
为鼓励用户使用订阅接收数据推送,对查询请求做了限流策略, 规则如下:
- accounts.list 查询请求,同一个用户(不论几个连接),每2次请求间隔不能小于25秒(此数字可能发生变化),否则会接收到“too many request"的错误应答。
- orders.list 和 orders.detail 查询请求,同一个用户(不论几个连接),每2次请求间隔不能小于5秒(此数字可能发生变化),否则会接收到“too many request"的错误应答。
附录
操作类型(OP )说明
类型 | 描述 |
---|---|
ping | 心跳发起(server) |
pong | 心跳应答 |
auth | 鉴权 |
sub | 订阅消息 |
unsub | 取消订阅消息 |
req | 请求数据 |
notify | 推送订阅消息(server) |
主题 (Topic) 类型说明
类型 | 适用操作类型 | 描述 |
---|---|---|
accounts | sub, unsub | 订阅、取消订阅所有资产变更消息 |
orders.$symbol | sub, unsub | 订阅、取消订阅指定交易对的订单变更消息,当 $symbol值为 * 时代表订阅所有交易对 |
accounts.list | req | 账户数据请求 |
orders.list | req | 订单列表查询请求 |
orders.detail | req | 订单详情查询请求 |
响应码(Err-Code)说明
具体码表请参照
error.json
订单类型(Order Type)说明
类型 | 描述 |
---|---|
buy-market | 市价买 |
sell-market | 市价卖 |
buy-limit | 限价买 |
sell-limit | 限价卖 |
buy-ioc | 买入立即执行或撤销 |
sell-ioc | 卖出立即执行或撤销 |
buy-limit-maker | 限价买入(只能成为maker) |
Sell-limit-maker | 限价卖出(只能成为maker) |
订单状态(Order State)说明
类型 | 描述 |
---|---|
submitted | 已提交 |
partial-filled | 部分成交 |
partial-canceled | 部分成交撤销(终态) |
filled | 完全成交(终态) |
canceled | 已撤销(终态) |
订单来源(Order Source)说明
类型 | 描述 |
---|---|
spot-web | 现货 Web 交易单 |
spot-api | 现货 Api 交易单 |
spot-app | 现货 App 交易单 |
margin-web | 借贷 Web 交易单 |
margin-api | 借贷 Api 交易单 |
margin-app | 借贷 App 交易单 |
fl-sys | 借贷强制平仓单(爆仓单) |