- ws的接入方式,以wss://global-api.bithumb.pro/message/realtime为地址,用户可以按着文档的步骤,进行接入。
- topic:服务端支持订阅的主题(用户可以根据自己的需要订阅相关的主题,一旦订阅,当服务端产生相关的信息时,则会向该通道发送消息),包含普通的主题(不需要身份认证,像行情,订单薄等),私有主题(需要先进行身份认证,认证成功后,即可订阅该类主题,像私有订单变化,仓位变化等)。
- 有些topic的响应信息里可能会包含ver字段,这个字段是用来防治消息出现回溯的情况
- 私有主题(private topic),该类主题一旦订阅,一个用户账户同一时刻只允许一个包含私有topic的链接,如果存在多个,则会导致接受不到消息。
ws的请求方式可以为:wss(ws)://{域名}/message/realtime 或者以如下的方式: wss(ws)://{域名}/message/realtime?subscribe=ORDERBOOK:BTC-USDT,TICKER:BTC-USDT
用户可以在创建连接的时候,订阅主题信息,并完成身份认证,通过header传递加密后的身份信息,服务端对传上来的信息进行校验,一旦验证通过,即可订阅私有主题,否则会立马关闭通道.
header的信息如下:
{
"apiKey":"",(从网页上获取)
"apiTimestamp":"1551848831",(连接发起的时间戳(毫秒),类型string)
"apiSignature":""(签名数据,签名方式见下)
}
签名串:
请求路径="/message/realtime"
signatureString="请求路径"+当前的时间戳(毫秒)+apiKey
apiSignature = sha256_HMAC(signatureString,secretKey)
响应的消息格式如下:
{
"code":4,
"data":{},
"timestamp":1552037368,
"topic":"CONTRACT_TICKER"
}
code:为响应消息标记(详情请见code详解)
data:响应的消息体
timestamp:服务器发送的消息时间
topic:主题
基本的命令发送的格式:
{"cmd":"", "args":["args1","args2","args3"...]}
cmd有四种指令:
subscribe: 用于订阅topic
unSubscribe: 用于取消订阅topic
authKey: 身份认证,用户可以在连接建立后,通过发送该指令,获取订阅私有topic的权限
ping: 心跳指令,客户端可设置为30s发送一次。客户端用来维持和服务器的连接的状态,超时未发送该指令时,服务端会清除掉此连接。
args参数数组:
subscribe指令:支持多个主题,例如:["TICKER:BTC-USDT","ORDERBOOK10:BTC-USDT"]
authKey指令:args数组是固定的,["apiKey","timestamp(毫秒,类型为string)","apiSignature"]
ping指令:不需要args
签名串:
请求路径="/message/realtime"
signatureString="请求路径"+当前的时间戳(毫秒)+apiKey
apiSignature = sha256_HMAC(signatureString,secretKey)
用户订阅某个交易对或合约的主题时,格式为:topic:symbol.例如:TICKER:BTC-USDT
目前支持的主题有如下几种,包含公共主题和私有主题:
消息体如下:
字段 | 说明 | 备注 | 类型 |
---|---|---|---|
c | 最新成交价 | String | |
h | 24小时最高价 | String | |
l | 24小时最低价 | String | |
p | 24小时涨跌幅 | String | |
symbol | 合约符号 | String | |
v | 24小时成交量 | String | |
ver | 版本号 | 该字段是单调递增的,用来保证消息不会出现回溯 | String |
示例:
{
"code":4,
"data": {
"c":"0.0015007503751875",
"h":"4005",
"l":"3998",
"p":"0.01",
"symbol":"TBTCUSD",
"v":"3577",
"ver":"314"
},
"timestamp":1553234681,
"topic":"TICKER"
}
注意:客户端完整的订单薄创建必须严格依赖于‘ver’字段的处理,当客户端订阅了该主题后,收到code=00007的消息为订单薄的增量变化信息,code=00006的消息为一次性完整订单薄信息,但是这两次的‘ver’可能不是连续的,此时可能会出现消息丢失的情况,完整的订单薄创建流程如下:
1、客户端先订阅具体交易对的websocket的ORDERBOOK主题,将收到的code=00007的订单薄变化信息存放于客户端的缓存中;
2、客户端通过rest api请求一次完整的订单薄信息;
3、最后将缓存的订单薄变化信息和完整的订单薄做一次合并,合并的规则是:
a:判断websocket收到的第一个订单薄变化版本‘ver’需小于或等于完整的订单薄版本‘ver’ + 1,否则需要重新继续上述过程重建订单薄;
b:判断每一个订单薄变化版本‘ver’ 需大于完整的订单薄版本‘ver’,否则丢弃该订单薄变化信息。
消息体如下:
字段 | 说明 | 备注 | 类型 |
---|---|---|---|
b | bids(买订单薄) | String[2],第一个为price,第二个为quantity | |
s | asks(卖订单薄) | String[2],第一个为price,第二个为quantity | |
symbol | 合约符号 | String | |
ver | 版本号 | 该字段是单调递增的,用来保证消息不会出现回溯 | String |
示例:
{
"code":4,
"data":{
"b":[["4003.5","1"],["4001.5","890"],["4000.5","10"],["3997","36"],["3996","100"]],
"s":[["4005","100"],["4006","107"]],
"symbol":"TBTCUSD",
"ver":"375"
},
"timestamp":1553235407,
"topic":"CONTRACT_ORDERBOOK"
}
消息体如下:
字段 | 说明 | 备注 | 类型 |
---|---|---|---|
p | 成交价格 | String | |
s | 交易类型 | buy or sell | String |
v | 成交量 | String | |
t | 成交时间戳 | String | |
symbol | 合约符号 | String | |
ver | 版本号 | 该字段是单调递增的,用来保证消息不会出现回溯 | String |
示例:
{
"code":4,
"data":{
"p":"4003.5",
"s":"buy",
"v":"0.1",
"t":"",
"symbol":"TBTCUSD",
"ver":"375"
},
"timestamp":1553235407,
"topic":"CONTRACT_ORDERBOOK"
}
CONTRACT_TICKER: 推送最新的合约行情消息
消息体如下:
字段 | 说明 | 备注 | 类型 |
---|---|---|---|
change | 24小时涨跌幅(需要*100才是百分数) | String | |
fundRate0 | 下次合约费率交换值 | String | |
fundTime0 | 下次费率交换的时间 | String | |
high | 24小时最高价 | String | |
low | 24小时最低价 | String | |
lastPrice | 最新成交价 | String | |
openValue | 未平仓数量 | String | |
symbol | 合约符号 | String | |
volume | 24小时成交量 | String | |
ver | 版本号 | 该字段是单调递增的,用来保证消息不会出现回溯 | String |
openInterest | String | ||
turnover | String |
示例:
{
"code":4,
"data": {
"change":"0.0015007503751875",
"fundRate0":"0.00375",
"fundTime0":"1553241600",
"high":"4005",
"low":"3998",
"lastPrice":"4004",
"openValue":"1.1581583219035874",
"symbol":"TBTCUSD",
"volume":"3577",
"ver":"314",
"openInterest":"",
"turnover":""
},
"timestamp":1553234681,
"topic":"CONTRACT_TICKER"
}
CONTRACT_ORDERBOOK:推送最新的合约订单薄消息,订阅完成,会立马返回全量的最新订单薄,后续当订单薄发生变化,会推送增量的订单薄变化信息,特别的当quantity=0时,表示订单薄里该档已经不存在了
消息体如下:
字段 | 说明 | 备注 | 类型 |
---|---|---|---|
b | bids订单薄 | String[2],第一个为price,第二个为quantity | |
s | asks订单薄 | String[2],第一个为price,第二个为quantity | |
symbol | 合约符号 | String | |
ver | 版本号 | String |
示例:
{
"code":4,
"data":{
"b":[["4003.5","1"],["4001.5","890"],["4000.5","10"],["3997","36"],["3996","100"]],
"s":[["4005","100"],["4006","107"]],
"symbol":"TBTCUSD",
"ver":"375"
},
"timestamp":1553235407,
"topic":"CONTRACT_ORDERBOOK"
}
CONTRACT_ORDERBOOK10:推送最新的合约订单薄消息,包含最新的买卖10条,订阅完成,会立马返回全量的最新订单薄,后续当订单薄发生变化时,会立即推送最新的买卖10订单薄
消息体参考CONTRACT_ORDERBOOK
消息体如下:
字段 | 说明 | 备注 | 类型 |
---|---|---|---|
oId | 订单id | String | |
price | 订单委托价格 | 当为“-1”时,表示市价 | String |
quantity | 订单委托数量 | String | |
side | 订单方向 | buy or sell | String |
symbol | String | ||
type | 订单类型 | limit or market | String |
status | 订单状态 | created(已创建),partDealt(部分成交),fullDealt(完全成交),canceled(已撤单) | String |
dealPrice | 成交价格 | 撤单时为0 | String |
dealQuantity | 成交数量 | 撤单时为0 | String |
dealVolume | 成交额 | 撤单时为0 | String |
fee | 手续费 | 撤单时为0 | String |
feeType | 手续费的单位 | 撤单时为"" | String |
cancelQuantity | 撤单的数量 | String | |
time | 订单变化发生时间 | Long |
示例:
{
"code":"00007",
"data":{"cancelQuantity":"10060.7","dealPrice":"0","dealQuantity":"0","dealVolume":"0","fee":"0","feeType":"","oId":"69663509668139008","price":"100.607","quantity":"100","side":"buy","status":"canceled","symbol":"BTC-USDT","time":1560758352705,"type":"limit"},
"topic":"ORDER",
"timestamp":1560758352743}
CONTRACT_ORDER: 推送用户私有合约订单的消息,当其订单发生变化时,如果用户订阅了此主题,则立即会向订阅的channel里发送消息
消息体如下:
字段 | 说明 | 备注 | 类型 |
---|---|---|---|
amountFill | 已成交的数量 | String | |
amountReal | 委托数量 | String | |
avgPrice | 成交均价 | String | |
msgNo | 用户自定义的请求信息 | String | |
orderId | 订单ID | String | |
price | 委托价格 | String | |
side | 方向 | buy,sell | String |
status | 订单状态 | (open(挂单中),filled(已成交),cancel(已取消),rejected(已拒绝)) | String |
symbol | 合约符号 | String | |
type | 订单类型 | limit,market | String |
time | 下单时间 | Long |
示例:
{
"code":4,
"data":{
"amountFill":"0",
"amountReal":"1",
"avgPrice":"4004",
"msgNo":"",
"orderId":"38112649639268352",
"price":"4004",
"side":"buy",
"status":"open",
"symbol":"TBTCUSD",
"type":"limit",
"time":1553245866000
},
"topic":"CONTRACT_ORDER",
"timestamp":1553235866
}
CONTRACT_ASSET: 推送用户私有资产的消息,当用户资产发生变动时,如果用户订阅了此主题,则立即会向订阅的channel里发送消息
消息体如下:
字段 | 说明 | 备注 | 类型 |
---|---|---|---|
availableAmount | 可用余额 | String | |
totalAmount | 总资产 | String | |
coin | 资产类型 | String | |
openPositionMargin | 仓位保证金 | String | |
openOrderMarginTotal | 委托保证金 | String | |
remainMargin | 保证金余额 | String |
示例:
{
"code":4,
"data":{
"availableAmount":"100000.0068646403170306",
"totalAmount":"100000.0096280041581585",
"coin":"BTC",
"openPositionMargin":"0.0000200306255019",
"openOrderMarginTotal":"0.0027432190040949",
"remainMargin":"0.0027633638411279"
},
"topic":"CONTRACT_ASSET",
"timestamp":1553236515
}
CONTRACT_POSITION: 推送用户合约私有仓位信息,当用户的合约仓位发生变动时,如果用户订阅了此主题,则立即会向订阅的channel里发送消息
消息体如下:
字段 | 说明 | 备注 | 类型 |
---|---|---|---|
symbol | 合约符号 | String | |
positionId | 仓位ID | String | |
amount | 仓位数量 | String | |
side | buy or sell | String | |
entryPrice | 开仓价格 | String | |
liquiPrice | 强平价格 | String | |
frozen | 冻结的金额 | String | |
margin | 仓位保证金 | String | |
positionValue | 仓位价值 | String | |
markPrice | 计算的mark价格 | String | |
maxRemovableMarginAmount | 最大可移除保证金 | String | |
lastUpdateTime | position最后变动的时间戳 | String | |
status | 仓位状态,newOpen(初始化),open,close | String | |
realProfit | 已实现盈亏 | String | |
leverage | 杠杆值 | String |
示例:
{
"code":4,
"data":{
"symbol":"BTCUSD",
"positionId":"100001",
"amount":"100",
"entryPrice":"4800",
"liquiPrice":"4820",
"frozen":"0.02083",
"margin":"0.03",
"positionValue":"0.02083",
"markPrice":"4802",
"maxRemovableMarginAmount":"0.001",
"lastUpdateTime":"1553580895",
"status":"open",
"realProfit":"0.01",
"leverage":"1"
},
"topic":"CONTRACT_POSITION",
"timestamp":1553236515
}
CONTRACT_INFO: 推送用户私有的通用消息,当用户仓位,订单,资产发生变动时,如果用户订阅了此主题,则立即会向订阅的channel里发送消息
消息体如下:
字段 | 说明 | 备注 | 类型 |
---|---|---|---|
symbol | 合约符号 | String | |
riskLimit | 风险限额 | String | |
leverage | 杠杆倍数 | String | |
fundRate0 | 资金费用 | String |
示例:
{
"code":4,
"data":{
"symbol":"100000.0068646403170306",
"riskLimit":"100000.0096280041581585",
"leverage":"BTC",
"fundRate0":"0.0000200306255019"
},
"topic":"CONTRACT_INFO",
"timestamp":1553236515
}
code格式为String,10000以下的code表示为服务端产生的正确的响应信息,10000以上的表示为错误的响应
code | msg | mark |
---|---|---|
0 | Pong | |
00000 | Auth key success | |
00001 | Subscribe success | |
00002 | Connect success | |
00003 | UnSubscribe success | |
00006 | Init msg | |
00007 | Normal msg | |
10000 | No cmd | |
10001 | No apiKey | |
10002 | Invalid apiKey | |
10003 | Signature Fail | |
10004 | Need verify apiKey | |
10005 | No topic | |
99999 | UnKnow error |