├── PHP-sdk.php └── README.md /PHP-sdk.php: -------------------------------------------------------------------------------- 1 | api_key = $api_key; 8 | $this->api_secret = $api_secret; 9 | $this->header= ''; 10 | } 11 | public function ping() { 12 | return $this->request("v1/ping"); 13 | } 14 | public function time() { 15 | return $this->request("v1/time"); 16 | } 17 | public function exchangeInfo() { 18 | return $this->request("v1/exchangeInfo"); 19 | } 20 | public function buy_test($symbol, $quantity, $price, $type = "LIMIT", $flags = []) { 21 | return $this->order_test("BUY", $symbol, $quantity, $price, $type, $flags); 22 | } 23 | public function sell_test($symbol, $quantity, $price, $type = "LIMIT", $flags = []) { 24 | return $this->order_test("SELL", $symbol, $quantity, $price, $type, $flags); 25 | } 26 | public function buy($symbol, $quantity, $price, $type = "LIMIT", $flags = []) { 27 | return $this->order("BUY", $symbol, $quantity, $price, $type, $flags); 28 | } 29 | public function sell($symbol, $quantity, $price, $type = "LIMIT", $flags = []) { 30 | return $this->order("SELL", $symbol, $quantity, $price, $type, $flags); 31 | } 32 | public function cancel($symbol, $orderid) { 33 | return $this->signedRequest("v1/order", ["symbol"=>$symbol, "orderId"=>$orderid], "DELETE"); 34 | } 35 | public function orderStatus($symbol, $orderid) { 36 | if(!$orderid){ 37 | return $this->signedRequest("v1/order",["symbol"=>$symbol]); 38 | } 39 | return $this->signedRequest("v1/order",["symbol"=>$symbol, "orderId"=>$orderid]); 40 | } 41 | public function openOrders($symbol) { 42 | return $this->signedRequest("v1/openOrders", ["symbol"=>$symbol]); 43 | } 44 | public function currentOrder($symbol, $limit = 500) { 45 | return $this->signedRequest("v1/order",["symbol"=>$symbol, "limit"=>$limit]); 46 | } 47 | public function orders($symbol, $limit = 500) { 48 | return $this->signedRequest("v1/allOrders",["symbol"=>$symbol]); 49 | } 50 | public function trades($symbol, $limit = 500) { 51 | return $this->request("v1/trades",["symbol"=>$symbol, "limit"=>$limit]); 52 | } 53 | public function historyTrades($symbol, $limit = 500, $from_id=0) { 54 | if($from_id) { 55 | return $this->request("v1/historicalTrades",["symbol"=>$symbol, "limit"=>$limit, "formId"=>$from_id]); 56 | } 57 | return $this->request("v1/historicalTrades",["symbol"=>$symbol, "limit"=>$limit]); 58 | } 59 | public function aggTrades($symbol) { 60 | return $this->request("v1/aggTrades", ["symbol"=>$symbol]); 61 | } 62 | //1m,3m,5m,15m,30m,1h,2h,4h,6h,8h,12h,1d,3d,1w,1M 63 | public function candlesticks($symbol, $interval = "5m") { 64 | return $this->request("v1/klines",["symbol"=>$symbol, "interval"=>$interval]); 65 | } 66 | public function prevDay($symbol='') { 67 | return $this->request("v1/ticker/24hr", ["symbol"=>$symbol]); 68 | } 69 | public function myTrades($symbol) { 70 | return $this->signedRequest("v1/myTrades", ["symbol"=>$symbol]); 71 | } 72 | public function price($symbol) { 73 | return $this->request("v1/ticker/price", ["symbol"=>$symbol]); 74 | } 75 | public function prices() { 76 | return $this->priceData($this->request("v1/ticker/allPrices")); 77 | } 78 | public function bookTicker($symbol) { 79 | return $this->request("v1/ticker/bookTicker", ["symbol"=>$symbol]); 80 | } 81 | public function bookPrices() { 82 | return $this->bookPriceData($this->request("v1/ticker/allBookTickers")); 83 | } 84 | public function account() { 85 | return $this->signedRequest("v1/account"); 86 | } 87 | public function depth($symbol) { 88 | return $this->request("v1/depth",["symbol"=>$symbol]); 89 | } 90 | public function balances($priceData = false) { 91 | return $this->balanceData($this->signedRequest("v1/account"),$priceData); 92 | } 93 | private function request($url, $params = [], $method = "GET") { 94 | $opt = [ 95 | "http" => [ 96 | "method" => $method, 97 | "header" => "User-Agent: Mozilla/4.0 (compatible; PHP Bitrue API)\r\n" 98 | ] 99 | ]; 100 | $headers = array('User-Agent: Mozilla/4.0 (compatible; PHP Bitrue API)', 101 | 'X-MBX-APIKEY: ' . $this->api_key, 102 | 'Content-type: application/x-www-form-urlencoded'); 103 | $context = stream_context_create($opt); 104 | $query = http_build_query($params, '', '&'); 105 | $ret = $this->http_get($this->base.$url.'?'.$query, $headers); 106 | return $ret; 107 | } 108 | private function signedRequest($url, $params = [], $method = "GET") { 109 | if ( empty($this->api_key) ) die("signedRequest error: API Key not set!"); 110 | if ( empty($this->api_secret) ) die("signedRequest error: API Secret not set!"); 111 | 112 | $timestamp_t = $this->getServerTime(); 113 | if($timestamp_t < 0) { 114 | $timestamp_t = number_format(microtime(true)*1000,0,'.',''); 115 | } 116 | $params['timestamp'] = $timestamp_t; 117 | $query = http_build_query($params, '', '&'); 118 | $signature = hash_hmac('sha256', $query, $this->api_secret); 119 | $headers = array("User-Agent: Mozilla/4.0 (compatible; PHP Bitrue API)", 120 | "X-MBX-APIKEY: {$this->api_key}", 121 | "Content-type: application/x-www-form-urlencoded"); 122 | $opt = [ 123 | "http" => [ 124 | "method" => $method, 125 | "ignore_errors" => true, 126 | "header" => "User-Agent: Mozilla/4.0 (compatible; PHP Bitrue API)\r\nX-MBX-APIKEY: {$this->api_key}\r\nContent-type: application/x-www-form-urlencoded\r\n" 127 | ] 128 | ]; 129 | if ( $method == 'GET' ) { 130 | // parameters encoded as query string in URL 131 | $endpoint = "{$this->base}{$url}?{$query}&signature={$signature}"; 132 | $ret = $this->http_get($endpoint, $headers); 133 | } else if ($method == 'POST'){ 134 | $endpoint = "{$this->base}{$url}"; 135 | $params['signature'] = $signature; 136 | $ret = $this->http_post($endpoint, $params, $headers); 137 | } else { 138 | $endpoint = "{$this->base}{$url}?{$query}&signature={$signature}"; 139 | $ret = $this->http_other($method, $endpoint, $headers); 140 | } 141 | return $ret; 142 | } 143 | private function order_test($side, $symbol, $quantity, $price, $type = "LIMIT", $flags = []) { 144 | $opt = [ 145 | "symbol" => $symbol, 146 | "side" => $side, 147 | "type" => $type, 148 | "quantity" => $quantity, 149 | "recvWindow" => 60000 150 | ]; 151 | if ( $type == "LIMIT" ) { 152 | $opt["price"] = $price; 153 | $opt["timeInForce"] = "GTC"; 154 | } 155 | // allow additional options passed through $flags 156 | if ( isset($flags['recvWindow']) ) $opt['recvWindow'] = $flags['recvWindow']; 157 | if ( isset($flags['timeInForce']) ) $opt['timeInForce'] = $flags['timeInForce']; 158 | if ( isset($flags['stopPrice']) ) $opt['stopPrice'] = $flags['stopPrice']; 159 | if ( isset($flags['icebergQty']) ) $opt['icebergQty'] = $flags['icebergQty']; 160 | return $this->signedRequest("v1/order/test", $opt, "POST"); 161 | } 162 | public function order($side, $symbol, $quantity, $price, $type = "LIMIT", $flags = []) { 163 | $side = strtoupper($side); 164 | $type = strtoupper($type); 165 | if (!in_array($side, ['BUY', 'SELL']) ) die("Unsupport side parameters, please check!"); 166 | if (!in_array($type, ['LIMIT', 'MARKET']) ) die("Unsupport type parameters, please check!"); 167 | $opt = [ 168 | "symbol" => $symbol, 169 | "side" => $side, 170 | "type" => $type, 171 | "quantity" => $quantity, 172 | "recvWindow" => 60000 173 | ]; 174 | if ( $type == "LIMIT" ) { 175 | $opt["price"] = $price; 176 | $opt["timeInForce"] = "GTC"; 177 | } 178 | // allow additional options passed through $flags 179 | if ( isset($flags['recvWindow']) ) $opt["recvWindow"] = $flags['recvWindow']; 180 | if ( isset($flags['timeInForce']) ) $opt["timeInForce"] = $flags['timeInForce']; 181 | if ( isset($flags['stopPrice']) ) $opt['stopPrice'] = $flags['stopPrice']; 182 | if ( isset($flags['icebergQty']) ) $opt['icebergQty'] = $flags['icebergQty']; 183 | return $this->signedRequest("v1/order", $opt, "POST"); 184 | } 185 | private function balanceData($array, $priceData = false) { 186 | if ( $priceData ) $btc_value = 0.00; 187 | $balances = []; 188 | foreach ( $array['balances'] as $obj ) { 189 | $asset = $obj['asset']; 190 | $balances[$asset] = ["available"=>$obj['free'], "onOrder"=>$obj['locked'], "btcValue"=>0.00000000]; 191 | if ( $priceData ) { 192 | if ( $obj['free'] < 0.00000001 ) continue; 193 | if ( $asset == 'BTC' ) { 194 | $balances[$asset]['btcValue'] = $obj['free']; 195 | $btc_value+= $obj['free']; 196 | continue; 197 | } 198 | $btcValue = number_format($obj['free'] * $priceData[$asset.'BTC'],8,'.',''); 199 | $balances[$asset]['btcValue'] = $btcValue; 200 | $btc_value+= $btcValue; 201 | } 202 | } 203 | if ( $priceData ) { 204 | uasort($balances, function($a, $b) { return $a['btcValue'] < $b['btcValue']; }); 205 | $this->btc_value = $btc_value; 206 | } 207 | return $balances; 208 | } 209 | private function bookPriceData($array) { 210 | $bookprices = []; 211 | foreach ( $array as $obj ) { 212 | $bookprices[$obj['symbol']] = [ 213 | "bid"=>$obj['bidPrice'], 214 | "bids"=>$obj['bidQty'], 215 | "ask"=>$obj['askPrice'], 216 | "asks"=>$obj['askQty'] 217 | ]; 218 | } 219 | return $bookprices; 220 | } 221 | private function priceData($array) { 222 | $prices = []; 223 | foreach ( $array as $obj ) { 224 | $prices[$obj['symbol']] = $obj['price']; 225 | } 226 | return $prices; 227 | } 228 | private function tradesData($trades) { 229 | $output = []; 230 | foreach ( $trades as $trade ) { 231 | $price = $trade['p']; 232 | $quantity = $trade['q']; 233 | $timestamp = $trade['T']; 234 | $maker = $trade['m'] ? 'true' : 'false'; 235 | $output[] = ["price"=>$price, "quantity"=> $quantity, "timestamp"=>$timestamp, "maker"=>$maker]; 236 | } 237 | return $output; 238 | } 239 | 240 | private function http_post($url, $data, $headers=[]) 241 | { 242 | $data = http_build_query($data); 243 | $curl = curl_init(); 244 | curl_setopt($curl, CURLOPT_URL, $url); 245 | curl_setopt($curl, CURLOPT_POST, TRUE); 246 | curl_setopt($curl, CURLOPT_POSTFIELDS, $data); 247 | curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE); 248 | curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); 249 | $output = curl_exec($curl); 250 | curl_close($curl); 251 | return $output; 252 | } 253 | 254 | private function http_get($url, $headers=[], $data=[]) 255 | { 256 | $curl = curl_init(); 257 | curl_setopt($curl, CURLOPT_URL, $url); 258 | curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE); 259 | curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); 260 | $output = curl_exec($curl); 261 | curl_close($curl); 262 | return $output; 263 | } 264 | 265 | private function http_other($method, $url, $headers=[]) 266 | { 267 | $curl = curl_init(); 268 | curl_setopt($curl, CURLOPT_URL, $url); 269 | curl_setopt($curl, CURLOPT_CUSTOMREQUEST, strtoupper($method)); 270 | curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE); 271 | curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); 272 | $output = curl_exec($curl); 273 | curl_close($curl); 274 | return $output; 275 | } 276 | 277 | private function getServerTime() 278 | { 279 | $t = $this->time(); 280 | $t_info = json_decode($t, true); 281 | if(isset($t_info['serverTime'])){ 282 | return $t_info['serverTime']; 283 | } 284 | 285 | return -1; 286 | } 287 | } 288 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Public Rest API for Bitrue (2023-07-14) 2 | # Release Note 2023-07-14 3 | * Fixed bugs 4 | * Add '[PENDING_CREATE](#pending_create)' status for order 5 | # Release Note 2023-03-20 6 | * Fixed bugs 7 | * Recovery TradeId in WS [Order Event](#ws_c) 8 | * Add 'tradeId' in endpoint [/v2/myTrades](#v2myTrades) 9 | # Release Note 2023-03-16 10 | * Update [Kline Data endpoint](#kline_endpoint) 11 | # Release Note 2022-09-22 12 | * Add endpoint for [ws_depth](#ws_depth) 13 | # Release Note 2022-09-06 14 | * Fixed bugs 15 | # Release Note 2022-07-01 16 | * Update [signature example for HTTP POST](#sign) 17 | # Release Note 2022-06-02 18 | * Modify rate limits in [ExchangeInfo endpoint](#exchangeInfo_endpoint) 19 | * Fixed bug 20 | # Release Note 2022-05-17 21 | * Add endpoint for [KLine Data](#kline_endpoint) 22 | # Release Note 2022-04-18 23 | * Modify privileges for [Account endpoint](#account_endpoint) 24 | * Modify data for [exchangeInfo endpoint](#exchangeInfo_endpoint) 25 | # Release Note 2022-03-14 26 | * Support `originClientOrderId` for [place an order](#place_order) and in [WS data with 'C'](#ws_c). 27 | * Fixed endpoint `/api/v1/allOrders` 28 | * Fixed endpoint `/api/v2/myTrades` 29 | * Add [rate limit policy](#rlp) in response header 30 | * Cache optimization 31 | # Release Note 2022-03-01 32 | * Descrition for [error code](#error_code). 33 | # General API Information 34 | * The base endpoint is: **https://openapi.bitrue.com** 35 | * All endpoints return either a JSON object or array. 36 | * All time and timestamp related fields are in milliseconds. 37 | * All data timestamp:GMT +8 38 | * HTTP `4XX` return codes are used for for malformed requests; 39 | the issue is on the sender's side. 40 | * HTTP `5XX` return codes are used for internal errors; the issue is on 41 | Bitrue's side. 42 | It is important to **NOT** treat this as a failure operation; the execution status is 43 | **UNKNOWN** and could have been a success. 44 | * Any endpoint can return an ERROR; the error payload is as follows: 45 | ```json 46 | { 47 | "code": -1121, 48 | "msg": "Invalid symbol." 49 | } 50 | ``` 51 | 52 | * Specific error codes and messages defined in another document. 53 | * For `GET` endpoints, parameters must be sent as a `query string`. 54 | * For `POST`, `PUT`, and `DELETE` endpoints, the parameters may be sent as a 55 | `query string` or in the `request body` with content type 56 | `application/x-www-form-urlencoded`. You may mix parameters between both the 57 | `query string` and `request body` if you wish to do so. 58 | * Parameters may be sent in any order. 59 | * If a parameter sent in both the `query string` and `request body`, the 60 | `query string` parameter will be used. 61 | 62 | # LIMITS 63 | * The `/api/v1/exchangeInfo` `rateLimits` array contains objects related to the exchange's `REQUEST_WEIGHT` and `ORDER` rate limits. 64 | * A 429 will be returned when either rate limit is violated. 65 | * Each route has a `weight` which determines for the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavier `weight`. 66 | * When a 429 is recieved, it's your obligation as an API to back off and not spam the API. 67 | * **Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban .** 68 | * IP bans are tracked and **scale in duration** for repeat offenders, **from 2 minutes to 3 days**. 69 | * If you got a 429, you could get the policy name from response header with key `rate_limit_p`. 70 | 71 | # Endpoint security type 72 | * Each endpoint has a security type that determines the how you will 73 | interact with it. 74 | * API-keys are passed into the Rest API via the `X-MBX-APIKEY` 75 | header. 76 | * API-keys and secret-keys **are case sensitive**. 77 | 78 | Security Type | Description 79 | ------------ | ------------ 80 | NONE | Endpoint can be accessed freely. 81 | TRADE | Endpoint requires sending a valid API-Key and signature. 82 | MARKET_DATA | Endpoint requires sending a valid API-Key. 83 | 84 | * `TRADE` endpoints are `SIGNED` endpoints. 85 | 86 | # SIGNED (TRADE and USER_DATA) Endpoint security 87 | * `SIGNED` endpoints require an additional parameter, `signature`, to be 88 | sent in the `query string`. 89 | * Endpoints use `HMAC SHA256` signatures. The `HMAC SHA256 signature` is a keyed `HMAC SHA256` operation. 90 | Use your `secretKey` as the key and `totalParams` as the value for the HMAC operation. 91 | * The `signature` is **not case sensitive**. 92 | * `totalParams` is defined as the `query string` concatenated with the 93 | `request body`. 94 | 95 | 96 | ## Timing security 97 | * A `SIGNED` endpoint also requires a parameter, `timestamp`, to be sent which 98 | should be the millisecond timestamp of when the request was created and sent. 99 | * An additional parameter, `recvWindow`, may be sent to specify the number of 100 | milliseconds after `timestamp` the request is valid for. If `recvWindow` 101 | is not sent, **it defaults to 5000**. 102 | * The logic is as follows: 103 | ```javascript 104 | if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) { 105 | // process request 106 | } else { 107 | // reject request 108 | } 109 | ``` 110 | 111 | **Serious trading is about timing.** Networks can be unstable and unreliable, 112 | which can lead to requests taking varying amounts of time to reach the 113 | servers. With `recvWindow`, you can specify that the request must be 114 | processed within a certain number of milliseconds or be rejected by the 115 | server. 116 | 117 | 118 | **It recommended to use a small recvWindow of 5000 or less!** 119 | 120 | 121 | ## SIGNED Endpoint Examples for POST /api/v1/order 122 | Here is a step-by-step example of how to send a vaild signed payload from the 123 | Linux command line using `echo`, `openssl`, and `curl`. 124 | 125 | Key | Value 126 | ------------ | ------------ 127 | apiKey | vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A 128 | secretKey | NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j 129 | 130 | 131 | Parameter | Value 132 | ------------ | ------------ 133 | symbol | LTCBTC 134 | side | BUY 135 | type | LIMIT 136 | timeInForce | GTC 137 | quantity | 1 138 | price | 0.1 139 | recvWindow | 5000 140 | timestamp | 1499827319559 141 | 142 | 143 | ### Example 1: As a query string 144 | * **queryString:** symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559 145 | * **HMAC SHA256 signature:** 146 | 147 | ``` 148 | [linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j" 149 | (stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71 150 | ``` 151 | 152 | 153 | * **curl command:** 154 | 155 | ``` 156 | (HMAC SHA256) 157 | [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://openapi.bitrue.com/api/v1/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71' 158 | ``` 159 | 160 | ### Example 2: As a request body 161 | * **requestBody:** {"symbol":"LTCBTC","side":"BUY","type":"LIMIT","timeInForce":"GTC","price":0.1,"quantity":1,"timestamp":1499827319559,"recvWindow":5000} 162 | * **HMAC SHA256 signature:** 163 | 164 | ``` 165 | [linux]$ echo -n '{"symbol":"LTCBTC","side":"BUY","type":"LIMIT","timeInForce":"GTC","price":0.1,"quantity":1,"timestamp":1499827319559,"recvWindow":5000}' | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j" 166 | (stdin)= a96755b9616ffcb19b47f38ee1c8e20bb9ff5ffdd3936ace8f457975fbc91a6a 167 | ``` 168 | 169 | 170 | * **curl command:** 171 | 172 | ``` 173 | (HMAC SHA256) 174 | [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://openapi.bitrue.com/api/v1/order?signature=a96755b9616ffcb19b47f38ee1c8e20bb9ff5ffdd3936ace8f457975fbc91a6a' -d '{"symbol":"LTCBTC","side":"BUY","type":"LIMIT","timeInForce":"GTC","price":0.1,"quantity":1,"timestamp":1499827319559,"recvWindow":5000}' 175 | ``` 176 | 177 | 178 | # Public API Endpoints 179 | ## Terminology 180 | * `base asset` refers to the asset that is the `quantity` of a symbol. 181 | * `quote asset` refers to the asset that is the `price` of a symbol. 182 | 183 | 184 | ## ENUM definitions 185 | **Symbol status:** 186 | 187 | * TRADING 188 | * HALT 189 | 190 | 191 | **Order status:** 192 | 193 | * PENDING_CREATE (means ur order is in queue) 194 | * NEW 195 | * PARTIALLY_FILLED 196 | * FILLED 197 | * CANCELED 198 | * PENDING_CANCEL (currently unused) 199 | * REJECTED 200 | * EXPIRED 201 | 202 | **Order types:** 203 | 204 | * LIMIT 205 | * MARKET 206 | 207 | **Order side:** 208 | 209 | * BUY 210 | * SELL 211 | 212 | **Time in force:** 213 | 214 | * GTC 215 | 216 | **Kline/Candlestick chart intervals:** 217 | 218 | m -> minutes; h -> hours; d -> days; w -> weeks; M -> months 219 | 220 | * 1m 221 | * 5m 222 | * 15m 223 | * 30m 224 | * 1h 225 | * 1d 226 | * 1w 227 | * 1M 228 | 229 | **Rate limiters (rateLimitType)** 230 | 231 | * REQUESTS_WEIGHT 232 | * ORDERS 233 | 234 | **Rate limit intervals** 235 | 236 | * SECOND 237 | * MINUTE 238 | * DAY 239 | 240 | ## Error Codes 241 | ### Http status 200 242 | Http status | code | desc 243 | ----- | ----- | ----- 244 | 200 | -2013 | Could not find order information for given order ID. 245 | 200 | -2017 | Could not find net-value for given symbol. 246 | 247 | ### Http status '4xx' 248 | Http status | code | desc 249 | ----- | ----- | ----- 250 | 412 | -1102 | Mandatory parameter is missing or illegal. 251 | 412 | -1121 | Invalid symbol name given. 252 | 401 | -1022 | Invalid signature or Invalid timestamp or Unauthorized for API. 253 | 412 | -1111 | Invalid volume or price or address given. 254 | 406 | -2010 | Order placement or cancellation or withdrawal rejected. 255 | 405 | -1020 | Method not supported. 256 | 257 | ### Http status '5xx' 258 | Http status | code | desc 259 | ----- | ----- | ----- 260 | 500 | -1016 | Service unavailable 261 | 503 | 503 | Service unavailable 262 | 263 | ## General endpoints 264 | ### Test connectivity 265 | ``` 266 | GET /api/v1/ping 267 | ``` 268 | Test connectivity to the Rest API. 269 | 270 | **Weight:** 271 | 1 272 | 273 | **Parameters:** 274 | NONE 275 | 276 | **Response:** 277 | ```json 278 | {} 279 | ``` 280 | 281 | ### Check server time 282 | ``` 283 | GET /api/v1/time 284 | ``` 285 | Test connectivity to the Rest API and get the current server time. 286 | 287 | **Weight:** 288 | 1 289 | 290 | **Parameters:** 291 | NONE 292 | 293 | **Response:** 294 | ```json 295 | { 296 | "serverTime": 1499827319559 297 | } 298 | ``` 299 | 300 | ### 301 | Exchange information （Some fields not support. only reserved） 302 | 303 | ``` 304 | GET /api/v1/exchangeInfo 305 | ``` 306 | Current exchange trading rules and symbol information 307 | 308 | **Weight:** 309 | 1 310 | 311 | **Parameters:** 312 | NONE 313 | 314 | **Response:** 315 | ```json 316 | { 317 | "timezone": "UTC", 318 | "serverTime": 1508631584636, 319 | "rateLimits": [ 320 | { 321 | "id": "general", 322 | "type": [ 323 | "IP" 324 | ], 325 | "replenishRate": 1200, 326 | "burstCapacity": 1200, 327 | "timeCount": 1, 328 | "timeUnit": "MINUTES", 329 | "refreshType": "FIRST_REQUEST", 330 | "weight": 1, 331 | "dynamicWeight": false, 332 | "overrideLevel": false, 333 | "dynamicWeightType": null 334 | },// That means only allow 1200 weight in 1 minute per IP. 335 | { 336 | "id": "orders_ip_seconds", 337 | "type": [ 338 | "IP" 339 | ], 340 | "replenishRate": 100, 341 | "burstCapacity": 100, 342 | "timeCount": 60, 343 | "timeUnit": "SECONDS", 344 | "refreshType": "FIRST_REQUEST", 345 | "weight": 1, 346 | "dynamicWeight": false, 347 | "overrideLevel": true, 348 | "dynamicWeightType": null 349 | },// That means only allow 100 weight for order endpoints in 60 seconds per IP. 350 | { 351 | "id": "orders_user_seconds", 352 | "type": [ 353 | "USER" 354 | ], 355 | "replenishRate": 100, 356 | "burstCapacity": 100, 357 | "timeCount": 60, 358 | "timeUnit": "SECONDS", 359 | "refreshType": "FIRST_REQUEST", 360 | "weight": 1, 361 | "dynamicWeight": false, 362 | "overrideLevel": true, 363 | "dynamicWeightType": null 364 | },// That means only allow 100 weight for order endpoints in 60 seconds per User. 365 | { 366 | "id": "withdraw_days", 367 | "type": [ 368 | "USER" 369 | ], 370 | "replenishRate": 1000, 371 | "burstCapacity": 1000, 372 | "timeCount": 1, 373 | "timeUnit": "DAYS", 374 | "refreshType": "FIRST_REQUEST", 375 | "weight": 1, 376 | "dynamicWeight": false, 377 | "overrideLevel": false, 378 | "dynamicWeightType": null 379 | },// That means only allow 1000 weight for withdraw endpoints in 1 day per User. 380 | { 381 | "id": "withdraw_read_hours", 382 | "type": [ 383 | "USER" 384 | ], 385 | "replenishRate": 3000, 386 | "burstCapacity": 3000, 387 | "timeCount": 1, 388 | "timeUnit": "HOURS", 389 | "refreshType": "FIRST_REQUEST", 390 | "weight": 1, 391 | "dynamicWeight": false, 392 | "overrideLevel": false, 393 | "dynamicWeightType": null 394 | } // That means only allow 3000 weight for withdraw read endpoints in 1 hour per User. 395 | ], 396 | "exchangeFilters": [], 397 | "symbols": [{ 398 | "symbol": "ETHBTC", 399 | "status": "TRADING", 400 | "baseAsset": "ETH", 401 | "baseAssetPrecision": 8, 402 | "quoteAsset": "BTC", 403 | "quotePrecision": 8, 404 | "orderTypes": ["LIMIT", "MARKET"], 405 | "icebergAllowed": false, 406 | "filters": [{ 407 | "filterType": "PRICE_FILTER", 408 | "minPrice": "0.666", // price >= minPrice 409 | "maxPrice": "66.600",// price <= maxPrice 410 | "tickSize": "0.01", // price % tickSize == 0 411 | "priceScale": 2 412 | }, 413 | { 414 | "filterType": "PERCENT_PRICE_BY_SIDE", 415 | "bidMultiplierUp": "1.3", // Order price <= bidMultiplierUp * lastPrice 416 | "bidMultiplierDown": "0.1", // Order price >= bidMultiplierDown * lastPrice 417 | "askMultiplierUp": "10.0", // Order Price <= askMultiplierUp * lastPrice 418 | "askMultiplierDown": "0.7", // Order Price >= askMultiplierDown * lastPrice 419 | "avgPriceMins": "1" 420 | }, 421 | { 422 | "filterType": "LOT_SIZE", 423 | "minQty": "0.1", // quantity >= minQty 424 | "minVal": "10.0", // quantity * lastPrice >= minVal 425 | "maxQty": "999999999999999", // quantity <= maxQty 426 | "stepSize": "0.01", // (quantity-minQty) % stepSize == 0 427 | "volumeScale": 2 428 | }] 429 | }], 430 | "coins": [{ 431 | "coin":"btr", 432 | "coinFulName":"Bitrue Coin", 433 | "enableWithdraw":true, 434 | "enableDeposit":true, 435 | "chains":["ERC20","BEP20"], 436 | "withdrawFee":"161.0", 437 | "minWithdraw":"1961.067474", 438 | "maxWithdraw":"88888888" 439 | }] 440 | } 441 | ``` 442 | 443 | ## Market Data endpoints 444 | ### Kline data 445 | ``` 446 | GET /api/v1/market/kline 447 | ``` 448 | **Weight:** 449 | 1 450 | 451 | **Parameters:** 452 | 453 | Name | Type | Mandatory | Description 454 | ------------ | ------------ | ------------ | ------------ 455 | symbol | STRING | YES | 456 | scale| ENUM |YES| 1m / 5m / 15m / 30m / 1H / 2H / 4H / 12H / 1D / 1W| 457 | fromIdx| NUMBER|NO|| 458 | limit| NUMBER|NO|Max to 1440| 459 | 460 | **Response:** 461 | ```json 462 | { 463 | "symbol": "BTCUSDT", 464 | "scale": "KLINE_15MIN", 465 | "data": [ 466 | { 467 | "i": 1648806300, 468 | "is": 1648806300000, 469 | "a": "3377268.173585", 470 | "v": "74.9149", 471 | "c": "45079.5", 472 | "h": "45161.82", 473 | "l": "44995.5", 474 | "o": "45065.49" 475 | }, 476 | { 477 | "i": 1648807200, 478 | "is": 1648807200000, 479 | "a": "2767084.210586", 480 | "v": "61.3727", 481 | "c": "45118.48", 482 | "h": "45126.03", 483 | "l": "45019.8", 484 | "o": "45076.49" 485 | } 486 | ] 487 | } 488 | ``` 489 | **Field in response:** 490 | 491 | Name | Type | Mandatory | Description 492 | ------------ | ------------ | ------------ | ------------ 493 | i| NUMBER |YES| Timestamp for kline data| 494 | a| STRING |YES| Trade amount | 495 | v| STRING |YES| Trade volume| 496 | c| STRING |YES| Close price| 497 | h| STRING |YES| High price| 498 | l| STRING |YES| Low price| 499 | o| STRING |YES| Open price| 500 | 501 | 502 | ### Order book 503 | ``` 504 | GET /api/v1/depth 505 | ``` 506 | 507 | **Weight:** 508 | Adjusted based on the limit: 509 | 510 | 511 | Limit | Weight 512 | ------------ | ------------ 513 | 5, 10, 20, 50, 100 | 1 514 | 500 | 5 515 | 1000 | 10 516 | 517 | **Parameters:** 518 | 519 | Name | Type | Mandatory | Description 520 | ------------ | ------------ | ------------ | ------------ 521 | symbol | STRING | YES | 522 | limit | INT | NO | Default 100; max 1000. Valid limits:[5, 10, 20, 50, 100, 500, 1000] 523 | 524 | **Caution:** setting limit=0 can return a lot of data. 525 | 526 | **Response:** 527 | ```json 528 | { 529 | "lastUpdateId": 1027024, 530 | "bids": [ 531 | [ 532 | "4.00000000", // PRICE 533 | "431.00000000", // QTY 534 | [] // Ignore. 535 | ] 536 | ], 537 | "asks": [ 538 | [ 539 | "4.00000200", 540 | "12.00000000", 541 | [] 542 | ] 543 | ] 544 | } 545 | ``` 546 | 547 | ### Recent trades list 548 | ``` 549 | GET /api/v1/trades 550 | ``` 551 | 552 | Get recent trades (up to last 1000). 553 | 554 | **Weight:** 555 | 1 556 | 557 | **Parameters:** 558 | 559 | Name | Type | Mandatory | Description 560 | ------------ | ------------ | ------------ | ------------ 561 | symbol | STRING | YES | 562 | limit | INT | NO | Default 100; max 1000. 563 | 564 | **Response:** 565 | ```json 566 | [ 567 | { 568 | "id": 28457, 569 | "price": "4.00000100", 570 | "qty": "12.00000000", 571 | "time": 1499865549590, 572 | "isBuyerMaker": true, 573 | "isBestMatch": true 574 | } 575 | ] 576 | ``` 577 | 578 | ### Old trade lookup (MARKET_DATA) 579 | ``` 580 | GET /api/v1/historicalTrades 581 | ``` 582 | Get older trades. 583 | 584 | **Weight:** 585 | 5 586 | 587 | **Parameters:** 588 | 589 | Name | Type | Mandatory | Description 590 | ------------ | ------------ | ------------ | ------------ 591 | symbol | STRING | YES | 592 | limit | INT | NO | Default 100; max 1000. 593 | fromId | LONG | NO | TradeId to fetch from. Default gets most recent trades. 594 | 595 | **Response:** 596 | ```json 597 | [ 598 | { 599 | "id": 28457, 600 | "price": "4.00000100", 601 | "qty": "12.00000000", 602 | "time": 1499865549590, 603 | "isBuyerMaker": true, 604 | "isBestMatch": true 605 | } 606 | ] 607 | ``` 608 | 609 | ### Compressed/Aggregate trades list 610 | ``` 611 | GET /api/v1/aggTrades 612 | ``` 613 | Get compressed, aggregate trades. Trades that fill at the time, from the same 614 | order, with the same price will have the quantity aggregated. 615 | 616 | **Weight:** 617 | 1 618 | 619 | **Parameters:** 620 | 621 | Name | Type | Mandatory | Description 622 | ------------ | ------------ | ------------ | ------------ 623 | symbol | STRING | YES | 624 | fromId | LONG | NO | ID to get aggregate trades from INCLUSIVE. 625 | startTime | LONG | NO | Timestamp in ms to get aggregate trades from INCLUSIVE. 626 | endTime | LONG | NO | Timestamp in ms to get aggregate trades until EXCLUSIVE. 627 | limit | INT | NO | Default 100; max 1000. 628 | 629 | * If both startTime and endTime are sent, time between startTime and endTime must be less than 1 hour. 630 | * If fromId, startTime, and endTime are not sent, the most recent aggregate trades will be returned. 631 | 632 | **Response:** 633 | ```json 634 | [ 635 | { 636 | "a": 26129, // Aggregate tradeId 637 | "p": "0.01633102", // Price 638 | "q": "4.70443515", // Quantity 639 | "f": 27781, // First tradeId 640 | "l": 27781, // Last tradeId 641 | "T": 1498793709153, // Timestamp 642 | "m": true, // Was the buyer the maker? 643 | "M": true // Was the trade the best price match? 644 | } 645 | ] 646 | ``` 647 | 648 | ### 24hr ticker price change statistics 649 | ``` 650 | GET /api/v1/ticker/24hr 651 | ``` 652 | 24 hour price change statistics. **Careful** when accessing this with no symbol. 653 | 654 | **Weight:** 655 | 1 for a single symbol; **40** when the symbol parameter is omitted 656 | 657 | **Parameters:** 658 | 659 | Name | Type | Mandatory | Description 660 | ------------ | ------------ | ------------ | ------------ 661 | symbol | STRING | NO | 662 | 663 | 24 hour price change statistics. **Careful** when accessing this with no symbol. 664 | **Weight:** 665 | 1 for a single symbol; **40** when the symbol parameter is omitted 666 | 667 | **Response:** 668 | ```json 669 | { 670 | "symbol": "BNBBTC", 671 | "priceChange": "-94.99999800", 672 | "priceChangePercent": "-95.960", 673 | "weightedAvgPrice": "0.29628482", 674 | "prevClosePrice": "0.10002000", 675 | "lastPrice": "4.00000200", 676 | "lastQty": "200.00000000", 677 | "bidPrice": "4.00000000", 678 | "askPrice": "4.00000200", 679 | "openPrice": "99.00000000", 680 | "highPrice": "100.00000000", 681 | "lowPrice": "0.10000000", 682 | "volume": "8913.30000000", 683 | "quoteVolume": "15.30000000", 684 | "openTime": 1499783499040, 685 | "closeTime": 1499869899040, 686 | "firstId": 28385, // First tradeId 687 | "lastId": 28460, // Last tradeId 688 | "count": 76 // Trade count 689 | } 690 | ``` 691 | OR 692 | ```json 693 | [ 694 | { 695 | "symbol": "BNBBTC", 696 | "priceChange": "-94.99999800", 697 | "priceChangePercent": "-95.960", 698 | "weightedAvgPrice": "0.29628482", 699 | "prevClosePrice": "0.10002000", 700 | "lastPrice": "4.00000200", 701 | "lastQty": "200.00000000", 702 | "bidPrice": "4.00000000", 703 | "askPrice": "4.00000200", 704 | "openPrice": "99.00000000", 705 | "highPrice": "100.00000000", 706 | "lowPrice": "0.10000000", 707 | "volume": "8913.30000000", 708 | "quoteVolume": "15.30000000", 709 | "openTime": 1499783499040, 710 | "closeTime": 1499869899040, 711 | "firstId": 28385, // First tradeId 712 | "lastId": 28460, // Last tradeId 713 | "count": 76 // Trade count 714 | } 715 | ] 716 | ``` 717 | 718 | ### Symbol price ticker 719 | ``` 720 | GET /api/v1/ticker/price 721 | ``` 722 | Latest price for a symbol. 723 | 724 | **Weight:** 725 | 1 726 | 727 | **Parameters:** 728 | 729 | Name | Type | Mandatory | Description 730 | ------------ | ------------ | ------------ | ------------ 731 | symbol | STRING | YES | 732 | 733 | 734 | **Response:** 735 | ```json 736 | { 737 | "symbol": "LTCBTC", 738 | "price": "4.00000200" 739 | } 740 | ``` 741 | 742 | 743 | 744 | ### Symbol order book ticker 745 | ``` 746 | GET /api/v1/ticker/bookTicker 747 | ``` 748 | Best price/qty on the order book for a symbol . 749 | 750 | **Weight:** 751 | 1 752 | 753 | **Parameters:** 754 | 755 | Name | Type | Mandatory | Description 756 | ------------ | ------------ | ------------ | ------------ 757 | symbol | STRING | YES | 758 | 759 | **Response:** 760 | ```json 761 | { 762 | "symbol": "LTCBTC", 763 | "bidPrice": "4.00000000", 764 | "bidQty": "431.00000000", 765 | "askPrice": "4.00000200", 766 | "askQty": "9.00000000" 767 | } 768 | ``` 769 | 770 | ## Account endpoints 771 | ### New order (TRADE) 772 | ``` 773 | POST /api/v1/order (HMAC SHA256) 774 | ``` 775 | Send in a new order. 776 | 777 | **Weight:** 778 | 1 779 | 780 | **Parameters:** 781 | 782 | Name | Type | Mandatory | Description 783 | ------------ | ------------ | ------------ | ------------ 784 | symbol | STRING | YES | 785 | side | ENUM | YES | 786 | type | ENUM | YES | 787 | timeInForce | ENUM | NO | 788 | quantity | DECIMAL | YES | 789 | price | DECIMAL | NO | 790 | newClientOrderId | STRING | NO | A unique id for the order. Automatically generated if not sent. 791 | stopPrice | DECIMAL | NO | 792 | icebergQty | DECIMAL | NO | 793 | recvWindow | LONG | NO | 794 | timestamp | LONG | YES | 795 | 796 | Additional mandatory parameters based on `type`: 797 | 798 | Type | Additional mandatory parameters 799 | ------------ | ------------ 800 | `LIMIT` | `quantity`, `price` 801 | `MARKET` | `quantity` 802 | 803 | **Response :** 804 | ```json 805 | { 806 | "symbol": "BTCUSDT", 807 | "orderId": 307650651173648896, 808 | "orderIdStr": "307650651173648896", 809 | "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP", 810 | "transactTime": 1507725176595 811 | } 812 | ``` 813 | 814 | ### Query order (USER_DATA) 815 | ``` 816 | GET /api/v1/order (HMAC SHA256) 817 | ``` 818 | Check an order's status. 819 | 820 | **Weight:** 821 | 1 822 | 823 | **Parameters:** 824 | 825 | Name | Type | Mandatory | Description 826 | ------------ | ------------ | ------------ | ------------ 827 | symbol | STRING | YES | 828 | orderId | LONG | YES | 829 | origClientOrderId | STRING | NO | 830 | recvWindow | LONG | NO | 831 | timestamp | LONG | YES | 832 | 833 | **Response:** 834 | ```json 835 | { 836 | "symbol": "LTCBTC", 837 | "orderId": 1, 838 | "clientOrderId": "myOrder1", 839 | "price": "0.1", 840 | "origQty": "1.0", 841 | "executedQty": "0.0", 842 | "cummulativeQuoteQty": "0.0", 843 | "status": "NEW", 844 | "timeInForce": "GTC", 845 | "type": "LIMIT", 846 | "side": "BUY", 847 | "stopPrice": "0.0", 848 | "icebergQty": "0.0", 849 | "time": 1499827319559, 850 | "updateTime": 1499827319559, 851 | "isWorking": true 852 | } 853 | ``` 854 | 855 | ### Cancel order (TRADE) 856 | ``` 857 | DELETE /api/v1/order (HMAC SHA256) 858 | ``` 859 | Cancel an active order. 860 | 861 | **Weight:** 862 | 1 863 | 864 | **Parameters:** 865 | 866 | Name | Type | Mandatory | Description 867 | ------------ | ------------ | ------------ | ------------ 868 | symbol | STRING | YES | 869 | orderId | LONG | NO | 870 | origClientOrderId | STRING | NO | 871 | newClientOrderId | STRING | NO | 872 | recvWindow | LONG | NO | 873 | timestamp | LONG | YES | 874 | 875 | 876 | **Response:** 877 | ```json 878 | { 879 | "symbol": "LTCBTC", 880 | "origClientOrderId": "myOrder1", 881 | "orderId": 1, 882 | "clientOrderId": "cancelMyOrder1" 883 | } 884 | ``` 885 | 886 | ### Current open orders (USER_DATA) 887 | ``` 888 | GET /api/v1/openOrders (HMAC SHA256) 889 | ``` 890 | 891 | **Weight:** 892 | 1 for a single symbol; 893 | 894 | **Parameters:** 895 | 896 | Name | Type | Mandatory | Description 897 | ------------ | ------------ | ------------ | ------------ 898 | symbol | STRING | YES | 899 | recvWindow | LONG | NO | 900 | timestamp | LONG | YES | 901 | 902 | 903 | **Response:** 904 | ```json 905 | [ 906 | { 907 | "symbol": "LTCBTC", 908 | "orderId": 1, 909 | "clientOrderId": "myOrder1", 910 | "price": "0.1", 911 | "origQty": "1.0", 912 | "executedQty": "0.0", 913 | "cummulativeQuoteQty": "0.0", 914 | "status": "NEW", 915 | "timeInForce": "GTC", 916 | "type": "LIMIT", 917 | "side": "BUY", 918 | "stopPrice": "0.0", 919 | "icebergQty": "0.0", 920 | "time": 1499827319559, 921 | "updateTime": 1499827319559, 922 | "isWorking": true 923 | } 924 | ] 925 | ``` 926 | 927 | ### All orders (USER_DATA) 928 | ``` 929 | GET /api/v1/allOrders (HMAC SHA256) 930 | ``` 931 | Get all account orders; active, canceled, or filled. 932 | 933 | **Weight:** 934 | 5 with symbol 935 | 936 | **Parameters:** 937 | 938 | Name | Type | Mandatory | Description 939 | ------------ | ------------ | ------------ | ------------ 940 | symbol | STRING | YES | 941 | fromId | LONG | NO | 942 | startTime | LONG | NO | 943 | endTime | LONG | NO | 944 | limit | INT | NO | Default 100; max 1000. 945 | recvWindow | LONG | NO | 946 | timestamp | LONG | YES | 947 | 948 | **Notes:** 949 | * If `fromId` is set, it will get orders >= that `orderId`. Otherwise most recent orders are returned. 950 | 951 | **Response:** 952 | ```json 953 | [ 954 | { 955 | "symbol": "LTCBTC", 956 | "orderId": 1, 957 | "clientOrderId": "myOrder1", 958 | "price": "0.1", 959 | "origQty": "1.0", 960 | "executedQty": "0.0", 961 | "cummulativeQuoteQty": "0.0", 962 | "status": "NEW", 963 | "timeInForce": "GTC", 964 | "type": "LIMIT", 965 | "side": "BUY", 966 | "stopPrice": "0.0", 967 | "icebergQty": "0.0", 968 | "time": 1499827319559, 969 | "updateTime": 1499827319559, 970 | "isWorking": true 971 | } 972 | ] 973 | ``` 974 | 975 | ### Account information (USER_DATA) 976 | ``` 977 | GET /api/v1/account (HMAC SHA256) 978 | ``` 979 | Get current account information. 980 | 981 | **Weight:** 982 | 5 983 | 984 | **Parameters:** 985 | 986 | Name | Type | Mandatory | Description 987 | ------------ | ------------ | ------------ | ------------ 988 | recvWindow | LONG | NO | 989 | timestamp | LONG | YES | 990 | 991 | **Response:** 992 | ```json 993 | { 994 | "makerCommission": 15, 995 | "takerCommission": 15, 996 | "buyerCommission": 0, 997 | "sellerCommission": 0, 998 | "canTrade": true, 999 | "canWithdraw": true, 1000 | "canDeposit": true, 1001 | "updateTime": 123456789, 1002 | "balances": [ 1003 | { 1004 | "asset": "BTC", 1005 | "free": "4723846.89208129", 1006 | "locked": "0.00000000" 1007 | }, 1008 | { 1009 | "asset": "LTC", 1010 | "free": "4763368.68006011", 1011 | "locked": "0.00000000" 1012 | } 1013 | ] 1014 | } 1015 | ``` 1016 | 1017 | ### Account trade list (USER_DATA) 1018 | ``` 1019 | GET /api/v2/myTrades (HMAC SHA256) 1020 | ``` 1021 | Get trades for a specific account and symbol. 1022 | 1023 | **Weight:** 1024 | 5 with symbol 1025 | 1026 | **Parameters:** 1027 | 1028 | Name | Type | Mandatory | Description 1029 | ------------ | ------------ | ------------ | ------------ 1030 | symbol | STRING | YES | 1031 | startTime | LONG | NO | 1032 | endTime | LONG | NO | 1033 | fromId | LONG | NO | TradeId to fetch from. Default gets most recent trades. 1034 | limit | INT | NO | Default 100; max 1000. 1035 | recvWindow | LONG | NO | 1036 | timestamp | LONG | YES | 1037 | 1038 | **Notes:** 1039 | * If `fromId` is set, it will get orders >= that `fromId`. 1040 | Otherwise most recent orders are returned. 1041 | 1042 | **Response:** 1043 | ```json 1044 | [ 1045 | { 1046 | "symbol": "BNBBTC", 1047 | "id": 28457, 1048 | "tradeId": 28457284572845728, // This is the same as 't' in WS order event. 1049 | "orderId": 100234, 1050 | "price": "4.00000100", 1051 | "qty": "12.00000000", 1052 | "commission": "10.10000000", 1053 | "commissionAsset": "BNB", 1054 | "time": 1499865549590, 1055 | "isBuyer": true, 1056 | "isMaker": false, 1057 | "isBestMatch": true 1058 | } 1059 | ] 1060 | ``` 1061 | ### ETF net value (MARKET_DATA) 1062 | 1063 | ``` 1064 | GET /api/v1/etf/net-value/{symbol} (HMAC SHA256) 1065 | ``` 1066 | 1067 | Get etf net value for a specific symbol. 1068 | 1069 | **Weight:** 1070 | 1 1071 | 1072 | **Parameters:** 1073 | 1074 | Name | Type | Mandatory | Description 1075 | ------------ | ------------ | ------------ | ------------ 1076 | symbol | STRING | YES | 1077 | 1078 | **Notes:** 1079 | 1080 | path variable symbol should set symbol ,for example 1081 | 1082 | /api/v1/etf/net-value/xrp3lusdt 1083 | 1084 | **Response:** 1085 | 1086 | ```json 1087 | { 1088 | "id": 5916134, 1089 | "symbol": "xrp3lusdt", //ETF symbol name 1090 | "futruesPrice": 1.1786, // contract price 1091 | "netValue": 1.079792003418094, // net value 1092 | "beginNetValue": 1.0075782872361934, // net value on the beginning 1093 | "beginFutruesPrice": 1.1511, // contract price on the beginning 1094 | "seqId": 182101153490862080, // sequence id 1095 | "beginTs": 1629144393980, // timestamp on the beginning 1096 | "ts": 1629147837595 // timestamp of this data 1097 | } 1098 | ``` 1099 | 1100 | 1101 | 1102 | ## Deposit & Withdraw (after 2021-10-12) 1103 | 1104 | ### Withdraw commit (WITHDRAW_DATA) 1105 | 1106 | ``` 1107 | POST /api/v1/withdraw/commit 1108 | ``` 1109 | 1110 | Commit one withdraw request. 1111 | 1112 | **Weight:** 1113 | 1 1114 | 1115 | **Parameters:** 1116 | 1117 | Name | Type | Mandatory | Description 1118 | ------------ | ------------ | ------------ | ------------ 1119 | coin | STRING | YES | Coin name without chain name. 1120 | amount | NUMBER | YES | How much coins to withdraw. 1121 | addressTo | STRING | YES | Which address to withdraw. 1122 | chainName | STRING | YES | Which chain to withdraw for this coin. 1123 | addressMark | STRING | NO | Mark of address. 1124 | addrType | STRING | NO | Type of address. 1125 | tag | STRING | NO | Tag for address. 1126 | 1127 | **Notes:** 1128 | 1129 | This method needs the API withdraw privilege and you MUST set limit IP for this API Key and you MUST set withdraw address white list before. 1130 | 1131 | **Response:** 1132 | 1133 | ```json 1134 | { 1135 | "code": 200, 1136 | "msg": "succ", 1137 | "data": { 1138 | "msg": null, 1139 | "amount": 1000, 1140 | "fee": 1, 1141 | "ctime": null, 1142 | "coin": "usdt_erc20", 1143 | "withdrawId": 1156423, 1144 | "addressTo": "0x2edfae3878d7b6db70ce4abed177ab2636f60c83" 1145 | } 1146 | } 1147 | ``` 1148 | 1149 | ErrorCode | Description 1150 | ------------ | ------------ 1151 | 2 | Parameter error 1152 | 6 | Withdraw amount too less 1153 | 19 | Insufficient balance 1154 | 32 | User auth error 1155 | 110049 | Withdraw locked 1156 | 110050 | Withdraw locked 1157 | 110051 | Withdraw locked 1158 | 110054 | Withdraw locked 1159 | 110055 | Withdraw locked 1160 | 110056 | Withdraw locked 1161 | 110057 | Withdraw locked 1162 | 966000 | Ip limit 1163 | 966001 | No privileges 1164 | 999503 | Withdraw fee error 1165 | 999504 | Withdraw limit 1166 | 999505 | Withdraw limit 1167 | 999508 | Withdraw locked 1168 | 999509 | Not deposit found 1169 | 999512 | Withdraw tag error 1170 | 999513 | Withdraw address error 1171 | 999901 | Coin chain error 1172 | 999902 | Account balance error 1173 | 1174 | ### Withdraw history (WITHDRAW_DATA) 1175 | 1176 | ``` 1177 | GET /api/v1/withdraw/history 1178 | ``` 1179 | 1180 | Query withdraw history 1181 | 1182 | **Weight:** 1183 | 1 1184 | 1185 | **Parameters:** 1186 | 1187 | Name | Type | Mandatory | Description 1188 | ------------ | ------------ | ------------ | ------------ 1189 | coin | STRING | YES | Coin name without chain name. 1190 | status | NUMBER | NO | 0: init 5: finished 6: canceled. Default 0. 1191 | offset | NUMBER | NO | Which offset to start. Default 0. 1192 | limit | NUMBER | NO | Limit data to query. Default 10. Max 1000. 1193 | startTime | NUMBER | NO | Start time to query. Timestamp in ms. 1194 | endTime | NUMBER | NO | End time to query. Timestamp in ms. 1195 | timestamp | LONG | YES | 1196 | 1197 | **Notes:** 1198 | 1199 | The other status means your withdraw request is in a flow. 1200 | 1201 | **Response:** 1202 | 1203 | ```json 1204 | { 1205 | "code": 200, 1206 | "msg": "succ", 1207 | "data": [ 1208 | { 1209 | "id": 183745, 1210 | "symbol": "usdt_erc20", 1211 | "amount": "8.4000000000000000", 1212 | "fee": "1.6000000000000000", 1213 | "payAmount": "0.0000000000000000", 1214 | "createdAt": 1595336441000, 1215 | "updatedAt": 1595336576000, 1216 | "addressFrom": "", 1217 | "addressTo": "0x2edfae3878d7b6db70ce4abed177ab2636f60c83", 1218 | "txid": "", 1219 | "confirmations": 0, 1220 | "status": 6, 1221 | "tagType": null 1222 | } 1223 | ] 1224 | } 1225 | ``` 1226 | 1227 | ### Deposit history (WITHDRAW_DATA) 1228 | 1229 | ``` 1230 | GET /api/v1/deposit/history 1231 | ``` 1232 | 1233 | Query deposit history 1234 | 1235 | **Weight:** 1236 | 1 1237 | 1238 | **Parameters:** 1239 | 1240 | Name | Type | Mandatory | Description 1241 | ------------ | ------------ | ------------ | ------------ 1242 | coin | STRING | YES | Coin name without chain name. 1243 | status | NUMBER | NO | 0: init 1: finished. Default 0. 1244 | offset | NUMBER | NO | Which offset to start. Default 0. 1245 | limit | NUMBER | NO | Limit data to query. Default 10. Max 1000. 1246 | startTime | NUMBER | NO | Start time to query. Timestamp in ms. 1247 | endTime | NUMBER | NO | End time to query. Timestamp in ms. 1248 | timestamp | LONG | YES | 1249 | 1250 | **Response:** 1251 | 1252 | ```json 1253 | { 1254 | "code": 200, 1255 | "msg": "succ", 1256 | "data": [ 1257 | { 1258 | "symbol": "XRP", 1259 | "amount": "261.3361000000000000", 1260 | "fee": "0.0E-15", 1261 | "createdAt": 1548816979000, 1262 | "updatedAt": 1548816999000, 1263 | "addressFrom": "", 1264 | "addressTo": "raLPjTYeGezfdb6crXZzcC8RkLBEwbBHJ5_18113641", 1265 | "txid": "86D6EB68A7A28938BCE06BD348F8C07DEF500C5F7FE92069EF8C0551CE0F2C7D", 1266 | "confirmations": 8, 1267 | "status": 1, 1268 | "tagType": "Tag" 1269 | }, 1270 | { 1271 | "symbol": "XRP", 1272 | "amount": "20.0000000000000000", 1273 | "fee": "0.0E-15", 1274 | "createdAt": 1544669393000, 1275 | "updatedAt": 1544669413000, 1276 | "addressFrom": "", 1277 | "addressTo": "raLPjTYeGezfdb6crXZzcC8RkLBEwbBHJ5_18113641", 1278 | "txid": "515B23E1F9864D3AF7F5B4C4FCBED784BAE861854FAB95F4031922B6AAEFC7AC", 1279 | "confirmations": 7, 1280 | "status": 1, 1281 | "tagType": "Tag" 1282 | } 1283 | ] 1284 | } 1285 | ``` 1286 | 1287 | ## Market Data Streams WebSocket （after 2022-09-22） 1288 | - The base websocket endpoint is: wss://ws.bitrue.com/market/ws 1289 | -  One connection can subscribe to multiple data streams at the same time 1290 | - The subscribed server sends a ping message every 15 seconds.After receiving the ping message, the client side need to return pong within 1 minutes. Otherwise, the connection will be disconnected automatically 1291 | - You should collect byte type of data and then unzip it with gzip, then convert it into string. 1292 | 1293 | ### Ping/Keep-alive (MARKET_STREAM) 1294 | Example of ping: 1295 | ``` 1296 | { 1297 |     "ping":"1663815268584" //timestamp 1298 | } 1299 | ``` 1300 | Example of pong: 1301 | ``` 1302 | { 1303 |     "pong":"1663815268584" //It can be any content 1304 | } 1305 | ``` 1306 | 1307 | ### Live Subscribing/Unsubscribing to streams 1308 | - Subscribe/unsubscribe from streams via the WebSocket instance.Examples can be seen below. 1309 | - After a successful subscription, you will receive a successful subscription response immediately, and then you will continue to receive the latest depth push 1310 | 1311 | #### Subscribe order book depth 1312 | **Request:** 1313 | ``` 1314 | { 1315 |     "event":"${event}", //sub:Subscribe，unsub:Unsubscribe 1316 |     "params":{ 1317 |         "cb_id":"${cb_id}", //trading pair，eg: btcusdt 1318 |         "channel":"${channel}" //channel: channel to be subscribed, {cb_id}：placeholder, depth:market_{cb_id}_simple_depth_step0 1319 |     } 1320 | } 1321 | ``` 1322 | **Parameters:** 1323 | 1324 | Name | Type | Mandatory | Description 1325 | ------------ | ------------ | ------------ | ------------ 1326 | event | STRING | YES | sub:Subscribe，unsub:Unsubscribe 1327 | cb_id | STRING | YES | Symbol name 1328 | channel | STRING | YES | depth channel will be like `market_${cb_id}_simple_depth_step0` 1329 | 1330 | **Request Example:** 1331 | ``` 1332 | { 1333 |     "event":"sub", 1334 |     "params":{ 1335 |         "cb_id":"btcusdt", 1336 |         "channel":"market_btcusdt_simple_depth_step0" 1337 |     } 1338 | } 1339 | ``` 1340 | **Response:** 1341 | ``` 1342 | { 1343 |     "channel":"${channel}", 1344 |     "cb_id":"${cb_id}", 1345 |     "event_rep":"subed", //subscripted 1346 |     "status":"ok", //success 1347 |     "ts":${timestamp} //timestamp 1348 | } 1349 | ``` 1350 | **Response Example:** 1351 | ``` 1352 | { 1353 |     "channel":"market_btcusdt_simple_depth_step0", 1354 |     "cb_id":"btcusdt", 1355 |     "event_rep":"subed", 1356 |     "status":"ok", 1357 |     "ts":1663815268584 1358 | } 1359 | ``` 1360 | **Response of DEPTH message pushing** 1361 | ``` 1362 | { 1363 |     "ts":1663815268584,         //timestamp 1364 |     "channel":"market_btcusdt_simple_depth_step0", 1365 |     "tick":{      1366 |         "buys":[    //Buy 1367 |             [ 1368 |                 "18619.40",  //Price 1369 |                 "0.0013"  //Quantity 1370 |             ], 1371 |             [ 1372 |                 "1000.00", 1373 |                 "0.0020" 1374 |             ] 1375 |         ], 1376 |         "asks":[    //Sell 1377 |             [ 1378 |                 "18620.32",  //Price 1379 |                 "0.0220"  //Quantity 1380 |             ], 1381 |             [ 1382 |                 "606500.00", 1383 |                 "0.0001" 1384 |             ] 1385 |         ] 1386 |     } 1387 | } 1388 | ``` 1389 | 1390 | ## User Data Streams WebSocket（after 2021-11-05） 1391 | 1392 | - The base API endpoint is: https://open.bitrue.com 1393 | - USER_STREAM : Security Type, Endpoint requires sending a valid API-Key. 1394 | - API-keys are passed into the API via the X-MBX-APIKEY header. 1395 | - API-keys are case sensitive. 1396 | - A User Data Stream listenKey is valid for 60 minutes after creation. 1397 | - Doing a PUT on a listenKey will extend its validity for 60 minutes. 1398 | - Doing a DELETE on a listenKey will close the stream and invalidate the listenKey. 1399 | - Doing a POST on an account with an active listenKey will return the currently active listenKey and extend its validity for 60 minutes. 1400 | - The base websocket endpoint is: wss://wsapi.bitrue.com 1401 | - User Data Streams are accessed at /stream?listenKey= 1402 | - A single connection to wsapi.bitrue.com is only valid for 24 hours; expect to be disconnected at the 24 hour mark 1403 | 1404 | Error Codes 1405 | 1406 | Errors consist of two parts: an error code and a message. Codes are universal, but messages can vary. 1407 | 1408 | 200 SUCCESS 1409 | 1410 | * 200 for success,others are error codes. 1411 | 1412 | 503 SERVICE_ERROR 1413 | 1414 | * An unknown error occurred while processing the request. 1415 | 1416 | -1022 INVALID_API_KEY 1417 | 1418 | * You are not authorized to execute this request. 1419 | 1420 | -1102 MANDATORY_PARAM_EMPTY_OR_MALFORMED 1421 | 1422 | * A mandatory parameter was not sent, was empty/null, or malformed. 1423 | 1424 | -1150 INVALID_LISTEN_KEY 1425 | 1426 | * This listenKey does not exist. 1427 | 1428 | ## ListenKey 1429 | 1430 | **CREATE A LISTENKEY (USER_STREAM)** 1431 | 1432 | **url** 1433 | 1434 | `POST /poseidon/api/v1/listenKey` 1435 | 1436 | Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent. If the account has an active listenKey, that listenKey will be returned and its validity will be extended for 60 minutes. 1437 | 1438 | **Response:** 1439 | 1440 | ```json 1441 | { 1442 | "msg": "succ", 1443 | "code": 200, 1444 | "data": 1445 | { 1446 | "listenKey": "ac3abbc8ac18f7977df42de27ab0c87c1f4ea3919983955d2fb5786468ccdb07" 1447 | } 1448 | } 1449 | ``` 1450 | 1451 | **Data Source**: Memory 1452 | 1453 | 1454 | #### Ping/Keep-alive a ListenKey (USER_STREAM) 1455 | 1456 | **url** 1457 | 1458 | `PUT /poseidon/api/v1/listenKey/{listenKey}` 1459 | Keepalive a user data stream to prevent a time out. User data streams will close after 60 minutes. It's recommended to send a ping about every 30 minutes. 1460 | 1461 | **Response:** 1462 | 1463 | ```json 1464 | { 1465 | "msg": "succ", 1466 | "code": 200 1467 | } 1468 | ``` 1469 | 1470 | **Data Source**: Memory 1471 | 1472 | 1473 | #### Close a ListenKey (USER_STREAM) 1474 | 1475 | **url:** 1476 | 1477 | DELETE /poseidon/api/v1/listenKey/{listenKey} 1478 | 1479 | Close out a user data stream. 1480 | 1481 | **Response:** 1482 | 1483 | ```json 1484 | { 1485 | "msg": "succ", 1486 | "code": 200 1487 | } 1488 | ``` 1489 | 1490 | **Data Source**: Memory 1491 | 1492 | 1493 | ## keep-alive 1494 | 1495 | you should send pong message within 10 minutes 1496 | **pong：** 1497 | 1498 | ``` 1499 | {"event":"pong","ts":"1635221621062"} 1500 | ``` 1501 | 1502 | 1503 | ## Order Update 1504 | 1505 | Orders are updated with the Order Event 1506 | **subscribe：** 1507 | 1508 | ``` 1509 | {"event":"sub","params":{"channel":"user_order_update"}} 1510 | ``` 1511 | 1512 | **response：** 1513 | 1514 | sub success : 1515 | 1516 | ``` 1517 | {"channel":"user_order_update","event_rep":"subed","status":"ok","ts":1623381851178} 1518 | ``` 1519 | 1520 | order event : 1521 | 1522 | ``` 1523 | { 1524 | "e": "executionReport", // Event type 1525 | "I": "209818131719847936", // Event ID 1526 | "E": 1499405658658, // Event time 1527 | "u": 123456, // UID 1528 | "s": "ETHBTC", // Symbol 1529 | "c": "mUvoqJxFIILMdfAW5iGSOW", // Client order ID 1530 | "S": 1, // Side 1531 | "o": 1, // Order type 1532 | "q": "1.00000000", // Order quantity 1533 | "p": "0.10264410", // Order price 1534 | "x": 1, // order event 1535 | "X": 1, // Current order status 1536 | "i": 4293153, // Order ID 1537 | "l": "0.00000000", // Last executed quantity 1538 | "L": "0.00000000", // Last executed price 1539 | "n": "0", // Commission amount 1540 | "N": null, // Commission asset 1541 | "T": 1499405658657, // Trade time 1542 | "t": -1, // Trade ID 1543 | "O": 1499405658657, // Order creation time 1544 | "z": "0.00000000", // Cumulative filled quantity 1545 | "Y": "0.00000000", // Cumulative transacted amount (i.e. Price * Qty) 1546 | "C": "test", // Origin client order id 1547 | } 1548 | ``` 1549 | 1550 | **unsubscribe：** 1551 | 1552 | ``` 1553 | {"event":"unsub","params":{"channel":"user_order_update"}} 1554 | ``` 1555 | 1556 | **response：** 1557 | 1558 | ``` 1559 | {"channel":"user_order_update","status":"ok","ts":1623381851178} 1560 | ``` 1561 | 1562 | **example:** 1563 | 1564 | subscribe 1565 | 1566 | ``` 1567 | {"event":"sub","params":{"channel":"user_order_update"}} 1568 | ``` 1569 | 1570 | unsubscribe 1571 | 1572 | ``` 1573 | {"event":"unsub","params":{"channel":"user_order_update"}} 1574 | ``` 1575 | 1576 | ## balance update 1577 | 1578 | balance are updated with the Balance Event 1579 | **subscribe：** 1580 | 1581 | ``` 1582 | {"event":"sub","params":{"channel":"user_balance_update"}} 1583 | ``` 1584 | 1585 | **response：** 1586 | 1587 | ``` 1588 | { 1589 | "e":"BALANCE", #event name 1590 | "x":"OutboundAccountPositionOrderEvent", #event type 1591 | "E":1635515839203, #event time 1592 | "I":208810488108744704, #event id 1593 | "i":1635515839203, # ignore 1594 | "B":[ 1595 | { 1596 | "a":"btr", # assert name 1597 | "F":"9999999.9658620755200000", # balance 1598 | "T":1635515839000, # balance update time 1599 | "f":"2.8125000000000000", # balance Delta 1600 | "L":"0.0000000000000000", # lock balance 1601 | "l":"-2.8125000000000000", # lock balance Delta 1602 | "t":1635515839000 # lock balance update time 1603 | }, 1604 | { 1605 | "a":"usdt", 1606 | "F":"10000008.8000000000000000", 1607 | "T":1635515839000, 1608 | "f":"10.2600000000000000", 1609 | "L":"0.0000000000000000", 1610 | "l":"-10.2600000000000000", 1611 | "t":1635515839000 1612 | } 1613 | ], 1614 | "u":1090862 1615 | } 1616 | ``` 1617 | 1618 | **unsubscribe：** 1619 | 1620 | ``` 1621 | {"event":"unsub","params":{"channel":"user_balance_update"}} 1622 | ``` 1623 | 1624 | **response：** 1625 | 1626 | ``` 1627 | {"channel":"user_balance_update","status":"ok","ts":1623381851178} 1628 | ``` 1629 | 1630 | ##Terminology 1631 | These terms will be used throughout the documentation, so it is recommended especially for new users to read to help their understanding of the API. 1632 | 1633 | base asset refers to the asset that is the quantity of a symbol. For the symbol BTCUSDT, BTC would be the base asset. 1634 | quote asset refers to the asset that is the price of a symbol. For the symbol BTCUSDT, USDT would be the quote asset. 1635 | 1636 | ENUM definitions 1637 | 1638 | `SPOT` 1639 | **balance event :** 1640 | 1641 | Event | Description 1642 | 1643 | OutboundAccountPositionEvent | ignore 1644 | 1645 | OutboundAccountPositionTradeEvent | the order has been filled 1646 | 1647 | OutboundAccountPositionOrderEvent | The order place or cancel 1648 | 1649 | OutboundAccountPositionTransferEvent | ignore 1650 | 1651 | OutboundAccountPositionBonusEvent | ignore 1652 | 1653 | 1654 | **order event :** 1655 | 1656 | Event | Description 1657 | 1658 | 1 | The order has been created by the user. 1659 | 1660 | 2 | The order has been canceled by the user. 1661 | 1662 | 3 | The order has been filled by the engine . 1663 | 1664 | 4 | The order has been canceled by the engine . 1665 | 1666 | 1667 | **order status :** 1668 | 1669 | status | Description 1670 | 1671 | 0 | The order has not been accepted by the engine. 1672 | 1673 | 1 | The order has been accepted by the engine. 1674 | 1675 | 2 | The order has been completed. 1676 | 1677 | 3 | A part of the order has been filled. 1678 | 1679 | 4 | The order has been canceled by the user. 1680 | 1681 | **order type :** 1682 | 1683 | type | Description 1684 | 1685 | 1 | LIMIT 1686 | 1687 | 2 | MARKET 1688 | 1689 | 1690 | **order side :** 1691 | 1692 | side | Description 1693 | 1694 | 1 | BUY 1695 | 1696 | 2 | SELL 1697 | 1698 | --------------------------------------------------------------------------------