REST API

User Manual of BitCoke's REST API

BitCoke provides two types of data interaction in REST API. The one type is to obtain market and quote data, and can be used without applying for API key. The other is to obtain or send transaction data, which requires user to loggin the system to apply for a key ( API KEY) and send the data encrypted in the specified format. The data returned by both methods is based on the Json.

API Specification

BitCoke REST API is developed based on the Swagger specification. For market api, please click Market (opens new window); And for trading api, please click Trade (opens new window). For details, please see below.

Market Data & Quote API

Market data and quote related interfaces are open, without applying for API KEY; Request frequency limit is based on IP address of client server.

Reference information

• Path: Basic Reference => /api/basic/refData
• Request frequency limit: 1 request/second/IP
• Response schema: symbol, Contract name; tick, Minimal price value; tick, Minimal price value; type, Contract type, PERP => Perpetual Contract. eg:

 {
   "code": 0,
   "message": "OK",
   "result": [
     {
       "symbol": "XBTCUSD",
       "tick": 1,
       "lotSize": 1,
       "type": "PERP"
     },
     {
       "symbol": "XETHUSD",
       "tick": 0.05,
       "lotSize": 1,
       "type": "PERP"
     },
     {
       "symbol": "XEOSUSD",
       "tick": 0.001,
       "lotSize": 1,
       "type": "PERP"
     },
     {
       "symbol": "XLTCUSD",
       "tick": 0.01,
       "lotSize": 1,
       "type": "PERP"
     },
     {
       "symbol": "XBCHUSD",
       "tick": 0.05,
       "lotSize": 1,
       "type": "PERP"
     }
   ]
 }

Last price

• Path: Basic Reference => /api/basic/lastPrice
• Request frequency limit: 1 request/second/IP
• Request argument: symbols，name of instrument(s)，multiple symbols separated by commas，eg: XBTCUSD,XETHUSD, etc. Will return last price of all contracts if it is empty
• Response:

     {
       "code": 0,
       "message": "OK",
       "result": [
         {
           "symbol": "XBTCUSD",
           "price": 42259,
           "time": 1632280154441
         },
         {
           "symbol": "XETHUSD",
           "price": 2877.7,
           "time": 1632280154356
         }
       ]
     }

Index Price

• Path: Index Price => /api/basic/indexPrice
• Request frequency limit: 5 requests/second/IP
• Request argument：symbols，name of instrument(s)，multiple symbols separated by commas，eg: BTCUSD,ETHUSD （Note：To distinguish with the name of Quanto Swap, there is no prefix X）
• Response sample：

   {
     "code": 0,
     "message": "OK",
     "result": [
       {
         "symbol": "BTCUSD",
         "price": 42236.59225,
         "time": 1632280073988
       }
     ]
   }

MarkPrice

• Path: Index Price => /api/basic/markPrice
• Request frequency limit: 5 requests/second/IP
• Request argument：symbols，name of instrument(s)，multiple symbols separated by commas，eg: BTCUSD,ETHUSD （Note：To distinguish with the name of Quanto Swap, there is no prefix X）
• Response sample：

   {
     "code": 0,
     "message": "OK",
     "result": [
       {
         "symbol": "BTCUSD",
         "price": 42169.00833333333,
         "time": 1632280351964
       },
       {
         "symbol": "ETHUSD",
         "price": 2870.4183333333335,
         "time": 1632280352563
       }
     ]
   }

Obtain Market Depth Records

• Path: Market Depth & Trade Records => /api/depth/depth
• Request frequency limit: 5 requests/second/IP
• Request argument: symbol，name of instrument，eg: XBTCUSD.
• Response: the top 20 quotes, sample(only show part of the content):

 {
   "code": 0,
   "message": "OK",
   "result": {
     "buyDepth": [
       {
         "price": 7292,
         "qty": 36303,
         "count": 6,
         "iceCount": 0
       },
       {
         "price": 7291,
         "qty": 34378,
         "count": 8,
         "iceCount": 0
       }
     ],
     "sellDepth": [
       {
         "price": 7293,
         "qty": 42245,
         "count": 6,
         "iceCount": 0
       },
       {
         "price": 7294,
         "qty": 53054,
         "count": 6,
         "iceCount": 0
       }
     ],
     "trades": null
   }
 }

