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