Introduction
Welcome to the Binance.US API Documentation!
Our REST APIs offer access to:
- Exchange data
- Market trade and price data
- User account data
- Trade order management
- Wallet management
Our WebSocket Steams offer access to:
- Market data streams
- User data streams
General API Information
The base endpoint is: https://api.binance.us
All endpoints return either a JSON object or array.
Data is returned in ascending order. oldest first, newest last.
All time and including for staking, referrals and airdrops etc fields are in milliseconds.
Making Requests
- 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 is sent in both the
query string
andrequest body
, thequery string
parameter will be used.
Data Sources
- The API system is asynchronous, so some delay in the response is normal.
- 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 have 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 one 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.
API Terminology
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
.
Enum Definitions
Symbol status (status):
- PRE_TRADING
- TRADING
- POST_TRADING
- END_OF_DAY
- HALT
- AUCTION_MATCH
- BREAK
Symbol type:
- SPOT
Order status (status):
Status | Description |
---|---|
NEW |
The order has been accepted by the engine. |
PARTIALLY_FILLED |
Part of the order has been filled. |
FILLED |
The order has been completed. |
CANCELED |
The order has been canceled by the user. |
PENDING_CANCEL |
This is 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 or 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 cancelation) |
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 is thus no longer active. |
REJECT |
The List Status is responding to a failed action either during order placement or the order was canceled. |
ContingencyType
- OCO
Order types (orderTypes, type):
- LIMIT
- MARKET
- STOP_LOSS
- STOP_LOSS_LIMIT
- TAKE_PROFIT
- TAKE_PROFIT_LIMIT
- LIMIT_MAKER
Order side (side):
- BUY
- SELL
Time in force (timeInForce):
Status | Description |
---|---|
GTC |
"Good Till 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)
Example - REQUEST_WEIGHT
{
"rateLimitType": "REQUEST_WEIGHT",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 1200
}
Example - ORDERS
{
"rateLimitType": "ORDERS",
"interval": "SECOND",
"intervalNum": 1,
"limit": 10
}
Example - RAW_REQUESTS
{
"rateLimitType": "RAW_REQUESTS",
"interval": "MINUTE",
"intervalNum": 5,
"limit": 5000
}
- REQUEST_WEIGHT
- ORDERS
- RAW_REQUESTS
Rate limit intervals (interval)
- SECOND
- MINUTE
- DAY
Authentication
Get API Keys
Creating a private API key provides access to markets and real-time trading services on Binance.US via a third-party site or application.
To create an API key, log in to Binance.US with your account details and go to Settings > API management.
Authentication Types
- 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. |
Authentication Timing
if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
// process request
} else {
// reject request
}
- A
SIGNED
endpoint also requires a parameter andtimestamp
to be sent, which should be the millisecond timestamp of when the request was created and sent. - An additional parameter,
recvWindow
, may be sent to specify the number of milliseconds after thetimestamp
request is valid for. IfrecvWindow
is not sent, it defaults to 5,000. - he exact timing authentication logic can be viewed in the code sample on the right panel (or below on a mobile device).
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.
Signature Authentication
Example 1 As a request body
# request body
# symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559
# Get HMAC SHA256 signature
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 result
# c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71
# Request signed endpoints, /api/v3/order as an example
curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.us/api/v3/order' -d 'symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'
import urllib.parse
import hashlib
import hmac
import base64
import requests
import calendar
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
payload={
**data,
"signature": signature,
}
req = requests.post((api_url + uri_path), headers=headers, data=payload)
return req.text
api_key = "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A"
secret_key = "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
uri_path = "/api/v3/order"
data = {
"symbol": "BTCUSDT",
"side": "BUY",
"type": "LIMIT",
"timeInForce": "GTC",
"quantity": 1,
"price": 0.1,
"timestamp": int(round(time.time() * 1000))
}
binanceus_request(uri_path, data, api_key, secret_key)
Example 2 As a query string
# query string
# symbol=BTCUSDT×tamp=1499827319559
# Get HMAC SHA256 signature
echo -n "symbol=BTCUSDT×tamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
# stdin result
# c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71
# Request signed endpoints, /api/v3/order as an example
curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X GET 'https://api.binance.us/api/v3/openOrders?symbol=BTCUSDT×tamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'
import urllib.parse
import hashlib
import hmac
import base64
import requests
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={**data, "signature": signature}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key = "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A"
secret_key = "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
uri_path = "/api/v3/openOrders"
data = {
"symbol": "BTCUSDT",
"timestamp": 1499827319559
}
get_open_order_result = binanceus_request(uri_path, data, api_key, secret_key)
Example 3 Mixed query string and request body
# query string
# symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC
# request body
# quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559
# Get HMAC SHA256 signature
shell echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000×tamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
# stdin result
# 0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77
# Request signed endpoints, /api/v3/order as an example
curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.us/api/v3/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559&signature=0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77'
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
.
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 |
Error Responses
Error Responses
{
"code":-1121,
"msg":"Invalid symbol."
}
Errors consist of two parts: an error code and a message. Codes are universal, but messages can vary. Here is the error JSON payload:
HTTP Errors
- 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.
Server/Network Errors
- 1000 UNKNOWN
- An unknown error occurred while processing the request.
- 1001 DISCONNECTED
- Internal error; unable to process your request. Please try again.
- 1002 UNAUTHORIZED
- You are not authorized to execute this request.
- 1003 TOO_MANY_REQUESTS
- Too many requests queued.
- Too many requests; please use the WebSocket for live updates.
- Too many requests; current limit is %s requests per minute. Please use the WebSocket for live updates to avoid polling the API.
- Way too much request weight used; IP banned until %s. Please use the WebSocket for live updates to avoid bans.
- 1006 UNEXPECTED_RESP
- An unexpected response was received from the message bus. Execution status is unknown.
- 1007 TIMEOUT
- Timeout waiting for a response from the backend server. Send status unknown; execution status unknown.
- 1014 UNKNOWN_ORDER_COMPOSITION
- Unsupported order combination.
- 1015 TOO_MANY_ORDERS
- Too many new orders.
- Too many new orders; current limit is %s orders per %s.
- 1016 SERVICE_SHUTTING_DOWN
- This service is no longer available.
- 1020 UNSUPPORTED_OPERATION
- This operation is not supported.
- 1021 INVALID_TIMESTAMP
- Timestamp for this request is outside of the recvWindow.
- Timestamp for this request was 1000ms ahead of the server's time.
- 1022 INVALID_SIGNATURE
- Signature for this request is not valid.
Request Errors
- 1100 ILLEGAL_CHARS
- Illegal characters found in a parameter.
- Illegal characters found in parameter '%s'; the legal range is '%s'.
- 1101 TOO_MANY_PARAMETERS
- Too many parameters sent for this endpoint.
- Too many parameters; expected '%s' and received '%s'.
- Duplicate values for a parameter detected.
- 1102 MANDATORY_PARAM_EMPTY_OR_MALFORMED
- A mandatory parameter was not sent, was empty/null, or malformed.
- Mandatory parameter '%s' was not sent, was empty/null, or malformed.
- Param '%s' or '%s' must be sent, but both were empty/null!
- 1103 UNKNOWN_PARAM
- An unknown parameter was sent.
- 1104 UNREAD_PARAMETERS
- Not all sent parameters were read.
- Not all sent parameters were read; read '%s' parameter(s) but was sent '%s'.
- 1105 PARAM_EMPTY
- A parameter was empty.
- Parameter '%s' was empty.
- 1106 PARAM_NOT_REQUIRED
- A parameter was sent when not required.
- Parameter '%s' sent when not required.
- 1111 BAD_PRECISION
- Precision is over the maximum defined for this asset.
- 1112 NO_DEPTH
- No orders on the book for this symbol.
- 1114 TIF_NOT_REQUIRED
- TimeInForce parameter sent when not required.
- 1115 INVALID_TIF
- Invalid timeInForce.
- 1116 INVALID_ORDER_TYPE
- Invalid orderType.
- 1117 INVALID_SIDE
- Invalid side.
- 1118 EMPTY_NEW_CL_ORD_ID
- New client order ID was empty.
- 1119 EMPTY_ORG_CL_ORD_ID
- Original client order ID was empty.
- 1120 BAD_INTERVAL
- Invalid interval.
- 1121 BAD_SYMBOL
- Invalid symbol.
- 1125 INVALID_LISTEN_KEY
- This listenKey does not exist.
- 1127 MORE_THAN_XX_HOURS
- Lookup interval is too big.
- More than %s hours between startTime and endTime.
- 1128 OPTIONAL_PARAMS_BAD_COMBO
- Combination of optional parameters invalid.
- 1130 INVALID_PARAMETER
- Invalid data sent for a parameter.
- Data sent for parameter '%s' is not valid.
- 2010 NEW_ORDER_REJECTED
- NEW_ORDER_REJECTED
- 2011 CANCEL_REJECTED
- CANCEL_REJECTED
- 2013 NO_SUCH_ORDER
- Order does not exist.
- 2014 BAD_API_KEY_FMT
- API-key format invalid.
- 2015 REJECTED_MBX_KEY
- Invalid API-key, IP, or permissions for action.
- 2016 NO_TRADING_WINDOW
- No trading window could be found for the symbol. Try ticker/24hrs instead.
Matching Engine Errors
Messages for -1010 ERROR_MSG_RECEIVED, -2010 NEW_ORDER_REJECTED, and -2011 CANCEL_REJECTED
This code is sent when an error has been returned by the matching engine. The following messages will indicate the specific error:
Error message | Description |
---|---|
"Unknown order sent." | The order (by either orderId , clOrdId , origClOrdId ) could not be found |
"Duplicate order sent." | The clOrdId is already in use |
"Market is closed." | The symbol is not trading |
"Account has insufficient balance for requested action." | Not enough funds to complete the action |
"Market orders are not supported for this symbol." | MARKET is not enabled on the symbol |
"Iceberg orders are not supported for this symbol." | icebergQty is not enabled on the symbol |
"Stop loss orders are not supported for this symbol." | STOP_LOSS is not enabled on the symbol |
"Stop loss limit orders are not supported for this symbol." | STOP_LOSS_LIMIT is not enabled on the symbol |
"Take profit orders are not supported for this symbol." | TAKE_PROFIT is not enabled on the symbol |
"Take profit limit orders are not supported for this symbol." | TAKE_PROFIT_LIMIT is not enabled on the symbol |
"Price * QTY is zero or less." | Price * quantity is too low |
"IcebergQty exceeds QTY." | icebergQty must be less than the order quantity |
"This action is disabled on this account." | Contact customer support; some actions have been disabled on the account |
"Unsupported order combination" | The orderType , timeInForce , stopPrice , and/or icebergQty combination isn't allowed |
"Order would trigger immediately." | The order's stop price is not valid compared to the last traded price |
"Cancel order is invalid. Check origClOrdId and orderId." | No origClOrdId or orderId was sent in |
"Order would immediately match and take." | LIMIT_MAKER order type would immediately match and trade, and not be a pure maker order |
"The relationship of the prices for the orders is not correct." | The prices set in the OCO are breaking the Price rules. The rules are: SELL Orders : Limit Price > Last Price > Stop Price BUY Orders : Limit Price < Last Price < Stop Price |
"OCO orders are not supported for this symbol" | OCO is not enabled on the symbol |
"Quote order qty market orders are not support for this symbol." | MARKET orders using the parameter quoteOrderQty are not enabled on this symbol |
Filter Failure Errors
Error message | Description |
---|---|
"Filter failure: PRICE_FILTER" | Price is too high, too low, and/or not following the tick size rule for the symbol |
"Filter failure: PERCENT_PRICE" | Price is X% too high or X% too low from the average weighted price over the last Y minutes |
"Filter failure: LOT_SIZE" | Quantity is too high, too low, and/or not following the step size rule for the symbol |
"Filter failure: MIN_NOTIONAL" | Price * quantity is too low to be a valid order for the symbol |
"Filter failure: ICEBERG_PARTS" | ICEBERG order would break into too many parts; icebergQty is too small |
"Filter failure: MARKET_LOT_SIZE" | MARKET order's quantity is too high, too low, and/or not following the step size rule for the symbol |
"Filter failure: MAX_NUM_ORDERS" | Account has too many open orders on the symbol |
"Filter failure: MAX_ALGO_ORDERS" | Account has too many open stop loss and/or take profit orders on the symbol |
"Filter failure: MAX_NUM_ICEBERG_ORDERS" | Account has too many open iceberg orders on the symbol |
"Filter failure: EXCHANGE_MAX_NUM_ORDERS" | Account has too many open orders on the exchange |
"Filter failure: EXCHANGE_MAX_ALGO_ORDERS" | Account has too many open stop loss and/or take profit orders on the exchange |
Rate Limits
- The following
intervalLetter
values for headers:- SECOND = S
- MINUTE = M
- HOUR = H
- DAY = D
- The
/api/v3/exchangeInfo
rateLimits
array contains objects related to the exchange'sRAW_REQUEST
,REQUEST_WEIGHT
, andORDER
rate limits. These are further defined in theENUM definitions
section underRate limiters (rateLimitType)
. - A 429 will be returned when either rate limit is violated.
- Each route has a
weight
that determines the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavierweight
.
IP Limits
- Every request will contain an
X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)
headers which has the current used weight for the IP for all request rate limiters defined. - Every successful order will contain a
X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)
header which has the current order count for the IP for all order rate limiters defined. Rejected/unsuccessful orders are not guaranteed to haveX-MBX-ORDER-COUNT-**
headers in the response. - 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 418, to prevent a ban, or, in the case of a 429, until the ban is over. - The limits on the API are based on the IPs, not the API keys.
Order Rate Limits
- 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. - 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.
Withdrawal Rate Limits
- The
/wapi/v3
rateLimits
array contains objects related to the exchange'sREQUESTS
andORDER
rate limits. - A 429 will be returned when either rather limit is violated.
- Each route has a
weight
that determines the number of requests each endpoint counts for. Heavier endpoints and endpoints that operate on multiple symbols will have a heavierweight
. - When a 429 recieved, it's your obligation as an API to back off and not spam the API.
- Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban (http status 418).
- IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.
Changelog
3/3/2022 - Updated five wallet endpoints related to crypto withdrawals and deposits, added a new trade order endpoint for querying rate limit usage, removed convert dust to BNB endpoints, and improved content readability and descriptions.
1/21/2022 - Added new OTC trade endpoints, which support large buy and sell order quotes, placements, and queries, as well as crypto-to-crypto conversion (e.g. KSHIB/SHIB).
1/22/2021 - Published new API documentation interface and added Python code samples.
REST API
General Data Endpoints
System Information
Test Connectivity
Example
curl 'https://api.binance.us/api/v3/ping'
import requests
resp = requests.get('https://api.binance.us/api/v3/ping')
print(resp.json())
Response
{}
GET /api/v3/ping
Use this endpoint to to the REST API.
Weight: 1
Parameters: NONE
Data Source: Memory
Get Server Time
Example
curl 'https://api.binance.us/api/v3/time'
import requests
resp = requests.get('https://api.binance.us/api/v3/time')
print(resp.json())
Response
{
"serverTime": 1499827319559
}
GET /api/v3/time
Use this endpoint to to the REST API and get the current server time.
Weight: 1
Parameters: NONE
Data Source: Memory
Get System Status
Example
curl 'https://api.binance.us/wapi/v3/systemStatus.html'
import requests
resp = requests.get('https://api.binance.us/wapi/v3/systemStatus.html')
print(resp.json())
Response
{
"status": 0, // 0: normal,1:system maintenance
"msg": "normal" // normal or system maintenance
}
GET /wapi/v3/systemStatus.html
Use this endpoint to fetch the system status.
Exchange Information
Get Exchange Information
Example
curl 'https://api.binance.us/api/v3/exchangeInfo'
import requests
resp = requests.get('https://api.binance.us/api/v3/exchangeInfo')
print(resp.json())
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,
"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,
"isSpotTradingAllowed": true,
"isMarginTradingAllowed": false,
"filters": [
//These are defined in the Filters section.
//All filters are optional
]
}
],
"permissions": [
"SPOT"
]
}
GET /api/v3/exchangeInfo
Use this endpoint to get the current exchange trading rules and trading pair information.
Weight: 10
Parameters:
There are three 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=BNBBTC,BTCUSDT" |
symbols | curl -g GET 'https://api.binance.com/api/v3/exchangeInfo?symbols=["BTCUSDT","BNBBTC"]' |
Data Source: Memory
Market Data Endpoints
Trade Data
Get Recent Trades
Example
curl -X "GET" "https://api.binance.us/api/v3/trades?symbol=LTCBTC"
import requests
resp = requests.get('https://api.binance.us/api/v3/trades?symbol=LTCBTC')
print(resp.json())
Response
[
{
"id": 981492,
"price": "0.00380100",
"qty": "0.22000000",
"quoteQty": "0.00083622",
"time": 1637128016269,
"isBuyerMaker": false,
"isBestMatch": true
},
]
GET /api/v3/trades
Use this endpoint to get the recent trades. Please note the maximum limit is 1,000 trades.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 500; max 1000. |
Data Source: Memory
Get Historical Trades
Example
curl -X "GET" "https://api.binance.us/api/v3/historicalTrades?symbol=<symbol>" \
-H "X-MBX-APIKEY: <your_api_key>"
import requests
headers = {}
headers['X-MBX-APIKEY'] = <your_api_key>
resp = requests.get('https://api.binance.us/api/v3/historicalTrades?symbol=<symbol>', headers=headers)
print(resp.json())
Response
[
{
"id": 17,
"price": "0.06800000",
"qty": "1.00000000",
"quoteQty": "0.06800000",
"time": 1635489737109,
"isBuyerMaker": false,
"isBestMatch": true
}
]
GET /api/v3/historicalTrades
Use this endpoint to get older trades. Please note the maximum limit is 1,000 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
Get Aggregate Trades
Example
curl -X "GET" "https://api.binance.us/api/v3/aggTrades?symbol=LTCBTC"
import requests
resp = requests.get('https://api.binance.us/api/v3/aggTrades?symbol=LTCBTC')
print(resp.json())
Response
[
{
"a": 874844,
"p": "0.00379700",
"q": "0.05000000",
"f": 981493,
"l": 981493,
"T": 1637128220041,
"m": true,
"M": true
}
]
GET /api/v3/aggTrades
Use this endpoint to get compressed, aggregate trades. Trades that fill at the time, from the same order, with the same price will have the quantity aggregated. Please note the maximum limit is 1,000 trades.
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, the 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
Get Order Book Depth
Example
curl -X "GET" "https://api.binance.us/api/v3/depth?symbol=LTCBTC"
import requests
resp = requests.get('https://api.binance.us/api/v3/depth?symbol=LTCBTC')
print(resp.json())
Response
{
"lastUpdateId": 1027024,
"bids": [
[
"0.00379200",
"31.26000000"
]
],
"asks": [
[
"0.00380100",
"32.37000000"
]
]
}
GET /api/v3/depth
Use this endpoint to get the order book depth. Please note the limits in the table below.
Weight: Adjusted based on the limit:
Limit | Weight |
---|---|
5, 10, 20, 50, 100 | 1 |
500 | 5 |
1000 | 10 |
5000 | 50 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 100; max 5000. Valid limits:[5, 10, 20, 50, 100, 500, 1000, 5000] |
Data Source: Memory
Get Candlestick Data
Example
curl -X "GET" "https://api.binance.us/api/v3/klines?symbol=LTCBTC&interval=1m"
import requests
resp = requests.get('https://api.binance.us/api/v3/klines?symbol=LTCBTC&interval=1m')
print(resp.json())
Response
[
[
1499040000000, // Open time
"0.00386200", // Open
"0.00386200", // High
"0.00386200", // Low
"0.00386200", // Close
"0.47000000", // Volume
1499644799999, // Close time
"0.00181514", // Quote asset volume
1, // Number of trades
"0.47000000", // Taker buy base asset volume
"0.00181514", // Taker buy quote asset volume
"0" // Ignore.
]
]
GET /api/v3/klines
Use this endpoint to get Kline/candlestick bars for a token symbol. Klines are uniquely identified by their open time. Please note the maximum limit is 1,000 bars.
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
Price Data
Get Live Ticker Price
Example
# Example A, symbol param provided
curl -X "GET" "https://api.binance.us/api/v3/ticker/price?symbol=LTCBTC"
# Example B, no symbol provided
curl -X "GET" "https://api.binance.us/api/v3/ticker/price"
# Example A, symbol param provided
import requests
resp = requests.get('https://api.binance.us/api/v3/ticker/price?symbol=LTCBTC')
print(resp.json())
# Example B, no symbol provided
import requests
resp = requests.get('https://api.binance.us/api/v3/ticker/price')
print(resp.json())
Response A
{
"symbol": "LTCBTC",
"price": "0.00378800"
}
Response B
[
{
"symbol": "BTCUSD",
"price": "59705.0700"
},
{
"symbol": "ETHUSD",
"price": "4178.7200"
}
]
GET /api/v3/ticker/price
Use this endpoint to get the latest price for a token symbol or symbols.
Weight: 1 for a single symbol; 2 when the symbol parameter is omitted
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO |
- If the symbol is not sent, prices for all symbols will be returned in an array.
Data Source: Memory
Get Average Price
Example
curl -X "GET" "https://api.binance.us/api/v3/avgPrice?symbol=LTCBTC"
import requests
resp = requests.get('https://api.binance.us/api/v3/avgPrice?symbol=LTCBTC')
print(resp.json())
Response
{
"mins": 5,
"price": "0.00378906"
}
GET /api/v3/avgPrice
Use this endpoint to get the current average price for a symbol.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES |
Data Source: Memory
Get Best Order Book Price
Example
# Example A, symbol param provided
curl -X "GET" "https://api.binance.us/api/v3/ticker/bookTicker?symbol=LTCBTC"
# Example B, no symbol provided
curl -X "GET" "https://api.binance.us/api/v3/ticker/bookTicker"
# Example A, symbol param provided
import requests
resp = requests.get('https://api.binance.us/api/v3/ticker/bookTicker?symbol=LTCBTC')
print(resp.json())
# Example B, no symbol provided
import requests
resp = requests.get('https://api.binance.us/api/v3/ticker/bookTicker')
print(resp.json())
Response A
{
"symbol": "LTCBTC",
"bidPrice": "0.00378600",
"bidQty": "3.50000000",
"askPrice": "0.00379100",
"askQty": "26.69000000"
}
Response B
[
{
"symbol": "BTCUSD",
"bidPrice": "59614.7400",
"bidQty": "0.07100000",
"askPrice": "59630.2500",
"askQty": "0.07100000"
},
{
"symbol": "ETHUSD",
"bidPrice": "4171.2800",
"bidQty": "0.72000000",
"askPrice": "4172.3700",
"askQty": "5.40000000"
},
]
GET /api/v3/ticker/bookTicker
Use this endpoint to get the best price/qty on the order book for a token symbol or symbols.
Weight: 1 for a single symbol; 2 when the symbol parameter is omitted
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO |
- If the symbol is not sent, bookTickers for all symbols will be returned in an array.
Data Source: Memory
Get 24h Price Change Statistics
Example
# Example A, symbol param provided
curl -X "GET" "https://api.binance.us/api/v3/ticker/24hr?symbol=BNBBTC"
# Example B, no symbol provided
curl -X "GET" "https://api.binance.us/api/v3/ticker/24hr"
# Example A, symbol param provided
import requests
resp = requests.get('https://api.binance.us/api/v3/ticker/24hr?symbol=BNBBTC')
print(resp.json())
# Example B, no symbol provided
import requests
resp = requests.get('https://api.binance.us/api/v3/ticker/24hr')
print(resp.json())
Response A
{
"symbol": "BNBBTC",
"priceChange": "-0.00046450",
"priceChangePercent": "-4.659",
"weightedAvgPrice": "0.00978390",
"prevClosePrice": "0.00997050",
"lastPrice": "0.00950520",
"lastQty": "0.09000000",
"bidPrice": "0.00950060",
"bidQty": "0.25000000",
"askPrice": "0.00950520",
"askQty": "13.74000000",
"openPrice": "0.00996970",
"highPrice": "0.01012120",
"lowPrice": "0.00950500",
"volume": "7936.25000000",
"quoteVolume": "77.64747556",
"openTime": 1637042984994,
"closeTime": 1637129384994,
"firstId": 1851686,
"lastId": 1856703,
"count": 5018
}
Response B
[
{
"symbol": "BTCUSD",
"priceChange": "-1267.1100",
"priceChangePercent": "-2.083",
"weightedAvgPrice": "60099.2142",
"prevClosePrice": "60842.0600",
"lastPrice": "59566.4300",
"lastQty": "0.03454900",
"bidPrice": "59525.6600",
"bidQty": "0.07100000",
"askPrice": "59543.0900",
"askQty": "0.42600000",
"openPrice": "60833.5400",
"highPrice": "61406.0700",
"lowPrice": "58585.4900",
"volume": "1675.88065900",
"quoteVolume": "100719110.6761",
"openTime": 1637043019764,
"closeTime": 1637129419764,
"firstId": 25821891,
"lastId": 25894571,
"count": 72681
},
{
"symbol": "ETHUSD",
"priceChange": "-160.0800",
"priceChangePercent": "-3.701",
"weightedAvgPrice": "4233.5077",
"prevClosePrice": "4326.0600",
"lastPrice": "4165.8000",
"lastQty": "2.42310000",
"bidPrice": "4165.2100",
"bidQty": "0.00484000",
"askPrice": "4165.4100",
"askQty": "6.12000000",
"openPrice": "4325.8800",
"highPrice": "4349.1400",
"lowPrice": "4065.6400",
"volume": "20975.27292000",
"quoteVolume": "88798979.5292",
"openTime": 1637043020441,
"closeTime": 1637129420441,
"firstId": 23606820,
"lastId": 23673128,
"count": 66309
},
]
GET /api/v3/ticker/24hr
Use this endpoint to get 24-hour rolling window price change statistics. Do not access this without a token symbol as this would return all pair data.
Weight: 1 for a single symbol; 40 when the symbol parameter is omitted
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO |
- If the symbol is not sent, tickers for all symbols will be returned in an array.
Data Source: Memory
User Data Endpoints
User Account Data
Get User Account Information
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/api/v3/account?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/api/v3/account"
data = {
"timestamp": int(round(time.time() * 1000)),
}
get_account_result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, get_account_result))
Response
{
"makerCommission": 15,
"takerCommission": 15,
"buyerCommission": 0,
"sellerCommission": 0,
"canTrade": true,
"canWithdraw": true,
"canDeposit": true,
"updateTime": 123456789,
"accountType": "SPOT",
"balances": [
{
"asset": "BTC",
"free": "0.03132408",
"locked": "0.01000000"
},
],
"permissions": [
"SPOT"
]
}
GET /api/v3/account (HMAC SHA256)
Use this endpoint to 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: Database
Get User Account Status
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/wapi/v3/accountStatus.html?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/wapi/v3/accountStatus.html"
data = {
"timestamp": int(round(time.time() * 1000)),
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
// Response A
{
"msg": "Order failed:Low Order fill rate! Will be reactivated after 5 minutes.",
"success": true,
"objs": [
"5"
]
}
// Response B
{
"msg":"Normal",
"success":true
}
GET /wapi/v3/accountStatus.html
Use this endpoint to fetch account status detail.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Get User API Trading Status
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/wapi/v3/apiTradingStatus.html?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/wapi/v3/apiTradingStatus.html"
data = {
"timestamp": int(round(time.time() * 1000)),
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
{
"success": true, // Query result
"status": { // API trading status detail
"isLocked": false, // API trading function is locked or not
"plannedRecoverTime": 0, // If API trading function is locked, this is the planned recover time
"triggerCondition": {
"GCR": 150, // Number of GTC orders
"IFER": 150, // Number of FOK/IOC orders
"UFR": 300 // Number of orders
},
"indicators": { // The indicators updated every 30 seconds
"BTCUSDT": [ // The symbol
{
"i": "UFR", // Unfilled Ratio (UFR)
"c": 20, // Count of all orders
"v": 0.05, // Current UFR value
"t": 0.995 // Trigger UFR value
},
{
"i": "IFER", // IOC/FOK Expiration Ratio (IFER)
"c": 20, // Count of FOK/IOC orders
"v": 0.99, // Current IFER value
"t": 0.99 // Trigger IFER value
},
{
"i": "GCR", // GTC Cancellation Ratio (GCR)
"c": 20, // Count of GTC orders
"v": 0.99, // Current GCR value
"t": 0.99 // Trigger GCR value
}
],
"ETHUSDT": [
{
"i": "UFR",
"c": 20,
"v": 0.05,
"t": 0.995
},
{
"i": "IFER",
"c": 20,
"v": 0.99,
"t": 0.99
},
{
"i": "GCR",
"c": 20,
"v": 0.99,
"t": 0.99
}
]
},
"updateTime": 1547630471725 // The query result return time
}
}
GET /wapi/v3/apiTradingStatus.html
Use this endpoint to fetch account API trading status details.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Get User Maker/Taker Rates
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/wapi/v3/tradeFee.html?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/wapi/v3/tradeFee.html"
data = {
"timestamp": int(round(time.time() * 1000)),
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
{
"tradeFee": [{
"symbol": "ADABNB",
"maker": 0.9000,
"taker": 1.0000
}, {
"symbol": "BNBBTC",
"maker": 0.3000,
"taker": 0.3000
}],
"success": true
}
GET /wapi/v3/tradeFee.html (HMAC SHA256)
Use this endpoint to fetch trading fees.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | |
timestamp | LONG | YES | |
symbol | STRING | NO |
Get Asset Distribution History
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/sapi/v1/asset/assetDividend?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/sapi/v1/asset/assetDividend"
data = {
"timestamp": int(round(time.time() * 1000)),
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
{
"rows":[
{
"amount":"10.00000000",
"asset":"BHFT",
"divTime":1563189166000,
"enInfo":"BHFT distribution",
"tranId":2968885920
},
{
"amount":"10.00000000",
"asset":"BHFT",
"divTime":1563189165000,
"enInfo":"BHFT distribution",
"tranId":2968885920
}
],
"total":2
}
GET /sapi/v1/asset/assetDividend (HMAC SHA256)
Use this endpoint to query asset distribution records, including for staking, referrals and airdrops etc.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
asset | STRING | NO | |
startTime | LONG | NO | |
endTime | LONG | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Sub-account Data
Get Sub-account Information
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/wapi/v3/sub-account/list.html?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/wapi/v3/sub-account/list.html"
data = {
"timestamp": int(round(time.time() * 1000)),
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
{
"success":true,
"subAccounts":[
{
"email":"123@test.com",
"status":"enabled",
"activated":true,
"mobile":"91605290",
"gAuth":true,
"createTime":1544433328000
},
{
"email":"321@test.com",
"status":"disabled",
"activated":true,
"mobile":"22501238",
"gAuth":true,
"createTime":1544433328000
}
]
}
GET /wapi/v3/sub-account/list.html (HMAC SHA256)
Use this endpoint to fetch your sub-account list.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
STRING | NO | Sub-account email | |
status | STRING | NO | Sub-account status: enabled or disabled |
page | INT | NO | Default value: 1 |
limit | INT | NO | Default value: 500 |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Get Sub-account Transfer History
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
email=<your_email>
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "email=$email×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/wapi/v3/sub-account/transfer/history.html?email=$email×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
email=<your_email>
uri_path = "/wapi/v3/sub-account/transfer/history.html"
data = {
"timestamp": int(round(time.time() * 1000)),
"email": email
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
{
"success":true,
"transfers":[
{
"from":"aaa@test.com",
"to":"bbb@test.com",
"asset":"BTC",
"qty":"1",
"time":1544433328000
},
{
"from":"bbb@test.com",
"to":"ccc@test.com",
"asset":"ETH",
"qty":"2",
"time":1544433328000
}
]
}
GET /wapi/v3/sub-account/transfer/history.html (HMAC SHA256)
Use this endpoint to fetch sub-account asset transfer history.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
STRING | YES | Sub-account email | |
startTime | LONG | NO | Default return the history with in 100 days |
endTime | LONG | NO | Default return the history with in 100 days |
page | INT | NO | Default value: 1 |
limit | INT | NO | Default value: 500 |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Execute Sub-account Transfer
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
fromEmail=<your_from_email>
toEmail=<your_to_email>
asset=<asset>
amount=<amount>
api_url="https://api.binance.us"
signature=`echo -n "fromEmail=$fromEmail&toEmail=$toEmail&asset=$asset&amount=$amount×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "POST" "$api_url/wapi/v3/sub-account/transfer.html" \
-H "X-MBX-APIKEY: $api_key" \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
--data-urlencode "fromEmail=$fromEmail&toEmail=$toEmail×tamp=$timestamp&signature=$signature"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
payload={
**data,
"signature": signature,
}
req = requests.post((api_url + uri_path), headers=headers, data=payload)
return req.text
api_key = <your_api_key>
secret_key = <your_secret_key>
fromEmail=<your_from_email>
toEmail=<your_to_email>
asset=<asset>
amount=<amount>
uri_path = "/wapi/v3/sub-account/transfer.html"
data = {
"timestamp": int(round(time.time() * 1000)),
"asset": asset,
"amount": amount,
"fromEmail": fromEmail,
"toEmail": toEmail
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("POST {}: {}".format(uri_path, result))
Response
{
"success":true,
"txnId":"2966662589"
}
POST /wapi/v3/sub-account/transfer.html (HMAC SHA256)
Use this endpoint to execute sub-account asset transfers.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
fromEmail | STRING | YES | Sender email |
toEmail | STRING | YES | Recipient email |
asset | STRING | YES | |
amount | DECIMAL | YES | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Get Sub-account Assets
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
email=<your_email>
api_url="https://api.binance.us"
signature=`echo -n "email=$email×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/wapi/v3/sub-account/assets.html?email=$email×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
email=<your_email>
uri_path = "/wapi/v3/sub-account/assets.html"
data = {
"timestamp": int(round(time.time() * 1000)),
"email": email
}
get_account_result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, get_account_result))
Response
{
"success":true,
"balances":[
{
"asset":"ADA",
"free":10000,
"locked":0
},
{
"asset":"BNB",
"free":10003,
"locked":0
},
{
"asset":"BTC",
"free":11467.6399,
"locked":0
},
{
"asset":"ETH",
"free":10004.995,
"locked":0
},
{
"asset":"USDT",
"free":11652.14213,
"locked":0
}
]
}
GET /wapi/v3/sub-account/assets.html (HMAC SHA256)
Use this endpoint to fetch sub-account assets.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
STRING | YES | Sub account email | |
recvWindow | LONG | NO | |
timestamp | LONG | YES | |
symbol | STRING | NO |
Trade Order Endpoints
General Orders
Get Order Rate Limits
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
recvWindow=<recvWindow>
api_url="https://api.binance.us"
signature=`echo -n "recvWindow=$recvWindow×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/api/v3/rateLimit/order?recvWindow=$recvWindow×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
payload={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=payload, headers=headers)
return req.text
api_key = <your_api_key>
secret_key = <your_secret_key>
recvWindow = <recvWindow>
uri_path = "/api/v3/rateLimit/order"
data = {
"recvWindow": recvWindow,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
[
{
"rateLimitType": "ORDERS",
"interval": "SECOND",
"intervalNum": 10,
"limit": 100,
"count": 0
},
{
"rateLimitType": "ORDERS",
"interval": "DAY",
"intervalNum": 1,
"limit": 200000,
"count": 0
}
]
GET /api/v3/rateLimit/order (HMAC SHA256)
Get the current trade order count rate limits for all time intervals.
Weight: 20
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Data Source: Memory
Create New Order
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
symbol=<symbol>
side=<side>
type=<type>
quantity=<quantity>
api_url="https://api.binance.us"
signature=`echo -n "symbol=$symbol&side=$side&type=$type&quantity=$quantity×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "POST" "$api_url/api/v3/order?symbol=$symbol&side=$side&type=$type&quantity=$quantity×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
payload={
**data,
"signature": signature,
}
req = requests.post((api_url + uri_path), headers=headers, data=payload)
return req.text
api_key = <your_api_key>
secret_key = <your_secret_key>
symbol=<symbol>
side=<side>
type=<type>
quantity=<quantity>
uri_path = "/api/v3/order"
data = {
"symbol": symbol,
"side": side,
"type": type,
"quantity": quantity,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("POST {}: {}".format(uri_path, result))
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"
},
{
"price": "3999.00000000",
"qty": "5.00000000",
"commission": "19.99500000",
"commissionAsset": "USDT"
},
{
"price": "3998.00000000",
"qty": "2.00000000",
"commission": "7.99600000",
"commissionAsset": "USDT"
},
{
"price": "3997.00000000",
"qty": "1.00000000",
"commission": "3.99700000",
"commissionAsset": "USDT"
},
{
"price": "3995.00000000",
"qty": "1.00000000",
"commission": "3.99500000",
"commissionAsset": "USDT"
}
]
}
POST /api/v3/order (HMAC SHA256)
Use this endpoint to place a new trade order.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | Order trading pair (e.g., BTCUSD, ETHUSD) |
side | ENUM | YES | Order side (e.g., BUY, SELL) |
type | ENUM | YES | Order type (e.g., LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, TAKE_PROFIT_LIMIT, LIMIT_MAKER) |
timeInForce | ENUM | NO | |
quantity | DECIMAL | NO | |
quoteOrderQty | DECIMAL | NO | |
price | DECIMAL | NO | Order price |
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. |
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., a MARKET order on BTCUSDT will specify how much BTC the user is buying or selling. MARKET orders using quoteOrderQty specify 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 |
This will execute a MARKET order when the stopPrice is reached. |
STOP_LOSS_LIMIT |
timeInForce , quantity , price , stopPrice |
This will execute a LIMIT order when the stopPrice is reached. |
TAKE_PROFIT |
quantity , stopPrice |
This will execute a MARKET order when the stopPrice is reached. |
TAKE_PROFIT_LIMIT |
timeInForce , quantity , price , stopPrice |
This will execute a LIMIT order when the stopPrice is reached. |
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
. MARKET
orders usingquoteOrderQty
will not breakLOT_SIZE
filter rules; the order will execute aquantity
with a 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
Test New Order
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
symbol=<symbol>
side=<side>
type=<type>
quantity=<quantity>
api_url="https://api.binance.us"
signature=`echo -n "symbol=$symbol&side=$side&type=$type&quantity=$quantity×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "POST" "$api_url/api/v3/order/test?symbol=$symbol&side=$side&type=$type&quantity=$quantity×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
payload={
**data,
"signature": signature,
}
req = requests.post((api_url + uri_path), headers=headers, data=payload)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
symbol=<symbol>
side=<side>
type=<type>
quantity=<quantity>
uri_path = "/api/v3/order/test"
data = {
"symbol": symbol,
"side": side,
"type": type,
"quantity": quantity,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("POST {}: {}".format(uri_path, result))
Response
{}
POST /api/v3/order/test (HMAC SHA256)
Use this endpoint to test new order creation and signature/recvWindow long. The endpoint 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
Get Order
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
orderId=<orderId>
symbol=<symbol>
api_url="https://api.binance.us"
signature=`echo -n "orderId=$orderId&symbol=$symbol×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/api/v3/order?orderId=$orderId&symbol=$symbol×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
orderId=<orderId>
symbol=<symbol>
uri_path = "/api/v3/order"
data = {
"orderId": orderId,
"symbol": symbol,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
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"
}
GET /api/v3/order (HMAC SHA256)
Use this endpoint to check a trade 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
Get All Open Orders
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/api/v3/openOrders?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/api/v3/openOrders"
data = {
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
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/openOrders (HMAC SHA256)
Use this endpoint to get all open trade orders on a token symbol. Do not access this without a token symbol as this would return all pair data.
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
Cancel Order
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
orderId=<orderId>
symbol=<symbol>
api_url="https://api.binance.us"
signature=`echo -n "orderId=$orderId&symbol=$symbol×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "DELETE" "$api_url/api/v3/order?orderId=$orderId&symbol=$symbol×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.delete((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
orderId=<orderId>
symbol=<symbol>
uri_path = "/api/v3/order"
data = {
"orderId": orderId,
"symbol": symbol,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("DELETE {}: {}".format(uri_path, result))
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/order (HMAC SHA256)
Use this endpoint to cancel an active trade 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.
Data Source: Matching Engine
Cancel Open Orders for Symbol
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
symbol=<symbol>
api_url="https://api.binance.us"
signature=`echo -n "symbol=$symbol×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "DELETE" "$api_url/api/v3/openOrders?symbol=$symbol×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.delete((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
symbol=<symbol>
uri_path = "/api/v3/openOrders"
data = {
"symbol": symbol,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("DELETE {}: {}".format(uri_path, result))
Response
[
{
"symbol": "BTCUSDT",
"origClientOrderId": "KZJijIsAFf5BU5oxkWTAU3",
"orderId": 0,
"orderListId": -1,
"clientOrderId": "8epSIUMvNCknntXcSzWs7H",
"price": "0.10000000",
"origQty": "1.00000000",
"executedQty": "0.00000000",
"cummulativeQuoteQty": "0.00000000",
"status": "CANCELED",
"timeInForce": "GTC",
"type": "LIMIT",
"side": "BUY"
}
]
DELETE /api/v3/openOrders
Use this endpoint to cancels all active trade orders on a token symbol(this includes OCO orders).
Weight: 1
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
recvWindow | LONG | NO | The value cannot be greater than 60000 . |
timestamp | LONG | YES |
Data Source: Matching Engine
Get Trades
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "symbol=BNBBTC×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/api/v3/myTrades?symbol=BNBBTC×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/api/v3/myTrades"
data = {
"timestamp": int(round(time.time() * 1000)),
"symbol": "BNBBTC"
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
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/myTrades (HMAC SHA256)
Use this endpoint to get trade data for a specific account and token 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 orders >= thatfromId
. Otherwise most recent orders are returned.
Data Source: Database
OCO Orders
Create New OCO Order
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
symbol=<symbol>
side=<side>
quantity=<quantity>
price=<price>
stopPrice=<stopPrice>
stopLimitPrice=<stopLimitPrice>
stopLimitTimeInForce=<stopLimitTimeInForce>
api_url="https://api.binance.us"
signature=`echo -n "symbol=$symbol&side=$side&quantity=$quantity&price=$price&stopPrice=$stopPrice&stopLimitPrice=$stopLimitPrice&stopLimitTimeInForce=$stopLimitTimeInForce×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "POST" "$api_url/api/v3/order/oco?symbol=$symbol&side=$side&quantity=$quantity&price=$price&stopPrice=$stopPrice&stopLimitPrice=$stopLimitPrice&stopLimitTimeInForce=$stopLimitTimeInForce×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
payload={
**data,
"signature": signature,
}
req = requests.post((api_url + uri_path), headers=headers, data=payload)
return req.text
api_key = <your_api_key>
secret_key = <your_secret_key>
symbol=<symbol>
side=<side>
quantity=<quantity>
price=<price>
stopPrice=<stopPrice>
stopLimitPrice=<stopLimitPrice>
stopLimitTimeInForce=<stopLimitTimeInForce>
uri_path = "/api/v3/order/oco"
data = {
"timestamp": int(round(time.time() * 1000)),
"symbol": symbol,
"side": side,
"quantity": quantity,
"price": price,
"stopPrice": stopPrice,
"stopLimitPrice": stopLimitPrice,
"stopLimitTimeInForce": stopLimitTimeInForce
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("POST {}: {}".format(uri_path, result))
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"
}
]
}
POST /api/v3/order/oco (HMAC SHA256)
Weight: 1
Use this endpoint to place a new OCO(one-cancels-the-other) order.
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 | |
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 | |
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 |
Other 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
Get OCO Order
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
orderListId=<orderListId>
api_url="https://api.binance.us"
signature=`echo -n "orderListId=$orderListId×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/api/v3/orderList?orderListId=$orderListId×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
orderListId=<orderListId>
uri_path = "/api/v3/orderList"
data = {
"orderListId": orderListId,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
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/orderList (HMAC SHA256)
Weight: 2
Use this endpoint to retrieve a specific OCO order 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
Get All OCO Order
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/api/v3/allOrderList?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/api/v3/allOrderList"
data = {
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
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/allOrderList (HMAC SHA256)
Weight: 10
Use this endpoint to retrieve all OCO orders based on provided optional parameters. Please note the maximum limit is 1,000 orders.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
fromId | LONG | NO | If supplied, neither startTime nor 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
Get Open OCO Orders
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/api/v3/openOrderList?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/api/v3/openOrderList"
data = {
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
[
{
"orderListId": 31,
"contingencyType": "OCO",
"listStatusType": "EXEC_STARTED",
"listOrderStatus": "EXECUTING",
"listClientOrderId": "wuB13fmulKj3YjdqWEcsnp",
"transactionTime": 1565246080644,
"symbol": "1565246079109",
"orders": [
{
"symbol": "LTCBTC",
"orderId": 4,
"clientOrderId": "r3EH2N76dHfLoSZWIUw1bT"
},
{
"symbol": "LTCBTC",
"orderId": 5,
"clientOrderId": "Cv1SnyPD3qhqpbjpYEHbd2"
}
]
}
]
GET /api/v3/openOrderList (HMAC SHA256)
Use this endpoint to query open OCO orders.
Weight: 3
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | The value cannot be greater than 60000 |
timestamp | LONG | YES |
Data Source: Database
Cancel OCO Order
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
symbol=<symbol>
orderListId=<orderListId>
api_url="https://api.binance.us"
signature=`echo -n "symbol=$symbol&orderListId=$orderListId×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "DELETE" "$api_url/api/v3/orderList?symbol=$symbol&orderListId=$orderListId×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.delete((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
symbol=<symbol>
orderListId=<orderListId>
uri_path = "/api/v3/orderList"
data = {
"symbol": symbol,
"orderListId": orderListId,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("DELETE {}: {}".format(uri_path, result))
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"
}
]
}
DELETE /api/v3/orderList (HMAC SHA256)
Weight: 1
Use this endpoint to 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
Data Source: Matching Engine
OTC Endpoints
Get Supported Coin Pairs
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/sapi/v1/otc/selectors?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/sapi/v1/otc/selectors"
data = {
"timestamp": int(round(time.time() * 1000)),
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
[
{
"fromCoin": "BTC",
"toCoin": "USDT",
"fromCoinMinAmount": 0.1,
"fromCoinMaxAmount": 100,
"toCoinMinAmount": 1000,
"toCoinMaxAmount": 500000
},
{
"fromCoin": "USDT",
"toCoin": "BNB",
"fromCoinMinAmount": 2000,
"fromCoinMaxAmount": 600000,
"toCoinMinAmount": 10,
"toCoinMaxAmount": 4000
}
]
GET /sapi/v1/otc/selectors
Use this endpoint to get a list of supported coin pairs for convert.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
fromCoin | STRING | NO | From coin name, e.g. BTC, KSHIB |
toCoin | STRING | NO | To coin name, e.g. USDT, SHIB |
Data Source: Database
Request for Quote
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
from_coin=BTC
to_coin=USDT
request_coin=BTC
request_amount=1
api_url="https://api.binance.us"
signature=`echo -n "fromCoin=$from_coin&toCoin=$to_coin&requestCoin=$request_coin&requestAmount=$request_amount×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "POST" "$api_url/sapi/v1/otc/quotes" \
-H "X-MBX-APIKEY: $api_key" \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
--data-urlencode "fromCoin=$from_coin&toCoin=$to_coin&requestCoin=$request_coin&requestAmount=$request_amount×tamp=$timestamp&signature=$signature"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
payload={
**data,
"signature": signature,
}
req = requests.post((api_url + uri_path), headers=headers, data=payload)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/sapi/v1/otc/quotes"
data = {
"fromCoin": "BTC",
"toCoin": "USDT",
"requestCoin": "BTC",
"requestAmount": 1,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("POST {}: {}".format(uri_path, result))
Response
{
"quoteId": "15848701022",
"symbol": "BTCUSDT",
"ratio": 50550.26,
"inverseRatio": 0.00001978,
"validTimestamp": 1641806714,
"toAmount": 50550.26,
"fromAmount": 1
}
POST /sapi/v1/otc/quotes
Use this endpoint to request a quote for a from-to coin pair.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
fromCoin | STRING | YES | From coin name, e.g. BTC, KSHIB |
toCoin | STRING | YES | To coin name, e.g. USDT, SHIB |
requestCoin | STRING | YES | Request coin name, e.g. BTC, KSHIB |
requestAmount | DECIMAL | YES | Amount of request coin, e.g. 1 |
Data Source: Database
Place OTC Trade Order
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
quote_id=<quoteId>
api_url="https://api.binance.us"
signature=`echo -n "quoteId=$quote_id×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "POST" "$api_url/sapi/v1/otc/orders" \
-H "X-MBX-APIKEY: $api_key" \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
--data-urlencode "quoteId=$quote_id×tamp=$timestamp&signature=$signature"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
payload={
**data,
"signature": signature,
}
req = requests.post((api_url + uri_path), headers=headers, data=payload)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/sapi/v1/otc/orders"
data = {
"quoteId": "4e5446f2cc6f44ab86ab02abf19a2fd2",
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("POST {}: {}".format(uri_path, result))
Response
{
"orderId": "10002349",
"createTime": 1641906714,
"orderStatus": "PROCESS" // Status: PROCESS / ACCEPT_SUCCESS / SUCCESS / FAIL
}
POST /sapi/v1/otc/orders
Use this endpoint to place an order using an acquired quote.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
quoteId | STRING | YES | STRING |
Data Source: Database
Get OTC Trade Order
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
orderid=<your_order_id>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/sapi/v1/otc/orders/$orderid?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/sapi/v1/otc/orders/10002349"
data = {
"timestamp": int(round(time.time() * 1000)),
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
{
"quoteId": "4e5446f2cc6f44ab86ab02abf19a2fd2",
"orderId": "10002349",
"orderStatus": "SUCCESS",
"fromCoin": "BTC",
"fromAmount": 1,
"toCoin": "USDT",
"toAmount": 50550.26,
"ratio": 50550.26,
"inverseRatio": 0.00001978,
"createTime": 1641806714
}
GET /sapi/v1/otc/orders/{orderId}
Use this endpoint to query OTC trade order details.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
orderId | STRING | YES | Order ID, e.g., 10002349 |
Data Source: Database
Get All OTC Trade Orders
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/sapi/v1/otc/orders?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/sapi/v1/otc/orders"
data = {
"timestamp": int(round(time.time() * 1000)),
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
[
{
"quoteId": "4e5446f2cc6f44ab86ab02abf19a2fd2",
"orderId": "10002349",
"orderStatus": "SUCCESS",
"fromCoin": "BTC",
"fromAmount": 1,
"toCoin": "USDT",
"toAmount": 50550.26,
"ratio": 50550.26,
"inverseRatio": 0.00001978,
"createTime": 1641806714
},
{
"quoteId": "15848645308",
"orderId": "10002380",
"orderStatus": "PROCESS",
"fromCoin": "SHIB",
"fromAmount": 10000,
"toCoin": "KSHIB",
"toAmount": 10,
"ratio": 0.001,
"inverseRatio": 1000,
"createTime": 1641916714
}
]
GET /sapi/v1/otc/orders
Use this endpoint to query OTC trade orders by condition.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
orderId | STRING | NO | Order ID |
fromCoin | STRING | NO | From coin name, e.g., BTC, KSHIB |
toCoin | STRING | NO | To coin name, e.g., USDT, SHIB |
startTime | LONG | NO | Start timestamp |
endTime | LONG | NO | End timestamp |
limit | INT | NO | Batch limit per page, default 10 |
Data Source: Database
Wallet Endpoints
Asset Fees & Wallet Status
Get Asset Fees & Wallet Status
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/sapi/v1/capital/config/getall?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/sapi/v1/capital/config/getall"
data = {
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
[
{
"coin": "BCH",
"depositAllEnable": true,
"withdrawAllEnable": true,
"name": "BCH",
"free": "0",
"locked": "0",
"freeze": "0",
"withdrawing": "0",
"ipoing": "0",
"ipoable": "0",
"storage": "0",
"isLegalMoney": false,
"trading": true,
"networkList": [
{
"network": "BCH",
"coin": "BCH",
"withdrawIntegerMultiple": "0.00000001",
"isDefault": true,
"depositEnable": true,
"withdrawEnable": true,
"depositDesc": "",
"withdrawDesc": "",
"name": "Bitcoin Cash",
"resetAddressStatus": false,
"withdrawFee": "0",
"withdrawMin": "0",
"withdrawMax": "9999999"
},
{
"network": "BNB",
"coin": "BCH",
"withdrawIntegerMultiple": "0.00000001",
"isDefault": false,
"depositEnable": true,
"withdrawEnable": true,
"depositDesc": "",
"withdrawDesc": "",
"name": "BEP222ee",
"resetAddressStatus": false,
"addressRegex": "^(bnb1)[0-9a-z]{38}$",
"memoRegex": "^[0-9A-Za-z\\-_]{1,120}$",
"withdrawFee": "0",
"withdrawMin": "0",
"withdrawMax": "9999999",
"minConfirm": 15,
"unLockConfirm": 3
},
{
"network": "BSC",
"coin": "BCH",
"withdrawIntegerMultiple": "0.00000001",
"isDefault": false,
"depositEnable": true,
"withdrawEnable": true,
"depositDesc": "",
"withdrawDesc": "",
"name": "BSC (BEP20)",
"resetAddressStatus": false,
"addressRegex": "^(0x)[0-9A-Fa-f]{40}$",
"memoRegex": "",
"withdrawFee": "0",
"withdrawMin": "0",
"withdrawMax": "9999999",
"minConfirm": 0,
"unLockConfirm": 0
}
]
},
{
"coin": "PAX",
"depositAllEnable": true,
"withdrawAllEnable": true,
"name": "PAX",
"free": "0",
"locked": "0",
"freeze": "0",
"withdrawing": "0",
"ipoing": "0",
"ipoable": "0",
"storage": "0",
"isLegalMoney": false,
"trading": false,
"networkList": [
{
"network": "BNB",
"coin": "PAX",
"withdrawIntegerMultiple": "0",
"isDefault": false,
"depositEnable": true,
"withdrawEnable": true,
"depositDesc": "",
"withdrawDesc": "",
"specialTips": "",
"name": "BEP222ee",
"resetAddressStatus": false,
"addressRegex": "^(bnb1)[0-9a-z]{38}$",
"memoRegex": "^[0-9A-Za-z\\-_]{1,120}$",
"withdrawFee": "0",
"withdrawMin": "0",
"withdrawMax": "9999999",
"minConfirm": 15,
"unLockConfirm": 3
}
]
}
]
GET /sapi/v1/capital/config/getall (HMAC SHA256)
Use this endpoint to fetch the details of all crypto assets, including fees, withdrawal limits and network status.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Data Source: Memory
Withdrawals
Withdraw Crypto
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
coin=<coin>
network=<network>
address=<address>
amount=<amount>
api_url="https://api.binance.us"
signature=`echo -n "coin=$coin&network=$network&address=$address&amount=$amount×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
payload=`echo "coin=$coin&network=$network&address=$address&amount=$amount×tamp=$timestamp&signature=$signature"`
curl -X "POST" "$api_url/sapi/v1/capital/withdraw/apply" \
-H "X-MBX-APIKEY: $api_key" \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
-d $payload
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
payload={
**data,
"signature": signature,
}
req = requests.post((api_url + uri_path), headers=headers, data=payload)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
coin=<coin>
network=<network>
address=<address>
amount=<amount>
uri_path = "/sapi/v1/capital/withdraw/apply"
data = {
"coin": coin,
"network": network,
"address": address,
"amount": amount,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("POST {}: {}".format(uri_path, result))
Response
{"id":"4e7f4f31560041ee880b5386f06d4053"}
POST /sapi/v1/capital/withdraw/apply (HMAC SHA256)
Use this endpoint to submit a crypto withdrawal request.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
coin | STRING | YES | |
network | STRING | YES | |
withdrawOrderId | STRING | NO | Client ID for withdraw |
address | STRING | YES | |
addressTag | STRING | NO | Memo: Acts as a secondary address identifier for coins like XRP, XMR etc. |
amount | DECIMAL | YES | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Data Source: Memory
Withdraw Fiat (via SEN)
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
paymentAccount=<paymentAccount>
amount=<amount>
api_url="https://api.binance.us"
signature=`echo -n "paymentAccount=$paymentAccount&amount=$amount×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "POST" "$api_url/sapi/v1/fiatpayment/apply/withdraw" \
-H "X-MBX-APIKEY: $api_key" \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
--data-urlencode "paymentAccount=$paymentAccount&amount=$amount×tamp=$timestamp&signature=$signature"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
payload={
**data,
"signature": signature,
}
req = requests.post((api_url + uri_path), headers=headers, data=payload)
return req.text
api_key = <your_api_key>
secret_key = <your_secret_key>
paymentAccount=<paymentAccount>
amount=<amount>
uri_path = "/sapi/v1/fiatpayment/apply/withdraw"
data = {
"timestamp": int(round(time.time() * 1000)),
"paymentAccount": paymentAccount,
"amount": amount
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("POST {}: {}".format(uri_path, result))
Response
{
"orderId": "6c2ff984890145fdac2b7160299062f0"
}
POST /sapi/v1/fiatpayment/apply/withdraw (HMAC SHA256)
Use this endpoint to submit a USD withdraw request via Silvergate Exchange Network (SEN).
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
paymentChannel | STRING | NO | default value="SILVERGATE" |
paymentMethod | STRING | NO | default value="SEN" |
paymentAccount | STRING | YES | The account to which the user wants to withdraw funds |
fiatCurrency | STRING | NO | default value="USD" |
amount | DECIMAL | YES | The amount |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Get Crypto Withdrawal History
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/sapi/v1/capital/withdraw/history?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/sapi/v1/capital/withdraw/history"
data = {
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
[
{
"id": "4e7f4f31560041ee880b5386f06d4053",
"amount": "0.9",
"transactionFee": "0.1",
"coin": "BNB",
"status": 2,
"address": "0xd709f9d0bbc6b0e746a13142dfe353086edf87c2",
"applyTime": "2022-02-18 03:36:04",
"network": "BSC",
"transferType": 0
}
]
GET /sapi/v1/capital/withdraw/history (HMAC SHA256)
Use this endpoint to fetch your crypto withdrawal history.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
coin | STRING | YES | |
withdrawOrderId | STRING | NO | Client ID for withdraw |
status | INT | NO | 0: email sent, 1: canceled, 2: awaiting approval, 3: rejected, 4: processing, 5: failure, 6: completed |
startTime | LONG | NO | Default: 90 days from current timestamp |
endTime | LONG | NO | Default: present timestamp |
offset | INT | NO | Default: 0 |
limit | INT | NO | Default: 1000, max: 1000 |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Data Source: Database
Get Fiat Withdrawal History
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/sapi/v1/fiatpayment/query/withdraw/history?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/sapi/v1/fiatpayment/query/withdraw/history"
data = {
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
{
"assetLogRecordList": [
{
"orderId":"6c2ff984890145fdac2b7160299062f0",
"paymentAccount": "4a992541-c12d-4cca-bbd6-df637f801526",
"paymentChannel": "PRIMETRUST",
"paymentMethod": "WIRE_INTERNATIONAL",
"orderStatus": "Processing",
"amount": "65",
"transactionFee": "20",
"platformFee": "0"
}
]
}
GET /sapi/v1/fiatpayment/query/withdraw/history (HMAC SHA256)
Use this endpoint to fetch your fiat (USD) withdrawal history.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
fiatCurrency | STRING | NO | |
orderId | STRING | NO | |
offset | INT | NO | |
paymentChannel | STRING | NO | |
paymentMethod | STRING | NO | |
startTime | LONG | NO | Default to 90 days from current timestamp |
endTime | LONG | NO | Default to current timestamp |
recvWindow | Long | NO | |
timestamp | Long | YES |
- Please pay attention to the default value of startTime and endTime.
- If both startTime and endTime are sent, the duration between startTime and endTime must be greater than 0 day and less than 90 days.
Deposits
Get Crypto Deposit Address
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
coin=<coin>
api_url="https://api.binance.us"
signature=`echo -n "coin=$coin×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/sapi/v1/capital/deposit/address?coin=$coin×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
coin=<coin>
uri_path = "/sapi/v1/capital/deposit/address"
data = {
"coin": coin,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
{
"coin": "BNB",
"address": "0xcf1988d27e402086941284313b632466fdf28a22",
"tag": "",
"url": "0xcf1988d27e402086941284313b632466fdf28a22"
}
GET /sapi/v1/capital/deposit/address (HMAC SHA256)
Use this endpoint to fetch a deposit address for a particular crypto asset.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
coin | STRING | YES | |
network | STRING | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Get Crypto Deposit History
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
coin=<coin>
api_url="https://api.binance.us"
signature=`echo -n "coin=$coin×tamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/sapi/v1/capital/deposit/hisrec?coin=$coin×tamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
coin=<coin>
uri_path = "/sapi/v1/capital/deposit/hisrec"
data = {
"coin": coin,
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
[
{
"amount": "8.73234",
"coin": "BNB",
"network": "BSC",
"status": 1,
"address": "0xd709f9d0bbc6b0e746a13142dfe353086edf87c2",
"addressTag": "",
"txId": "0xa9ebf3f4f60bc18bd6bdf4616ff8ffa14ef93a08fe79cad40519b31ea1044290",
"insertTime": 1638342348000,
"transferType": 0,
"confirmTimes": "0/0"
}
]
GET /sapi/v1/capital/deposit/hisrec (HMAC SHA256)
Use this endpoint to fetch your crypto deposit history.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
coin | STRING | YES | |
status | INT | NO | 0: pending, 6: credited but cannot withdraw, 1: success |
startTime | LONG | NO | Default: 90 days from current timestamp |
endTime | LONG | NO | Default: present timestamp |
offset | INT | NO | Default: 0 |
limit | INT | NO | Default: 1000, max: 1000 |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Data Source: Memory
Get Fiat Deposit History
Example
# Get HMAC SHA256 signature
timestamp=`date +%s000`
api_key=<your_api_key>
secret_key=<your_secret_key>
api_url="https://api.binance.us"
signature=`echo -n "timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`
curl -X "GET" "$api_url/sapi/v1/fiatpayment/query/deposit/history?timestamp=$timestamp&signature=$signature" \
-H "X-MBX-APIKEY: $api_key"
import urllib.parse
import hashlib
import hmac
import base64
import requests
import time
api_url = "https://api.binance.us"
# get binanceus signature
def get_binanceus_signature(data, secret):
postdata = urllib.parse.urlencode(data)
message = postdata.encode()
byte_key = bytes(secret, 'UTF-8')
mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
return mac
# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
headers = {}
headers['X-MBX-APIKEY'] = api_key
signature = get_binanceus_signature(data, api_sec)
params={
**data,
"signature": signature,
}
req = requests.get((api_url + uri_path), params=params, headers=headers)
return req.text
api_key=<your_api_key>
secret_key=<your_secret_key>
uri_path = "/sapi/v1/fiatpayment/query/deposit/history"
data = {
"timestamp": int(round(time.time() * 1000))
}
result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))
Response
{
"assetLogRecordList": [
{
"orderId":"a1d377c72de544f2ba881399f5ad36bb",
"paymentAccount": "4a992541-c12d-4cca-bbd6-df637f801526",
"paymentChannel": "Silvergate",
"paymentMethod": "SEN",
"orderStatus": "Failed",
"amount": "0.95",
"transactionFee": "0.05",
"platformFee": "0"
}
]
}
GET /sapi/v1/fiatpayment/query/deposit/history (HMAC SHA256)
Use this endpoint to fetch your fiat (USD) deposit history.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
fiatCurrency | STRING | NO | |
orderId | STRING | NO | |
offset | INT | NO | |
paymentChannel | STRING | NO | |
paymentMethod | STRING | NO | |
startTime | LONG | NO | Default to 90 days from current timestamp |
endTime | LONG | NO | Default to current timestamp |
recvWindow | Long | NO | |
timestamp | Long | YES |
- Please pay attention to the default value of startTime and endTime.
- If both startTime and endTime are sent, the duration between startTime and endTime must be greater than 0 day and less than 90 days.
Filters
Filters define trading rules on a symbol or an exchange.
Filters come in two forms: symbol filters
and exchange filters
.
Symbol Filters
Price Filter
/exchangeInfo format:
{
"filterType": "PRICE_FILTER",
"minPrice": "0.00000100",
"maxPrice": "100000.00000000",
"tickSize": "0.00000100"
}
The PRICE_FILTER
defines the price
rules for a symbol. There are three 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
-minPrice
) %tickSize
== 0
Percent Price Filter
/exchangeInfo format:
{
"filterType": "PERCENT_PRICE",
"multiplierUp": "1.3000",
"multiplierDown": "0.7000",
"avgPriceMins": 5
}
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
Lot Size Filter
/exchangeInfo format:
{
"filterType": "LOT_SIZE",
"minQty": "0.00100000",
"maxQty": "100000.00000000",
"stepSize": "0.00100000"
}
The LOT_SIZE
filter defines the quantity
(aka "lots" in auction terms) rules for a symbol. There are three 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
Min Notional Filter
/exchangeInfo format:
{
"filterType": "MIN_NOTIONAL",
"minNotional": "0.00100000",
"applyToMarket": true,
"avgPriceMins": 5
}
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.
Iceberg Parts Filter
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
}
Market Order Lot Size Filter
/exchangeInfo format:
{
"filterType": "MARKET_LOT_SIZE",
"minQty": "0.00100000",
"maxQty": "100000.00000000",
"stepSize": "0.00100000"
}
The MARKET_LOT_SIZE
filter defines the quantity
(aka "lots" in auction terms) rules for MARKET
orders on a symbol. There are three 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
Symbol Max Orders Filter
/exchangeInfo format:
{
"filterType": "MAX_NUM_ORDERS",
"limit": 25
}
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.
Symbol Max Algo Orders Filter
/exchangeInfo format:
{
"filterType": "MAX_NUM_ALGO_ORDERS",
"maxNumAlgoOrders": 5
}
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.
Max Iceberg Orders Filter
/exchangeInfo format:
{
"filterType": "MAX_NUM_ICEBERG_ORDERS",
"maxNumIcebergOrders": 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.
Max Position Filter
/exchangeInfo format:
{
"filterType":"MAX_POSITION",
"maxPosition":"10.00000000"
}
The MAX_POSITION
filter defines the allowed maximum position an account can have on the base asset of a symbol.
An account's position is 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.
Exchange Filters
Exchange Max Orders Filter
/exchangeInfo format:
{
"filterType": "EXCHANGE_MAX_NUM_ORDERS",
"maxNumOrders": 1000
}
The MAX_NUM_ORDERS
filter defines the maximum number of orders an account is allowed to have open on the exchange.
Note that both "algo" orders and normal orders are counted for this filter.
Exchange Max Algo Orders Filter
/exchangeInfo format:
{
"filterType": "EXCHANGE_MAX_ALGO_ORDERS",
"maxNumAlgoOrders": 200
}
The MAX_ALGO_ORDERS
filter defines the maximum number of "algo" orders an account is allowed to have open on the exchange.
"Algo" orders are STOP_LOSS
, STOP_LOSS_LIMIT
, TAKE_PROFIT
, and TAKE_PROFIT_LIMIT
orders.
WebSocket Streams
WebSocket Information
- The base endpoint is: wss://stream.binance.us:9443
- Streams can be accessed either in a single raw stream or in a combined stream
- Raw streams are accessed at /ws/<streamName>
- Combined streams are accessed at /stream?streams=<streamName1>/<streamName2>/<streamName3>
- Combined stream events are wrapped as follows: {"stream":"<streamName>","data":<rawPayload>}
- All symbols for streams are in lowercase
- A single connection to stream.binance.us is only valID for 24-hours; expect to be disconnected at the 24 hour mark
- The WebSocket server will send a
ping frame
every 3 minutes. If the WebSocket server does not receive apong frame
back from the connection within a 10-minute period, the connection will be disconnected. Unsolicitedpong frames
are allowed.
WebSocket Rate Limits
- WebSocket connections have a limit of 5 incoming messages per second. A message is consIDered:
- A PING frame
- A PONG frame
- A JSON controlled message (e.g., subscribe, unsubscribe)
- A connection that goes beyond the limit will be disconnected; IPs that are repeatedly disconnected may be banned.
- A single connection can listen to a maximum of 1024 streams.
WebSocket Errors
Error Message | Description |
---|---|
{"code": 0, "msg": "Unknown property", "ID": '%s'} | Parameter used in the SET_PROPERTY or GET_PROPERTY was invalID |
{"code": 1, "msg": "InvalID value type: expected Boolean"} | Value should only be true or false |
{"code": 2, "msg": "InvalID request: property name must be a string"} | Property name provIDed was invalID |
{"code": 2, "msg": "InvalID request: request ID must be an unsigned integer"} | Parameter ID had to be provIDed or the value provIDed in the ID parameter is an unsupported type |
{"code": 2, "msg": "InvalID request: unknown variant %s, expected one of SUBSCRIBE , UNSUBSCRIBE , LIST_SUBSCRIPTIONS , SET_PROPERTY , GET_PROPERTY at line 1 column 28"} |
Possible typo in the provIDed method or provIDed method was neither of the expected values |
{"code": 2, "msg": "InvalID request: too many parameters"} | Unnecessary parameters provIDed in the data |
{"code": 2, "msg": "InvalID request: property name must be a string"} | Property name was not provIDed |
{"code": 2, "msg": "InvalID request: missing field method at line 1 column 73"} |
method was not provIDed in the data |
{"code":3,"msg":"InvalID JSON: expected value at line %s column %s"} | JSON data sent has incorrect syntax |
Subscribing/Unsubscribing
- The following data can be sent through the WebSocket instance in order to subscribe/unsubscribe from streams. Examples can be seen below.
- The
ID
used in the JSON payloads is an unsigned INT used as an IDentifier to uniquely IDentify the messages going back and forth. - In the response, if the
result
received isnull
this means the request sent was a success for non-query requests (e.g., subscribing/unsubscribing).
Subscribe to a Stream
Request
{ "method": "SUBSCRIBE", "params": [ "btcusdt@aggTrade", "btcusdt@depth" ], "ID": 1 }
Response
{ "result": null, "ID": 1 }
Unsubscribe to a Stream
Request
{ "method": "UNSUBSCRIBE", "params": [ "btcusdt@depth" ], "ID": 312 }
Response
{ "result": null, "ID": 312 }
List Subscriptions
Request
{ "method": "LIST_SUBSCRIPTIONS", "ID": 3 }
Response
{ "result": [ "btcusdt@aggTrade" ], "ID": 3 }
Set Properties
Currently, the only property that can be set is whether combined
stream payloads are enabled or not.
The combined property is set to false
when connecting using /ws/
("raw streams") and true
when connecting using /stream/
.
Request
{ "method": "SET_PROPERTY", "params": [ "combined", true ], "ID": 5 }
Response
{ "result": null, "ID": 5 }
Retrieve Properties
Request
{ "method": "GET_PROPERTY", "params": [ "combined" ], "ID": 2 }
Response
{ "result": true, // Indicates that combined is set to true. "ID": 2 }
Market Data Streams
- The base endpoint is: wss://stream.binance.us:9443
- Streams can be accessed either in a single raw stream or in a combined stream
- Raw streams are accessed at /ws/<streamName>
- Combined streams are accessed at /stream?streams=<streamName1>/<streamName2>/<streamName3>
- Combined stream events are wrapped as follows: {"stream":"<streamName>","data":<rawPayload>}
- All symbols for streams are lowercase
- A single connection to stream.binance.us is only valid for 24-hours; expect to be disconnected at the 24 hour mark
- The WebSocket server will send a
ping frame
every 3 minutes. If the WebSocket server does not receive apong frame
back from the connection within a 10-minute period, the connection will be disconnected. Unsolicitedpong frames
are allowed.
Trade Data Streams
Aggregate Trade Stream
Payload:
{
"e": "aggTrade", // Event type
"E": 123456789, // Event time
"s": "BNBBTC", // Symbol
"a": 12345, // Aggregate trade ID
"p": "0.001", // Price
"q": "100", // Quantity
"f": 100, // First trade ID
"l": 105, // Last trade ID
"T": 123456785, // Trade time
"m": true, // Is the buyer the market maker?
"M": true // Ignore
}
The Aggregate Trade Streams push trade information that is aggregated for a single taker order.
Stream Name: <symbol>@aggTrade
Update Speed: Real-time
Trade Data Stream
Payload:
{
"e": "trade", // Event type
"E": 123456789, // Event time
"s": "BNBBTC", // Symbol
"t": 12345, // Trade ID
"p": "0.001", // Price
"q": "100", // Quantity
"b": 88, // Buyer order ID
"a": 50, // Seller order ID
"T": 123456785, // Trade time
"m": true, // Is the buyer the market maker?
"M": true // Ignore
}
The Trade Streams push raw trade information; each trade has a unique buyer and seller.
Stream Name: <symbol>@trade
Update Speed: Real-time
Candlestick Data Stream
Payload:
{
"e": "kline", // Event type
"E": 123456789, // Event time
"s": "BNBBTC", // Symbol
"k": {
"t": 123400000, // Kline start time
"T": 123460000, // Kline close time
"s": "BNBBTC", // Symbol
"i": "1m", // Interval
"f": 100, // First trade ID
"L": 200, // Last trade ID
"o": "0.0010", // Open price
"c": "0.0020", // Close price
"h": "0.0025", // High price
"l": "0.0015", // Low price
"v": "1000", // Base asset volume
"n": 100, // Number of trades
"x": false, // Is this kline closed?
"q": "1.0000", // Quote asset volume
"V": "500", // Taker buy base asset volume
"Q": "0.500", // Taker buy quote asset volume
"B": "123456" // Ignore
}
}
The Kline/Candlestick Stream pushes updates to the current klines/candlestick every second.
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
Stream Name: <symbol>@kline_<interval>
Update Speed: 2000ms
Ticker Streams
Individual Ticker Stream
Payload:
{
"u":400900217, // order book updateId
"s":"BNBUSDT", // symbol
"b":"25.35190000", // best bid price
"B":"31.21000000", // best bid qty
"a":"25.36520000", // best ask price
"A":"40.66000000" // best ask qty
}
Pushes any update to the best bid or ask's price or quantity in real-time for a specified symbol.
Stream Name: <symbol>@bookTicker
Update Speed: Real-time
All Markets Ticker Stream
Payload:
[
{
// Same as <symbol>@ticker payload
}
]
24hr rolling window ticker statistics for all symbols that changed in an array. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs. Note that only tickers that have changed will be present in the array.
Stream Name: !ticker@arr
Update Speed: 1000ms
Price Change Streams
Ticker 24h Change Stream
Payload:
{
"e": "24hrTicker", // Event type
"E": 123456789, // Event time
"s": "BNBBTC", // Symbol
"p": "0.0015", // Price change
"P": "250.00", // Price change percent
"w": "0.0018", // Weighted average price
"x": "0.0009", // First trade(F)-1 price (first trade before the 24hr rolling window)
"c": "0.0025", // Last price
"Q": "10", // Last quantity
"b": "0.0024", // Best bid price
"B": "10", // Best bid quantity
"a": "0.0026", // Best ask price
"A": "100", // Best ask quantity
"o": "0.0010", // Open price
"h": "0.0025", // High price
"l": "0.0010", // Low price
"v": "10000", // Total traded base asset volume
"q": "18", // Total traded quote asset volume
"O": 0, // Statistics open time
"C": 86400000, // Statistics close time
"F": 0, // First trade ID
"L": 18150, // Last trade Id
"n": 18151 // Total number of trades
}
24hr rolling window ticker statistics for a single symbol. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs.
Stream Name: <symbol>@ticker
Update Speed: 1000ms
All Markets 24h Change Stream
Payload:
[
{
// Same as <symbol>@miniTicker payload
}
]
24hr rolling window mini-ticker statistics for all symbols that changed in an array. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs. Note that only tickers that have changed will be present in the array.
Stream Name: !miniTicker@arr
Update Speed: 1000ms
Order Book Streams
Ticker Order Book Stream
Payload:
{
"u":400900217, // order book updateId
"s":"BNBUSDT", // symbol
"b":"25.35190000", // best bid price
"B":"31.21000000", // best bid qty
"a":"25.36520000", // best ask price
"A":"40.66000000" // best ask qty
}
Pushes any update to the best bid or ask's price or quantity in real-time for a specified symbol.
Stream Name: <symbol>@bookTicker
Update Speed: Real-time
All Markets Order Book Stream
Payload:
{
// Same as <symbol>@bookTicker payload
}
Pushes any update to the best bid or ask's price or quantity in real-time for all symbols.
Stream Name: !bookTicker
Update Speed: Real-time
Partial Order Book Depth Stream
Payload:
{
"lastUpdateId": 160, // Last update ID
"bids": [ // Bids to be updated
[
"0.0024", // Price level to be updated
"10" // Quantity
]
],
"asks": [ // Asks to be updated
[
"0.0026", // Price level to be updated
"100" // Quantity
]
]
}
Top <levels> bids and asks, pushed every second. Valid <levels> are 5, 10, or 20.
Stream Names: <symbol>@depth<levels> OR <symbol>@depth<levels>@100ms
Update Speed: 1000ms or 100ms
Order Book Depth Diff Stream
Payload:
{
"e": "depthUpdate", // Event type
"E": 123456789, // Event time
"s": "BNBBTC", // Symbol
"U": 157, // First update ID in event
"u": 160, // Final update ID in event
"b": [ // Bids to be updated
[
"0.0024", // Price level to be updated
"10" // Quantity
]
],
"a": [ // Asks to be updated
[
"0.0026", // Price level to be updated
"100" // Quantity
]
]
}
Order book price and quantity depth updates are used to manage an order book locally.
Stream Name: <symbol>@depth OR <symbol>@depth@100ms
Update Speed: 1000ms or 100ms
Managing a Local Order Book
- Open a stream to wss://stream.binance.us:9443/ws/bnbbtc@depth
- Buffer the events you receive from the stream
- Get a depth snapshot from https://www.binance.us/api/v1/depth?symbol=BNBBTC&limit=1000
- Drop any event where
u
is <=lastUpdateId
in the snapshot - The first processed should have
U
<=lastUpdateId
+1 ANDu
>=lastUpdateId
+1 - While listening to the stream, each new event's
U
should be equal to the previous event'su
+1 - The data in each event is the absolute quantity for a price level
- If the quantity is 0, remove the price level
- Receiving an event that removes a price level that is not in your local order book is normal
User Data Streams
- The base API endpoint is: https://api.binance.us
- A User Data Stream
listenKey
is valid for 60 minutes after creation. - Doing a
PUT
on alistenKey
will extend its validity for 60 minutes. - Doing a
DELETE
on alistenKey
will close the stream and invalidate thelistenKey
. - Doing a
POST
on an account with an activelistenKey
will return the currently activelistenKey
and extend its validity for 60 minutes. - The base WebSocket endpoint is: wss://stream.binance.us:9443
- User Data Streams are accessed at /ws/<listenKey> or /stream?streams=<listenKey>
- A single connection to stream.binance.us is only valid for 24 hours; expect to be disconnected at the 24-hour mark
User Data Endpoints
Create User Data Stream
Example
curl -X "POST" "https://api.binance.us/api/v3/userDataStream" \
-H "X-MBX-APIKEY: <your_api_key>"
import requests
headers = {}
headers['X-MBX-APIKEY'] = <your_api_key>
resp = requests.post('https://api.binance.us/api/v3/userDataStream', headers=headers)
print(resp.json())
Response
{
"listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}
POST /api/v3/userDataStream
Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent. If the account has an active listenKey
, that listenKey
will be returned and its validity will be extended for 60 minutes.
Weight: 1
Parameters: NONE
Extend User Data Stream
Example
curl -X "PUT" "https://api.binance.us/api/v3/userDataStream" \
-H "X-MBX-APIKEY: <your_api_key>" \
-d 'listenKey=<listen_key>'
import requests
headers = {}
headers['X-MBX-APIKEY'] = <your_api_key>
data={
"listenKey": <listen_key>
}
resp = requests.put('https://api.binance.us/api/v3/userDataStream', params=data, headers=headers)
print(resp.json())
Response
{}
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
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
listenKey | STRING | YES |
Close User Data Stream
Example
curl -X "DELETE" "https://api.binance.us/api/v3/userDataStream" \
-H "X-MBX-APIKEY: <your_api_key>" \
-d 'listenKey=<listen_key>'
import requests
headers = {}
headers['X-MBX-APIKEY'] = <your_api_key>
data={
"listenKey": <listen_key>
}
resp = requests.delete('https://api.binance.us/api/v3/userDataStream', data=data, headers=headers)
print(resp.json())
Response
{}
DELETE /api/v3/userDataStream
Close out a user data stream.
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
listenKey | STRING | YES |
User Data Stream Payloads
Account Update
{
"e": "outboundAccountPosition", //Event type
"E": 1564034571105, //Event Time
"u": 1564034571073, //Time of last account update
"B": [ //Balances Array
{
"a": "ETH", //Asset
"f": "10000.000000", //Free
"l": "0.000000" //Locked
}
]
}
The event outboundAccountPosition
is sent any time an account balance has changed and contains the assets that were possibly changed by the event that generated the balance change.
Order Update
Payload A
{
"e": "executionReport", // Event type
"E": 1499405658658, // Event time
"s": "ETHBTC", // Symbol
"c": "mUvoqJxFIILMdfAW5iGSOW", // Client order ID
"S": "BUY", // Side
"o": "LIMIT", // Order type
"f": "GTC", // Time in force
"q": "1.00000000", // Order quantity
"p": "0.10264410", // Order price
"P": "0.00000000", // Stop price
"F": "0.00000000", // Iceberg quantity
"g": -1, // OrderListId
"C": "", // Original client order ID; This is the ID of the order being canceled
"x": "NEW", // Current execution type
"X": "NEW", // Current order status
"r": "NONE", // Order reject reason; will be an error code.
"i": 4293153, // Order ID
"l": "0.00000000", // Last executed quantity
"z": "0.00000000", // Cumulative filled quantity
"L": "0.00000000", // Last executed price
"n": "0", // Commission amount
"N": null, // Commission asset
"T": 1499405658657, // Transaction time
"t": -1, // Trade ID
"I": 8641984, // Ignore
"w": true, // Is the order on the book?
"m": false, // Is this trade the maker side?
"M": false, // Ignore
"O": 1499405658657, // Order creation time
"Z": "0.00000000", // Cumulative quote asset transacted quantity
"Y": "0.00000000", // Last quote asset transacted quantity (i.e. lastPrice * lastQty)
"Q": "0.00000000" //Quote Order Quantity
}
Payload B
{
"e": "listStatus", //Event Type
"E": 1564035303637, //Event Time
"s": "ETHBTC", //Symbol
"g": 2, //OrderListId
"c": "OCO", //Contingency Type
"l": "EXEC_STARTED", //List Status Type
"L": "EXECUTING", //List Order Status
"r": "NONE", //List Reject Reason
"C": "F4QN4G8DlFATFlIUQ0cjdD", //List Client Order ID
"T": 1564035303625, //Transaction Time
"O": [ //An array of objects
{
"s": "ETHBTC", //Symbol
"i": 17, // orderId
"c": "AJYsMjErWJesZvqlJCTUgL" //ClientOrderId
},
{
"s": "ETHBTC",
"i": 18,
"c": "bfYPSQdLoqAJeNrOr9adzq"
}
]
}
Orders are updated with the executionReport
event.
Check the REST API Documentation and below for relevant enum definitions.
Average price can be found by doing Z
divided by z
.
Execution types:
- NEW - The order has been accepted into the engine
- CANCELED - The order has been canceled by the user
- REPLACED - This is currently unused
- REJECTED - The order has been rejected and was not processed(this is never pushed into the User Data Stream)
- TRADE - Part of the order or all of the order's quantity has been filled
- 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)
If the order is an OCO, an event will be displayed named ListStatus
in addition to the executionReport
event.
Balance Update
Payload
{
"e": "balanceUpdate", //Event Type
"E": 1573200697110, //Event Time
"a": "BTC", //Asset
"d": "100.00000000", //Balance Delta
"T": 1573200697068 //Clear Time
}
Balance Update occurs during deposits or withdrawals from the account.
placeholder
Get API Keys
Creating a private API key provides access to markets and real-time trading services on Binance.US via a third-party site or application.
To create an API key, login to Binance.US with your account details and go to Settings > API management.
Support
Contact Support
To contact support please submit a ticket here.