Obtain Latest Transaction Records

• Path: Market Depth & Trade Records => /api/depth/trades
• Request frequency limit: 5 requests/second/IP
• Request argument: symbol，name of instrument，eg: XBTCUSD; sequence，the latest trade's id from last response, will return the latest 50 trades if value is null.
• Response: latest trades, sample(only show part of the content):

 {
   "code": 0,
   "message": "OK",
   "result": [
               {
                 "id": "1577707870474000001",
                 "symbol": "XBTCUSD",
                 "price": 7292,
                 "qty": 484,
                 "buyActive": false,
                 "timestamp": "2019-12-30T12:11:10.476+0000"
               },
               {
                 "id": "1577707869615000003",
                 "symbol": "XBTCUSD",
                 "price": 7294,
                 "qty": 900,
                 "buyActive": true,
                 "timestamp": "2019-12-30T12:11:09.616+0000"
               },
               {
                 "id": "1577707869064000001",
                 "symbol": "XBTCUSD",
                 "price": 7294,
                 "qty": 91,
                 "buyActive": false,
                 "timestamp": "2019-12-30T12:11:09.064+0000"
               },
               {
                 "id": "1577707860030000008",
                 "symbol": "XBTCUSD",
                 "price": 7294,
                 "qty": 1338,
                 "buyActive": false,
                 "timestamp": "2019-12-30T12:11:00.034+0000"
               }
   ]
 }

Obtain Historical K Line And Trade Statistics

• Path: K Line & Trade Statistics

1. /api/kLine/byIndex: Obtain K line by index and step. Request frequency limit: 15 requests/minute/IP. Response sample:

   {
       "code": 0,
       "message": "OK",
       "result": [
         {
           "source": null,
           "symbol": "XBTCUSD",
           "open": 7301,
           "close": 7302,
           "high": 7304,
           "low": 7301,
           "keyTime": "2019-12-30T12:15:00.000+0000",
           "timeStamp": "2019-12-30T12:15:24.515+0000",
           "volume": 17513,
           "turnover": 2.3984301196547184
         },
         {
           "source": null,
           "symbol": "XBTCUSD",
           "open": 7301,
           "close": 7301,
           "high": 7301,
           "low": 7297,
           "keyTime": "2019-12-30T12:14:00.000+0000",
           "timeStamp": "2019-12-30T12:14:58.729+0000",
           "volume": 41975,
           "turnover": 5.7505751906818965
         },
         {
           "source": null,
           "symbol": "XBTCUSD",
           "open": 7296,
           "close": 7301,
           "high": 7301,
           "low": 7294,
           "keyTime": "2019-1  2-30T12:13:00.000+0000",
           "timeStamp": "2019-12-30T12:13:58.178+0000",
           "volume": 48008,
           "turnover": 6.57901338020993
         }
       ]
     }

2. /api/kLine/byTime: Obtain K line by time and step. Request frequency limit: 15 requests/minute/IP. Response sample:

{
  "code": 0,
  "message": "OK",
  "result": [
    {
      "source": null,
      "symbol": "XBTCUSD",
      "open": 7301,
      "close": 7305,
      "high": 7305,
      "low": 7301,
      "keyTime": "2019-12-30T12:17:00.000+0000",
      "timeStamp": "2019-12-30T12:17:22.071+0000",
      "volume": 24375,
      "turnover": 3.337353658167195
    },
    {
      "source": null,
      "symbol": "XBTCUSD",
      "open": 7304,
      "close": 7301,
      "high": 7308,
      "low": 7300,
      "keyTime": "2019-12-30T12:16:00.000+0000",
      "timeStamp": "2019-12-30T12:16:57.444+0000",
      "volume": 56130,
      "turnover": 7.684110329772189
    },
    {
      "source": null,
      "symbol": "XBTCUSD",
      "open": 7301,
      "close": 7304,
      "high": 7304,
      "low": 7301,
      "keyTime": "2019-12-30T12:15:00.000+0000",
      "timeStamp": "2019-12-30T12:15:53.072+0000",
      "volume": 44210,
      "turnover": 6.054037463066494
    }
  ]
}

