HTTP 4XX
return codes are used for malformed requests; the issue is on the sender's side.
HTTP 403
return code is used when the WAF Limit (Web Application Firewall) has been violated.
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 receiving 429
codes.
HTTP 5XX
return codes are used for internal errors; the issue is on
Server's side.
It is important to NOT treat this as a failure operation; the execution status is
UNKNOWN and could have been a success.
Name | Type | Mandatory | Description |
---|---|---|---|
code | Number | Yes | Error Code,0 is success,else is fail |
msg | String | Yes | error message |
timestamp | Number | Yes | server timestamp |
data | Object | No | response data |
GET
endpoints, parameters must be sent as a query string
.POST
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.query string
and request body
, the body string
parameter will be used.The following intervalLetter
values for headers:
intervalNum
describes the amount of the interval. For example, intervalNum
5 with intervalLetter
M means "Every 5 minutes".X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)
in the response headers which has the current used weight for the IP for all request rate limiters defined.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
.Retry-After
header is sent with a 418 or 429 responses and will give the number of seconds required to wait, in the case of a 418, to prevent a ban, or, in the case of a 429, until the ban is over.We recommend using the websocket for getting data as much as possible, as this will not count to the request rate limit.
X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)
header which has the current order count for the account for all order rate limiters defined.X-MBX-ORDER-COUNT-**
headers in the response.Each endpoint has a security type that determines the how you will interact with it. This is stated next to the NAME of the endpoint.
X-MBX-APIKEY
header.Security Type | Description |
---|---|
NONE | Endpoint can be accessed freely. |
SIGNED | Endpoint requires sending a valid API-Key and signature. |
API_KEY | Endpoint requires sending a valid API-Key. |
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
.
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 is recommended to use a small recvWindow of 5000 or less! The max cannot go beyond 60,000!
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 | cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV |
secretKey | f9AbA6a8AD6bC2a97294a212244dda04ETfl0kc4BSUGOtL7m7rNELpt3Jh25SiP |
Parameter | Value |
---|---|
symbol | BTC_USDT |
side | 0 |
type | 1 |
quantity | '0.16' |
price | '7500' |
recvWindow | 5000 |
timestamp | 1581720670624 |
requestBody: symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000
HMAC SHA256 signature:
[linux]$ echo -n "symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000" | openssl dgst -sha256 -hmac "cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV"
(stdin)= 33824b5160daefc34257ab9cd3c3db7a0158a446674f896c9fc3b122ae656bfa
curl command:
(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV" -X POST 'https://www.tokocrypto.com/open/v1/orders' -d 'symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000&signature=33824b5160daefc34257ab9cd3c3db7a0158a446674f896c9fc3b122ae656bfa'
queryString: symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000
HMAC SHA256 signature:
[linux]$ echo -n "symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000" | openssl dgst -sha256 -hmac "cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV"
(stdin)= 33824b5160daefc34257ab9cd3c3db7a0158a446674f896c9fc3b122ae656bfa
curl command:
(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV" -X POST 'https://www.tokocrypto.com/open/v1/orders?symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000&signature=33824b5160daefc34257ab9cd3c3db7a0158a446674f896c9fc3b122ae656bfa'
queryString: symbol=BTC_USDT&side=0&type=1
requestBody: quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559
requestBody: symbol=BTC_USDT&side=0&type=1quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000
HMAC SHA256 signature:
[linux]$ echo -n "symbol=BTC_USDT&side=0&type=1quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000" | openssl dgst -sha256 -hmac "cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV"
(stdin)= 27dbb813ab6ee7ef61902f88f1a0a6cd4daca0503a5195dbdd3174f49a61ad79
curl command:
(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV" -X POST 'https://www.tokocrypto.com/open/v1/orders?symbol=BTC_USDT&side=0&type=1' -d 'quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000&signature=27dbb813ab6ee7ef61902f88f1a0a6cd4daca0503a5195dbdd3174f49a61ad79'
Note that the signature is different in example 3. There is no & between "1" and "quantity=1".
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.Symbol type:
Order status (status):
Order types (orderTypes, type):
Order side (side):
Kline/Candlestick chart intervals:
m -> minutes; h -> hours; d -> days; w -> weeks; M -> months
Filters define trading rules on a symbol or an exchange.
Filters come in two forms: symbol filters
and exchange filters
.
The PRICE_FILTER
defines the price
rules for a symbol. There are 3 parts:
minPrice
defines the minimum price
/stopPrice
allowed; disabled on minPrice
== 0.maxPrice
defines the maximum price
/stopPrice
allowed; disabled on maxPrice
== 0.tickSize
defines the intervals that a price
/stopPrice
can be increased/decreased by; disabled on tickSize
== 0.Any of the above variables can be set to 0, which disables that rule in the price filter
. In order to pass the price filter
, the following must be true for price
/stopPrice
of the enabled rules:
price
>= minPrice
price
<= maxPrice
price
-minPrice
) % tickSize
== 0/exchangeInfo format:
{
"filterType": "PRICE_FILTER",
"minPrice": "0.00000100",
"maxPrice": "100000.00000000",
"tickSize": "0.00000100"
}
The PERCENT_PRICE
filter defines valid range for a price based on the average of the previous trades.
avgPriceMins
is the number of minutes the average price is calculated over. 0 means the last price is used.
In order to pass the percent price
, the following must be true for price
:
price
<= weightedAveragePrice
* multiplierUp
price
>= weightedAveragePrice
* multiplierDown
/exchangeInfo format:
{
"filterType": "PERCENT_PRICE",
"multiplierUp": "1.3000",
"multiplierDown": "0.7000",
"avgPriceMins": 5
}
The LOT_SIZE
filter defines the quantity
(aka "lots" in auction terms) rules for a symbol. There are 3 parts:
minQty
defines the minimum quantity
/icebergQty
allowed.maxQty
defines the maximum quantity
/icebergQty
allowed.stepSize
defines the intervals that a quantity
/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/exchangeInfo format:
{
"filterType": "LOT_SIZE",
"minQty": "0.00100000",
"maxQty": "100000.00000000",
"stepSize": "0.00100000"
}
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
.
applyToMarket
determines whether or not the MIN_NOTIONAL
filter will also be applied to MARKET
orders.
Since MARKET
orders have no price, the average price is used over the last avgPriceMins
minutes.
avgPriceMins
is the number of minutes the average price is calculated over. 0 means the last price is used.
/exchangeInfo format:
{
"filterType": "MIN_NOTIONAL",
"minNotional": "0.00100000",
"applyToMarket": true,
"avgPriceMins": 5
}
The ICEBERG_PARTS
filter defines the maximum parts an iceberg order can have. The number of ICEBERG_PARTS
is defined as CEIL(qty / icebergQty)
.
/exchangeInfo format:
{
"filterType": "ICEBERG_PARTS",
"limit": 10
}
The MARKET_LOT_SIZE
filter defines the quantity
(aka "lots" in auction terms) rules for MARKET
orders on a symbol. There are 3 parts:
minQty
defines the minimum quantity
allowed.maxQty
defines the maximum quantity
allowed.stepSize
defines the intervals that a quantity
can be increased/decreased by.In order to pass the market lot size
, the following must be true for quantity
:
quantity
>= minQty
quantity
<= maxQty
quantity
-minQty
) % stepSize
== 0/exchangeInfo format:
{
"filterType": "MARKET_LOT_SIZE",
"minQty": "0.00100000",
"maxQty": "100000.00000000",
"stepSize": "0.00100000"
}
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.
/exchangeInfo format:
{
"filterType": "MAX_NUM_ORDERS",
"limit": 25
}
The MAX_NUM_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.
/exchangeInfo format:
{
"filterType": "MAX_NUM_ALGO_ORDERS",
"maxNumAlgoOrders": 5
}
The MAX_NUM_ICEBERG_ORDERS
filter defines the maximum number of ICEBERG
orders an account is allowed to have open on a symbol.
An ICEBERG
order is any order where the icebergQty
is > 0.
/exchangeInfo format:
{
"filterType": "MAX_NUM_ICEBERG_ORDERS",
"maxNumIcebergOrders": 5
}
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.
/exchangeInfo format:
{
"filterType": "EXCHANGE_MAX_NUM_ORDERS",
"maxNumOrders": 1000
}
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.
/exchangeInfo format:
{
"filterType": "EXCHANGE_MAX_ALGO_ORDERS",
"maxNumAlgoOrders": 200
}
GET /open/v1/common/time
Test connectivity to the Rest API and get the current server time.
Parameters: NONE
Response:
{
"code": 0,
"msg": "success",
"timestamp": 1572265137927
}
GET /open/v1/common/symbols
This endpoint returns all Exchange's supported trading symbol.
Parameters: NONE
Response:
{
"code": 0,
"msg": "success",
"data": {
"list": [
{
"type": 1, // 1 - Main, 2 - Next.
"symbol": "ADA_BNB",
"baseAsset": "ADA",
"basePrecision": 8,
"quoteAsset": "BNB",
"quotePrecision": 8,
"filters": [
{
"applyToMarket": false,
"filterType": "PRICE_FILTER",
"maxPrice": "1000.00000000",
"minPrice": "0.00000100",
"tickSize": "0.00000100"
},
{
"applyToMarket": false,
"avgPriceMins": "5",
"filterType": "PERCENT_PRICE",
"multiplierDown": 0.2,
"multiplierUp": 5
},
{
"applyToMarket": false,
"filterType": "LOT_SIZE",
"maxQty": "9000000.00000000",
"minQty": "1.00000000",
"stepSize": "1.00000000"
},
{
"applyToMarket": true,
"avgPriceMins": "5",
"filterType": "MIN_NOTIONAL",
"minNotional": "0.10000000"
},
{
"applyToMarket": false,
"filterType": "ICEBERG_PARTS",
"limit": "10"
},
{
"applyToMarket": false,
"filterType": "MARKET_LOT_SIZE",
"maxQty": "4526300.00000000",
"minQty": "0.00000000",
"stepSize": "0.00000000"
},
{
"applyToMarket": false,
"filterType": "MAX_NUM_ALGO_ORDERS",
"maxNumAlgoOrders": "5"
}
],
"orderTypes": [
"LIMIT",
"LIMIT_MAKER",
"MARKET",
"STOP_LOSS_LIMIT",
"TAKE_PROFIT_LIMIT"
],
"icebergEnable": 1,
"ocoEnable": 1,
"spotTradingEnable": 1,
"marginTradingEnable": 0
}
]
},
"timestamp": 1571921637091
}
GET https://api.binance.cc/api/v3/depth (when symbol type is 1)
GET /open/v1/market/depth (when symbol type is not 1)
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | when symbol type is 1, replace _ of symbol with null string |
limit | INT | NO | Default 100; max 5000. Valid limits:[5, 10, 20, 50, 100, 500] |
Response:
{
"code": 0,
"msg": "success",
"data": {
"lastUpdateId": 1027024,
"bids": [
[
"4.00000000", // 价位
"431.00000000", // 挂单量
]
],
"asks": [
[
"4.00000200",
"12.00000000",
]
]
},
"timestamp": 1571921637091
}
GET https://api.binance.cc/api/v3/trades (when symbol type is 1)
GET /open/v1/market/trades (when symbol type is not 1)
Get recent trades (up to last 500).
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | when symbol type is 1, replace _ of symbol with null string |
fromId | LONG | NO | ID to get trades from INCLUSIVE. |
limit | INT | NO | Default 500; max 1000. |
Response:
{
"code": 0,
"msg": "success",
"data": [
{
"id": 28457,
"price": "4.00000100",
"qty": "12.00000000",
"time": 1499865549590,
"isBuyerMaker": true,
"isBestMatch": true
}
],
"timestamp": 1571921637091
}
GET https://api.binance.cc/api/v3/aggTrades (when symbol type is 1)
GET /open/v1/market/agg-trades (when symbol type is not 1)
Get compressed, aggregate trades. Trades that fill at the time, from the same order, with the same price will have the quantity aggregated.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | when symbol type is 1, replace _ of symbol with null string |
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 INCLUSIVE. |
limit | INT | NO | Default 500; max 1000. |
Response:
{
"code": 0,
"msg": "success",
"data": [
{
"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?
}
],
"timestamp": 1571921637091
}
GET https://api.binance.cc/api/v1/klines (when symbol type is 1)
GET /open/v1/market/klines (when symbol type is not 1)
Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | when symbol type is 1, replace _ of symbol with null string |
interval | ENUM | YES | |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | Default 500; max 1000. |
Response:
{
"code": 0,
"msg": "success",
"data": [
[
1499040000000, // Open time
"0.01634790", // Open
"0.80000000", // High
"0.01575800", // Low
"0.01577100", // Close
"148976.11427815", // Volume
1499644799999, // Close time
"2434.19055334", // Quote asset volume
308, // Number of trades
"1756.87402397", // Taker buy base asset volume
"28.46694368", // Taker buy quote asset volume
"17928899.62484339" // Ignore.
]
],
"timestamp": 1571921637091
}
POST /open/v1/orders (HMAC SHA256)
Send in a new order.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
side | ENUM | YES | 0,1 |
type | ENUM | YES | 1,2,4,6 |
quantity | STRING | NO | |
quoteOrderQty | STRING | NO | |
price | STRING | NO | |
clientId | STRING | NO | Client's custom ID for the order, Server does not check it's uniqueness. Automatically generated if not sent. |
stopPrice | STRING | NO | Used with STOP_LOSS , STOP_LOSS_LIMIT , TAKE_PROFIT , and TAKE_PROFIT_LIMIT orders. |
icebergQty | STRING | NO | Used with LIMIT , STOP_LOSS_LIMIT , and TAKE_PROFIT_LIMIT to create an iceberg order. |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Additional mandatory parameters based on type
:
Type | Additional mandatory parameters |
---|---|
1 |
quantity , price |
2 |
quantity (sell) or quoteOrderQty (buy) |
3 |
quantity , stopPrice |
4 |
quantity , price , stopPrice |
5 |
quantity , stopPrice |
6 |
quantity , price , stopPrice |
7 |
quantity , price |
Other info:
LIMIT_MAKER
are LIMIT
orders that will be rejected if they would immediately match and trade as a taker.STOP_LOSS
and TAKE_PROFIT
will execute a MARKET
order when the stopPrice
is reached.LIMIT
or LIMIT_MAKER
type order can be made an iceberg order by sending an icebergQty
.icebergQty
MUST have timeInForce
set to GTC
.MARKET
orders using quantity
specifies how much a user wants to buy or sell based on the market price.MARKET
orders using quoteOrderQty
specifies the amount the user wants to spend (when buying) of the quote asset; the correct quantity
will be determined based on the market liquidity and quoteOrderQty
.MARKET
orders using quoteOrderQty
will not break LOT_SIZE
filter rules; the order will execute a quantity
that will have the notional value as close as possible to quoteOrderQty
.Trigger order price rules against market price for both MARKET and LIMIT versions:
STOP_LOSS
BUY
, TAKE_PROFIT
SELL
STOP_LOSS
SELL
, TAKE_PROFIT
BUY
Response:
{
"code": 0,
"message": "success",
"data": {
"orderId": "4",
"createTime": 1550130502385
},
"timestamp": 1550130502489
}
GET /open/v1/orders/detail (HMAC SHA256)
Check an order's status.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
orderId | LONG | YES | |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Response:
{
"code": 0,
"message": "success",
"data": {
"orderId": 4,
"orderListId": -1 //Unless part of an OCO, the value will always be -1.
"clientId": "myOrder1",
"symbol": "BTC_USDT",
"side": 1,
"type": 1,
"price": 1,
"status": 0,
"origQty": 10.88,
"origQuoteQty": 0,
"executedQty": 0,
"executedPrice": 0,
"executedQuoteQty": 0,
"createTime": 1550130502000
},
"timestamp": 1550130554182
}
POST /open/v1/orders/cancel (HMAC SHA256)
Cancel an active order.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
orderId | LONG | YES | |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Response:
{
"code": 0,
"message": "success",
"data": {
"orderId": 4,
"orderListId": -1 // Unless part of an OCO, the value will always be -1.
"clientId": "myOrder1",
"symbol": "BTC_USDT",
"side": 1,
"type": 1,
"price": 1,
"status": 0,
"origQty": 10.88,
"origQuoteQty": 0,
"executedQty": 0,
"executedPrice": 0,
"executedQuoteQty": 0,
"createTime": 1550130502000
},
"timestamp": 1550130554182
}
GET /open/v1/orders (HMAC SHA256)
Get all account orders; active, canceled, or filled.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
type | ENUM | NO | 1-open, 2-history, -1-all |
side | ENUM | NO | |
startTime | LONG | NO | |
endTime | LONG | NO | |
fromId | String | NO | start order ID the searching to begin with. |
direct | ENUM | NO | searching direction: prev - in ascending order from the start order ID; next - in descending order from the start order ID |
limit | INT | NO | Default 500; max 1000. |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Notes:
Response:
{
"code": 0,
"msg": "success",
"data": {
"list": [
{
"orderId": "21",
"clientId": "uuid",
"symbol": "ADA_USDT",
"symbolType": 1,
"side": 1,
"type": 1,
"price": "0.1",
"origQty": "10",
"origQuoteQty": "1",
"executedQty": "0",
"executedPrice": "0",
"executedQuoteQty": "0",
"timeInForce": 1,
"stopPrice": "0.0000000000000000",
"icebergQty": "0.0000000000000000",
"status": 0,
"isWorking": 0,
"createTime": 1572692016811
}
]
},
"timestamp": 1572860756458
}
POST /open/v1/orders/oco (HMAC SHA256)
Send in a new OCO
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
listClientId | STRING | NO | Client's custom ID for the entire orderList, Server does not check it's uniqueness. Automatically generated if not sent. |
side | ENUM | YES | |
quantity | STRING | YES | |
limitClientId | STRING | NO | Client's custom ID for the limit order, Server does not check it's uniqueness. Automatically generated if not sent. |
price | STRING | YES | |
stopClientId | STRING | NO | Client's custom ID for the stop loss/stop loss limit order, Server does not check it's uniqueness. Automatically generated if not sent. |
stopPrice | STRING | YES | Stop price |
stopLimitPrice | STRING | YES | Stop limit price. |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Additional Info:
Price Restrictions:
SELL
: Limit Price > Last Price > Stop PriceBUY
: Limit Price < Last Price < Stop PriceResponse:
{
"code": 0,
"message": "success",
"data": {
"orderId": "4",
"createTime": 1550130502385
},
"timestamp": 1550130502489
}
GET /open/v1/account/spot (HMAC SHA256)
Get current account information.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Response:
{
"code": 0,
"msg": "success",
"data": {
"makerCommission": "10.00000000",
"takerCommission": "10.00000000",
"buyerCommission": "0.00000000",
"sellerCommission": "0.00000000",
"canTrade": 1,
"canWithdraw": 1,
"canDeposit": 1,
"accountAssets": [
{
"asset": "ADA",
"free": "272.5550000000000000",
"locked": "3.0000000000000000"
}
]
},
"timestamp": 1572514387348
}
GET /open/v1/account/spot/asset (HMAC SHA256)
Get current account information for a specific asset.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
asset | STRING | YES | |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Response:
{
"code": 0,
"msg": "success",
"data": {
"asset": "ADA",
"free": "272.5550000000000000",
"locked": "3.0000000000000000",
},
"timestamp": 1572514387348
}
GET /open/v1/orders/trades (HMAC SHA256)
Get trades for a specific account and symbol.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | String | NO | |
startTime | LONG | NO | |
endTime | LONG | NO | |
fromId | LONG | NO | TradeId to fetch from. Default gets most recent trades. |
direct | ENUM | NO | searching direction: prev - in ascending order from the start order ID; next - in descending order from the start order ID |
limit | INT | NO | Default 500; max 1000. |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Notes:
Response:
{
"code": 0,
"msg": "success",
"data": {
"list": [
{
"tradeId": "3",
"orderId": "2",
"symbol": "ADA_USDT",
"price": "0.04398",
"qty": "250",
"quoteQty": "10.995",
"commission": "0.25",
"commissionAsset": "ADA",
"isBuyer": 1,
"isMaker": 0,
"isBestMatch": 1,
"time": "1572920872276"
}
]
},
"timestamp": 1573723498893
}
POST /open/v1/withdraws (HMAC SHA256)
Submit a withdraw request.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
asset | STRING | YES | |
clientId | STRING | NO | Client's custom ID for withdraw order, Server does not check it's uniqueness. Automatically generated if not sent. |
network | STRING | NO | |
address | STRING | YES | |
addressTag | STRING | NO | Secondary address identifier for coins like XRP,XMR etc. |
amount | STRING | YES | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Response:
{
"code": 0,
"msg": "成功",
"data": {
"withdrawId":"12"
},
"timestamp": 1571745049095
}
GET /open/v1/withdraws (HMAC SHA256)
Fetch withdraw history.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
asset | STRING | NO | |
status | INT | NO | 0(0:Email Sent,1:Cancelled 2:Awaiting Approval 3:Rejected 4:Processing 5:Failure 10:Completed) |
fromId | LONG | NO | ID to fetch from. Default gets most recent records. |
startTime | LONG | NO | |
endTime | LONG | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Response:
{
"code": 0,
"msg": "成功",
"data": {
"list": [
{
"id": 1,
"clientId": "1",
"asset": "BTC",
"network": "BTC",
"address": "1G58aoKLVd1vHkv7wi6R2rKUrjuk4ZRtY3",
"amount": "0.001",
"fee": "0.0005",
"txId": "",
"status": 4,
"createTime": 1572359825000,
}
]
},
"timestamp": 1572402980747
}
GET /open/v1/deposits (HMAC SHA256)
Fetch deposit history.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
asset | STRING | NO | |
status | INT | NO | 0(0:pending, 1:success) |
fromId | LONG | NO | ID to fetch from. Default gets most recent records. |
startTime | LONG | NO | |
endTime | LONG | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Response:
{
"code": 0,
"msg": "成功",
"data": {
"list": [
{
"id": 1,
"asset": "BTC",
"network": "BTC",
"address": "2",
"addressTag": "2",
"txId": "1",
"amount": "1.000000000000000000000000000000",
"status": 1,
"insertTime": "0"
}
]
},
"timestamp": 1572317515063
}
GET /open/v1/deposits/address (HMAC SHA256)
Fetch deposit address.
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
asset | STRING | YES | |
network | STRING | YES | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Response:
{
"code": 0,
"msg": "成功",
"data": {
"address": "0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b",
"addressTag": "1231212",
"asset": "BNB"
},
"timestamp": 1571745049095
}
ping frame
every 3 minutes. If the websocket server does not receive a pong frame
back from the connection within a 10 minute period, the connection will be disconnected. Unsolicited pong frames
are allowed.id
used in the JSON payloads is an unsigned INT used as an identifier to uniquely identify the messages going back and forth.result
received is null
this means the request sent was a success for non-query requests (e.g. Subscribing/Unsubscribing).Request
{
"method": "SUBSCRIBE",
"params": [
"btcusdt@aggTrade",
"btcusdt@depth"
],
"id": 1
}
Response
{
"result": null,
"id": 1
}
Request
{
"method": "UNSUBSCRIBE",
"params": [
"btcusdt@depth"
],
"id": 312
}
Response
{
"result": null,
"id": 312
}
Request
{
"method": "LIST_SUBSCRIPTIONS",
"id": 3
}
Response
{
"result": [
"btcusdt@aggTrade"
],
"id": 3
}
Currently, the only property can be set is to set whether combined
stream payloads are enabled are not.
The combined property is set to false
when connecting using /ws/
("raw streams") and true
when connecting using /stream/
.
Request
{
"method": "SET_PROPERTY",
"params": [
"combined",
true
],
"id": 5
}
Response
{
"result": null,
"id": 5
}
Request
{
"method": "GET_PROPERTY",
"params": [
"combined"
],
"id": 2
}
Response
{
"result": true, // Indicates that combined is set to true.
"id": 2
}
Error Message | Description |
---|---|
{"code": 0, "msg": "Unknown property"} | Parameter used in the SET_PROPERTY or GET_PROPERTY was invalid |
{"code": 1, "msg": "Invalid value type: expected Boolean"} | Value should only be true or false |
{"code": 2, "msg": "Invalid request: property name must be a string"} | Property name provided was invalid |
{"code": 2, "msg": "Invalid request: request ID must be an unsigned integer"} | Parameter id had to be provided or the value provided in the id parameter is an unsupported type |
{"code": 2, "msg": "Invalid request: unknown variant %s, expected one of SUBSCRIBE , UNSUBSCRIBE , LIST_SUBSCRIPTIONS , SET_PROPERTY , GET_PROPERTY at line 1 column 28"} |
Possible typo in the provided method or provided method was neither of the expected values |
{"code": 2, "msg": "Invalid request: too many parameters"} | Unnecessary parameters provided in the data |
{"code": 2, "msg": "Invalid request: property name must be a string"} | Property name was not provided |
{"code": 2, "msg": "Invalid request: missing field method at line 1 column 73"} |
method was not provided in the data |
{"code":3,"msg":"Invalid JSON: expected value at line %s column %s"} | JSON data sent has incorrect syntax. |
The Aggregate Trade Streams push trade information that is aggregated for a single taker order.
Stream Name: \<symbol>@aggTrade
Update Speed: Real-time
Payload:
{
"e": "aggTrade", // Event type
"E": 123456789, // Event time
"s": "BNBBTC", // Symbol
"a": 12345, // Aggregate trade ID
"p": "0.001", // Price
"q": "100", // Quantity
"f": 100, // First trade ID
"l": 105, // Last trade ID
"T": 123456785, // Trade time
"m": true, // Is the buyer the market maker?
"M": true // Ignore
}
The Trade Streams push raw trade information; each trade has a unique buyer and seller.
Stream Name: \<symbol>@trade
Update Speed: Real-time
Payload:
{
"e": "trade", // Event type
"E": 123456789, // Event time
"s": "BNBBTC", // Symbol
"t": 12345, // Trade ID
"p": "0.001", // Price
"q": "100", // Quantity
"b": 88, // Buyer order ID
"a": 50, // Seller order ID
"T": 123456785, // Trade time
"m": true, // Is the buyer the market maker?
"M": true // Ignore
}
The Kline/Candlestick Stream push updates to the current klines/candlestick every second.
Kline/Candlestick chart intervals:
m -> minutes; h -> hours; d -> days; w -> weeks; M -> months
Stream Name: \<symbol>@kline_\<interval>
Update Speed: 2000ms
Payload:
{
"e": "kline", // Event type
"E": 123456789, // Event time
"s": "BNBBTC", // Symbol
"k": {
"t": 123400000, // Kline start time
"T": 123460000, // Kline close time
"s": "BNBBTC", // Symbol
"i": "1m", // Interval
"f": 100, // First trade ID
"L": 200, // Last trade ID
"o": "0.0010", // Open price
"c": "0.0020", // Close price
"h": "0.0025", // High price
"l": "0.0015", // Low price
"v": "1000", // Base asset volume
"n": 100, // Number of trades
"x": false, // Is this kline closed?
"q": "1.0000", // Quote asset volume
"V": "500", // Taker buy base asset volume
"Q": "0.500", // Taker buy quote asset volume
"B": "123456" // Ignore
}
}
24hr rolling window mini-ticker statistics. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs.
Stream Name: \<symbol>@miniTicker
Update Speed: 1000ms
Payload:
{
"e": "24hrMiniTicker", // Event type
"E": 123456789, // Event time
"s": "BNBBTC", // Symbol
"c": "0.0025", // Close price
"o": "0.0010", // Open price
"h": "0.0025", // High price
"l": "0.0010", // Low price
"v": "10000", // Total traded base asset volume
"q": "18" // Total traded quote asset volume
}
24hr rolling window mini-ticker statistics for all symbols that changed in an array. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs. Note that only tickers that have changed will be present in the array.
Stream Name: !miniTicker@arr
Update Speed: 1000ms
Payload:
[
{
// Same as <symbol>@miniTicker payload
}
]
Top \<levels> bids and asks, pushed every second. Valid \<levels> are 5, 10, or 20.
Stream Names: \<symbol>@depth\<levels> OR \<symbol>@depth\<levels>@100ms
Update Speed: 1000ms or 100ms
Payload:
{
"lastUpdateId": 160, // Last update ID
"bids": [ // Bids to be updated
[
"0.0024", // Price level to be updated
"10" // Quantity
]
],
"asks": [ // Asks to be updated
[
"0.0026", // Price level to be updated
"100" // Quantity
]
]
}
Order book price and quantity depth updates used to locally manage an order book.
Stream Name: \<symbol>@depth OR \<symbol>@depth@100ms
Update Speed: 1000ms or 100ms
Payload:
{
"e": "depthUpdate", // Event type
"E": 123456789, // Event time
"s": "BNBBTC", // Symbol
"U": 157, // First update ID in event
"u": 160, // Final update ID in event
"b": [ // Bids to be updated
[
"0.0024", // Price level to be updated
"10" // Quantity
]
],
"a": [ // Asks to be updated
[
"0.0026", // Price level to be updated
"100" // Quantity
]
]
}
u
is <= lastUpdateId
in the snapshot.U
<= lastUpdateId
+1 AND u
>= lastUpdateId
+1.U
should be equal to the previous event's u
+1.