Skip to content

rest-api.md

Latest commit

 

History

History
880 lines (732 loc) · 20.9 KB

rest-api.md

File metadata and controls

880 lines (732 loc) · 20.9 KB

Public Rest API for Bitrue (2018-10-18)

General API Information

  • The base endpoint is: https://www.bitrue.com
  • All endpoints return either a JSON object or array.
  • All time and timestamp related fields are in milliseconds.
  • All timezone:GMT +8
  • HTTP 4XX return codes are used for for malformed requests; the issue is on the sender's side.
  • HTTP 5XX return codes are used for internal errors; the issue is on Bitrue's side. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.
  • Any endpoint can return an ERROR; the error payload is as follows:
{
  "code": -1121,
  "msg": "Invalid symbol."
}
  • Specific error codes and messages defined in another document.
  • For GET endpoints, parameters must be sent as a query string.
  • For POST, PUT, and DELETE endpoints, the parameters may be sent as a query string or in the request body with content type application/x-www-form-urlencoded. You may mix parameters between both the query string and request body if you wish to do so.
  • Parameters may be sent in any order.
  • If a parameter sent in both the query string and request body, the query string parameter will be used.

LIMITS

  • The /api/v1/exchangeInfo rateLimits array contains objects related to the exchange's REQUEST_WEIGHT and ORDER rate limits.
  • A 429 will be returned when either rate limit is violated.
  • 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.
  • When a 429 is recieved, it's your obligation as an API to back off and not spam the API.
  • Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban .
  • IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.

Endpoint security type

  • Each endpoint has a security type that determines the how you will interact with it.
  • API-keys are passed into the Rest API via the X-MBX-APIKEY header.
  • API-keys and secret-keys are case sensitive.
Security Type Description
NONE Endpoint can be accessed freely.
TRADE Endpoint requires sending a valid API-Key and signature.
MARKET_DATA Endpoint requires sending a valid API-Key.
  • TRADE endpoints are SIGNED endpoints.

SIGNED (TRADE and USER_DATA) Endpoint security

  • SIGNED endpoints require an additional parameter, signature, to be sent in the query string or request body.
  • Endpoints use HMAC SHA256 signatures. The HMAC SHA256 signature is a keyed HMAC SHA256 operation. Use your secretKey as the key and totalParams as the value for the HMAC operation.
  • The signature is not case sensitive.
  • totalParams is defined as the query string concatenated with the request body.

Timing security

  • A SIGNED endpoint also requires a parameter, timestamp, to be sent which should be the millisecond timestamp of when the request was created and sent.
  • An additional parameter, recvWindow, may be sent to specify the number of milliseconds after timestamp the request is valid for. If recvWindow is not sent, it defaults to 5000.
  • The logic is as follows: 
    if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
  // process request
} else {
  // reject request
}

Serious trading is about timing. Networks can be unstable and unreliable, which can lead to requests taking varying amounts of time to reach the servers. With recvWindow, you can specify that the request must be processed within a certain number of milliseconds or be rejected by the server.

It recommended to use a small recvWindow of 5000 or less!

SIGNED Endpoint Examples for POST /api/v1/order

Here is a step-by-step example of how to send a vaild signed payload from the Linux command line using echo, openssl, and curl.

Key Value
apiKey vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKey NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
Parameter Value
symbol LTCBTC
side BUY
type LIMIT
timeInForce GTC
quantity 1
price 0.1
recvWindow 5000
timestamp 1499827319559

