Public Rest API (2018-09-25)
General API Information
All endpoints return either a JSON object or array.
Data is returned in ascending order. Oldest first, newest last.
All time and timestamp related fields are in milliseconds.
HTTP
4XX
return codes are used for for malformed requests; the issue is on the sender's side.HTTP
429
return code is used when breaking a request rate limit.HTTP
418
return code is used when an IP has been auto-banned for continuing to send requests after receiving429
codes.HTTP
5XX
return codes are used for internal errors; the issue is on exchange'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:
Specific error codes and messages defined in another document.
For
GET
endpoints, parameters must be sent as aquery string
.For
POST
,PUT
, andDELETE
endpoints, the parameters may be sent as aquery string
or in therequest body
with content typeapplication/x-www-form-urlencoded
. You may mix parameters between both thequery string
andrequest body
if you wish to do so.Parameters may be sent in any order.
If a parameter sent in both the
query string
andrequest body
, thequery string
parameter will be used.
LIMITS
The
/openapi/v1/exchange
rateLimits
array contains objects related to the exchange'sREQUEST_WEIGHT
andORDER
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 heavierweight
.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 (http status 418).
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-BH-APIKEY
header.API-keys and secret-keys are case sensitive.
API-keys can be configured to only access certain types of secure endpoints. For example, one API-key could be used for TRADE only, while another API-key can access everything except for TRADE routes.
By default, API-keys can access all secure routes.
TRADE
andUSER_DATA
endpoints areSIGNED
endpoints.
SIGNED (TRADE and USER_DATA) Endpoint security
SIGNED
endpoints require an additional parameter,signature
, to be sent in thequery string
orrequest body
.Endpoints use
HMAC SHA256
signatures. TheHMAC SHA256 signature
is a keyedHMAC SHA256
operation. Use yoursecretKey
as the key andtotalParams
as the value for the HMAC operation.The
signature
is not case sensitive.totalParams
is defined as thequery string
concatenated with therequest 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 aftertimestamp
the request is valid for. IfrecvWindow
is not sent, it defaults to 5000.Currently,
recvWindow
is only used when creates order.The logic is as follows:
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 /openapi/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
.
Example 1: As a query string
queryString: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000
HMAC SHA256 signature:
curl command:
Example 2: As a request body
requestBody: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000
HMAC SHA256 signature:
curl command:
Example 3: Mixed query string and request body
queryString: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC
requestBody: quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000
HMAC SHA256 signature:
curl command:
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 thequantity
of a symbol.quote asset
refers to the asset that is theprice
of a symbol.
ENUM definitions
Symbol status:
TRADING
HALT
BREAK
Symbol type:
SPOT
Asset type:
CASH
MARGIN
Order status:
NEW
PARTIALLY_FILLED
FILLED
CANCELED
PENDING_CANCEL
REJECTED
Order types:
LIMIT
MARKET
LIMIT_MAKER
STOP_LOSS (unavailable now)
STOP_LOSS_LIMIT (unavailable now)
TAKE_PROFIT (unavailable now)
TAKE_PROFIT_LIMIT (unavailable now)
MARKET_OF_PAYOUT (unavailable now)
Order side:
BUY
SELL
Time in force:
GTC
IOC
FOK
Kline/Candlestick chart intervals:
m -> minutes; h -> hours; d -> days; w -> weeks; M -> months
1m
3m
5m
15m
30m
1h
2h
4h
6h
8h
12h
1d
3d
1w
1M
Rate limiters (rateLimitType)
REQUESTS_WEIGHT
ORDERS
Rate limit intervals
SECOND
MINUTE
DAY
General endpoints
Test connectivity
Test connectivity to the Rest API.
Weight: 0
Parameters: NONE
Response:
Check server time
Test connectivity to the Rest API and get the current server time.
Weight: 0
Parameters: NONE
Response:
Exchange information
Current trading rules and symbol information
Weight: 0
Parameters: NONE
Response:
Market Data endpoints
Order book
Weight: Adjusted based on the limit:
Parameters:
Caution: setting limit=0 can return a lot of data.
Response:
[PRICE, QTY]
Recent trades list
Get recent trades (up to last 500).
Weight: 1
Parameters:
Response:
Kline/Candlestick data
Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.
Weight: 1
Parameters:
If startTime and endTime are not sent, the most recent klines are returned.
Response:
24hr ticker price change statistics
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:
If the symbol is not sent, tickers for all symbols will be returned in an array.
Response:
OR
Symbol price ticker
Latest price for a symbol or symbols.
Weight: 1
Parameters:
If the symbol is not sent, prices for all symbols will be returned in an array.
Response:
OR
Symbol order book ticker
Best price/qty on the order book for a symbol or symbols.
Weight: 1
Parameters:
If the symbol is not sent, bookTickers for all symbols will be returned in an array.
Response:
OR
Account endpoints
New order (TRADE)
Send in a new order.
Weight: 1
Parameters:
Additional mandatory parameters based on type
:
Other info:
LIMIT_MAKER
areLIMIT
orders that will be rejected if they would immediately match and trade as a taker.STOP_LOSS
andTAKE_PROFIT
will execute aMARKET
order when thestopPrice
is reached.Any
LIMIT
orLIMIT_MAKER
type order can be made an iceberg order by sending anicebergQty
.Any order with an
icebergQty
MUST havetimeInForce
set toGTC
.
Trigger order price rules against market price for both MARKET and LIMIT versions:
Price above market price:
STOP_LOSS
BUY
,TAKE_PROFIT
SELL
Price below market price:
STOP_LOSS
SELL
,TAKE_PROFIT
BUY
Response:
Test new order (TRADE)
Test new order creation and signature/recvWindow long. Creates and validates a new order but does not send it into the matching engine.
Weight: 1
Parameters:
Same as POST /openapi/v1/order
Response:
Query order (USER_DATA)
Check an order's status.
Weight: 1
Parameters:
Notes:
Either
orderId
ororigClientOrderId
must be sent.For some historical orders
cummulativeQuoteQty
will be < 0, meaning the data is not available at this time.
Response:
Cancel order (TRADE)
Cancel an active order.
Weight: 1
Parameters:
Either orderId
or clientOrderId
must be sent.
Response:
Current open orders (USER_DATA)
GET all open orders on a symbol. Careful when accessing this with no symbol.
Weight: 1
Parameters:
Notes:
If
orderId
is set, it will get orders < thatorderId
. Otherwise most recent orders are returned.
Response:
History orders (USER_DATA)
GET all orders of the account; canceled, filled or rejected.
Weight: 5
Parameters:
Notes:
If
orderId
is set, it will get orders < thatorderId
. Otherwise most recent orders are returned.
Response:
Account information (USER_DATA)
GET current account information.
Weight: 5
Parameters:
Response:
Account trade list (USER_DATA)
GET trades for a specific account.
Weight: 5
Parameters:
Notes:
If only
fromId
is set,it will get orders < thatfromId
in descending order.If only
toId
is set, it will get orders > thattoId
in ascending order.If
fromId
is set andtoId
is set, it will get orders < thatfromId
and > thattoId
in descending order.If
fromId
is not set andtoId
it not set, most recent order are returned in descending order.
Response:
Account deposit list (USER_DATA)
GET deposit orders for a specific account.
Weight: 5
Parameters:
Notes:
If
fromId
is set, it will get orders > thatfromId
. Otherwise most recent orders are returned.
Response:
User data stream endpoints
Specifics on how user data streams work is in another document.
Start user data stream (USER_STREAM)
Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent.
Weight: 1
Parameters:
Response:
Keepalive user data stream (USER_STREAM)
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.
Weight: 1
Parameters:
Response:
Close user data stream (USER_STREAM)
Close out a user data stream.
Weight: 1
Parameters:
Response:
Sub-account list(SUB_ACCOUNT_LIST)
Query sub-account lists
Parameters:
None
Weight: 5
Response:
Internal Account Transfer (ACCOUNT_TRANSFER)
Internal transfer
Weight: 1
Parameters:
Response:
Explanation
Either transferring or receiving account must be the main account (Token trading account)
Main account api can support transferring to other account(including sub-accounts) and receiving from other accounts
Sub-account API only supports transferring from current account to the main-account. Therefore
fromAccountType\fromAccountIndex\toAccountType\toAccountIndex
should be left empty.
Check Balance Flow (BALANCE_FLOW)
Check blance flow
Weight: 5
Parameters:
Response:
Explanation
Main-account API can query balance flow for token account and other accounts(including sub-accounts, or designated
accountType
andaccountIndex
accounts)Sub-account API can only query current sub-account, therefore
accountType
andaccountIndex
is not required.
Please see the following for balance flow types
Filters
Filters define trading rules on a symbol. Filters come in two forms: symbol filters
and broker filters
.
Symbol filters
PRICE_FILTER
The PRICE_FILTER
defines the price
rules for a symbol. There are 3 parts:
minPrice
defines the minimumprice
/stopPrice
allowed.maxPrice
defines the maximumprice
/stopPrice
allowed.tickSize
defines the intervals that aprice
/stopPrice
can be increased/decreased by.
In order to pass the price filter
, the following must be true for price
/stopPrice
:
price
>=minPrice
price
<=maxPrice
(
price
-minPrice
) %tickSize
== 0
/exchange format:
LOT_SIZE
The LOT_SIZE
filter defines the quantity
(aka "lots" in auction terms) rules for a symbol. There are 3 parts:
minQty
defines the minimumquantity
/icebergQty
allowed.maxQty
defines the maximumquantity
/icebergQty
allowed.stepSize
defines the intervals that aquantity
/icebergQty
can be increased/decreased by.
In order to pass the lot size
, the following must be true for quantity
/icebergQty
:
quantity
>=minQty
quantity
<=maxQty
(
quantity
-minQty
) %stepSize
== 0
/exchange format:
MIN_NOTIONAL
The MIN_NOTIONAL
filter defines the minimum notional value allowed for an order on a symbol. An order's notional value is the price
* quantity
.
/exchange format:
MAX_NUM_ORDERS
The MAX_NUM_ORDERS
filter defines the maximum number of orders an account is allowed to have open on a symbol. Note that both "algo" orders and normal orders are counted for this filter.
/exchange format:
MAX_NUM_ALGO_ORDERS
The MAX_ALGO_ORDERS
filter defines the maximum number of "algo" orders an account is allowed to have open on a symbol. "Algo" orders are STOP_LOSS
, STOP_LOSS_LIMIT
, TAKE_PROFIT
, and TAKE_PROFIT_LIMIT
orders.
/exchange format:
ICEBERG_PARTS
The ICEBERG_PARTS
filter defines the maximum parts an iceberg order can have. The number of ICEBERG_PARTS
is defined as CEIL(qty / icebergQty)
.
/exchange format:
Broker Filters
BROKER_MAX_NUM_ORDERS
The MAX_NUM_ORDERS
filter defines the maximum number of orders an account is allowed to have open on the exchange. Note that both "algo" orders and normal orders are counted for this filter.
/exchange format:
BROKER_MAX_NUM_ALGO_ORDERS
The MAX_ALGO_ORDERS
filter defines the maximum number of "algo" orders an account is allowed to have open on the exchange. "Algo" orders are STOP_LOSS
, STOP_LOSS_LIMIT
, TAKE_PROFIT
, and TAKE_PROFIT_LIMIT
orders.
/exchange format:
user transfer (TRANSFER)
Last updated