Change Log
Notice: All changes are being rolled out gradually to all our servers, and may take a week to complete.
GENERAL CHANGES
- The error messages for certain issues have been improved for easier troubleshooting.
Situation | Old Error Message | New Error Message |
---|---|---|
An account cannot place or cancel an order, due to trading ability disabled. | This action is disabled on this account. | This account may not place or cancel orders. |
When the permissions configured on the symbol do not match the permissions on the account. | This symbol is not permitted for this account. | |
When the account tries to place an order on a symbol it has no permissions for. | This symbol is restricted for this account. | |
Placing an order when symbol is not TRADING. | Unsupported order combination. | This order type is not possible in this trading phase. |
Placing an order with timeinForce=IOC or FOK on a trading phase that does not support it. | Limit orders require GTC for this phase. |
- Fixed error message for querying archived orders:
- Previously, If an archived order (i.e. order with status
CANCELED
orEXPIRED
whereexecutedQty
== 0 that occurred more than 90 days in the past.) is queried, the error message would be:{"code": -2013,"msg": "Order does not exist."}
- Now, the error message is:
{"code": -2026,"msg": "Order was canceled or expired with no executed qty over 90 days ago and has been archived."}
- Previously, If an archived order (i.e. order with status
- Behavior for API requests with
startTime
andendTime
:- Previously some requests failed if the
startTime
==endTime
. - Now, all API requests that accept
startTime
andendTime
allow the parameters to be equal. This applies to the following requests:- Websocket API
trades.aggregate
klines
allOrderList
allOrders
myTrades
- Websocket API
- Previously some requests failed if the
- Users connected to the websocket API will now be disconnected if their IP is banned due to violation of the IP rate limits(status
418
).
The following changes will take effect approximately a week from the release date, but the rest of the documentation has been updated to reflect the future changes:
- Changes to Filter Evaluation:
- Previous behavior:
LOT_SIZE
andMARKET_LOT_SIZE
required that (quantity
-minQty
) %stepSize
== 0. - New behavior: This has now been changed to (
quantity
%stepSize
) == 0.
- Previous behavior:
- Bug fix with reverse
MARKET
orders (i.e.,MARKET
usingquoteOrderQty
):- Previous behavior: Reverse market orders would always have the status
FILLED
even if the order did not fully fill due to low liquidity. - New behavior: If the reverse market order did not fully fill due to low liquidity the order status will be
EXPIRED
, andFILLED
only if the order was completely filled.
- Previous behavior: Reverse market orders would always have the status
- Changes to
order.cancel
andorder.cancelReplace
:- A new optional parameter
cancelRestrictions
that determines whether the cancel will succeed if the order status isNEW
orPARTIALLY_FILLED
. - If the order cancellation fails due to
cancelRestrictions
, the error will be:{"code": -2011,"msg": "Order was not canceled due to cancel restrictions."}
- A new optional parameter
**2023-02-17**
The WS-API now only allows 300 connections requests every 5 minutes.
This limit is per IP address.
Please be careful when trying to open multiple connections or reconnecting to the Websocket API.
**2023-01-26**
As per the announcement, Self Trade Prevention will be enabled at 2023-01-26 08:00 UTC.
Please refer to GET /api/v3/exchangeInfo
from the Rest API or exchangeInfo
from the Websocket API on the default and allowed modes.
**2023-01-19**
ACTUAL RELEASE DATE TBD
New Feature: Self-Trade Prevention (aka STP) will be added to the system. This will prevent orders from matching with orders from the same account, or accounts under the same tradeGroupId
.
Please refer to GET /api/v3/exchangeInfo
from the SPOT API or exchangeInfo
from the Websocket API on the status.
- New order status:
EXPIRED_IN_MATCH
- This means that the order expired due to STP being triggered. - New optional parameter
selfTradePreventionMode
has been added to the following requests:order.place
orderList.place
order.cancelReplace
- New request:
myPreventedMatches
- This queries the orders that expired due to STP being triggered. - New responses that will appear for all order placement requests if there was a prevented match (i.e. if an order could have matched with an order of the same account, or the accounts are in the same
tradeGroupId
):tradeGroupId
- This will only appear if account is configured to atradeGroupId
and if there was a prevented match.preventedQuantity
- Only appears if there was a prevented match.- An array
preventedMatches
with the following fields:preventedMatchId
makerOrderId
price
takerPreventedQuantity
- This will only appear ifselfTradePreventionMode
set isEXPIRE_TAKER
orEXPIRE_BOTH
.makerPreventedQuantity
- This will only appear ifselfTradePreventionMode
set isEXPIRE_MAKER
orEXPIRE_BOTH
.
- New fields
preventedMatchId
andpreventedQuantity
that can appear in the order query requests if the order had expired due to STP trigger:order.status
openOrders.status
allOrders
**2022-12-28**
- Updated to show how to sign a request using RSA key.
**2022-12-26**
- Spot Websocket API is now available on the live exchange.
- Spot Websocket API can be accessed through this URL:
wss://ws-api.binance.com/ws-api/v3
**2022-12-15**
SPOT WebSocket API is now available on SPOT Testnet.
- WebSocket API allows placing orders, canceling orders, etc. through a WebSocket connection.
- WebSocket API is a separate service from WebSocket Market Data streams. I.e., placing orders and listening to market data requires two separate WebSocket connections.
- WebSocket API is subject to the same Filter and Rate Limit rules as REST API.
- WebSocket API and REST API are functionally equivalent: they provide the same features, accept the same parameters, return the same status and error codes.
SPOT WEBSOCKET API WILL BE AVAILABLE ON THE LIVE EXCHANGE AT A LATER DATE.
Introduction
#
API Key Setup- Some endpoints will require an API Key. Please refer to this page regarding API key creation.
- Once API key is created, it is recommended to set IP restrictions on the key for security reasons.
- Never share your API key/secret key to ANYONE.
#
API Key Restrictions- After creating the API key, the default restrictions is
Enable Reading
. - To enable withdrawals via the API, the API key restriction needs to be modified through the Binance UI.
#
Spot TestnetUsers can use the SPOT Testnet to practice SPOT
trading.
Currently, this is only available via the API.
Please refer to the SPOT Testnet page for more information and how to set up the Testnet API key.
#
Contact Us- Binance API Telegram Group
- For any questions in sudden drop in performance with the API and/or Websockets.
- For any general questions about the API not covered in the documentation.
- Binance Developers
- For any questions on your code implementation with the API and/or Websockets.
- Binance Customer Support
- For cases such as missing funds, help with 2FA, etc.
General Info
#
General API Information- The base endpoint is:
wss://ws-api.binance.com:443/ws-api/v3
- If you experience issues with the standard 443 port, alternative port 9443 is also available.
- The base endpoint for testnet is:
wss://testnet.binance.vision/ws-api/v3
.
- A single connection to the API is only valid for 24 hours; Expect to be disconnected after the 24-hour mark.
- WebSocket server will send a ping frame every 3 minutes.
- If the server does not receive a pong frame response within 10 minutes, you will be disconnected.
- Unsolicited pong frames are allowed and will prevent disconnection.
- Lists are returned in chronological order, unless noted otherwise.
- All timestamps are in milliseconds in UTC, unless noted otherwise.
- All field names and values are case-sensitive, unless noted otherwise.
#
Request formatRequests must be sent as JSON in text frames, one request per frame.
Example of request:
Request fields:
Name | Type | Mandatory | Description |
---|---|---|---|
id | INT / STRING / null | YES | Arbitrary ID used to match responses to requests |
method | STRING | YES | Request method name |
params | OBJECT | NO | Request parameters. May be omitted if there are no parameters |
Request
id
is truly arbitrary. You can use UUIDs, sequential IDs, current timestamp, etc. The server does not interpretid
in any way, simply echoing it back in the response.You can freely reuse IDs within a session. However, be careful to not send more than one request at a time with the same ID, since otherwise it might be impossible to tell the responses apart.
Request method names may be prefixed with explicit version: e.g.,
"v3/order.place"
.The order of
params
is not significant.
#
Response formatResponses are returned as JSON in text frames, one response per frame.
Example of successful response:
Example of failed response:
Response fields:
Name | Type | Mandatory | Description |
---|---|---|---|
id | INT / STRING / null | YES | Same as in the original request |
status | INT | YES | Response status. See Status codes |
result | OBJECT / ARRAY | YES | Response content. Present if request succeeded |
error | OBJECT | Error description. Present if request failed | |
rateLimits | ARRAY | NO | Rate limiting status. See Rate limits |
#
Status codesStatus codes in the status
field are the same as in HTTP.
Here are some common status codes that you might encounter:
200
indicates a successful response.4XX
status codes indicate invalid requests; the issue is on your side.400
– your request failed, seeerror
for the reason.403
– you have been blocked by the Web Application Firewall.409
– your request partially failed but also partially succeeded, seeerror
for details.418
– you have been auto-banned for repeated violation of rate limits.429
– you have exceeded API request rate limit, please slow down.
5XX
status codes indicate internal errors; the issue is on Binance's side.- Important: If a response contains 5xx status code, it does not necessarily mean that your request has failed. Execution status is unknown and the request might have actually succeeded. Please use query methods to confirm the status. You might also want to establish a new WebSocket connection for that.
See Error codes section for a list of error codes and messages.
Rate Limits
#
Connection limitsThere is a limit of 300 connections per attempt every 5 minutes.
The connection is per IP address.
#
General information on rate limits- Current API rate limits can be queried using the
exchangeInfo
request. - There are multiple rate limit types across multiple intervals.
- Responses can indicate current rate limit status in the optional
rateLimits
field. - Requests fail with status
429
when request rate limits or order rate limits are violated.
#
How to interpret rate limitsA response with rate limit status may look like this:
The rateLimits
array describes all currently active rate limits affected by the request.
Name | Type | Mandatory | Description |
---|---|---|---|
rateLimitType | ENUM | YES | Rate limit type: REQUEST_WEIGHT , ORDERS |
interval | ENUM | YES | Rate limit interval: SECOND , MINUTE , HOUR , DAY |
intervalNum | INT | YES | Rate limit interval multiplier |
limit | INT | YES | Request limit per interval |
count | INT | YES | Current usage per interval |
Rate limits are accounted by intervals.
For example, a 1 MINUTE
interval starts every minute.
Request submitted at 00:01:23.456 counts towards the 00:01:00 minute's limit.
Once the 00:02:00 minute starts, the count will reset to zero again.
Other intervals behave in a similar manner.
For example, 1 DAY
rate limit resets at 00:00 UTC every day,
and 10 SECOND
interval resets at 00, 10, 20... seconds of each minute.
APIs have multiple rate-limiting intervals. If you exhaust a shorter interval but the longer interval still allows requests, you will have to wait for the shorter interval to expire and reset. If you exhaust a longer interval, you will have to wait for that interval to reset, even if shorter rate limit count is zero.
#
How to show/hide rate limit informationrateLimits
field is included with every response by default.
However, rate limit information can be quite bulky.
If you are not interested in detailed rate limit status of every request,
the rateLimits
field can be omitted from responses to reduce their size.
Optional
returnRateLimits
boolean parameter in request.Use
returnRateLimits
parameter to control whether to includerateLimits
fields in response to individual requests.Default request and response:
Request and response without rate limit status:
Optional
returnRateLimits
boolean parameter in connection URL.If you wish to omit
rateLimits
from all responses by default, usereturnRateLimits
parameter in the query string instead:This will make all requests made through this connection behave as if you have passed
"returnRateLimits": false
.If you want to see rate limits for a particular request, you need to explicitly pass the
"returnRateLimits": true
parameter.
Note: Your requests are still rate limited if you hide the rateLimits
field in responses.
#
IP limits- Every request has a certain weight, added to your limit as you perform requests.
- Most requests cost 1 unit of weight, heavier requests acting on multiple symbols cost more.
- Connecting to WebSocket API costs 1 weight.
- Current weight usage is indicated by the
REQUEST_WEIGHT
rate limit type. - Use the
exchangeInfo
request to keep track of the current weight limits. - Weight is accumulated per IP address and is shared by all connections from that address.
- If you go over the weight limit, requests fail with status
429
.- This status code indicates you should back off and stop spamming the API.
- Rate-limited responses include a
retryAfter
field, indicating when you can retry the request.
- Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban and you will be disconnected.
- Requests from a banned IP address fail with status
418
. retryAfter
field indicates the timestamp when the ban will be lifted.
- Requests from a banned IP address fail with status
- IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.
Successful response indicating that in 1 minute you have used 70 weight out of your 1200 limit:
Failed response indicating that you are banned and the ban will last until epoch 1659146400000:
#
Order rate limits- Every request to place an order counts towards your order limit.
- Successfully placed orders update the
ORDERS
rate limit type. - Rejected or unsuccessful orders might or might not update the
ORDERS
count.
- Successfully placed orders update the
- Use the
account.rateLimits.orders
request to keep track of the current order rate limits. - Order rate limit is maintained per account and is shared by all API keys of the account.
- If you go over the order rate limit, requests fail with status
429
.- This status code indicates you should back off and stop spamming the API.
- Rate-limited responses include a
retryAfter
field, indicating when you can retry the request.
Successful response indicating that you have placed 12 orders in 10 seconds, and 4043 orders in the past 24 hours:
Request security
- Every method has a security type which determines how to call it.
- Security type is stated next to the method name. For example, Place new order (TRADE).
- If no security type is stated, the security type is NONE.
Security type | API key | Signature | Description |
---|---|---|---|
NONE | Public market data | ||
TRADE | required | required | Trading on the exchange, placing and canceling orders |
USER_DATA | required | required | Private account information, such as order status and your trading history |
USER_STREAM | required | Managing User Data Stream subscriptions | |
MARKET_DATA | required | Historical market data access |
- Secure methods require a valid API key to be specified and authenticated.
- API keys can be created on the API Management page of your Binance account.
- Both API key and secret key are sensitive. Never share them with anyone. If you notice unusual activity in your account, immediately revoke all the keys and contact Binance support.
- API keys can be configured to allow access only to certain types of secure methods.
- For example, you can have an API key with
TRADE
permission for trading, while using a separate API key withUSER_DATA
permission to monitor your order status. - By default, an API key cannot
TRADE
. You need to enable trading in API Management first.
- For example, you can have an API key with
TRADE
andUSER_DATA
requests are also known asSIGNED
requests.
#
SIGNED (TRADE and USER_DATA) request securitySIGNED
requests require an additional parameter:signature
, authorizing the request.- Please consult SIGNED request example (HMAC) and SIGNED request example (RSA) on how to compute signature.
#
Timing securitySIGNED
requests also require atimestamp
parameter which should be the current millisecond timestamp.An additional optional parameter,
recvWindow
, specifies for how long the request stays valid.- If
recvWindow
is not sent, it defaults to 5000 milliseconds. - Maximum
recvWindow
is 60000 milliseconds.
- If
Request processing 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 is recommended to use a small recvWindow
of 5000 or less!
#
SIGNED request example (HMAC)Here is a step-by-step guide on how to sign requests using HMAC secret key.
Example API key and secret key:
Key | Value |
---|---|
apiKey | vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A |
secretKey | NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j |
WARNING: DO NOT SHARE YOUR API KEY AND SECRET KEY WITH ANYONE.
The example keys are provided here only for illustrative purposes.
Example of request with missing
signature
parameter:
Step 1. Resulting signature payload:
Step 1. Construct the signature payload
Take all request params
except for the signature
, sort them by name in alphabetical order:
Parameter | Value |
---|---|
apiKey | vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A |
newOrderRespType | ACK |
price | 52000.00 |
quantity | 0.01000000 |
recvWindow | 100 |
side | SELL |
symbol | BTCUSDT |
timeInForce | GTC |
timestamp | 1645423376532 |
type | LIMIT |
Format parameters as parameter=value
pairs separated by &
.
Step 2. Example signature:
Step 2. Compute the signature
- Interpret
secretKey
as ASCII data, using it as a key for HMAC-SHA-256. - Sign signature payload as ASCII data.
- Encode HMAC-SHA-256 output as a hex string.
Note that apiKey
, secretKey
, and the payload are case-sensitive, while resulting signature value is case-insensitive.
You can cross-check your signature algorithm implementation with OpenSSL.
Step 3. Complete Request:
Step 3. Add signature
to request params
Finally, complete the request by adding the signature
parameter with the signature string.
#
SIGNED request example (RSA)Here is a step-by-step guide on how to sign requests using your RSA private key.
Key | Value |
---|---|
apiKey | CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ |
In this example, we assume the private key is stored in the test-prv-key.pem
file.
WARNING: DO NOT SHARE YOUR API KEY AND PRIVATE KEY WITH ANYONE.
The example keys are provided here only for illustrative purposes.
Example of request with missing
signature
parameter:
Step 1. Resulting signature payload:
Step 1. Construct the signature payload
Take all params
from the request example in the right, except for the signature
, and sort them by name in alphabetical order:
Parameter | Value |
---|---|
apiKey | CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ |
newOrderRespType | ACK |
price | 52000.00 |
quantity | 0.01000000 |
recvWindow | 100 |
side | SELL |
symbol | BTCUSDT |
timeInForce | GTC |
timestamp | 1645423376532 |
type | LIMIT |
Format parameters as parameter=value
pairs separated by &
.
Step 2:
Step 2. Compute the signature
- Encode signature payload as ASCII data.
- Sign payload using RSASSA-PKCS1-v1_5 algorithm with SHA-256 hash function.
- Encode output as base64 string.
Note that apiKey
, the payload, and the resulting signature
are case-sensitive.
You can cross-check your signature algorithm implementation with OpenSSL.
Step 3:
Step 3. Add signature
to request params
Finally, complete the request by adding the signature
parameter with the signature string.
Data sources
The API system is asynchronous. Some delay in the response is normal and expected.
Each method has a data source indicating where the data is coming from, and thus how up-to-date it is.
Data Source | Latency | Description |
---|---|---|
Matching Engine | lowest | The matching engine produces the response directly |
Memory | low | Data is fetched from API server's local or external memory cache |
Database | moderate | Data is retrieved from the database |
Public API Definitions
#
TerminologyThese 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
.
#
ENUM definitionsSymbol 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
TRD_GRP_005
TRD_GRP_006
TRD_GRP_007
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) |
EXPIRED_IN_MATCH | The order was canceled by the exchange due to STP trigger. (e.g. an order with EXPIRE_TAKER will match with existing orders on the book with the same account or same tradeGroupId ) |
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
General requests
#
Test connectivityRequest:
Response:
Test connectivity to the WebSocket API.
Note:
You can use regular WebSocket ping frames to test connectivity as well,
WebSocket API will respond with pong frames as soon as possible.
ping
request along with time
is a safe way to test request-response handling in your application.
Weight(IP): 1
Parameters: NONE
Data Source: Memory
#
Check server timeRequest:
Response:
Test connectivity to the WebSocket API and get the current server time.
Weight(IP): 1
Parameters: NONE
Data Source: Memory
#
Exchange informationRequest:
Response:
Query current exchange trading rules, rate limits, and symbol information.
Weight(IP): 10
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | Describe a single symbol |
symbols | ARRAY of STRING | Describe multiple symbols | |
permissions | ARRAY of STRING | Filter symbols by permissions |
Notes:
Only one of
symbol
,symbols
,permissions
parameters can be specified.Without parameters,
exchangeInfo
displays all symbols with["SPOT, "MARGIN", "LEVERAGED"]
permissions.- In order to list all active symbols on the exchange, you need to explicitly request all permissions.
permissions
accepts either a list of permissions, or a single permission name:"SPOT"
.
Data Source: Memory
Market data requests
#
Order bookRequest:
Response:
Get current order book.
Note that this request returns limited market depth.
If you need to continuously monitor order book updates, please consider using WebSocket Streams:
You can use depth
request together with <symbol>@depth
streams to maintain a local order book.
Weight(IP):
Adjusted based on the limit:
Limit | 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 |
Data Source: Memory
#
Recent tradesRequest:
Response:
Get recent trades.
If you need access to real-time trading activity, please consider using WebSocket Streams:
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 500; max 1000 |
Data Source: Memory
#
Historical trades (MARKET_DATA)Request:
Response:
Get historical trades.
Weight(IP): 5
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
fromId | INT | NO | Trade ID to begin at |
limit | INT | NO | Default 500; max 1000 |
apiKey | STRING | YES |
Notes:
- If
fromId
is not specified, the most recent trades are returned.
Data Source: Database
#
Aggregate tradesRequest:
Response:
Get aggregate trades.
An aggregate trade (aggtrade) represents one or more individual trades. Trades that fill at the same time, from the same taker order, with the same price – those trades are collected into an aggregate trade with total quantity of the individual trades.
If you need access to real-time trading activity, please consider using WebSocket Streams:
If you need historical aggregate trade data, please consider using data.binance.vision.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
fromId | INT | NO | Aggregate trade ID to begin at |
startTime | INT | NO | |
endTime | INT | NO | |
limit | INT | NO | Default 500; max 1000 |
Notes:
If
fromId
is specified, return aggtrades with aggregate trade ID >=fromId
.Use
fromId
andlimit
to page through all aggtrades.If
startTime
and/orendTime
are specified, aggtrades are filtered by execution time (T
).fromId
cannot be used together withstartTime
andendTime
.If no condition is specified, the most recent aggregate trades are returned.
Data Source: Database
#
KlinesRequest:
Response:
Get klines (candlestick bars).
Klines are uniquely identified by their open & close time.
If you need access to real-time kline updates, please consider using WebSocket Streams:
If you need historical kline data, please consider using data.binance.vision.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
interval | ENUM | YES | |
startTime | INT | NO | |
endTime | INT | NO | |
limit | INT | NO | Default 500; max 1000 |
Interval | interval value |
---|---|
seconds | 1s |
minutes | 1m , 3m , 5m , 15m , 30m |
hours | 1h , 2h , 4h , 6h , 8h , 12h |
days | 1d , 3d |
weeks | 1w |
months | 1M |
Notes:
- If
startTime
,endTime
are not specified, the most recent klines are returned.
Data Source: Database
#
UI KlinesRequest:
Response:
Get klines (candlestick bars) optimized for presentation.
This request is similar to klines
, having the same parameters and response.
uiKlines
return modified kline data, optimized for presentation of candlestick charts.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
interval | ENUM | YES | See klines |
startTime | INT | NO | |
endTime | INT | NO | |
limit | INT | NO | Default 500; max 1000 |
Notes:
- If
startTime
,endTime
are not specified, the most recent klines are returned.
Data Source: Database
#
Current average priceRequest:
Response:
Get current average price for a symbol.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES |
Data Source: Memory
#
24hr ticker price change statisticsRequest:
Response:
FULL
type, for a single symbol:
MINI
type, for a single symbol:
If more than one symbol is requested, response returns an array:
Get 24-hour rolling window price change statistics.
If you need to continuously monitor trading statistics, please consider using WebSocket Streams:
If you need different window sizes,
use the ticker
request.
Weight(IP):
Adjusted based on the number of requested symbols:
Symbols | Weight |
---|---|
1–20 | 1 |
21–100 | 20 |
101 or more | 40 |
all symbols | 40 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | Query ticker for a single symbol |
symbols | ARRAY of STRING | Query ticker for multiple symbols | |
type | ENUM | NO | Ticker type: FULL (default) or MINI |
Notes:
symbol
andsymbols
cannot be used together.If no symbol is specified, returns information about all symbols currently trading on the exchange.
Data Source: Memory
#
Rolling window price change statisticsRequest:
Response:
FULL
type, for a single symbol:
MINI
type, for a single symbol:
If more than one symbol is requested, response returns an array:
Get rolling window price change statistics with a custom window.
This request is similar to ticker.24hr
,
but statistics are computed on demand using the arbitrary window you specify.
Note: Window size precision is limited to 1 minute.
While the closeTime
is the current time of the request, openTime
always start on a minute boundary.
As such, the effective window might be up to 59999 ms wider than the requested windowSize
.
For example, a request for "windowSize": "7d"
might result in the following window:
"openTime": 1659580020000, "closeTime": 1660184865291
- Time of the request –
closeTime
– is 1660184865291 (August 11, 2022 02:27:45.291). - Requested window size should put the
openTime
7 days before that – August 4, 02:27:45.291 – but due to limited precision it ends up a bit earlier: 1659580020000 (August 4, 2022 02:27:00), exactly at the start of a minute.
If you need to continuously monitor trading statistics, please consider using WebSocket Streams:
Weight(IP):
Adjusted based on the number of requested symbols:
Symbols | Weight |
---|---|
1–50 | 2 per symbol |
51–100 | 100 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | Query ticker of a single symbol |
symbols | ARRAY of STRING | Query ticker for multiple symbols | |
type | ENUM | NO | Ticker type: FULL (default) or MINI |
windowSize | ENUM | NO | Default 1d |
Supported window sizes:
Unit | windowSize value |
---|---|
minutes | 1m , 2m ... 59m |
hours | 1h , 2h ... 23h |
days | 1d , 2d ... 7d |
Notes:
Either
symbol
orsymbols
must be specified.Maximum number of symbols in one request: 100.
Window size units cannot be combined. E.g.,
1d 2h
is not supported.
Data Source: Database
#
Symbol price tickerRequest:
Response:
If more than one symbol is requested, response returns an array:
Get the latest market price for a symbol.
If you need access to real-time price updates, please consider using WebSocket Streams:
Weight(IP):
Adjusted based on the number of requested symbols:
Parameter | Weight |
---|---|
symbol | 1 |
symbols | 2 |
none | 2 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | Query price for a single symbol |
symbols | ARRAY of STRING | Query price for multiple symbols |
Notes:
symbol
andsymbols
cannot be used together.If no symbol is specified, returns information about all symbols currently trading on the exchange.
Data Source: Memory
#
Symbol order book tickerRequest:
Response:
If more than one symbol is requested, response returns an array:
Get the current best price and quantity on the order book.
If you need access to real-time order book ticker updates, please consider using WebSocket Streams:
Weight(IP):
Adjusted based on the number of requested symbols:
Parameter | Weight |
---|---|
symbol | 1 |
symbols | 2 |
none | 2 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | Query ticker for a single symbol |
symbols | ARRAY of STRING | Query ticker for multiple symbols |
Notes:
symbol
andsymbols
cannot be used together.If no symbol is specified, returns information about all symbols currently trading on the exchange.
Data Source: Memory
Trading requests
#
Place new order (TRADE)Request:
Response:
ACK
response type:
RESULT
response type:
FULL
response type:
Send in a new order.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
side | ENUM | YES | BUY or SELL |
type | ENUM | YES | |
timeInForce | ENUM | NO * | |
price | DECIMAL | NO * | |
quantity | DECIMAL | NO * | |
quoteOrderQty | DECIMAL | NO * | |
newClientOrderId | STRING | NO | Arbitrary unique ID among open orders. Automatically generated if not sent |
newOrderRespType | ENUM | NO | Select response format:
|
stopPrice | DECIMAL | NO * | |
trailingDelta | INT | NO * | For more details on SPOT implementation on trailing stops, please refer to Trailing Stop FAQ |
icebergQty | DECIMAL | NO | |
strategyId | INT | NO | Arbitrary numeric value identifying the order within an order strategy. |
strategyType | INT | NO | Arbitrary numeric value identifying the order strategy. Values smaller than |
selfTradePreventionMode | ENUM | NO | The allowed enums is dependent on what is configured on the symbol. The possible supported values are EXPIRE_TAKER , EXPIRE_MAKER , EXPIRE_BOTH , NONE . |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Order type | Mandatory parameters |
---|---|
LIMIT |
|
LIMIT_MAKER |
|
MARKET |
|
STOP_LOSS |
|
STOP_LOSS_LIMIT |
|
TAKE_PROFIT |
|
TAKE_PROFIT_LIMIT |
|
Supported order types:
Order type | Description |
---|---|
LIMIT | Buy or sell |
LIMIT_MAKER |
This order type is also known as a POST-ONLY order. |
MARKET | Buy or sell at the best available market price.
|
STOP_LOSS | Execute a I.e., when |
STOP_LOSS_LIMIT | Place a |
TAKE_PROFIT | Like |
TAKE_PROFIT_LIMIT | Like |
Available timeInForce
options,
setting how long the order should be active before expiration:
TIF | Description |
---|---|
GTC | Good 'til Canceled – the order will remain on the book until you cancel it, or the order is completely filled. |
IOC | Immediate or Cancel – the order will be filled for as much as possible, the unfilled quantity immediately expires. |
FOK | Fill or Kill – the order will expire unless it cannot be immediately filled for the entire quantity. |
Notes:
newClientOrderId
specifiesclientOrderId
value for the order.A new order with the same
clientOrderId
is accepted only when the previous one is filled or expired.Any
LIMIT
orLIMIT_MAKER
order can be made into an iceberg order by specifying theicebergQty
.An order with an
icebergQty
must havetimeInForce
set toGTC
.Trigger order price rules for
STOP_LOSS
/TAKE_PROFIT
orders:stopPrice
must be above market price:STOP_LOSS BUY
,TAKE_PROFIT SELL
stopPrice
must be below market price:STOP_LOSS SELL
,TAKE_PROFIT BUY
MARKET
orders usingquoteOrderQty
followLOT_SIZE
filter rules.The order will execute a quantity that has notional value as close as possible to requested
quoteOrderQty
.
Data Source: Matching Engine
#
Conditional fields in Order ResponsesThere are fields in the order responses (e.g. order placement, order query, order cancellation) that appear only if certain conditions are met.
These fields can apply to OCO Orders.
The fields are listed below:
Field | Description | Visibility conditions | Examples |
---|---|---|---|
icebergQty | Quantity for the iceberg order | Appears only if the parameter icebergQty was sent in the request. | "icebergQty": "0.00000000" |
preventedMatchId | When used in combination with symbol , can be used to query a prevented match. | Appears only if the order expired due to STP. | "preventedMatchId": 0 |
preventedQuantity | Order quantity that expired due to STP | Appears only if the order expired due to STP. | "preventedQuantity": "1.200000" |
stopPrice | Price when the algorithmic order will be triggered | Appears for STOP_LOSS . TAKE_PROFIT , STOP_LOSS_LIMIT and TAKE_PROFIT_LIMIT orders. | "stopPrice": "23500.00000000" |
strategyId | Can be used to label an order that's part of an order strategy. | Appears if the parameter was populated in the request. | "strategyId": 37463720 |
strategyType | Can be used to label an order that is using an order strategy. | Appears if the parameter was populated in the request. | "strategyType": 1000000 |
trailingDelta | Delta price change required before order activation | Appears for Trailing Stop Orders. | "trailingDelta": 10 |
trailingTime | Time when the trailing order is now active and tracking price changes | Appears only for Trailing Stop Orders. | "trailingTime": -1 |
#
Test new order (TRADE)Request:
Response:
Test order placement.
Validates new order parameters and verifies your signature but does not send the order into the matching engine.
Weight(IP): 1
Parameters:
Same as for order.place
.
Data Source: Memory
#
Query order (USER_DATA)Request:
Response:
Check execution status of an order.
Weight(IP): 2
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | INT | YES | Lookup order by orderId |
origClientOrderId | STRING | Lookup order by clientOrderId | |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Notes:
If both
orderId
andorigClientOrderId
parameters are specified, onlyorderId
is used andorigClientOrderId
is ignored.For some historical orders the
cummulativeQuoteQty
response field may be negative, meaning the data is not available at this time.
Data Source: Memory => Database
Note: The payload sample does not show all fields that can appear. Please refer to Conditional fields in Order Responses.
#
Cancel order (TRADE)Request:
Response:
When an individual order is canceled:
When an OCO is canceled:
Cancel an active order.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | INT | YES | Cancel order by orderId |
origClientOrderId | STRING | Cancel order by clientOrderId | |
newClientOrderId | STRING | NO | New ID for the canceled order. Automatically generated if not sent |
cancelRestrictions | ENUM | NO | Supported values: ONLY_NEW - Cancel will succeed if the order status is NEW .ONLY_PARTIALLY_FILLED - Cancel will succeed if order status is PARTIALLY_FILLED . |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Notes:
If both
orderId
andorigClientOrderId
parameters are specified, onlyorderId
is used andorigClientOrderId
is ignored.newClientOrderId
will replaceclientOrderId
of the canceled order, freeing it up for new orders.If you cancel an order that is a part of an OCO pair, the entire OCO is canceled.
Data Source: Matching Engine
Note: The payload sample does not show all fields that can appear. Please refer to Conditional fields in Order Responses.
cancelRestrictions
#
Regarding - If the
cancelRestrictions
value is not any of the supported values, the error will be:{"code": -1145,"msg": "Invalid cancelRestrictions"}
- If the order did not pass the conditions for
cancelRestrictions
, the error will be:{"code": -2011,"msg": "Order was not canceled due to cancel restrictions."}
#
Cancel and replace order (TRADE)Request
Response:
If both cancel and placement succeed, you get the following response with
"status": 200
:
In
STOP_ON_FAILURE
mode, failed order cancellation prevents new order from being placed and returns the following response with"status": 400
:
If cancel-replace mode allows failure and one of the operations fails, you get a response with
"status": 409
, and the"data"
field detailing which operation succeeded, which failed, and why:
If both operations fail, response will have
"status": 400
:
Cancel an existing order and immediately place a new order instead of the canceled one.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
cancelReplaceMode | ENUM | YES | |
cancelOrderId | INT | YES | Cancel order by orderId |
cancelOrigClientOrderId | STRING | Cancel order by clientOrderId | |
cancelNewClientOrderId | STRING | NO | New ID for the canceled order. Automatically generated if not sent |
side | ENUM | YES | BUY or SELL |
type | ENUM | YES | |
timeInForce | ENUM | NO * | |
price | DECIMAL | NO * | |
quantity | DECIMAL | NO * | |
quoteOrderQty | DECIMAL | NO * | |
newClientOrderId | STRING | NO | Arbitrary unique ID among open orders. Automatically generated if not sent |
newOrderRespType | ENUM | NO | Select response format:
|
stopPrice | DECIMAL | NO * | |
trailingDelta | DECIMAL | NO * | See Trailing Stop FAQ |
icebergQty | DECIMAL | NO | |
strategyId | INT | NO | Arbitrary numeric value identifying the order within an order strategy. |
strategyType | INT | NO | Arbitrary numeric value identifying the order strategy. Values smaller than 1000000 are reserved and cannot be used. |
selfTradePreventionMode | ENUM | NO | The allowed enums is dependent on what is configured on the symbol. The possible supported values are |
cancelRestrictions | ENUM | NO | Supported values: ONLY_NEW - Cancel will succeed if the order status is NEW .ONLY_PARTIALLY_FILLED - Cancel will succeed if order status is PARTIALLY_FILLED . For more information please refer to Regarding cancelRestrictions . |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Similar to the order.place
request,
additional mandatory parameters (*) are determined by the new order type
.
Available cancelReplaceMode
options:
STOP_ON_FAILURE
– if cancellation request fails, new order placement will not be attemptedALLOW_FAILURE
– new order placement will be attempted even if the cancel request fails
Request | Response | ||
---|---|---|---|
cancelReplaceMode | cancelResult | newOrderResult | status |
STOP_ON_FAILURE | ✅ SUCCESS | ✅ SUCCESS | 200 |
❌ FAILURE | ➖ NOT_ATTEMPTED | 400 | |
✅ SUCCESS | ❌ FAILURE | 409 | |
ALLOW_FAILURE | ✅ SUCCESS | ✅ SUCCESS | 200 |
❌ FAILURE | ❌ FAILURE | 400 | |
❌ FAILURE | ✅ SUCCESS | 409 | |
✅ SUCCESS | ❌ FAILURE | 409 |
Notes:
If both
cancelOrderId
andcancelOrigClientOrderId
parameters are specified, onlycancelOrderId
is used andcancelOrigClientOrderId
is ignored.cancelNewClientOrderId
will replaceclientOrderId
of the canceled order, freeing it up for new orders.newClientOrderId
specifiesclientOrderId
value for the placed order.A new order with the same
clientOrderId
is accepted only when the previous one is filled or expired.The new order can reuse old
clientOrderId
of the canceled order.This cancel-replace operation is not transactional.
If one operation succeeds but the other one fails, the successful operation is still executed.
For example, in
STOP_ON_FAILURE
mode, if the new order placement fails, the old order is still canceled.Filters and order count limits are evaluated before cancellation and order placement occurs.
If new order placement is not attempted, your order count is still incremented.
Like
order.cancel
, if you cancel a leg of an OCO, the entire OCO is canceled.
Data Source: Matching Engine
Note: The payload sample does not show all fields that can appear. Please refer to Conditional fields in Order Responses.
#
Current open orders (USER_DATA)Request:
Response:
Query execution status of all open orders.
If you need to continuously monitor order status updates, please consider using WebSocket Streams:
userDataStream.start
requestexecutionReport
user data stream event
Status reports for open orders are identical to order.status
.
Note that some fields are optional and included only for orders that set them.
Open orders are always returned as a flat list.
If all symbols are requested, use the symbol
field to tell which symbol the orders belong to.
Weight(IP):
Adjusted based on the number of requested symbols:
Parameter | Weight |
---|---|
symbol | 3 |
none | 40 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | If omitted, open orders for all symbols are returned |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Data Source: Memory => Database
Note: The payload sample does not show all fields that can appear. Please refer to Conditional fields in Order Responses.
#
Cancel open orders (TRADE)Request:
Response:
Cancel all open orders on a symbol,
including OCO orders.
Cancellation reports for orders and OCOs have the same format as in order.cancel
.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Data Source: Matching Engine
Note: The payload sample does not show all fields that can appear. Please refer to Conditional fields in Order Responses.
#
Place new OCO (TRADE)Request
Response:
Send in a new one-cancels-the-other (OCO) pair:
LIMIT_MAKER
+ STOP_LOSS
/STOP_LOSS_LIMIT
orders (called legs),
where activation of one order immediately cancels the other.
Response format for orderReports
is selected using the newOrderRespType
parameter.
The following example is for RESULT
response type.
See order.place
for more examples.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
side | ENUM | YES | BUY or SELL |
price | DECIMAL | YES | Price for the limit order |
quantity | DECIMAL | YES | |
listClientOrderId | STRING | NO | Arbitrary unique ID among open OCOs. Automatically generated if not sent |
limitClientOrderId | STRING | NO | Arbitrary unique ID among open orders for the limit order. Automatically generated if not sent |
limitIcebergQty | DECIMAL | NO | |
limitStrategyId | INT | NO | Arbitrary numeric value identifying the limit order within an order strategy. |
limitStrategyType | INT | NO | Arbitrary numeric value identifying the limit order strategy. Values smaller than |
stopPrice | DECIMAL | YES * | Either stopPrice or trailingDelta , or both must be specified |
trailingDelta | INT | YES * | See Trailing Stop FAQ |
stopClientOrderId | STRING | NO | Arbitrary unique ID among open orders for the stop order. Automatically generated if not sent |
stopLimitPrice | DECIMAL | NO * | |
stopLimitTimeInForce | ENUM | NO * | See order.place for available options |
stopIcebergQty | DECIMAL | NO * | |
stopStrategyId | INT | NO | Arbitrary numeric value identifying the stop order within an order strategy. |
stopStrategyType | INT | NO | Arbitrary numeric value identifying the stop order strategy. Values smaller than |
newOrderRespType | ENUM | NO | Select response format: ACK , RESULT , FULL (default) |
selfTradePreventionMode | ENUM | NO | The allowed enums is dependent on what is configured on the symbol. The possible supported values are EXPIRE_TAKER , EXPIRE_MAKER , EXPIRE_BOTH , NONE . |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Notes:
listClientOrderId
parameter specifieslistClientOrderId
for the OCO pair.A new OCO with the same
listClientOrderId
is accepted only when the previous one is filled or completely expired.listClientOrderId
is distinct fromclientOrderId
of individual orders.limitClientOrderId
andstopClientOrderId
specifyclientOrderId
values for both legs of the OCO.A new order with the same
clientOrderId
is accepted only when the previous one is filled or expired.Price restrictions on the legs:
side | Price relation |
---|---|
BUY | price < market price < stopPrice |
SELL | price > market price > stopPrice |
Both legs have the same
quantity
.However, you can set different iceberg quantity for individual legs.
If
stopIcebergQty
is used,stopLimitTimeInForce
must beGTC
.trailingDelta
applies only to theSTOP_LOSS
/STOP_LOSS_LIMIT
leg of the OCO.OCO counts as 2 orders against the order rate limit.
Data Source: Matching Engine
#
Query OCO (USER_DATA)Request:
Response:
Check execution status of an OCO.
For execution status of individual orders, use order.status
.
Weight(IP): 2
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
origClientOrderId | STRING | YES | Query OCO by listClientOrderId |
orderListId | INT | Query OCO by orderListId | |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Notes:
origClientOrderId
refers tolistClientOrderId
of the OCO itself.If both
origClientOrderId
andorderListId
parameters are specified, onlyorigClientOrderId
is used andorderListId
is ignored.
Data Source: Database
#
Cancel OCO (TRADE)Request:
Response:
Cancel an active OCO.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderListId | INT | YES | Cancel OCO by orderListId |
listClientOrderId | STRING | Cancel OCO by listClientId | |
newClientOrderId | STRING | NO | New ID for the canceled OCO. Automatically generated if not sent |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Notes:
If both
orderListId
andlistClientOrderId
parameters are specified, onlyorderListId
is used andlistClientOrderId
is ignored.Canceling an individual leg with
order.cancel
will cancel the entire OCO as well.
Data Source: Matching Engine
#
Current open OCOs (USER_DATA)Request:
Response:
Query execution status of all open OCOs.
If you need to continuously monitor order status updates, please consider using WebSocket Streams:
userDataStream.start
requestexecutionReport
user data stream event
Weight(IP): 3
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Data Source: Database
Account requests
#
Account information (USER_DATA)Request:
Response:
Query information about your account.
Weight(IP): 10
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Data Source: Memory => Database
#
Account order rate limits (USER_DATA)Request:
Response:
Query your current order rate limit.
Weight(IP): 20
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Data Source: Memory
#
Account order history (USER_DATA)Request:
Response:
Query information about all your orders – active, canceled, filled – filtered by time range.
Status reports for orders are identical to order.status
.
Note that some fields are optional and included only for orders that set them.
Weight(IP): 10
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | INT | NO | Order ID to begin at |
startTime | INT | NO | |
endTime | INT | NO | |
limit | INT | NO | Default 500; max 1000 |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Notes:
If
startTime
and/orendTime
are specified,orderId
is ignored.Orders are filtered by
time
of the last execution status update.If
orderId
is specified, return orders with order ID >=orderId
.If no condition is specified, the most recent orders are returned.
For some historical orders the
cummulativeQuoteQty
response field may be negative, meaning the data is not available at this time.
Data Source: Database
#
Account OCO history (USER_DATA)Request:
Query information about all your OCOs, filtered by time range.
Status reports for OCOs are identical to orderList.status
.
Response:
Weight(IP): 10
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
fromId | INT | NO | Order list ID to begin at |
startTime | INT | NO | |
endTime | INT | NO | |
limit | INT | NO | Default 500; max 1000 |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Notes:
If
startTime
and/orendTime
are specified,fromId
is ignored.OCOs are filtered by
transactionTime
of the last OCO execution status update.If
fromId
is specified, return OCOs with order list ID >=fromId
.If no condition is specified, the most recent OCOs are returned.
Data Source: Database
#
Account trade history (USER_DATA)Request:
Response:
Query information about all your trades, filtered by time range.
Weight(IP): 10
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | INT | NO | |
startTime | INT | NO | |
endTime | INT | NO | |
fromId | INT | NO | First trade ID to query |
limit | INT | NO | Default 500; max 1000 |
apiKey | STRING | YES | |
recvWindow | INT | NO | The value cannot be greater than 60000 |
signature | STRING | YES | |
timestamp | INT | YES |
Notes:
If
fromId
is specified, return trades with trade ID >=fromId
.If
startTime
and/orendTime
are specified, trades are filtered by execution time (time
).fromId
cannot be used together withstartTime
andendTime
.If
orderId
is specified, only trades related to that order are returned.startTime
andendTime
cannot be used together withorderId
.If no condition is specified, the most recent trades are returned.
Data Source: Memory => Database
#
Account prevented matches (USER_DATA)Request:
Response:
Displays the list of orders that were expired because of STP trigger.
These are the combinations supported:
symbol
+preventedMatchId
symbol
+orderId
symbol
+orderId
+fromPreventedMatchId
(limit
will default to 500)symbol
+orderId
+fromPreventedMatchId
+limit
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
preventedMatchId | LONG | NO | |
orderId | LONG | NO | |
fromPreventedMatchId | LONG | NO | |
limit | INT | NO | Default: 500 ; Max: 1000 |
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Weight (IP)
Case | Weight |
---|---|
If symbol is invalid | 1 |
Querying by preventedMatchId | 1 |
Querying by orderId | 10 |
Data Source:
Database
User Data Stream requests
The following requests manage User Data Stream subscriptions.
Note: You will need to establish a separate WebSocket connection to listen to user data streams.
#
Start user data stream (USER_STREAM)Request:
Response:
Start a new user data stream.
The response will output a listen key that can be subscribed through on the Websocket stream afterwards.
Note: the stream will close in 60 minutes
unless userDataStream.ping
requests are sent regularly.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
apiKey | STRING | YES |
Data Source: Memory
#
Ping user data stream (USER_STREAM)Request:
Response:
Ping a user data stream to keep it alive.
User data streams close automatically after 60 minutes,
even if you're listening to them on WebSocket Streams.
In order to keep the stream open, you have to regularly send pings using the userDataStream.ping
request.
It is recommended to send a ping once every 30 minutes.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
listenKey | STRING | YES | |
apiKey | STRING | YES |
Data Source: Memory
#
Stop user data stream (USER_STREAM)Request:
Response:
Explicitly stop and close the user data stream.
Weight(IP): 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
listenKey | STRING | YES | |
apiKey | STRING | YES |
Data Source: Memory