# WebSocket API

# Quanto Swap

WebSocket API is used to receive dynamic data update by subscribing specific channel, both readonly trading api and market data api are ready for use, if initial data snapshot is required, please refer to HTTP API.

# WebSocket Overview

WebSocket is a new protocol for HTML5, which enables full-duplex communication between the client and the server, allowing data to travel in both directions quickly. The client and server connections can be established through a simple handshake, and the server can actively push information to the client according to the business rules. The advantages are as follows:

  • When the client and the server perform data transmission, the request header information is relatively small, about 2 bytes.
  • Both the client and the server can actively send data to the other party.
  • There is no need to create TCP requests and destroy multiple times, saving bandwidth and server resources.

# Command format

# Message format

Information is transferred in GSON format

# Subscribe

To subscribe the dynamic update of data, you need to set path value for channel and optional parameters

{"op":"subscribe", "channel":"xxxxxx", ...}

# Update

Dynamic update according to subscription, event is path value of the channel

{"event": "xxxxxx", ...}

# Unsubscribe

To unsubscribe the dynamic update of the subscription data, similar to the subscription, path value for channel and optional parameters should be given

{"op":"unsubscribe", "channel":"xxxxxx", ...}

# Market Data Api

wss://api.bitcoke.cc/ws/market

# IndexPrice

Channel:/api/basic/indexPrice;
Subscribe:

{"op":"subscribe", "channel":"/api/basic/indexPrice", "key":"BTCUSD"}

Update:

{"symbol":"BTCUSD","price":42185.0175,"time":1632279344860}

Unsubscribe:

{"op":"unsubscribe", "channel":"/api/basic/indexPrice", "key":"BTCUSD"}

# MarkPrice

Channel:/api/basic/markPrice;
Subscribe:

{"op":"subscribe", "channel":"/api/basic/markPrice", "key":"BTCUSD"}

Update:

{"symbol":"BTCUSD","price":42081.77333333333,"time":1632279504363}

Unsubscribe:

{"op":"unsubscribe", "channel":"/api/basic/markPrice", "key":"BTCUSD"}

# lastPrice

Channel:/api/basic/lastPrice;
Subscribe:

{"op":"subscribe", "channel":"/api/basic/lastPrice", "key":"XBTCUSD"}

Update:

{"symbol":"XBTCUSD","price":42058.0,"time":1632279653441}

Unsubscribe:

{"op":"unsubscribe", "channel":"/api/basic/lastPrice", "key":"XBTCUSD"}

# Depth

Channel: /api/depth/depth; Subscribe:

{"op":"subscribe", "channel":"/api/depth/depth", "key":"XBTCUSD"}

Update:

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

Unsubscribe:

{"op":"unsubscribe", "channel":"/api/depth/depth", "key":"XBTCUSD"}

# Funding rate

Channel: /api/kLine/fundingRate; Subscribe:

{"op":"subscribe", "channel":"/api/kLine/fundingRate", "key":"XBTCUSD"}

Update:

{
    "key": "XBTCUSD", 
    "event": "/api/kLine/fundingRate", 
    "rate": -0.0001, 
    "date": "Jun 17, 2020 12:00:00 PM"
}

Unsubscribe:

{"op":"unsubscribe", "channel":"/api/kLine/fundingRate", "key":"XBTCUSD"}

# Open interest:

Channel: /api/kLine/openInterest; Subscribe:

{"op":"subscribe", "channel":"/api/kLine/openInterest", "key":"BTCUSD"}

Update:

{
    "key": "BTCUSD", 
    "event": "/api/kLine/openInterest", 
    "value": 6323.8854145971545, 
    "date": "Jun 17, 2020 09:42:26 AM", 
    "qty": 60000677
}

Unsubscribe:

{"op":"unsubscribe", "channel":"/api/kLine/openInterest", "key":"BTCUSD"}

# Trade statistics of latest 24 hours

Channel:/api/kLine/tradeStatistics; Subscribe:

{"op":"subscribe", "channel":"/api/kLine/tradeStatistics", "key":"XBTCUSD"}

Update:

{
    "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
    ]
}

Unsubscribe:

{"op":"unsubscribe", "channel":"/api/kLine/tradeStatistics", "key":"XBTCUSD"}

# K line

Channel: /api/kLine/kLine; Subscribe:

{"op":"subscribe", "channel":"/api/kLine/kLine", "key":"XBTCUSD", "type":"1M"}

Update:

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

Unsubscribe:

{"op":"unsubscribe", "channel":"/api/kLine/kLine", "key":"XBTCUSD", "type":"1M"}