Example 1: As a query string

  • queryString: symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

  • HMAC SHA256 signature:

    [linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71

  • curl command:

    (HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST ' https://www.bitrue.com/api/v1/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'

Example 2: As a request body

  • requestBody: symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

  • HMAC SHA256 signature:

    [linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71

  • curl command:

    (HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST ' https://www.bitrue.com/api/v1/order' -d 'symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'

Example 3: Mixed query string and request body

  • queryString: symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC

  • requestBody: quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

  • HMAC SHA256 signature:

    [linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= 0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77

  • curl command:

    (HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST ' https://www.bitrue.com/api/v1/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77'

Note that the signature is different in example 3. There is no & between "GTC" and "quantity=1".

Public API Endpoints

Terminology

  • base asset refers to the asset that is the quantity of a symbol.
  • quote asset refers to the asset that is the price of a symbol.

ENUM definitions

Symbol status:

  • TRADING
  • HALT

Order status:

  • NEW
  • PARTIALLY_FILLED
  • FILLED
  • CANCELED
  • PENDING_CANCEL (currently unused)
  • REJECTED
  • EXPIRED

Order types:

  • LIMIT
  • MARKET

Order side:

  • BUY
  • SELL

Time in force:

  • GTT

Kline/Candlestick chart intervals:

m -> minutes; h -> hours; d -> days; w -> weeks; M -> months

  • 1m
  • 5m
  • 15m
  • 30m
  • 1h
  • 1d
  • 1w
  • 1M

Rate limiters (rateLimitType)

  • REQUESTS_WEIGHT
  • ORDERS

Rate limit intervals

  • SECOND
  • MINUTE
  • DAY

General endpoints

Test connectivity

GET /api/v1/ping

Test connectivity to the Rest API.

Weight: 1

Parameters: NONE

Response:

{}

Check server time

GET /api/v1/time

Test connectivity to the Rest API and get the current server time.

Weight: 1

Parameters: NONE

Response:

{
  "serverTime": 1499827319559
}

Exchange information （Some fields not support. only reserved）

GET /api/v1/exchangeInfo

Current exchange trading rules and symbol information

Weight: 1

Parameters: NONE

Response:

{
  "timezone": "UTC",
  "serverTime": 1508631584636,
  "rateLimits": [{
      "rateLimitType": "REQUESTS_WEIGHT",
      "interval": "MINUTE",
      "limit": 1200
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "limit": 10
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "limit": 100000
    }
  ],
  "exchangeFilters": [],
  "symbols": [{
    "symbol": "ETHBTC",
    "status": "TRADING",
    "baseAsset": "ETH",
    "baseAssetPrecision": 8,???
    "quoteAsset": "BTC",
    "quotePrecision": 8,
    "orderTypes": ["LIMIT", "MARKET"],
    "icebergAllowed": false,  ???
    "filters": [{   ??
      "filterType": "PRICE_FILTER", ??
      "minPrice": "0.00000100", ??
      "maxPrice": "100000.00000000", ??
      "tickSize": "0.00000100" ??
    }, {
      "filterType": "LOT_SIZE",
      "minQty": "0.00100000",
      "maxQty": "100000.00000000",
      "stepSize": "0.00100000"
    }, {
      "filterType": "MIN_NOTIONAL",
      "minNotional": "0.00100000"
    }]
  }]
}

Market Data endpoints

Order book

GET /api/v1/depth

Weight: Adjusted based on the limit:

Limit Weight
5, 10, 20, 50, 100 1
500 5
1000 10

Parameters:

Name Type Mandatory Description
symbol STRING YES
limit INT NO Default 100; max 1000. Valid limits:[5, 10, 20, 50, 100, 500, 1000]

Caution: setting limit=0 can return a lot of data.

Response:

{
  "lastUpdateId": 1027024,
  "bids": [
    [
      "4.00000000",     // PRICE
      "431.00000000",   // QTY
      []                // Ignore.
    ]
  ],
  "asks": [
    [
      "4.00000200",
      "12.00000000",
      []
    ]
  ]
}

Recent trades list

GET /api/v1/trades

Get recent trades (up to last 1000).

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
limit INT NO Default 100; max 1000.

Response:

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "time": 1499865549590,
    "isBuyerMaker": true, 
    "isBestMatch": true  //预留
  }
]

Old trade lookup (MARKET_DATA)

GET /api/v1/historicalTrades

Get older trades.

Weight: 5

Parameters:

Name Type Mandatory Description
symbol STRING YES
limit INT NO Default 100; max 1000.
fromId LONG NO TradeId to fetch from. Default gets most recent trades.

Response:

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "time": 1499865549590,
    "isBuyerMaker": true,
    "isBestMatch": true   //预留
  }
]

Compressed/Aggregate trades list

GET /api/v1/aggTrades

Get compressed, aggregate trades. Trades that fill at the time, from the same order, with the same price will have the quantity aggregated.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
fromId LONG NO ID to get aggregate trades from INCLUSIVE.
startTime LONG NO Timestamp in ms to get aggregate trades from INCLUSIVE.
endTime LONG NO Timestamp in ms to get aggregate trades until EXCLUSIVE.
limit INT NO Default 100; max 1000.
  • If both startTime and endTime are sent, time between startTime and endTime must be less than 1 hour.
  • If fromId, startTime, and endTime are not sent, the most recent aggregate trades will be returned.

Response:

[
  {
    "a": 26129,         // Aggregate tradeId
    "p": "0.01633102",  // Price
    "q": "4.70443515",  // Quantity
    "f": 27781,         // First tradeId
    "l": 27781,         // Last tradeId
    "T": 1498793709153, // Timestamp
    "m": true,          // Was the buyer the maker?
    "M": true           // Was the trade the best price match?
  }
]

24hr ticker price change statistics

GET /api/v1/ticker/24hr

24 hour price change statistics. Careful when accessing this with no symbol.

Weight: 1 for a single symbol; 40 when the symbol parameter is omitted

Parameters:

Name Type Mandatory Description
symbol STRING NO

24 hour price change statistics. Careful when accessing this with no symbol. Weight: 1 for a single symbol; 40 when the symbol parameter is omitted

Response:

{
  "symbol": "BNBBTC",
  "priceChange": "-94.99999800",
  "priceChangePercent": "-95.960",
  "weightedAvgPrice": "0.29628482",
  "prevClosePrice": "0.10002000",
  "lastPrice": "4.00000200",
  "lastQty": "200.00000000",
  "bidPrice": "4.00000000",
  "askPrice": "4.00000200",
  "openPrice": "99.00000000",
  "highPrice": "100.00000000",
  "lowPrice": "0.10000000",
  "volume": "8913.30000000",
  "quoteVolume": "15.30000000",
  "openTime": 1499783499040,
  "closeTime": 1499869899040,
  "firstId": 28385,   // First tradeId
  "lastId": 28460,    // Last tradeId
  "count": 76         // Trade count
}

OR

[
  {
    "symbol": "BNBBTC",
    "priceChange": "-94.99999800",
    "priceChangePercent": "-95.960",
    "weightedAvgPrice": "0.29628482",
    "prevClosePrice": "0.10002000",
    "lastPrice": "4.00000200",
    "lastQty": "200.00000000",
    "bidPrice": "4.00000000",
    "askPrice": "4.00000200",
    "openPrice": "99.00000000",
    "highPrice": "100.00000000",
    "lowPrice": "0.10000000",
    "volume": "8913.30000000",
    "quoteVolume": "15.30000000",
    "openTime": 1499783499040,
    "closeTime": 1499869899040,
    "firstId": 28385,   // First tradeId
    "lastId": 28460,    // Last tradeId
    "count": 76         // Trade count
  }
]

Symbol price ticker

GET /api/v1/ticker/price

Latest price for a symbol or symbols.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES

Response:

{
  "symbol": "LTCBTC",
  "price": "4.00000200"
}

Symbol order book ticker

GET /api/v1/ticker/bookTicker

Best price/qty on the order book for a symbol or symbols.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES

Response:

{
  "symbol": "LTCBTC",
  "bidPrice": "4.00000000",
  "bidQty": "431.00000000",
  "askPrice": "4.00000200",
  "askQty": "9.00000000"
}

Account endpoints

New order (TRADE)

POST /api/v1/order  (HMAC SHA256)

Send in a new order.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
side ENUM YES
type ENUM YES
timeInForce ENUM NO
quantity DECIMAL YES
price DECIMAL NO
newClientOrderId STRING NO A unique id for the order. Automatically generated if not sent. Reserved
stopPrice DECIMAL NO Reserved
icebergQty DECIMAL NO Reserved
recvWindow LONG NO
timestamp LONG YES

Additional mandatory parameters based on type:

Type Additional mandatory parameters
LIMIT quantity, price
MARKET quantity

Response :

{
  "symbol": "BTCUSDT",
  "orderId": 28,
  "clientOrderId": "6gCrw2kRUAF9CvJDGP16IP", **Reserved**
  "transactTime": 1507725176595
}

Query order (USER_DATA)

GET /api/v1/order (HMAC SHA256)

Check an order's status.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG YES
origClientOrderId STRING NO Reserved
recvWindow LONG NO
timestamp LONG YES

Response:

{
  "symbol": "LTCBTC",
  "orderId": 1,
  "clientOrderId": "myOrder1",  **Reserved**
  "price": "0.1",
  "origQty": "1.0", **Reserved**
  "executedQty": "0.0", 
  "cummulativeQuoteQty": "0.0", **Reserved**
  "status": "NEW",
  "timeInForce": "GTC", **Reserved**
  "type": "LIMIT",
  "side": "BUY",
  "stopPrice": "0.0",  **Reserved**
  "icebergQty": "0.0", **Reserved**
  "time": 1499827319559,
  "updateTime": 1499827319559,
  "isWorking": true  **Reserved**
}

Cancel order (TRADE)

DELETE /api/v1/order  (HMAC SHA256)

Cancel an active order.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO
origClientOrderId STRING NO Reserved
newClientOrderId STRING NO Reserved
recvWindow LONG NO
timestamp LONG YES

Response:

{
  "symbol": "LTCBTC",
  "origClientOrderId": "myOrder1",  **Reserved**
  "orderId": 1,
  "clientOrderId": "cancelMyOrder1"  **Reserved**
}

Current open orders (USER_DATA)

GET /api/v1/openOrders  (HMAC SHA256)

Weight: 1 for a single symbol;

Parameters:

Name Type Mandatory Description
symbol STRING YES
recvWindow LONG NO
timestamp LONG YES

Response:

[
  {
    "symbol": "LTCBTC",
    "orderId": 1,
    "clientOrderId": "myOrder1",
    "price": "0.1",
    "origQty": "1.0",  **Reserved**
    "executedQty": "0.0",  **Reserved**
    "cummulativeQuoteQty": "0.0",  **Reserved**
    "status": "NEW",
    "timeInForce": "GTC",  **Reserved**
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0", **Reserved**
    "icebergQty": "0.0",  **Reserved**
    "time": 1499827319559,
    "updateTime": 1499827319559,
    "isWorking": true  **Reserved**
  }
]

All orders (USER_DATA)

GET /api/v1/allOrders (HMAC SHA256)

Get all account orders; active, canceled, or filled.

Weight: 5 with symbol

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO
startTime LONG NO
endTime LONG NO
limit INT NO Default 100; max 1000.
recvWindow LONG NO
timestamp LONG YES

Notes:

  • If orderId is set, it will get orders >= that orderId. Otherwise most recent orders are returned.

Response:

[
  {
    "symbol": "LTCBTC",
    "orderId": 1,
    "clientOrderId": "myOrder1",
    "price": "0.1",
    "origQty": "1.0",
    "executedQty": "0.0",
    "cummulativeQuoteQty": "0.0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "icebergQty": "0.0",
    "time": 1499827319559,
    "updateTime": 1499827319559,
    "isWorking": true
  }
]

Account information (USER_DATA)

GET /api/v1/account (HMAC SHA256)

Get current account information.

Weight: 5

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Response:

{
  "makerCommission": 15,   **Reserved**
  "takerCommission": 15,  **Reserved**
  "buyerCommission": 0,   **Reserved**
  "sellerCommission": 0,   **Reserved**
  "canTrade": true,   **Reserved**
  "canWithdraw": true,  **Reserved**
  "canDeposit": true,  **Reserved**
  "updateTime": 123456789,
  "balances": [
    {
      "asset": "BTC",
      "free": "4723846.89208129",
      "locked": "0.00000000"
    },
    {
      "asset": "LTC",
      "free": "4763368.68006011",
      "locked": "0.00000000"
    }
  ]
}

Account trade list (USER_DATA)

GET /api/v1/myTrades  (HMAC SHA256)

Get trades for a specific account and symbol.

Weight: 5 with symbol;40 when the symbol parameter is omitted

Parameters:

Name Type Mandatory Description
symbol STRING NO
startTime LONG NO
endTime LONG NO
fromId LONG NO TradeId to fetch from. Default gets most recent trades.
limit INT NO Default 100; max 1000.
recvWindow LONG NO
timestamp LONG YES

Notes:

  • If fromId is set, it will get orders >= that fromId. Otherwise most recent orders are returned.

Response:

[
  {
    "symbol": "BNBBTC",
    "id": 28457,
    "orderId": 100234,
    "price": "4.00000100",
    "qty": "12.00000000",
    "commission": "10.10000000",
    "commissionAsset": "BNB",
    "time": 1499865549590,
    "isBuyer": true,
    "isMaker": false,
    "isBestMatch": true    **Reserved**
  }
]