3. /api/kLine/latest: Obtain the latest one K line by type. Request frequency limit: 75 requests/minute/IP. Response sample:

 {
   "code": 0,
   "message": "OK",
   "result": {
     "source": null,
     "symbol": "XBTCUSD",
     "open": 7306,
     "close": 7308,
     "high": 7311,
     "low": 7306,
     "keyTime": "2019-12-30T12:18:00.000+0000",
     "timeStamp": "2019-12-30T12:18:17.670+0000",
     "volume": 45537,
     "turnover": 6.23014651310752
   }
 }

4. /api/kLine/latestPeriod: Obtain latest K lines after the given million seconds of key time. Request frequency limit: 75 requests/minute/IP. Response sample:

 {
   "code": 0,
   "message": "OK",
   "result": [
     {
       "source": null,
       "symbol": "XBTCUSD",
       "open": 7312,
       "close": 7312,
       "high": 7314,
       "low": 7310,
       "keyTime": "2019-12-30T12:19:00.000+0000",
       "timeStamp": "2019-12-30T12:19:08.377+0000",
       "volume": 35453,
       "turnover": 4.848914726098417
     }
   ]
 }

5. /api/kLine/fundingRate：Obtain funding rate of instrument. Request frequency limit: 5 requests/second/IP. Response sample:

{
  "code": 0,
  "message": "OK",
  "result": [
    {
      "symbol": "XBTCUSD",
      "rate": 0.000202,
      "date": null
    }
  ]
}

6. /api/kLine/tradeStatistics: Obtain trade statistics of latest 24 hours by given instrument. Request frequency limit: 5 requests/second/IP. Response sample:

    {
      "code": 0,
      "message": "OK",
      "result": [
        {
          "symbol": "XBTCUSD",
          "maxPrice": 7522,
          "minPrice": 7277,
          "priceChange": -18,
          "priceChangeRatio": -0.0024566671216050225,
          "volume": 106729948,
          "turnover": 14465.838637952624,
          "lastPrice": 7309,
          "volumeRatioList": null
        }
      ]
    }
   

7. /api/kLine/openInterest：Obtain open interest of instrument in exchange. Parameter：symbol，eg: BTCUSD. Request frequency limit: 5次/秒/IP. Response sample:

     {
       "code": 0,
       "message": "OK",
       "result": {
         "symbol": "BTCUSD",
         "value": 499991892,           
         "date": "2020-03-03T09:18:30.075+0000",
         "qty": 4386163872813.2397     
       }
     }
   

Apply for API KEY

There are two types of API keys: ReadOnly and Trading. The former allows user access to personal trading records; The latter supports trading functions which will be coming soon. Steps to apply for API Key: Main page-> Assets-> API settings; After successful application, REMEMBER to copy and keep the key & secret manually!

Path and Request frequency limit

Path: Personal Trading Information. Request frequency limit of Trading API is based on API Key. If the request frequency exceeds the limit, please wait for one minute before continuing the request.

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_vk3FNzs5novWWePOST/api/trade/queryAccounts1577458481)

Trading Information

/api/trade/queryAccounts

Obtain trading account(s) information of user. GET request. Request frequency limit: 60 requests/minute/Key. Response schema:

Parameter	Type	Comment
currency	String	Currency of trading account
cash	Double	Total cash in trading account
withdrawableCash	Double	Withdrawable cash in trading account
frozenCash	Double	Frozen cash in trading account
urPnl	Double	UnRealized Profit & Loss of account

/api/trade/queryActiveOrders