# Apply for API KEY

  • Market data api is public, everyone can access to them without Api Key.
  • We have two types of API keys: ReadOnly and Trading. The former allows user request/subscribe personal trading information; The latter supports trading with HTTP Api.
  • Steps to apply for API Key: Main page-> Assets-> API settings; After successful application, REMEMBER to copy and keep the key & secret manually!
  • Each user can apply 10 Api Keys in total.

# Request arguments of Trading API

There are three mandatory arguments for Trading API, and all of them must be in the header of request:

  • apiKey - The key returned from API Key application.
  • expires - Timestamp in seconds of expiration time in UTC. For example: if the current time is '2019-12-30 11:29:20', the valid time of the request is 10 seconds, then add the current time to 10 seconds, which is '2019-12-30 11:29:30', converted to seconds: 1577676570; If the server does not receive the request after 10 seconds, request times out will be returned.
  • signature - Request cipher text. Encryption method: sha256Hex (secret + request method(GET/POST) + request path + expires); such as: sha256Hex (gJQxkMdaLxq9JdQO5yWoRwtaqlUNtwcFv_vk3FNzs5novWWeGET/api/trade/queryAccounts1577458481)

# Trading API (GET)

wss://api.bitcoke.cc/ws/trade

# Establish connection

Once connection established, the following message will be received, system is ready for next step when state equals true, eg:

{"state":true,"message":"On connect","event":"state"}

# Login

Once connected, you need to login into system before any request or subscription, user is the uid provided by BitCoke, password should be encrypted in SHA1, eg:

{"op":"login", "user":"uid", "password":"5f75ab6f9dec6fbf69adf1ca75f6a7e9672b06bb", "txId":"TX20200317-133934-511-458"}

Response: errCode is 0 if login succeed, eg:

{"event":"login", "errCode": 0, "txId":"TX20200317-133934-511-458"}

# Connection maintenance

To prevent connection from disconnecting due to no data updating, please send heartbeat request every 30 seconds to 1 minute; eg:

{"op":"heartbeat", "user":"uid","txId":"TX20200317-133934-511-458"}

Heartbeat response:

{"event":"heartbeat", "errCode":0, "txId":"TX20200317-133934-511-458"}

# Trading Account

# Subscribe the dynamic update of trading account

Channel: /api/trade/accountUpdate, eg:

{
	"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
	"signature": "745914181a51e05fd2dd735918fab0c6a96b4652ec18287792548b80571f89ec",
	"expires": "1585688861",
	"op": "subscribe",
	"channel": "/api/trade/accountUpdate"
}

System verifies and publishes data every 2 seconds if any value changes, eg:

{
	"account": {
        "uid": "12345678",
		"currency": "BTC",
		"cash": 9.717310432978316,
		"withdrawableCash": 9.717310432978316,
		"frozenCash": 0.0,
		"urPnl": 2.3944120552325733E-4
	},
	"key": "JhXdAeV77tG7g1sdbM6mHc0q",
	"event": "/api/trade/accountUpdate"
}

# Unsubscribe the update of trading account

{
	"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
	"op": "unsubscribe",
	"channel": "/api/trade/accountUpdate"
}

# Order information

# Subscribe the update of order

Channel: /api/trade/orderUpdate; eg:

{
	"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
	"signature": "d8449a44530abb955fa01c65c250bc371a7c8e18f99bc180941e66772cd12610",
	"expires": "1585688861",
	"op": "subscribe",
	"channel": "/api/trade/orderUpdate"
}

Once successfully subscribed, you will receive the order update, eg:

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

# Unsubscribe the update of order

{
	"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
	"op": "unsubscribe",
	"channel": "/api/trade/orderUpdate"
}

# Position information

# Subscribe the position update

Channel: /api/trade/positionUpdate, eg:

{
	"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
	"signature": "f497e1a3a12a6fc4b9c77e5c0b372260a4bcc253f4db64a72a25cba81e62e0b1",
	"expires": "1585688861",
	"op": "subscribe",
	"channel": "/api/trade/positionUpdate"
}

Position update:

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

# Unsubscribe the position update

{
	"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
	"op": "unsubscribe",
	"channel": "/api/trade/positionUpdate"
}

# Trade ledger information

# Subscribe the trade ledger update

Channel: /api/trade/tradeLedgerUpdate, eg:

{
	"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
	"signature": "873d0f75d484db86b7081d0276c636eb4b1582d53fb83ad0a1d898c65cd91aab",
	"expires": "1585688861",
	"op": "subscribe",
	"channel": "/api/trade/tradeLedgerUpdate"
}

Trade ledger update:

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

# Unsubscribe the trade ledger update

{
	"apiKey": "JhXdAeV77tG7g1sdbM6mHc0q",
	"op": "unsubscribe",
	"channel": "/api/trade/tradeLedgerUpdate"
}