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