Obtain active orders of user, including normal orders and conditional orders. Request method: GET. Request frequency limit: 60 requests/minute/Key. Request argument: symbol, retrieve active orders by the given symbol, which is optional; all active orders will be returned if value is null. Response schema:

Parameter	Type	Comment
id	String	Order id，eg: O101-20190910-033720-922-1879
currency	String	Currency of trading account
symbol	String	Instrument name, eg: XBTCUSD
created	Date	Created time of order
modified	Date	Updated time of order
side	String	Order side: Buy/Sell
type	String	Type of order: Limit/Market
price	Double	Price of order
qty	Double	Quantity of order
openPosition	Boolean	Open / Close position order; true=Open, false=Close
cumQty	Double	Quantity of order already be filled
avgPx	Double	Average price of order
ordStatus	String	Order Status: NEW; PARTIALLY_FILLED; FILLED; CANCELED; REJECTED; WAITING(Conditional Order)
iceberg	Boolean	Hidden order or not
showQty	Double	Show quantity of hidden order
source	String	Order Source: Normal; Conditional; StopWin; StopLoss; TrailingStop; SysRisk
stopLossPrice	Double	Stop loss price of order
stopWinPrice	Double	Stop win price of order
stopWinType	Double	Stop win type, Limit/Market
trailingStop	Double	Trailing stop value
triggerPrice	Double	Trigger price of conditional order
triggerType	String	Type of trigger price. LAST - Execution price, INDEX - Index price

/api/trade/queryOrders

Obtain order history of user, orders are sorted in descending order by created time, which means first record is latest. Request method: GET. Request argument: prevId，id of latest order(optional), return orders after prevId(included) according to updated time, all orders will be returned if prevId is null. Request frequency limit: 30 requests/minute/Key. Response schema:

Parameter	Type	Comment
id	String	Order id，eg: O101-20190910-033720-922-1879
currency	String	Currency of trading account
symbol	String	Instrument name, eg: XBTCUSD
created	Date	Created time of order
modified	Date	Updated time of order
side	String	Order side: Buy/Sell
type	String	Type of order: Limit/Market
price	Double	Price of order
qty	Double	Quantity of order
openPosition	Boolean	Open / Close position order; true=Open, false=Close
cumQty	Double	Quantity of order already be filled
avgPx	Double	Average price of order
ordStatus	String	Order Status: NEW; PARTIALLY_FILLED; FILLED; CANCELED; REJECTED; WAITING(Conditional Order)
iceberg	Boolean	Hidden order or not
showQty	Double	Show quantity of hidden order
source	String	Order Source: Normal; Conditional; StopWin; StopLoss; TrailingStop; SysRisk
stopLossPrice	Double	Stop loss price of order
stopWinPrice	Double	Stop win price of order
stopWinType	Double	Stop win type, Limit/Market
trailingStop	Double	Trailing stop value
triggerPrice	Double	Trigger price of conditional order
triggerType	String	Type of trigger price. LAST - Execution price, INDEX - Index price

/api/trade/queryOrderById

Obtain order by id. Request method: GET. Request frequency limit: 5 requests/second/Key. Response schema:

Parameter	Type	Comment
id	String	Order id，eg: O101-20190910-033720-922-1879
currency	String	Currency of trading account
symbol	String	Instrument name, eg: XBTCUSD
created	Date	Created time of order
modified	Date	Updated time of order
side	String	Order side: Buy/Sell
type	String	Type of order: Limit/Market
price	Double	Price of order
qty	Double	Quantity of order
openPosition	Boolean	Open / Close position order; true=Open, false=Close
cumQty	Double	Quantity of order already be filled
avgPx	Double	Average price of order
ordStatus	String	Order Status: NEW; PARTIALLY_FILLED; FILLED; CANCELED; REJECTED; WAITING(Conditional Order)
iceberg	Boolean	Hidden order or not
showQty	Double	Show quantity of hidden order
source	String	Order Source: Normal; Conditional; StopWin; StopLoss; TrailingStop; SysRisk
stopLossPrice	Double	Stop loss price of order
stopWinPrice	Double	Stop win price of order
stopWinType	Double	Stop win type, Limit/Market
trailingStop	Double	Trailing stop value
triggerPrice	Double	Trigger price of conditional order
triggerType	String	Type of trigger price. LAST - Execution price, INDEX - Index price

