# WebSocket API
# 混合合约
以下是混合合约相关 WebSocket API，主要包括：交易只读 API，以及行情 API。主要以订阅消息的方式接收用户数据和行情数据更新，如需获取初始记录，可以访问 HTTP API。
# WebSocket 概述
WebSocket 是 HTML5 一种新的协议(Protocol)。它实现了客户端与服务器全双工通信，使得数据可以快速地双向传播。通过一次简单的握手就可以建立客户端和服务器连接，服务器根据业务规则可以主动推送信息给客户端。其优点如下：
- 客户端和服务器进行数据传输时，请求头信息比较小，大概 2 个字节。
- 客户端和服务器皆可以主动地发送数据给对方。
- 不需要多次创建 TCP 请求和销毁，节约宽带和服务器的资源。
# 指令格式
# 消息格式
信息基于 GSON 格式传递
# 订阅数据更新
订阅数据的动态更新，需要指定具体的 channel，以及需要的参数
{"op":"subscribe", "channel":"xxxxxx", ...}
# 数据更新
根据订阅返回更新数据，event 为对应订阅的 channel 路径
{"event": "xxxxxx", ...}
# 取消订阅
取消订阅数据的动态更新，与订阅类似，同样需要指定具体的 channel，以及需要的参数
{"op":"unsubscribe", "channel":"xxxxxx", ...}
# 行情数据
# 链接
wss://api.bitcoke.cc/ws/market
# 指数价
Channel：/api/basic/indexPrice；订阅格式如下：
{"op":"subscribe", "channel":"/api/basic/indexPrice", "key":"BTCUSD"}
数据更新格式如下：
{"symbol":"BTCUSD","price":42185.0175,"time":1632279344860}
取消订阅：
{"op":"unsubscribe", "channel":"/api/basic/indexPrice", "key":"BTCUSD"}
# 标记价
Channel：/api/basic/markPrice；订阅格式如下：
{"op":"subscribe", "channel":"/api/basic/markPrice", "key":"BTCUSD"}
数据更新格式如下：
{"symbol":"BTCUSD","price":42081.77333333333,"time":1632279504363}
取消订阅：
{"op":"unsubscribe", "channel":"/api/basic/markPrice", "key":"BTCUSD"}
# 合约成交价
Channel：/api/basic/lastPrice；订阅格式如下：
{"op":"subscribe", "channel":"/api/basic/lastPrice", "key":"XBTCUSD"}
数据更新格式如下：
{"symbol":"XBTCUSD","price":42058.0,"time":1632279653441}
取消订阅：
{"op":"unsubscribe", "channel":"/api/basic/lastPrice", "key":"XBTCUSD"}
# 深度
Channel：/api/depth/depth；订阅格式如下：
{"op":"subscribe", "channel":"/api/depth/depth", "key":"XBTCUSD"}
数据更新格式如下：
{
"buyDepth": [
{
"price": 9482,
"qty": 160929,
"count": 13,
"iceCount": 0
},
{
"price": 9481,
"qty": 130095,
"count": 7,
"iceCount": 0
},
{
"price": 9463,
"qty": 384114,
"count": 6,
"iceCount": 0
},
{
"price": 9483,
"qty": 0,
"count": 0,
"iceCount": 0
}
],
"sellDepth": [
{
"price": 9483,
"qty": 9331,
"count": 1,
"iceCount": 0
},
{
"price": 9494,
"qty": 201324,
"count": 13,
"iceCount": 0
},
{
"price": 9503,
"qty": 0,
"count": 0,
"iceCount": 0
}
],
"trades": [
{
"id": "1592385671049000011",
"symbol": "XBTCUSD",
"price": 9482,
"qty": 704,
"buyActive": false,
"timestamp": "Jun 17, 2020 09:21:11 AM"
},
{
"id": "1592385671049000008",
"symbol": "XBTCUSD",
"price": 9482,
"qty": 243,
"buyActive": false,
"timestamp": "Jun 17, 2020 09:21:11 AM"
},
{
"id": "1592385671049000005",
"symbol": "XBTCUSD",
"price": 9482,
"qty": 866,
"buyActive": false,
"timestamp": "Jun 17, 2020 09:21:11 AM"
},
{
"id": "1592385671048000003",
"symbol": "XBTCUSD",
"price": 9483,
"qty": 11596,
"buyActive": true,
"timestamp": "Jun 17, 2020 09:21:11 AM"
}
],
"key": "XBTCUSD",
"event": "/api/depth/depth"
}
取消订阅：
{"op":"unsubscribe", "channel":"/api/depth/depth", "key":"XBTCUSD"}
# 资金费率
Channel：/api/kLine/fundingRate；订阅格式如下：
{"op":"subscribe", "channel":"/api/kLine/fundingRate", "key":"XBTCUSD"}
数据更新格式如下：
{
"key": "XBTCUSD",
"event": "/api/kLine/fundingRate",
"rate": -0.0001,
"date": "Jun 17, 2020 12:00:00 PM"
}
取消订阅：
{"op":"unsubscribe", "channel":"/api/kLine/fundingRate", "key":"XBTCUSD"}
# 持仓量
Channel：/api/kLine/openInterest；订阅格式如下：
{"op":"subscribe", "channel":"/api/kLine/openInterest", "key":"BTCUSD"}
数据更新格式如下：
{
"key": "BTCUSD",
"event": "/api/kLine/openInterest",
"value": 6323.8854145971545,
"date": "Jun 17, 2020 09:42:26 AM",
"qty": 60000677
}
取消订阅：
{"op":"unsubscribe", "channel":"/api/kLine/openInterest", "key":"BTCUSD"}
# 24小时成交统计
Channel：/api/kLine/tradeStatistics；订阅格式如下：
{"op":"subscribe", "channel":"/api/kLine/tradeStatistics", "key":"XBTCUSD"}
数据更新格式如下：
{
"key": "XBTCUSD",
"event": "/api/kLine/tradeStatistics",
"maxPrice": 9591,
"minPrice": 9396,
"priceChange": -9,
"priceChangeRatio": -0.0009483667017913594,
"volume": 476875741,
"turnover": 50260.22409205384,
"lastPrice": 9481,
"volumeRatioList": [
0.04125656269781181,
0.3933914651530134,
0.5241644199874432,
0.5129134007442344,
0.5047321924171744,
0.5168734503777649,
0.4990268608778209
]
}
取消订阅：
{"op":"unsubscribe", "channel":"/api/kLine/tradeStatistics", "key":"XBTCUSD"}
# K 线更新
Channel：/api/kLine/kLine；订阅格式如下：
{"op":"subscribe", "channel":"/api/kLine/kLine", "key":"XBTCUSD", "type":"1M"}
数据更新格式如下：
{
"event": "/api/kLine/kLine",
"key": "XBTCUSD",
"type": "1M",
"open": 9482,
"close": 9481,
"high": 9482,
"low": 9478,
"keyTime": "Jun 17, 2020 09:47:00 AM",
"timeStamp": "Jun 17, 2020 09:47:52 AM",
"volume": 102120,
"turnover": 10.771662545934651
}
取消订阅：
{"op":"unsubscribe", "channel":"/api/kLine/kLine", "key":"XBTCUSD", "type":"1M"}
# 申请 API KEY
- 行情数据为开放数据，无需 API Key，就可以获取；交易只读和交易功能则需要 API Key。
- 交易 API KEY 分两种类型，只读 API，允许获取交易数据，包括：账户、持仓、订单等；可交易 API，支持下单、撤单、平仓、修改设定等，也可以获取交易数据。
- 申请 API Key 步骤：主页面 -> 资产 -> API 设置；申请成功后，切记要手动复制并保管好秘钥信息。
- API Key 数量限制：每个用户支持最多10个 Key。
# 交易 API 请求参数
所有只读 API 都有三个必须的参数：
- apiKey - 申请 API 时生成的 Key
- expires - 请求过期时间的秒数，时区为 UTC。如：当前时间：2019-12-30 11:29:20，请求的有效时间为10秒，就把当前时间加10秒，也就是：2019-12-30 11:29:30，转换为秒：1577676570；如果10秒后服务端才收到请求，则回报请求超时
- signature - 请求密文，加密方式：sha256Hex(secret + 请求方式GET/POST + 请求路径 + expires)；如：GET请求获取账号信息，sha256Hex(gJQxkMdaLxq9JdQO5yWoRwtaqlUNtwcFv_vk3FNzs5novWWeGET/api/trade/queryAccounts1577458481)
# 交易只读 API（GET）
# 链接
wss://api.bitcoke.cc/ws/trade
# 建立连接
连接创建成功后，收到如下信息，state 为 true，表示系统正常运行，可以进入下一步操作，格式如下：
{"state":true,"message":"On connect","event":"state"}
# 登录系统
建立链接后，需要用户登录系统；请求参数中，user 为用户的 uid，password 为用户密码通过 SHA1 加密后的密文，txId 则为唯一性字符串。如：
{"op":"login", "user":"uid", "password":"5f75ab6f9dec6fbf69adf1ca75f6a7e9672b06bb", "txId":"TX20200317-133934-511-458"}
响应数据：event 为对应请求的 op 值，errCode 为0表示登录成功，链接建立完成，txId 为对应请求的 txId 值；格式如下：
{"event":"login", "errCode": 0, "txId":"TX20200317-133934-511-458"}
# 维护连接
为防止因长时间无数据更新引起的 WebSocket 连接断开，请每30秒到1分钟发送一次心跳请求；如：
{"op":"heartbeat", "user":"uid","txId":"TX20200317-133934-511-458"}
心跳回报；格式如下：
{"event":"heartbeat", "errCode":0, "txId":"TX20200317-133934-511-458"}
# 交易账号
# 订阅账号数据更新
Channel: /api/trade/accountUpdate，通过订阅的方式接收账号的动态更新，格式如下：
{
"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
"signature": "745914181a51e05fd2dd735918fab0c6a96b4652ec18287792548b80571f89ec",
"expires": "1585688861",
"op": "subscribe",
"channel": "/api/trade/accountUpdate"
}
数据将每2秒发送一次更新，如果数据没有变化，则不发送更新，数据格式如下：
{
"account": {
"uid": "12345678",
"currency": "BTC",
"cash": 9.717310432978316,
"withdrawableCash": 9.717310432978316,
"frozenCash": 0.0,
"urPnl": 2.3944120552325733E-4
},
"key": "JhXdAeV77tG7g1sdbM6mHc0q",
"event": "/api/trade/accountUpdate"
}
# 取消订阅账号数据更新
{
"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
"op": "unsubscribe",
"channel": "/api/trade/accountUpdate"
}
# 订单信息
# 订阅订单数据更新
Channel：/api/trade/orderUpdate；订阅格式如下：
{
"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
"signature": "d8449a44530abb955fa01c65c250bc371a7c8e18f99bc180941e66772cd12610",
"expires": "1585688861",
"op": "subscribe",
"channel": "/api/trade/orderUpdate"
}
成功订阅后，如有下单操作，或已有订单状态发生变化，就会收到订单更新；格式如下:
{
"order": {
"id": "O101-20200331-075753-395-0155",
"uid": "12345678",
"symbol": "XBTCUSD",
"created": "Mar 31, 2020 07:57:53 AM",
"modified": "Mar 31, 2020 07:57:53 AM",
"side": "Buy",
"type": "Market",
"tif": "GOOD_TILL_CANCEL",
"currency": "BTC",
"price": 0.0,
"qty": 100.0,
"openPosition": true,
"cumQty": 0.0,
"avgPx": 0.0,
"ordStatus": "NEW",
"iceberg": false,
"showQty": 0.0,
"source": "Normal",
"pnl": 0.0,
"fee": 0.0
},
"key": "JhXdAeV77tG7g1sdbM6mHc0q",
"event": "/api/trade/orderUpdate"
}
# 取消订阅订单数据更新
{
"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
"op": "unsubscribe",
"channel": "/api/trade/orderUpdate"
}
# 仓位数据
# 订阅仓位数据更新
Channel: /api/trade/positionUpdate，格式如下：
{
"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
"signature": "f497e1a3a12a6fc4b9c77e5c0b372260a4bcc253f4db64a72a25cba81e62e0b1",
"expires": "1585688861",
"op": "subscribe",
"channel": "/api/trade/positionUpdate"
}
订阅成功，会收到仓位数据每2秒钟一次的更新数据，格式如下：
{
"position": {
"uid": "12345678",
"currency": "BTC",
"symbol": "XBTCUSD",
"side": "Short",
"qty": 9900.0,
"individualPosition": true,
"price": 6463.0,
"closableQty": 9900.0,
"pnlRate": "-Infinity",
"value": 1.5273531005480072,
"positionLeverage": 10,
"trailingStopPrice": 0.0,
"stopLossPrice": 0.0,
"stopWinPrice": 0.0,
"trailingStop": 0.0,
"pnl": -4.3524326253571645E-4,
"urPnL": -0.0044432788423687634,
"liquidationPrice": 6430.84577114428,
"deposit": 0.0,
"created": "Mar 31, 2020 07:18:55 AM",
"lastPrice": 9849
},
"key": "JhXdAeV77tG7g1sdbM6mHc0q",
"event": "/api/trade/positionUpdate"
}
# 取消订阅仓位数据更新
{
"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
"op": "unsubscribe",
"channel": "/api/trade/positionUpdate"
}
# 合约账号出入金
# 订阅合约账号出入金数据更新
Channel: /api/trade/tradeLedgerUpdate，格式如下：
{
"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
"signature": "873d0f75d484db86b7081d0276c636eb4b1582d53fb83ad0a1d898c65cd91aab",
"expires": "1585688861",
"op": "subscribe",
"channel": "/api/trade/tradeLedgerUpdate"
}
数据更新格式如下：
{
"tradeLedger": {
"id": "AC101-20200331-120000-003-0055",
"currency": "BTC",
"balance": 9.711536775876008,
"amount": -0.00580259456080025,
"transferType": "FUNDING",
"created": "Mar 31, 2020 12:00:00 PM"
},
"key": "JhXdAeV77tG7g1sdbM6mHc0q",
"event": "/api/trade/tradeLedgerUpdate"
}
# 取消订阅合约账号出入金数据更新
{
"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
"op": "unsubscribe",
"channel": "/api/trade/tradeLedgerUpdate"
}
REST API →