Table of Contents generated with DocToc
- General API Information
- HTTP Return Codes
- Error Codes
- General Information on Endpoints
- LIMITS
- Data Sources
- Endpoint security type
- SIGNED (TRADE and USER_DATA) Endpoint security
- Public API Endpoints
- Terminology
- ENUM definitions
- General endpoints
- Market Data endpoints
- Account endpoints
- New order (TRADE)
- Test new order (TRADE)
- Query order (USER_DATA)
- Cancel order (TRADE)
- Cancel All Open Orders on a Symbol (TRADE)
- Cancel an Existing Order and Send a New Order (TRADE)
- Current open orders (USER_DATA)
- All orders (USER_DATA)
- New OCO (TRADE)
- Cancel OCO (TRADE)
- Query OCO (USER_DATA)
- Query all OCO (USER_DATA)
- Query Open OCO (USER_DATA)
- Account information (USER_DATA)
- Account trade list (USER_DATA)
- Query Current Order Count Usage (TRADE)
- User data stream endpoints
- Filters
- The base endpoint is: https://api.binance.com
- If there are performance issues with the endpoint above, these API clusters are also available:
- 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 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 receiving429
codes. - HTTP
5XX
return codes are used for internal errors; the issue is on Binance'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
Sample Payload below:
{
"code": -1121,
"msg": "Invalid symbol."
}
- Specific error codes and messages are defined in Errors Codes.
- 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.
- The following
intervalLetter
values for headers:- SECOND => S
- MINUTE => M
- HOUR => H
- DAY => D
intervalNum
describes the amount of the interval. For example,intervalNum
5 withintervalLetter
M means "Every 5 minutes".- The
/api/v3/exchangeInfo
rateLimits
array contains objects related to the exchange'sRAW_REQUESTS
,REQUEST_WEIGHT
, andORDERS
rate limits. These are further defined in theENUM definitions
section underRate limiters (rateLimitType)
. - A 429 will be returned when either rate limit is violated.
- Every request will contain
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. - 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 received, 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.
- A
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 429, to prevent a ban, or, in the case of a 418, until the ban is over. - The limits on the API are based on the IPs, not the API keys.
- Every successful order response will contain a
X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)
header which has the current order count for the account for all order rate limiters defined. To monitor order count usage, refer toGET api/v3/rateLimit/order
. - When the order count exceeds the limit, you will receive a 429 error without the
Retry-After
header. Please check the Order Rate Limit rules usingGET api/v3/exchangeInfo
and wait for reactivation accordingly. - Rejected/unsuccessful orders are not guaranteed to have
X-MBX-ORDER-COUNT-**
headers in the response. - The order rate limit is counted against each account.
- The API system is asynchronous, so some delay in the response is normal and expected.
- Each endpoint has a data source indicating where the data is being retrieved, and thus which endpoints have the most up-to-date response.
These are the three sources, ordered by which is has the most up-to-date response to the one with potential delays in updates.
- Matching Engine - the data is from the matching Engine
- Memory - the data is from a server's local or external memory
- Database - the data is taken directly from a database
Some endpoints can have more than 1 data source. (e.g. Memory => Database) This means that the endpoint will check the first Data Source, and if it cannot find the value it's looking for it will check the next one.
- Each endpoint has a security type that determines how you will interact with it. This is stated next to the NAME of the endpoint.
- If no security type is stated, assume the security type is NONE.
- API-keys are passed into the Rest API via the
X-MBX-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.
Security Type | Description |
---|---|
NONE | Endpoint can be accessed freely. |
TRADE | Endpoint requires sending a valid API-Key and signature. |
USER_DATA | Endpoint requires sending a valid API-Key and signature. |
USER_STREAM | Endpoint requires sending a valid API-Key. |
MARKET_DATA | Endpoint requires sending a valid API-Key. |
TRADE
andUSER_DATA
endpoints areSIGNED
endpoints.
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
.
-
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. -
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 valid 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 |
-
requestBody: symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559
-
HMAC SHA256 signature:
[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" (stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71
-
curl command:
(HMAC SHA256) [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.com/api/v3/order' -d 'symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'
-
queryString: symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559
-
HMAC SHA256 signature:
[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" (stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71
-
curl command:
(HMAC SHA256) [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.com/api/v3/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'
-
queryString: symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC
-
requestBody: quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559
-
HMAC SHA256 signature:
[linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000×tamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j" (stdin)= 0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77
-
curl command:
(HMAC SHA256) [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.com/api/v3/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559&signature=0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77'
Note that the signature is different in example 3. There is no & between "GTC" and "quantity=1".
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.
base asset
refers to the asset that is thequantity
of a symbol. For the symbol BTCUSDT, BTC would be thebase asset
.quote asset
refers to the asset that is theprice
of a symbol. For the symbol BTCUSDT, USDT would be thequote asset
.
Symbol status (status):
- PRE_TRADING
- TRADING
- POST_TRADING
- END_OF_DAY
- HALT
- AUCTION_MATCH
- BREAK
Account and Symbol Permissions (permissions):
- SPOT
- MARGIN
- LEVERAGED
- TRD_GRP_002
- TRD_GRP_003
- TRD_GRP_004
Order status (status):
Status | Description |
---|---|
NEW |
The order has been accepted by the engine. |
PARTIALLY_FILLED |
A part of the order has been filled. |
FILLED |
The order has been completed. |
CANCELED |
The order has been canceled by the user. |
PENDING_CANCEL |
Currently unused |
REJECTED |
The order was not accepted by the engine and not processed. |
EXPIRED |
The order was canceled according to the order type's rules (e.g. LIMIT FOK orders with no fill, LIMIT IOC or MARKET orders that partially fill) or by the exchange, (e.g. orders canceled during liquidation, orders canceled during maintenance) |
OCO Status (listStatusType):
Status | Description |
---|---|
RESPONSE |
This is used when the ListStatus is responding to a failed action. (E.g. Orderlist placement or cancellation) |
EXEC_STARTED |
The order list has been placed or there is an update to the order list status. |
ALL_DONE |
The order list has finished executing and thus no longer active. |
OCO Order Status (listOrderStatus):
Status | Description |
---|---|
EXECUTING |
Either an order list has been placed or there is an update to the status of the list. |
ALL_DONE |
An order list has completed execution and thus no longer active. |
REJECT |
The List Status is responding to a failed action either during order placement or order canceled |
ContingencyType
- OCO
Order types (orderTypes, type):
- LIMIT
- MARKET
- STOP_LOSS
- STOP_LOSS_LIMIT
- TAKE_PROFIT
- TAKE_PROFIT_LIMIT
- LIMIT_MAKER
Order Response Type (newOrderRespType):
- ACK
- RESULT
- FULL
Order side (side):
- BUY
- SELL
Time in force (timeInForce):
This sets how long an order will be active before expiration.
Status | Description |
---|---|
GTC |
Good Til Canceled An order will be on the book unless the order is canceled. |
IOC |
Immediate Or Cancel An order will try to fill the order as much as it can before the order expires. |
FOK |
Fill or Kill An order will expire if the full order cannot be filled upon execution. |
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)
-
REQUEST_WEIGHT
{ "rateLimitType": "REQUEST_WEIGHT", "interval": "MINUTE", "intervalNum": 1, "limit": 1200 }
-
ORDERS
{ "rateLimitType": "ORDERS", "interval": "SECOND", "intervalNum": 1, "limit": 10 }
-
RAW_REQUESTS
{ "rateLimitType": "RAW_REQUESTS", "interval": "MINUTE", "intervalNum": 5, "limit": 5000 }
Rate limit intervals (interval)
- SECOND
- MINUTE
- DAY
GET /api/v3/ping
Test connectivity to the Rest API.
Weight: 1
Parameters: NONE
Data Source: Memory
Response:
{}
GET /api/v3/time
Test connectivity to the Rest API and get the current server time.
Weight: 1
Parameters: NONE
Data Source: Memory
Response:
{
"serverTime": 1499827319559
}
GET /api/v3/exchangeInfo
Current exchange trading rules and symbol information
Weight: 10
Parameters:
There are 3 possible options:
Options | Example |
---|---|
No parameter | curl -X GET "https://api.binance.com/api/v3/exchangeInfo" |
symbol | curl -X GET "https://api.binance.com/api/v3/exchangeInfo?symbol=BNBBTC" |
symbols | curl -X GET "https://api.binance.com/api/v3/exchangeInfo?symbols=%5B%22BNBBTC%22,%22BTCUSDT%22%5D" or curl -g GET 'https://api.binance.com/api/v3/exchangeInfo?symbols=["BTCUSDT","BNBBTC"]' |
If any symbol provided in either symbol
or symbols
do not exist, the endpoint will throw an error.
Data Source: Memory
Response:
{
"timezone": "UTC",
"serverTime": 1565246363776,
"rateLimits": [
{
//These are defined in the `ENUM definitions` section under `Rate Limiters (rateLimitType)`.
//All limits are optional
}
],
"exchangeFilters": [
//These are the defined filters in the `Filters` section.
//All filters are optional.
],
"symbols": [
{
"symbol": "ETHBTC",
"status": "TRADING",
"baseAsset": "ETH",
"baseAssetPrecision": 8,
"quoteAsset": "BTC",
"quotePrecision": 8, // will be removed in future api versions (v4+)
"quoteAssetPrecision": 8,
"baseCommissionPrecision": 8,
"quoteCommissionPrecision": 8,
"orderTypes": [
"LIMIT",
"LIMIT_MAKER",
"MARKET",
"STOP_LOSS",
"STOP_LOSS_LIMIT",
"TAKE_PROFIT",
"TAKE_PROFIT_LIMIT"
],
"icebergAllowed": true,
"ocoAllowed": true,
"quoteOrderQtyMarketAllowed": true,
"allowTrailingStop": false,
"cancelReplaceAllowed":false,
"isSpotTradingAllowed": true,
"isMarginTradingAllowed": true,
"filters": [
//These are defined in the Filters section.
//All filters are optional
],
"permissions": [
"SPOT",
"MARGIN"
]
}
]
}
GET /api/v3/depth
Weight: Adjusted based on the limit:
Limit | Request Weight |
---|---|
1-100 | 1 |
101-500 | 5 |
501-1000 | 10 |
1001-5000 | 50 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 100; max 5000. If limit > 5000. then the response will truncate to 5000. |
Data Source: Memory
Response:
{
"lastUpdateId": 1027024,
"bids": [
[
"4.00000000", // PRICE
"431.00000000" // QTY
]
],
"asks": [
[
"4.00000200",
"12.00000000"
]
]
}
GET /api/v3/trades
Get recent trades.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 500; max 1000. |
Data Source: Memory
Response:
[
{
"id": 28457,
"price": "4.00000100",
"qty": "12.00000000",
"quoteQty": "48.000012",
"time": 1499865549590,
"isBuyerMaker": true,
"isBestMatch": true
}
]
GET /api/v3/historicalTrades
Get older trades.
Weight: 5
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 500; max 1000. |
fromId | LONG | NO | TradeId to fetch from. Default gets most recent trades. |
Data Source: Database
Response:
[
{
"id": 28457,
"price": "4.00000100",
"qty": "12.00000000",
"quoteQty": "48.000012",
"time": 1499865549590,
"isBuyerMaker": true,
"isBestMatch": true
}
]
GET /api/v3/aggTrades
Get compressed, aggregate trades. Trades that fill at the time, from the same taker 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 INCLUSIVE. |
limit | INT | NO | Default 500; 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.
Data Source: Database
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?
}
]
GET /api/v3/klines
Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
interval | ENUM | YES | |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | Default 500; max 1000. |
- If startTime and endTime are not sent, the most recent klines are returned.
Data Source: Database
Response:
[
[
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.
]
]
Current average price for a symbol.
GET /api/v3/avgPrice
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES |
Data Source: Memory
Response:
{
"mins": 5,
"price": "9.35751834"
}
GET /api/v3/ticker/24hr
24 hour rolling window price change statistics. Careful when accessing this with no symbol.
Weight:
Parameter | Symbols Provided | Weight |
---|---|---|
symbol | 1 | 1 |
symbol parameter is omitted | 40 | |
symbols | 1-20 | 1 |
21-100 | 20 | |
101 or more | 40 | |
symbols parameter is omitted | 40 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | Parameter symbol and symbols cannot be used in combination. If neither parameter is sent, tickers for all symbols will be returned in an array. Examples of accepted format for the symbols parameter: ["BTCUSDT","BNBUSDT"] or %5B%22BTCUSDT%22,%22BNBUSDT%22%5D |
symbols | STRING | NO |
Data Source: Memory
Response:
{
"symbol": "BNBBTC",
"priceChange": "-94.99999800",
"priceChangePercent": "-95.960",
"weightedAvgPrice": "0.29628482",
"prevClosePrice": "0.10002000",
"lastPrice": "4.00000200",
"lastQty": "200.00000000",
"bidPrice": "4.00000000",
"bidQty": "100.00000000",
"askPrice": "4.00000200",
"askQty": "100.00000000",
"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",
"bidQty": "100.00000000",
"askPrice": "4.00000200",
"askQty": "100.00000000",
"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
}
]
GET /api/v3/ticker/price
Latest price for a symbol or symbols.
Weight:
Parameter | Symbols Provided | Weight |
---|---|---|
symbol | 1 | 1 |
symbol parameter is omitted | 2 | |
symbols | Any | 2 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | Parameter symbol and symbols cannot be used in combination. If neither parameter is sent, prices for all symbols will be returned in an array. Examples of accepted format for the symbols parameter: ["BTCUSDT","BNBUSDT"] or %5B%22BTCUSDT%22,%22BNBUSDT%22%5D |
symbols | STRING | NO |
Data Source: Memory
Response:
{
"symbol": "LTCBTC",
"price": "4.00000200"
}
OR
[
{
"symbol": "LTCBTC",
"price": "4.00000200"
},
{
"symbol": "ETHBTC",
"price": "0.07946600"
}
]
GET /api/v3/ticker/bookTicker
Best price/qty on the order book for a symbol or symbols.
Weight:
Parameter | Symbols Provided | Weight |
---|---|---|
symbol | 1 | 1 |
symbol parameter is omitted | 2 | |
symbols | Any | 2 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | Parameter symbol and symbols cannot be used in combination. If neither parameter is sent, bookTickers for all symbols will be returned in an array. Examples of accepted format for the symbols parameter: ["BTCUSDT","BNBUSDT"] or %5B%22BTCUSDT%22,%22BNBUSDT%22%5D |
symbols | STRING | NO |
Data Source: Memory
Response:
{
"symbol": "LTCBTC",
"bidPrice": "4.00000000",
"bidQty": "431.00000000",
"askPrice": "4.00000200",
"askQty": "9.00000000"
}
OR
[
{
"symbol": "LTCBTC",
"bidPrice": "4.00000000",
"bidQty": "431.00000000",
"askPrice": "4.00000200",
"askQty": "9.00000000"
},
{
"symbol": "ETHBTC",
"bidPrice": "0.07946700",
"bidQty": "9.00000000",
"askPrice": "100000.00000000",
"askQty": "1000.00000000"
}
]
GET /api/v3/ticker
Note: This endpoint is different from the GET /api/v3/ticker/24hr
endpoint.
The window used to compute statistics will be no more than 59999ms from the requested windowSize
.
openTime
for /api/v3/ticker
always starts on a minute, while the closeTime
is the current time of the request.
As such, the effective window will be up to 59999ms wider than windowSize
.
E.g. If the closeTime
is 1641287867099 (January 04, 2022 09:17:47:099 UTC) , and the windowSize
is 1d
. the openTime
will be: 1641201420000 (January 3, 2022, 09:17:00)
Weight:
2 for each requested symbol regardless of windowSize.
The weight for this request will cap at 100 once the number of symbols
in the request is more than 50.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | Either symbol or symbols must be provided Examples of accepted format for the symbols parameter: ["BTCUSDT","BNBUSDT"] or %5B%22BTCUSDT%22,%22BNBUSDT%22%5D The maximum number of symbols allowed in a request is 100. |
symbols | |||
windowSize | ENUM | NO | Defaults to 1d if no parameter provided Supported windowSize values: 1m,2m....59m for minutes 1h, 2h....23h - for hours 1d...7d - for days Units cannot be combined (e.g. 1d2h is not allowed) |
Data Source: Database
Response
When using symbol
:
{
"symbol": "BNBBTC",
"priceChange": "-8.00000000", // Absolute price change
"priceChangePercent": "-88.889", // Relative price change in percent
"weightedAvgPrice": "2.60427807", // QuoteVolume / Volume
"openPrice": "9.00000000",
"highPrice": "9.00000000",
"lowPrice": "1.00000000",
"lastPrice": "1.00000000",
"volume": "187.00000000",
"quoteVolume": "487.00000000", // Sum of (price * volume) for all trades
"openTime": 1641859200000, // Open time for ticker window
"closeTime": 1642031999999, // Close time for ticker window
"firstId": 0, // Trade IDs
"lastId": 60,
"count": 61 // Number of trades in the interval
}
or
When using symbols
:
[
{
"symbol": "BTCUSDT",
"priceChange": "-154.13000000",
"priceChangePercent": "-0.740",
"weightedAvgPrice": "20677.46305250",
"openPrice": "20825.27000000",
"highPrice": "20972.46000000",
"lowPrice": "20327.92000000",
"lastPrice": "20671.14000000",
"volume": "72.65112300",
"quoteVolume": "1502240.91155513",
"openTime": 1655432400000,
"closeTime": 1655446835460,
"firstId": 11147809,
"lastId": 11149775,
"count": 1967
},
{
"symbol": "BNBBTC",
"priceChange": "0.00008530",
"priceChangePercent": "0.823",
"weightedAvgPrice": "0.01043129",
"openPrice": "0.01036170",
"highPrice": "0.01049850",
"lowPrice": "0.01033870",
"lastPrice": "0.01044700",
"volume": "166.67000000",
"quoteVolume": "1.73858301",
"openTime": 1655432400000,
"closeTime": 1655446835460,
"firstId": 2351674,
"lastId": 2352034,
"count": 361
}
]
POST /api/v3/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 | NO | |
quoteOrderQty | DECIMAL | NO | |
price | DECIMAL | NO | |
newClientOrderId | STRING | NO | A unique id among open orders. Automatically generated if not sent. Orders with the same newClientOrderID can be accepted only when the previous one is filled, otherwise the order will be rejected. |
stopPrice | DECIMAL | NO | Used with STOP_LOSS , STOP_LOSS_LIMIT , TAKE_PROFIT , and TAKE_PROFIT_LIMIT orders. |
trailingDelta | LONG | NO | Used with STOP_LOSS , STOP_LOSS_LIMIT , TAKE_PROFIT , and TAKE_PROFIT_LIMIT orders. |
icebergQty | DECIMAL | NO | Used with LIMIT , STOP_LOSS_LIMIT , and TAKE_PROFIT_LIMIT to create an iceberg order. |
newOrderRespType | ENUM | NO | Set the response JSON. ACK , RESULT , or FULL ; MARKET and LIMIT order types default to FULL , all other orders default to ACK . |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Some additional mandatory parameters based on order type
:
Type | Additional mandatory parameters | Additional Information |
---|---|---|
LIMIT |
timeInForce , quantity , price |
|
MARKET |
quantity or quoteOrderQty |
MARKET orders using the quantity field specifies the amount of the base asset the user wants to buy or sell at the market price. E.g. MARKET order on BTCUSDT will specify how much BTC the user is buying or selling. MARKET orders using quoteOrderQty specifies the amount the user wants to spend (when buying) or receive (when selling) the quote asset; the correct quantity will be determined based on the market liquidity and quoteOrderQty . E.g. Using the symbol BTCUSDT: BUY side, the order will buy as many BTC as quoteOrderQty USDT can. SELL side, the order will sell as much BTC needed to receive quoteOrderQty USDT. |
STOP_LOSS |
quantity , stopPrice or trailingDelta |
This will execute a MARKET order when the conditions are met. (e.g. stopPrice is met or trailingDelta is activated) |
STOP_LOSS_LIMIT |
timeInForce , quantity , price , stopPrice or trailingDelta |
|
TAKE_PROFIT |
quantity , stopPrice or trailingDelta |
This will execute a MARKET order when the conditions are met. (e.g. stopPrice is met or trailingDelta is activated) |
TAKE_PROFIT_LIMIT |
timeInForce , quantity , price , stopPrice or trailingDelta |
|
LIMIT_MAKER |
quantity , price |
This is a LIMIT order that will be rejected if the order immediately matches and trades as a taker. This is also known as a POST-ONLY order. |
Other info:
-
Any
LIMIT
orLIMIT_MAKER
type order can be made an iceberg order by sending anicebergQty
. -
Any order with an
icebergQty
MUST havetimeInForce
set toGTC
. -
For
STOP_LOSS
,STOP_LOSS_LIMIT
,TAKE_PROFIT_LIMIT
andTAKE_PROFIT
orders,trailingDelta
can be combined withstopPrice
. -
MARKET
orders usingquoteOrderQty
will not breakLOT_SIZE
filter rules; the order will execute aquantity
that will have the notional value as close as possible toquoteOrderQty
. 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
Data Source: Matching Engine
Response ACK:
{
"symbol": "BTCUSDT",
"orderId": 28,
"orderListId": -1, //Unless OCO, value will be -1
"clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
"transactTime": 1507725176595
}
Response RESULT:
{
"symbol": "BTCUSDT",
"orderId": 28,
"orderListId": -1, //Unless OCO, value will be -1
"clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
"transactTime": 1507725176595,
"price": "0.00000000",
"origQty": "10.00000000",
"executedQty": "10.00000000",
"cummulativeQuoteQty": "10.00000000",
"status": "FILLED",
"timeInForce": "GTC",
"type": "MARKET",
"side": "SELL"
}
Response FULL:
{
"symbol": "BTCUSDT",
"orderId": 28,
"orderListId": -1, //Unless OCO, value will be -1
"clientOrderId": "6gCrw2kRUAF9CvJDGP16IP",
"transactTime": 1507725176595,
"price": "0.00000000",
"origQty": "10.00000000",
"executedQty": "10.00000000",
"cummulativeQuoteQty": "10.00000000",
"status": "FILLED",
"timeInForce": "GTC",
"type": "MARKET",
"side": "SELL",
"fills": [
{
"price": "4000.00000000",
"qty": "1.00000000",
"commission": "4.00000000",
"commissionAsset": "USDT",
"tradeId": 56
},
{
"price": "3999.00000000",
"qty": "5.00000000",
"commission": "19.99500000",
"commissionAsset": "USDT",
"tradeId": 57
},
{
"price": "3998.00000000",
"qty": "2.00000000",
"commission": "7.99600000",
"commissionAsset": "USDT",
"tradeId": 58
},
{
"price": "3997.00000000",
"qty": "1.00000000",
"commission": "3.99700000",
"commissionAsset": "USDT",
"tradeId": 59
},
{
"price": "3995.00000000",
"qty": "1.00000000",
"commission": "3.99500000",
"commissionAsset": "USDT",
"tradeId": 60
}
]
}
POST /api/v3/order/test (HMAC SHA256)
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 /api/v3/order
Data Source: Memory
Response:
{}
GET /api/v3/order (HMAC SHA256)
Check an order's status.
Weight: 2
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | LONG | NO | |
origClientOrderId | STRING | NO | |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Notes:
- Either
orderId
ororigClientOrderId
must be sent. - For some historical orders
cummulativeQuoteQty
will be < 0, meaning the data is not available at this time.
Data Source: Database
Response:
{
"symbol": "LTCBTC",
"orderId": 1,
"orderListId": -1 //Unless part of an OCO, the value will always be -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,
"origQuoteOrderQty": "0.000000"
}
DELETE /api/v3/order (HMAC SHA256)
Cancel an active order.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | LONG | NO | |
origClientOrderId | STRING | NO | |
newClientOrderId | STRING | NO | Used to uniquely identify this cancel. Automatically generated by default. |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Either orderId
or origClientOrderId
must be sent.
If both parameters are sent, orderId
takes precedence.
Data Source: Matching Engine
Response:
{
"symbol": "LTCBTC",
"origClientOrderId": "myOrder1",
"orderId": 4,
"orderListId": -1, //Unless part of an OCO, the value will always be -1.
"clientOrderId": "cancelMyOrder1",
"price": "2.00000000",
"origQty": "1.00000000",
"executedQty": "0.00000000",
"cummulativeQuoteQty": "0.00000000",
"status": "CANCELED",
"timeInForce": "GTC",
"type": "LIMIT",
"side": "BUY"
}
DELETE /api/v3/openOrders (HMAC SHA256)
Cancels all active orders on a symbol. This includes OCO orders.
Weight 1
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Data Source: Matching Engine
Response
[
{
"symbol": "BTCUSDT",
"origClientOrderId": "E6APeyTJvkMvLMYMqu1KQ4",
"orderId": 11,
"orderListId": -1,
"clientOrderId": "pXLV6Hz6mprAcVYpVMTGgx",
"price": "0.089853",
"origQty": "0.178622",
"executedQty": "0.000000",
"cummulativeQuoteQty": "0.000000",
"status": "CANCELED",
"timeInForce": "GTC",
"type": "LIMIT",
"side": "BUY"
},
{
"symbol": "BTCUSDT",
"origClientOrderId": "A3EF2HCwxgZPFMrfwbgrhv",
"orderId": 13,
"orderListId": -1,
"clientOrderId": "pXLV6Hz6mprAcVYpVMTGgx",
"price": "0.090430",
"origQty": "0.178622",
"executedQty": "0.000000",
"cummulativeQuoteQty": "0.000000",
"status": "CANCELED",
"timeInForce": "GTC",
"type": "LIMIT",
"side": "BUY"
},
{
"orderListId": 1929,
"contingencyType": "OCO",
"listStatusType": "ALL_DONE",
"listOrderStatus": "ALL_DONE",
"listClientOrderId": "2inzWQdDvZLHbbAmAozX2N",
"transactionTime": 1585230948299,
"symbol": "BTCUSDT",
"orders": [
{
"symbol": "BTCUSDT",
"orderId": 20,
"clientOrderId": "CwOOIPHSmYywx6jZX77TdL"
},
{
"symbol": "BTCUSDT",
"orderId": 21,
"clientOrderId": "461cPg51vQjV3zIMOXNz39"
}
],
"orderReports": [
{
"symbol": "BTCUSDT",
"origClientOrderId": "CwOOIPHSmYywx6jZX77TdL",
"orderId": 20,
"orderListId": 1929,
"clientOrderId": "pXLV6Hz6mprAcVYpVMTGgx",
"price": "0.668611",
"origQty": "0.690354",
"executedQty": "0.000000",
"cummulativeQuoteQty": "0.000000",
"status": "CANCELED",
"timeInForce": "GTC",
"type": "STOP_LOSS_LIMIT",
"side": "BUY",
"stopPrice": "0.378131",
"icebergQty": "0.017083"
},
{
"symbol": "BTCUSDT",
"origClientOrderId": "461cPg51vQjV3zIMOXNz39",
"orderId": 21,
"orderListId": 1929,
"clientOrderId": "pXLV6Hz6mprAcVYpVMTGgx",
"price": "0.008791",
"origQty": "0.690354",
"executedQty": "0.000000",
"cummulativeQuoteQty": "0.000000",
"status": "CANCELED",
"timeInForce": "GTC",
"type": "LIMIT_MAKER",
"side": "BUY",
"icebergQty": "0.639962"
}
]
}
]
POST /api/v3/order/cancelReplace
Cancels an existing order and places a new order on the same symbol.
Filters and Order Count are evaluated before the processing of the cancellation and order placement occurs.
A new order that was not attempted (i.e. when newOrderResult: NOT_ATTEMPTED
), will still increase the order count by 1.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
side | ENUM | YES | |
type | ENUM | YES | |
cancelReplaceMode | ENUM | YES | The allowed values are: STOP_ON_FAILURE - If the cancel request fails, the new order placement will not be attempted. ALLOW_FAILURE - new order placement will be attempted even if cancel request fails. |
timeInForce | ENUM | NO | |
quantity | DECIMAL | NO | |
quoteOrderQty | DECIMAL | NO | |
price | DECIMAL | NO | |
cancelNewClientOrderId | STRING | NO | Used to uniquely identify this cancel. Automatically generated by default. |
cancelOrigClientOrderId | STRING | NO | Either the cancelOrigClientOrderId or cancelOrderId must be provided. If both are provided, cancelOrderId takes precedence. |
cancelOrderId | LONG | NO | Either the cancelOrigClientOrderId or cancelOrderId must be provided. If both are provided, cancelOrderId takes precedence. |
newClientOrderId | STRING | NO | Used to identify the new order. |
stopPrice | DECIMAL | NO | |
trailingDelta | LONG | NO | |
icebergQty | DECIMAL | NO | |
newOrderRespType | ENUM | NO | Allowed values: ACK , RESULT , FULL MARKET and LIMIT orders types default to FULL ; all other orders default to ACK |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Similar to POST /api/v3/order
, additional mandatory parameters are determined by type
.
Response format varies depending on whether the processing of the message succeeded, partially succeeded, or failed.
Data Source: Matching Engine
Response SUCCESS:
//Both the cancel order placement and new order placement succeeded.
{
"cancelResult": "SUCCESS",
"newOrderResult": "SUCCESS",
"cancelResponse": {
"symbol": "BTCUSDT",
"origClientOrderId": "DnLo3vTAQcjha43lAZhZ0y",
"orderId": 9,
"orderListId": -1,
"clientOrderId": "osxN3JXAtJvKvCqGeMWMVR",
"price": "0.01000000",
"origQty": "0.000100",
"executedQty": "0.00000000",
"cummulativeQuoteQty": "0.00000000",
"status": "CANCELED",
"timeInForce": "GTC",
"type": "LIMIT",
"side": "SELL"
},
"newOrderResponse": {
"symbol": "BTCUSDT",
"orderId": 10,
"orderListId": -1,
"clientOrderId": "wOceeeOzNORyLiQfw7jd8S",
"transactTime": 1652928801803,
"price": "0.02000000",
"origQty": "0.040000",
"executedQty": "0.00000000",
"cummulativeQuoteQty": "0.00000000",
"status": "NEW",
"timeInForce": "GTC",
"type": "LIMIT",
"side": "BUY",
"fills": []
}
}
Response when Cancel Order Fails with STOP_ON FAILURE:
{
"code": -2022,
"msg": "Order cancel-replace failed.",
"data": {
"cancelResult": "FAILURE",
"newOrderResult": "NOT_ATTEMPTED",
"cancelResponse": {
"code": -2011,
"msg": "Unknown order sent."
},
"newOrderResponse": null
}
}
Response when Cancel Order Succeeds but New Order Placement Fails:
{
"code": -2021,
"msg": "Order cancel-replace partially failed.",
"data": {
"cancelResult": "SUCCESS",
"newOrderResult": "FAILURE",
"cancelResponse": {
"symbol": "BTCUSDT",
"origClientOrderId": "86M8erehfExV8z2RC8Zo8k",
"orderId": 3,
"orderListId": -1,
"clientOrderId": "G1kLo6aDv2KGNTFcjfTSFq",
"price": "0.006123",
"origQty": "10000.000000",
"executedQty": "0.000000",
"cummulativeQuoteQty": "0.000000",
"status": "CANCELED",
"timeInForce": "GTC",
"type": "LIMIT_MAKER",
"side": "SELL"
},
"newOrderResponse": {
"code": -2010,
"msg": "Order would immediately match and take."
}
}
}
Response when Cancel Order fails with ALLOW_FAILURE:
{
"code": -2021,
"msg": "Order cancel-replace partially failed.",
"data": {
"cancelResult": "FAILURE",
"newOrderResult": "SUCCESS",
"cancelResponse": {
"code": -2011,
"msg": "Unknown order sent."
},
"newOrderResponse": {
"symbol": "BTCUSDT",
"orderId": 11,
"orderListId": -1,
"clientOrderId": "pfojJMg6IMNDKuJqDxvoxN",
"transactTime": 1648540168818
}
}
}
Response when both Cancel Order and New Order Placement fail:
{
"code": -2022,
"msg": "Order cancel-replace failed.",
"data": {
"cancelResult": "FAILURE",
"newOrderResult": "FAILURE",
"cancelResponse": {
"code": -2011,
"msg": "Unknown order sent."
},
"newOrderResponse": {
"code": -2010,
"msg": "Order would immediately match and take."
}
}
}
GET /api/v3/openOrders (HMAC SHA256)
Get all open orders on a symbol. Careful when accessing this with no symbol.
Weight: 3 for a single symbol; 40 when the symbol parameter is omitted
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
- If the symbol is not sent, orders for all symbols will be returned in an array.
Data Source: Database
Response:
[
{
"symbol": "LTCBTC",
"orderId": 1,
"orderListId": -1, //Unless OCO, the value will always be -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,
"origQuoteOrderQty": "0.000000"
}
]
GET /api/v3/allOrders (HMAC SHA256)
Get all account orders; active, canceled, or filled.
Weight: 10 with symbol
Data Source: Database
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | LONG | NO | |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | Default 500; max 1000. |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Notes:
- If
orderId
is set, it will get orders >= thatorderId
. Otherwise most recent orders are returned. - For some historical orders
cummulativeQuoteQty
will be < 0, meaning the data is not available at this time. - If
startTime
and/orendTime
provided,orderId
is not required.
Response:
[
{
"symbol": "LTCBTC",
"orderId": 1,
"orderListId": -1, //Unless OCO, the value will always be -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,
"origQuoteOrderQty": "0.000000"
}
]
POST /api/v3/order/oco (HMAC SHA256)
Weight: 1
Send in a new OCO
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
listClientOrderId | STRING | NO | A unique Id for the entire orderList |
side | ENUM | YES | |
quantity | DECIMAL | YES | |
limitClientOrderId | STRING | NO | A unique Id for the limit order |
price | DECIMAL | YES | |
limitIcebergQty | DECIMAL | NO | Used to make the LIMIT_MAKER leg an iceberg order. |
trailingDelta | LONG | NO | |
stopClientOrderId | STRING | NO | A unique Id for the stop loss/stop loss limit leg |
stopPrice | DECIMAL | YES | |
stopLimitPrice | DECIMAL | NO | If provided, stopLimitTimeInForce is required. |
stopIcebergQty | DECIMAL | NO | Used with STOP_LOSS_LIMIT leg to make an iceberg order. |
stopLimitTimeInForce | ENUM | NO | Valid values are GTC /FOK /IOC |
newOrderRespType | ENUM | NO | Set the response JSON. |
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 Price
- Quantity Restrictions:
- Both legs must have the same quantity.
ICEBERG
quantities however do not have to be the same
- Order Rate Limit
OCO
counts as 2 orders against the order rate limit.
Data Source: Matching Engine
Response:
{
"orderListId": 0,
"contingencyType": "OCO",
"listStatusType": "EXEC_STARTED",
"listOrderStatus": "EXECUTING",
"listClientOrderId": "JYVpp3F0f5CAG15DhtrqLp",
"transactionTime": 1563417480525,
"symbol": "LTCBTC",
"orders": [
{
"symbol": "LTCBTC",
"orderId": 2,
"clientOrderId": "Kk7sqHb9J6mJWTMDVW7Vos"
},
{
"symbol": "LTCBTC",
"orderId": 3,
"clientOrderId": "xTXKaGYd4bluPVp78IVRvl"
}
],
"orderReports": [
{
"symbol": "LTCBTC",
"orderId": 2,
"orderListId": 0,
"clientOrderId": "Kk7sqHb9J6mJWTMDVW7Vos",
"transactTime": 1563417480525,
"price": "0.000000",
"origQty": "0.624363",
"executedQty": "0.000000",
"cummulativeQuoteQty": "0.000000",
"status": "NEW",
"timeInForce": "GTC",
"type": "STOP_LOSS",
"side": "BUY",
"stopPrice": "0.960664"
},
{
"symbol": "LTCBTC",
"orderId": 3,
"orderListId": 0,
"clientOrderId": "xTXKaGYd4bluPVp78IVRvl",
"transactTime": 1563417480525,
"price": "0.036435",
"origQty": "0.624363",
"executedQty": "0.000000",
"cummulativeQuoteQty": "0.000000",
"status": "NEW",
"timeInForce": "GTC",
"type": "LIMIT_MAKER",
"side": "BUY"
}
]
}
DELETE /api/v3/orderList (HMAC SHA256)
Weight: 1
Cancel an entire Order List
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderListId | LONG | NO | Either orderListId or listClientOrderId must be provided |
listClientOrderId | STRING | NO | Either orderListId or listClientOrderId must be provided |
newClientOrderId | STRING | NO | Used to uniquely identify this cancel. Automatically generated by default |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Additional notes:
- Canceling an individual leg will cancel the entire OCO
- If both
orderListId
andlistClientOrderId
are sent,orderListId
takes precedence.
Data Source: Matching Engine
Response
{
"orderListId": 0,
"contingencyType": "OCO",
"listStatusType": "ALL_DONE",
"listOrderStatus": "ALL_DONE",
"listClientOrderId": "C3wyj4WVEktd7u9aVBRXcN",
"transactionTime": 1574040868128,
"symbol": "LTCBTC",
"orders": [
{
"symbol": "LTCBTC",
"orderId": 2,
"clientOrderId": "pO9ufTiFGg3nw2fOdgeOXa"
},
{
"symbol": "LTCBTC",
"orderId": 3,
"clientOrderId": "TXOvglzXuaubXAaENpaRCB"
}
],
"orderReports": [
{
"symbol": "LTCBTC",
"origClientOrderId": "pO9ufTiFGg3nw2fOdgeOXa",
"orderId": 2,
"orderListId": 0,
"clientOrderId": "unfWT8ig8i0uj6lPuYLez6",
"price": "1.00000000",
"origQty": "10.00000000",
"executedQty": "0.00000000",
"cummulativeQuoteQty": "0.00000000",
"status": "CANCELED",
"timeInForce": "GTC",
"type": "STOP_LOSS_LIMIT",
"side": "SELL",
"stopPrice": "1.00000000"
},
{
"symbol": "LTCBTC",
"origClientOrderId": "TXOvglzXuaubXAaENpaRCB",
"orderId": 3,
"orderListId": 0,
"clientOrderId": "unfWT8ig8i0uj6lPuYLez6",
"price": "3.00000000",
"origQty": "10.00000000",
"executedQty": "0.00000000",
"cummulativeQuoteQty": "0.00000000",
"status": "CANCELED",
"timeInForce": "GTC",
"type": "LIMIT_MAKER",
"side": "SELL"
}
]
}
GET /api/v3/orderList (HMAC SHA256)
Weight: 2
Retrieves a specific OCO based on provided optional parameters
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
orderListId | LONG | NO | Either orderListId or listClientOrderId must be provided |
origClientOrderId | STRING | NO | Either orderListId or listClientOrderId must be provided |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Data Source: Database
Response:
{
"orderListId": 27,
"contingencyType": "OCO",
"listStatusType": "EXEC_STARTED",
"listOrderStatus": "EXECUTING",
"listClientOrderId": "h2USkA5YQpaXHPIrkd96xE",
"transactionTime": 1565245656253,
"symbol": "LTCBTC",
"orders": [
{
"symbol": "LTCBTC",
"orderId": 4,
"clientOrderId": "qD1gy3kc3Gx0rihm9Y3xwS"
},
{
"symbol": "LTCBTC",
"orderId": 5,
"clientOrderId": "ARzZ9I00CPM8i3NhmU9Ega"
}
]
}
GET /api/v3/allOrderList (HMAC SHA256)
Weight: 10
Retrieves all OCO based on provided optional parameters
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
fromId | LONG | NO | If supplied, neither startTime or endTime can be provided |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | Default Value: 500; Max Value: 1000 |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Data Source: Database
Response:
[
{
"orderListId": 29,
"contingencyType": "OCO",
"listStatusType": "EXEC_STARTED",
"listOrderStatus": "EXECUTING",
"listClientOrderId": "amEEAXryFzFwYF1FeRpUoZ",
"transactionTime": 1565245913483,
"symbol": "LTCBTC",
"orders": [
{
"symbol": "LTCBTC",
"orderId": 4,
"clientOrderId": "oD7aesZqjEGlZrbtRpy5zB"
},
{
"symbol": "LTCBTC",
"orderId": 5,
"clientOrderId": "Jr1h6xirOxgeJOUuYQS7V3"
}
]
},
{
"orderListId": 28,
"contingencyType": "OCO",
"listStatusType": "EXEC_STARTED",
"listOrderStatus": "EXECUTING",
"listClientOrderId": "hG7hFNxJV6cZy3Ze4AUT4d",
"transactionTime": 1565245913407,
"symbol": "LTCBTC",
"orders": [
{
"symbol": "LTCBTC",
"orderId": 2,
"clientOrderId": "j6lFOfbmFMRjTYA7rRJ0LP"
},
{
"symbol": "LTCBTC",
"orderId": 3,
"clientOrderId": "z0KCjOdditiLS5ekAFtK81"
}
]
}
]
GET /api/v3/openOrderList (HMAC SHA256)
Weight: 3
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Data Source: Database
Response:
[
{
"orderListId": 31,
"contingencyType": "OCO",
"listStatusType": "EXEC_STARTED",
"listOrderStatus": "EXECUTING",
"listClientOrderId": "wuB13fmulKj3YjdqWEcsnp",
"transactionTime": 1565246080644,
"symbol": "LTCBTC",
"orders": [
{
"symbol": "LTCBTC",
"orderId": 4,
"clientOrderId": "r3EH2N76dHfLoSZWIUw1bT"
},
{
"symbol": "LTCBTC",
"orderId": 5,
"clientOrderId": "Cv1SnyPD3qhqpbjpYEHbd2"
}
]
}
]
GET /api/v3/account (HMAC SHA256)
Get current account information.
Weight: 10
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Data Source: Memory => Database
Response:
{
"makerCommission": 15,
"takerCommission": 15,
"buyerCommission": 0,
"sellerCommission": 0,
"canTrade": true,
"canWithdraw": true,
"canDeposit": true,
"updateTime": 123456789,
"accountType": "SPOT",
"balances": [
{
"asset": "BTC",
"free": "4723846.89208129",
"locked": "0.00000000"
},
{
"asset": "LTC",
"free": "4763368.68006011",
"locked": "0.00000000"
}
],
"permissions": [
"SPOT"
]
}
GET /api/v3/myTrades (HMAC SHA256)
Get trades for a specific account and symbol.
Weight: 10 with symbol
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | LONG | NO | This can only be used in combination with symbol . |
startTime | LONG | NO | |
endTime | LONG | NO | |
fromId | LONG | NO | TradeId to fetch from. Default gets most recent trades. |
limit | INT | NO | Default 500; max 1000. |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Notes:
- If
fromId
is set, it will get trades >= thatfromId
. Otherwise most recent trades are returned.
Data Source: Database
Response:
[
{
"symbol": "BNBBTC",
"id": 28457,
"orderId": 100234,
"orderListId": -1,
"price": "4.00000100",
"qty": "12.00000000",
"quoteQty": "48.000012",
"commission": "10.10000000",
"commissionAsset": "BNB",
"time": 1499865549590,
"isBuyer": true,
"isMaker": false,
"isBestMatch": true
}
]
GET /api/v3/rateLimit/order
Displays the user's current order count usage for all intervals.
Weight: 20
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Data Source: Memory
Response:
[
{
"rateLimitType": "ORDERS",
"interval": "SECOND",
"intervalNum": 10,
"limit": 50,
"count": 0
},
{
"rateLimitType": "ORDERS",
"interval": "DAY",
"intervalNum": 1,
"limit": 160000,
"count": 0
}
]
Specifics on how user data streams work can be found here.
POST /api/v3/userDataStream
Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent.
Weight: 1
Parameters: NONE
Data Source: Memory
Response:
{
"listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}
PUT /api/v3/userDataStream
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
Data Source" Memory
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
listenKey | STRING | YES |
Response:
{}
DELETE /api/v3/userDataStream
Close out a user data stream.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
listenKey | STRING | YES |
Data Source: Memory
Response:
{}
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 minimumprice
/stopPrice
allowed; disabled onminPrice
== 0.maxPrice
defines the maximumprice
/stopPrice
allowed; disabled onmaxPrice
== 0.tickSize
defines the intervals that aprice
/stopPrice
can be increased/decreased by; disabled ontickSize
== 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
%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 PERCENT_PRICE_BY_SIDE
filter defines the valid range for the price based on the last price of the symbol.
There is a different range depending on whether the order is placed on the BUY
side or the SELL
side.
Buy orders will succeed on this filter if:
Order price
<=bidMultiplierUp
*lastPrice
Order price
>=bidMultiplierDown
*lastPrice
Sell orders will succeed on this filter if:
Order Price
<=askMultiplierUp
*lastPrice
Order Price
>=askMultiplierDown
*lastPrice
/exchangeInfo format:
{
"filterType": "PERCENT_PRICE_BY_SIDE",
"bidMultiplierUp": "1.2",
"bidMultiplierDown": "0.2",
"askMultiplierUp": "5",
"askMultiplierDown": "0.8",
"avgPriceMins": 1
}
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
/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 NOTIONAL
filter defines the acceptable notional range allowed for an order on a symbol.
applyMinToMarket
determines whether the minNotional
will be applied to MARKET
orders.
applyMaxToMarket
determines whether the maxNotional
will be applied to MARKET
orders.
In order to pass this filter, the notional (price * quantity
) has to pass the following conditions:
price * quantity
<=maxNotional
price * quantity
>=minNotional
For MARKET
orders, the average price used over the last avgPriceMins
minutes will be used for calculation.
If the avgPriceMins
is 0, then the last price will be used.
/exchangeInfo format:
{
"filterType": "NOTIONAL",
"minNotional": "10.00000000",
"applyMinToMarket": false,
"maxNotional": "10000.00000000",
"applyMaxToMarket": false,
"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 minimumquantity
allowed.maxQty
defines the maximumquantity
allowed.stepSize
defines the intervals that aquantity
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",
"maxNumOrders": 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_POSITION
filter defines the allowed maximum position an account can have on the base asset of a symbol. An account's position defined as the sum of the account's:
- free balance of the base asset
- locked balance of the base asset
- sum of the qty of all open BUY orders
BUY
orders will be rejected if the account's position is greater than the maximum position allowed.
If an order's quantity
can cause the position to overflow, this will also fail the MAX_POSITION
filter.
/exchangeInfo format:
{
"filterType":"MAX_POSITION",
"maxPosition":"10.00000000"
}
The TRAILING_DELTA
filter defines the minimum and maximum value for the parameter trailingDelta
.
In order for a trailing stop order to pass this filter, the following must be true:
For STOP_LOSS BUY
, STOP_LOSS_LIMIT_BUY
,TAKE_PROFIT SELL
and TAKE_PROFIT_LIMIT SELL
orders:
trailingDelta
>=minTrailingAboveDelta
trailingDelta
<=maxTrailingAboveDelta
For STOP_LOSS SELL
, STOP_LOSS_LIMIT SELL
, TAKE_PROFIT BUY
, and TAKE_PROFIT_LIMIT BUY
orders:
trailingDelta
>=minTrailingBelowDelta
trailingDelta
<=maxTrailingBelowDelta
/exchangeInfo format:
{
"filterType": "TRAILING_DELTA",
"minTrailingAboveDelta": 10,
"maxTrailingAboveDelta": 2000,
"minTrailingBelowDelta": 10,
"maxTrailingBelowDelta": 2000
}
The EXCHANGE_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 EXCHANGE_MAX_NUM_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_NUM_ALGO_ORDERS",
"maxNumAlgoOrders": 200
}
The EXCHANGE_MAX_NUM_ICEBERG_ORDERS
filter defines the maximum number of iceberg orders an account is allowed to have open on the exchange.
/exchangeInfo format:
{
"filterType": "EXCHANGE_MAX_NUM_ICEBERG_ORDERS",
"maxNumIcebergOrders": 10000
}