# 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
         }
       ]
     }
  1. /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
    }
  ]
}
  1. /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
   }
 }
  1. /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
     }
   ]
 }
  1. /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
    }
  ]
}
  1. /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
         }
       ]
     }
    
  2. /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