# 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)
# WS連結
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 →