/api/trade/queryPosition

Obtain currency position of user. Request method: GET. Request frequency limit: 60 requests/minute/Key. Response schema:

Parameter	Type	Comment
currency	String	Currency of trading account
symbol	String	Instrument name, eg: XBTCUSD
side	String	Position side, Long / Short
qty	Double	Quantity of position
individualPosition	Boolean	The trading mode is individual or not, true - yes，false - no
price	Double	Average price of position
closableQty	Double	Closable quantity of position
pnlRate	Double	Rate of unrealized P&L
value	Double	Value of position
positionLeverage	Double	Position leverage
stopLossPrice	Double	Stop loss price of position
stopWinPrice	Double	Stop win price of position
stopWinType	String	Stop win type, Limit / Market
trailingStop	Double	Trailing stop value
trailingStopPrice	Double	Stop loss price calculated by trailing stop value
pnl	Double	Realized P&L
urPnL	Double	Unrealized P&L
liquidationPrice	Double	Liquidation price of position calculated by current market data
deposit	Double	Deposit value of position

/api/trade/ledger

Obtain ledger records of trading account by currency, retrieve all records page by page at first time, then request new increment records by sending latest record id. Request method: GET. Request frequency limit: 10 requests/minute/Key. Request argument: currency, eg: BTC, EOS, etc.; pageNo; pageSize; from: latest record id. Response schema:

Parameter	Type	Comment
id	String	ledger ID
currency	String	Currency of trading account
balance	Double	Cash of account
amount	Double	Value change of cash
transferType	String	Transfer type
created	String	Created time of ledger record

Dictionary Of Transfer Type (Trading Account)

Type	Comment
INVITE_RETURN	Invite return
TRADE_FEE	Trading commission
POSITION_SETTLE	Position settlement fee
ACCOUNT_TRANSFER_IN	Transfer cash from wallet account to trading account
ACCOUNT_TRANSFER_OUT	Transfer cash from trading account to wallet account
BUST_ORDER	Liquidation order
FUNDING	Funding rate
GIFT_CREDIT	Gift credit

Wallet Information

/api/wallet/list

Obtain wallet account list of user. Request method: GET. Request frequency limit: 10 requests/minute/Key. Response schema:

Parameter	Type	Comment
currency	String	Currency of wallet
blocked	Double	Frozen cash（not available）
available	Double	Available cash
balance	Double	Total cash in wallet

/api/wallet/depositAddress

Obtain wallet address list of user. Request method: GET. Request frequency limit: 10 requests/minute/Key. Response schema:

Parameter	Type	Comment
currency	String	Currency of wallet
address	String	Wallet address
memo	String	Memo of some type of wallet

/api/wallet/ledger

Obtain ledger records of wallet account by currency, retrieve all records page by page at first time, then request new increment records by sending latest record id. Request method: GET. Request frequency limit: 10 requests/minute/Key. Request argument: currency, eg: BTC, EOS, etc.; pageNo; pageSize, from: latest record id. Response schema:

Parameter	Type	Comment
id	String	Ledger ID
currency	String	Currency of trading account
balance	Double	Total cash in account
amount	Double	Value change of cash
fee	Double	Fee
transferType	String	Transfer type
transferState	String	Transfer state
created	String	Created time of ledger record

Dictionary Of Transfer Type (Wallet Account)

Type	Comment
DEPOSIT	Deposit
WITHDRAW	Withdraw
TRANSFER_IN	Transfer cash from trading account to wallet account
TRANSFER_OUT	Transfer cash from wallet account to trading account
OTC_BUY	Buy with OTC
OTC_SELL	Sell with OTC

Dictionary Of Transfer State

Type	Comment
WITHDRAW_REQUEST	Withdraw is applied
WITHDRAW_CANCEL	Withdraw cancelled
WITHDRAW_REFUSAL	Withdraw is refused by manager
WITHDRAW_WAITING	Withdraw is waiting for confirm
WITHDRAW_CONFIRMING	Manager is confirming the withdraw action
DEPOSIT_WAITING	Deposit is waiting for confirm
DEPOSIT_CONFIRMING	Manager is confirming the deposit, withdraw is not allowed in this stage
AUDIT_SUCCESS	Succeed to audit
AUDIT_FAIL	Failed to audit
COMPLETE	Completed

Trading API (POST)

/api/trade/enterOrder

Enter order, advanced order, conditional order, close-position order with different parameters combination. Request method: POST. Request frequency limit: 10 requests/second/Key. Request schema:

Parameter	Type	Comment
currency	String	Currency of trading account
hidden	boolean	A hidden order or not
showQty	double	Show quantity of hidden order
openPosition	boolean	Open or close position order
orderType	String	Order type
price	Double	Order price
qty	Double	Order quantity
side	String	Order side
symbol	String	Name of symbol
stopLossPrice	Double	Stop loss price for advanced order
trailingStop	Double	Trailing stop value for advanced order
stopWinPrice	Double	Stop win price for advanced order
stopWinType	String	Stop win type for advanced order
triggerPrice	Double	Trigger price for conditional order
triggerType	String	Trigger type for conditional order price
tif	String	Time in force

/api/trade/cancelOrder

Cancel order by id. Request method: POST. Request frequency limit: 20 requests/second/Key. Request schema:

Parameter	Type	Comment
orderId	String	Order Id

/api/trade/amendOrder

Amend order. Request method: POST. Request frequency limit: 5 requests/second/Key. Request schema:

Parameter	Type	Comment
orderId	String	Order Id
price	Double	Order price
qty	Double	Order quantity
stopLossPrice	Double	Stop loss price
trailingStop	Double	Trailing stop
stopWinPrice	Double	Stop win price
stopWinType	String	Stop win type
triggerPrice	Double	Trigger price

/api/trade/closePosition

Close all position at market price. Request method: POST. Request frequency limit: 4 requests/second/Key. Request schema:

Parameter	Type	Comment
currency	String	Currency of trading account
symbol	String	Name of symbol
side	String	Position side

/api/trade/changePosLeverage

Change position leverage for individual position mode. Request method: POST. Request frequency limit: 4 requests/second/Key. Request schema:

Parameter	Type	Comment
currency	String	Currency of trading account
symbol	String	Name of symbol
leverage	Double	Position leverage

/api/trade/riskSetting

Change risk setting of position. Request method: POST. Request frequency limit: 5 requests/second/Key. Request schema:

Parameter	Type	Comment
currency	String	Currency of trading account
symbol	String	Name of symbol
side	String	Position side
addDeposit	Double	Increase or decrease extra deposit for position
stopLossPrice	Double	Stop loss price
trailingStop	Double	Trailing stop
stopWinPrice	Double	Stop win price
stopWinType	String	Stop win type of price

/api/trade/switchPosSide

Switch position side. Request method: POST. Request frequency limit: 4 requests/second/Key. Request schema:

Parameter	Type	Comment
currency	String	Currency of trading account
twoSidePosition	boolean	Switch to two side position mode

/api/trade/changePosMode

Change position mode between Individual and Cross. Request method: POST. Request frequency limit: 4 requests/second/Key. Request schema:

Parameter	Type	Comment
currency	String	Currency of trading account
individual	Boolean	true -> Change to Individual mode; false -> Change to Cross mode

Error Code List

ErrorCode	Description
29000	Exceed number limit of API KEY
29001	Invalid API KEY
29002	Disabled API KEY
29003	No permission of API KEY
29004	Wrong signature value
29005	Request expired
29006	Invalid ip address
20041	Prohibited Ip address