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 APIs offer access to:

• Market data
• Trade order management
• User account data
• User data stream

Our WebSocket Steams offer access to:

• Market data streams
• User data streams

Authentication

Get API Keys

Important Reminder For Binance.US API Key Users

• Do not disclose your API Key to anyone to avoid asset losses. It is recommended to bind IP for API Key to increase your account security.
• Be aware that your API Key may be disclosed by authorizing it to a third-party platform.
• You will not be able to create an API if KYC is not completed.
• Learn more about API key best practices and safety tips.

API Key Types

Binance.US currently offers three API key types: Exchange API Keys, Custodial Solution API Keys, and Credit Line API Keys. Please read on for more information on the differences and instructions on how to set up your key type.

Exchange API Keys

• Private API keys for the majority of API users to interact with Binance.US API endpoints.
• Provides access to markets and real-time trading services on Binance.US via a third-party site or application.

Get Exchange API Keys

To create this API key type:

1. Log into Binance.US with your account details

2. From the profile icon drop-down menu > select ‘API Management’

3. Enter a name for your API key for reference.

4. Click ‘Create.’ Enter your 2FA code to confirm when prompted

Custodial Solution API Keys

• Private API keys only available to users who have entered into a Custody Exchange Network agreement between a participating custody partner and Binance.US.
• Provides access to Custodial Solution related API endpoints only. To access other types of API endpoints, please generate other corresponding API keys.

Get Custodial Solution API Keys

After entering into a Custody Exchange Network agreement between a participating custody partner and Binance.US, users can create a Custodial Solution API key:

1. Log into Binance.US with your account details

2. From the profile icon drop-down menu > select ‘API Management’

3. Select ‘Custodial Solution API’’ and give your API key a label for reference

4. Click ‘Create.’ Enter your 2FA code to confirm when prompted

Credit Line API Keys

• Private API keys only available to institutional users who have signed a credit line agreement with Binance.US.
• Provides access to Credit Line related API endpoints only. To access other types of API endpoints, please generate other corresponding API keys.

Get Credit Line API Keys

After signing a credit line agreement with Binance.US, users can create a Credit Line API key:

1. Log into Binance.US with your account details

2. From the profile icon drop-down menu > select ‘API Management’

3. Select ‘Credit Line API’ and give your API key a label for reference

4. Click ‘Create.’ Enter your 2FA code to confirm when prompted

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.

Authentication Timing

if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
  // process request
} else {
  // reject request
}

• A SIGNED endpoint also requires a parameter and timestamp to be sent, which should be the millisecond timestamp of when the request was created and sent.
• An additional parameter, recvWindow, may be sent to specify the number of milliseconds after the timestamp that the request is valid for. If recvWindow is not sent, it defaults to 5,000.
• The 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&timestamp=1499827319559

# Get HMAC SHA256 signature
echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=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&timestamp=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&timestamp=1499827319559

# Get HMAC SHA256 signature
echo -n "symbol=BTCUSDT&timestamp=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&timestamp=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&timestamp=1499827319559

# Get HMAC SHA256 signature
shell echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000&timestamp=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&timestamp=1499827319559&signature=0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77'

• SIGNED endpoints require an additional parameter: signature, to be sent in the query string or request body.
• Endpoints use HMAC SHA256 signatures. The HMAC SHA256 signature is a keyed HMAC SHA256 operation. Use your secretKey as the key and totalParams as the value for the HMAC operation.
• The signature is not case sensitive.
• totalParams is defined as the query string concatenated with the request body.

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.

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 (Web Application Firewall) Limit has been violated.
• HTTP 409 return code is used when a cancelReplace order partially succeeds. (i.e. if the cancellation of the order fails but the new order placement succeeds.)
• HTTP 429 return code is used when breaking a request rate limit.
• HTTP 418 return code is used when an IP has been auto-banned for continuing to send requests after receiving 429 codes.
• HTTP 5XX return codes are used for internal errors; the issue is on 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 much request weight used; current limit is %s request weight per %s. Please use WebSocket Streams for live updates to avoid polling the API.
• Way too much request weight used; IP banned until %s. Please use WebSocket Streams 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.

- 1008 SERVER_BUSY

• Spot server is currently overloaded with other requests. Please try again in a few minutes.

- 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 was malformed.
• Mandatory parameter '%s' was not sent, was empty/null, or was 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.

- 1108 PARAM_OVERFLOW

• Parameter '%s' overflowed.

- 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 p arameter '%s' is not valid.

- 1135 INVALID_JSON

• Invalid JSON Request
• JSON sent for parameter '%s' is not valid

- 1145 INVALID_CANCEL_RESTRICTIONS

• cancelRestrictions has to be either ONLY_NEW or ONLY_PARTIALLY_FILLED.

- 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.

- 2021 Order cancel-replace partially failed

• This code is sent when either the cancellation of the order failed or the new order placement failed but not both.

- 2022 Order cancel-replace failed.

• This code is sent when both the cancellation of the order failed and the new order placement failed.

- 2026 ORDER_ARCHIVED

• Order was canceled or expired with no executed qty over 90 days ago and has been archived.

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:

Filter Failure Errors

Changelog

13/10/2023

Removed ‘Quick Enable Crypto Withdrawal’ and ‘Quick Disable Crypto Withdrawal’ endpoints.

20/9/2023

• Added ‘Withdraw Fiat via BITGO’ endpoint

13/9/2023

• Updated ‘Get Credit Line Account Information (C.L.)’ and ‘Get Alert History (C.L.)’ endpoints to support multi-asset loan.

6/9/2023

• Removed 1s candlestick interval

20/7/2023

• Removed order related Credit Line endpoints

26/6/2023

• Added ‘API Partner Endpoints’ section and updated ‘Get Asset Distribution History’ endpoint for API Partner Program.

9/6/2023

• Removed USD from Convert Dust

12/5/2023

• Spot WebSocket APIs are now available for Binance US.
  • WebSocket API allows placing orders, canceling orders, etc. through a WebSocket connection.
  • WebSocket API is a separate service from WebSocket Market Data streams. i.e., placing orders and listening to market data requires two separate WebSocket connections.
  • WebSocket API is subject to the same Filter and Rate Limit rules as REST API.
  • WebSocket API and REST API are functionally equivalent: they provide the same features, accept the same parameters, return the same status and error codes.
• The full documentation can be found here.

11/5/2023

• Trading parameters for 3 trading pairs have been updated. Click here to learn more.

17/4/2023

• Updated convert dust endpoints to support dust conversion to BNB/BTC/ETH/USD.

3/4/2023

• Removed ‘Withdraw Fiat (via SIGNET)’ endpoint

16/3/2023

• Improved error messages for certain issues for easier troubleshooting.

• Fixed error message for querying archived orders(status CANCELED or EXPIRED
  where executedQty == 0 in the last 90 days):
  • Previous error message:
    {
"code": -2013,
"msg": "Order does not exist."
}
    
  • Now error message:
    {
"code": -2026,
"msg": "Order was canceled or expired with no executed qty over 90 days ago and has been archived."
}
    

• Behavior for API requests with startTime and endTime:

  • Previously some requests failed if the startTime == endTime.
  • Now, all API requests that accept startTime and endTime allow the parameters to be equal. This applies to the following requests:
    • GET /api/v3/aggTrades
    • GET /api/v3/klines
    • GET /api/v3/allOrderList
    • GET /api/v3/allOrders
    • GET /api/v3/myTrades

• Changes to Filter Evaluation:

  • Previous behavior: LOT_SIZE and MARKET_LOT_SIZE required that (quantity -
    minQty) % stepSize == 0.
  • New behavior changed to: (quantity % stepSize) == 0.

• Bug fix with reverse MARKET orders (i.e. MARKET using quoteOrderQty):

  • Previous behavior: Reverse market orders would have the status FILLED even if the order was not fully filled.
  • New behavior: If the reverse market order did not fully fill due to low liquidity, the order status will be EXPIRED, and FILLED only if completely filled.

REST API

• Changes to DELETE /api/v3/order and POST /api/v3/order/cancelReplace:
  • New optional parameter cancelRestrictions that determines whether the cancel will succeed if the order status is NEW or PARTIALLY_FILLED.
  • If the order cancellation fails due to cancelRestrictions, error will be:
    {
"code": -2011,
"msg": "Order was not canceled due to cancel restrictions."
}
    
• Added a new endpoint to get all orders GET /api/v3/allOrders

2/3/2023

Trading parameters for 153 trading pairs have been updated. Click here to learn more.

23/2/2023

• New API Key Type (Credit Line): Added a new API Key type (Credit Line) and instructions for generating this key type in ‘Get API Keys.’
• Added Credit Line Endpoints: Added ‘Credit Line Endpoints’ section for new Credit Line API.

20/2/2023

• Withdraw Fiat (via SIGNET) updated to remove SEN channel.

24/1/2023

The changes to the system will take place on January 31, 2023.

Additional details on the functionality of STP is explained in the STP FAQ document.

Rest API

• Self-Trade Prevention (aka STP) has been added to the system. STP is a measure to prevent users from trading against their own account or other accounts that share the same tradeGroupId (such as parent and sub-accounts which belong to the same entity). The default and allowed modes of STP are as follows, and can be confirmed using GET /api/v3/exchangeInfo:
  "defaultSelfTradePreventionMode": "EXPIRE_MAKER", //If selfTradePreventionMode not provided, this will be the value passed to the engine
"allowedSelfTradePreventionModes": [//What the allowed modes of
selfTradePrevention are
"EXPIRE_MAKER",
"EXPIRE_TAKER",
"EXPIRE_BOTH"
]

• New order status: EXPIRED_IN_MATCH - This means that the order expired due to STP being triggered.

• New endpoints:

  • GET /api/v3/myPreventedMatches - This queries the orders that expired due to STP being triggered.

• New optional parameter selfTradePreventionMode has been added to the following endpoints:

  • POST /api/v3/order
  • POST /api/v3/order/oco
  • POST /api/v3/order/cancelReplace

• New responses that will appear for all order placement endpoints if there was a prevented match (i.e. if an order could have matched with an order of the same account, or the accounts are in the same tradeGroupId):

  • tradeGroupId - This will only appear if account is configured to a tradeGroupId and if there was a prevented match.
  • preventedQuantity - Only appears if there was a prevented match
  • An array preventedMatches with the following fields:
    • preventedMatchId
    • makerOrderId
    • price
    • takerPreventedQuantity - This will only appear if selfTradePreventionMode set is EXPIRE_TAKER or EXPIRE_BOTH .
    • makerPreventedQuantity - This will only appear if selfTradePreventionMode set is EXPIRE_MAKER or EXPIRE_BOTH .

• New fields preventedMatchId and preventedQuantity that can appear in the order query endpoints if the order had expired due to STP :

  • GET /api/v3/order
  • GET /api/v3/openOrders
  • GET /api/v3/allOrders

• New field tradeGroupId will appear in the GET /api/v3/account response.

USER DATA STREAM

• New execution Type: TRADE_PREVENTION
• New fields for executionReport (These fields will only appear if the order has expired due to STP)
  • u - tradeGroupId
  • v - preventedMatchId
  • U - counterOrderId
  • A - preventedQuantity
  • B - lastPreventedQuantity

18/1/2023

• ’Withdraw Fiat (via SEN or SIGNET)’ updated to support signet.
• ’Get All OTC Trade Orders’ and ‘Get All OCBS Trade Orders’ parameters updated. 90-day limit removed from both.
• ’Get User’s Spot Asset Snapshot’ API removed.

30/11/2022

WEBSOCKET

• !bookTicker removed.
  • Please use Individual Book Ticker streams (@bookTicker) instead.
  • Multiple streams can be subscribed to over one connection. (E.g. wss://stream.binance.us:9443/stream?streams=btcusdt@bookTicker/bnbbtc@bookTicker)

REST API

• New error code -1135 occurs if a parameter requiring a JSON object is invalid.
• New error code -1108 occurs if a value sent to a parameter is too large.
• Changes to GET /api/v3/aggTrades
  • startTime and endTime can now be used individually and the 1-hour limit has been removed.
• Changes to GET /api/v3/myTrades
  • Bug fixed: The combination of symbol + orderId no longer returns all trades beyond the 500 default limit.
  • Sending an unsupported combination of optional parameters now responds with generic error: { “code”: -1128, “msg”: “Combination of optional parameters invalid.” }.
• defaultSelfTradePreventionMode and allowedSelfTradePreventionModes fields will appear in GET /api/v3/exchangeInfo
• selfTradePreventionMode field will appear in the response for several order endpoints.
• requireSelfTradePrevention field will appear in the response for GET /api/v3/account
• workingTime field indicating when the order started working on the order book, will appear in several order endpoints.
• trailingTime field will appear in order types: (TAKE_PROFIT, TAKE_PROFIT_LIMIT, STOP_LOSS, STOP_LOSS_LIMIT if trailingDelta parameter was provided), for several order endpoints.
• commissionRates field will appear in the GET /api/v3/acccount response.

USER DATA STREAM

• eventType executionReport has new fields:
  • V - selfTradePreventionMode
  • D - trailing_time (Appears if the trailing stop order is active)
  • W - workingTime (Appears if the order is working on the order book)

16/11/2022

• Staking Endpoints: Added four new staking-focused endpoints, including:
  • Stake Asset: Initiate staking for a supported asset.
  • Unstake Asset: Unstake an asset that is currently staking.
  • Get Staking Asset Information: Information on staking asset(s) including reward asset received, APR, APY, unstaking period (hrs.), minimum and maximum staking amounts, and whether auto restaking is enabled.
  • Get Staking History: History of staking transactions for an asset in a given time period, including transaction amount, type, and initiation time.
• Revised Error Messages: Updated several API error messages related to staking for increased clarity.

15/11/2022

• New API Key Type (Custodial Solution): Added a new API Key type (Custodial Solution) and instructions for generating this key type in 'Get API Keys.'
• Added Custodial Solution API & Endpoints: Added 'Custodial Solution Endpoints' section for new Custodial Solution API. Contains four endpoint categories and 18 endpoints in total:
  • User Account Data (Custodial): Two endpoints.
  • Transfer (Custodial): Five endpoints.
  • Trade Order (Custodial): Nine endpoints.
  • Settlement (Custodial): Two endpoints.

11/4/2022

• Enabled trailing stop order: Updated three endpoints: POST /api/v3/order, POST /api/v3/order/test, POST /api/v3/order/oco, and added one new filter: TRAILING_DELTA, to support trailing stop orders. This type of stop order activates based on the percentage of a price change in the market using the new parameter: trailingDelta. This can be used with STOP_LOSS_LIMIT, or TAKE_PROFIT_LIMIT.
• Enabled replace order: Added one endpoint to cancel an existing order and place a new order with the same symbol.
• Scheduled changes: The All Book Tickers stream (!bookTicker) is set to be removed in late November 2022. Please use the Individual Book Ticker Streams instead. (<symbol>@bookTicker). Multiple <symbol>@bookTicker streams can be subscribed to over one connection. For example: wss://stream.binance.us:9443/stream?streams=btcusdt@bookTicker/bnbbtc@bookTicker
• Market Data: Added a new optional parameter type in two endpoints: GET /api/v3/ticker and GET /api/v3/ticker/24hr. Also removed Individual Symbol Ticker Streams as it duplicates with Ticker Order Book Stream, supported new candlestick chart interval: 1s.
• Get Asset Distribution History endpoint: Updated this endpoint to also query the rebate distribution record.
• Get Exchange Information endpoint: Added a service line permission parameter to display all symbols with the permission matching the value provided.

9/20/2022

• Updated trade fee API to reflect the manual fee adjustment.

8/12/2022

• User data endpoints: Added two endpoints to get trading fees and trading volume for the past 30 days.
• Convert dust to BNB endpoints: Added three endpoints to convert dust to BNB and query the conversion history and convertible assets.
• Staking endpoints: Added two endpoints to get staking balance and staking reward history.
• Market data endpoints: Added one endpoint to get price change data within a requested time window and updated four endpoints to support more parameter options.
• Market data streams: Added two ticker streams with 1h and 4h windows, individual symbol ticker streams, and all market ticker streams.
• Filters: Added three filters (percent price by side, notional, exchange maximum number iceberg orders) and updated the rules of price filters.
• Usability improvements: Fixed some language errors and improved the content.

6/15/2022

• User data endpoints: Migrated seven endpoints from WAPI to SAPI to improve performance and added five endpoints for status query and crypto withdrawals.
• Wallet endpoints: Added two endpoints to get sub-account deposit addresses and history.
• OTC endpoints: Added one OTC endpoint for users to query all OTC order details.
• Referral endpoints: Added one referral endpoint for users to get referral rewards history.
• Usability improvements: Made several improvements to content and readability.
• Miscellaneous updates: Temporarily removed the Get User Maker/Taker Rates endpoint. The endpoint will return in a future update.

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.
• Improved content readability and descriptions.

1/21/2022

• Added new OTC trade endpoints which support larger 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.

Support

Get API Support

Have questions about our APIs? Find the help you need in our Telegram support group.

Contact Customer Support

For non-API issues, please submit a ticket here.

REST API

General REST 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 times for the fields of staking, referrals, airdrops, etc. are in milliseconds.

Making Requests

• For GET endpoints, parameters must be sent as a query string.
• For POST, PUT, and DELETE endpoints, the parameters may be sent as a query string or in the request body with content type application/x-www-form-urlencoded. You may mix parameters between both the query string and request body if you wish to do so.
• Parameters may be sent in any order.
• If a parameter is sent in both the query string and request body, the query string parameter will be used.

Data Sources(REST)

• 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 from 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. If it cannot find the value it's looking for it will check the next one etc.

API Terminology

These terms will be used throughout the documentation, so it is recommended that you read them to enhance your understanding of the API (especially for new users).

• Base asset refers to the asset that is the quantity of a symbol; for the symbol BTCUSDT, BTC would be the base asset.
• Quote asset refers to the asset that is the price of a symbol; for the symbol BTCUSDT, USDT would be the quote asset.

Enum Definitions(REST)

Symbol status (status):

• PRE_TRADING
• TRADING
• POST_TRADING
• END_OF_DAY
• HALT
• AUCTION_MATCH
• BREAK

Symbol type:

• SPOT

Order status (status):

OCO Status (listStatusType):

OCO Order Status (listOrderStatus):

ContingencyType

• OCO

Order types (orderTypes, type):

• LIMIT
• MARKET
• STOP_LOSS_LIMIT
• TAKE_PROFIT_LIMIT
• LIMIT_MAKER

Order side (side):

• BUY
• SELL

Time in force (timeInForce):

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

Rate Limits(REST)

• The following are intervalLetter values for headers:
  • SECOND = S
  • MINUTE = M
  • HOUR = H
  • DAY = D
• The /api/v3/exchangeInfo rateLimits array contains objects related to the exchange's RAW_REQUEST, REQUEST_WEIGHT, and ORDER rate limits. These are further defined in the ENUM definitions section under Rate 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 heavier weight.
• REST API and WebSocket API are subject to the same Rate Limit rules.

IP Limits(REST)

• Every request will contain an X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter) header which has the currently used weight for the IP of all request rate limiters defined.
• Every successful order will contain an X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter) header which has the current order count for the IP of all order rate limiters defined. Rejected/unsuccessful orders are not guaranteed to have a X-MBX-ORDER-COUNT-** header in the response.

• When a 429 is received, it's your obligation as an API user/trader 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 response and will give the number of seconds required to wait to prevent a ban (for a 418) or until the ban is over (for a 429).

• The limits on the API are based on the IPs, not the API keys.

Order Rate Limits(REST)

• Every successful order response will contain an 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 a X-MBX-ORDER-COUNT-** header in the response.
• The order rate limit is counted against each account.

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 test connectivity to the exchange.

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 get the exchange’s server time.

Weight: 1

Parameters: NONE

Data Source: Memory

Get System 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/system/status?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/system/status"
data = {
   "timestamp": int(round(time.time() * 1000)),
}

result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))

Response

{
   "status": 0 // 0: normal, 1: system maintenance
}

GET /sapi/v1/system/status (HMAC SHA256)

Use this endpoint to fetch whether the system status is normal or under maintenance.

Weight: 1

Parameters:

Data Source: Memory

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,
      "allowTrailingStop": false
      "cancelReplaceAllowed": true,
      "isSpotTradingAllowed": true,
      "isMarginTradingAllowed": false,
      "filters": [
        //These are defined in the Filters section.
        //All filters are optional
      ]
    }
  ],
  "permissions": [
     "SPOT"
  ],
  "defaultSelfTradePreventionMode": "EXPIRE_MAKER", //If selfTradePreventionMode not provided, this will be the value passed to the engine
  "allowedSelfTradePreventionModes": [ //What the allowed modes of selfTradePrevention are
    "EXPIRE_MAKER",
    "EXPIRE_TAKER",
    "EXPIRE_BOTH"
    ]
}

GET /api/v3/exchangeInfo

Use this endpoint to get the current exchange trading rules and trading pair information.

Weight: 10

Parameters:

There are 4 possible options:

Notes:

• If the value provided to symbol or symbols do not exist, the endpoint will throw an error saying the symbol is invalid.
• All parameters are optional.
• If permissions parameter not provided, the default values will be ["SPOT"].

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:

Data Source: Memory

Get Historical Trades (MARKET_DATA)

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:

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 same 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:

• 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 order book depth (prices and quantities of bids and asks).

Weight(IP): Adjusted based on the limit:

Parameters:

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:

• 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 live ticker price.

Weight(IP):

Parameters:

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:

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 available order book price.

Weight(IP):

Parameters:

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 price change data for the past 24hrs.

Weight(IP):

Parameters:

• If the symbol is not sent, tickers for all symbols will be returned in an array.

Data Source: Memory

Get Rolling Window Price Change Statistics

Example

# Example A, symbol param provided
curl -X "GET" "https://api.binance.us/api/v3/ticker?symbol=BNBBTC"

# Example A, symbols param provided
curl -X "GET" "https://api.binance.us/api/v3/ticker?symbols=%5B%22BTCUSDT%22,%22BNBBTC%22%5D"

# Example A, symbol param provided
import requests

resp = requests.get('https://api.binance.us/api/v3/ticker?symbol=BNBBTC')

print(resp.json())

# Example B, symbols provided
import requests

resp = requests.get('https://api.binance.us/api/v3/ticker?symbols=%5B%22BTCUSDT%22,%22BNBBTC%22%5D')

print(resp.json())

Response A

{
  "symbol":             "BNBBTC",
  "priceChange":        "-8.00000000",  // Absolute price change
  "priceChangePercent": "-88.889",      // Relative price change in percent
  "weightedAvgPrice":   "2.60427807",   // QuoteVolume / Volume
  "openPrice":          "9.00000000",
  "highPrice":          "9.00000000",
  "lowPrice":           "1.00000000",
  "lastPrice":          "1.00000000",
  "volume":             "187.00000000",
  "quoteVolume":        "487.00000000", // Sum of (price * volume) for all trades
  "openTime":           1641859200000,  // Open time for ticker window
  "closeTime":          1642031999999,  // Current Time of the Request
  "firstId":            0,              // Trade IDs
  "lastId":             60,
  "count":              61              // Number of trades in the interval
}

Response B

[
  {
    "symbol": "BTCUSDT",
    "priceChange": "-154.13000000",
    "priceChangePercent": "-0.740",
    "weightedAvgPrice": "20677.46305250",
    "openPrice": "20825.27000000",
    "highPrice": "20972.46000000",
    "lowPrice": "20327.92000000",
    "lastPrice": "20671.14000000",
    "volume": "72.65112300",
    "quoteVolume": "1502240.91155513",
    "openTime": 1655432400000,
    "closeTime": 1655446835460,
    "firstId": 11147809,
    "lastId": 11149775,
    "count": 1967
  },
  {
    "symbol": "BNBBTC",
    "priceChange": "0.00008530",
    "priceChangePercent": "0.823",
    "weightedAvgPrice": "0.01043129",
    "openPrice": "0.01036170",
    "highPrice": "0.01049850",
    "lowPrice": "0.01033870",
    "lastPrice": "0.01044700",
    "volume": "166.67000000",
    "quoteVolume": "1.73858301",
    "openTime": 1655432400000,
    "closeTime": 1655446835460,
    "firstId": 2351674,
    "lastId": 2352034,
    "count": 361
  }
]

GET /api/v3/ticker

Use this endpoint to get the price change data within a requested window of time.

Note: openTime reverts to the start of the minute (e.g. 09:17:00 UTC, instead of 09:17:47:99). closeTime is the current time of the request (including seconds and milliseconds). Therefore, the effective window can be up to 59999ms (59 seconds) longer than the specified windowSize.

E.g. If the closeTime is 1641287867099 (January 04, 2022 09:17:47:099 UTC), and the windowSize is 1d. the openTime will be: 1641201420000 (January 3, 2022, 09:17:00 UTC).

Weight:

2 for each requested symbol regardless of windowSize.

The weight for this request will cap at 100 once the number of symbols in the request is more than 50.

Parameters:

Data Source: Database

User Data Endpoints

User Account Data

Get User Account Information (USER_DATA)

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,
    "commissionRates":{
        "maker":"0.00150000",
        "taker":"0.00150000",
        "buyer":"0.00000000",
        "seller":"0.00000000"
    },
    "canTrade":true,
    "canWithdraw":true,
    "canDeposit":true,
    "brokered":false,
    "requireSelfTradePrevention":false,
    "updateTime":123456789,
    "accountType":"SPOT",
    "balances":[
        {
            "asset":"BTC",
            "free":"4723846.89208129",
            "locked":"0.00000000"
        },
        {
            "asset":"LTC",
            "free":"4763368.68006011",
            "locked":"0.00000000"
        }
    ],
    "permissions":[
        "SPOT"
    ]
}

GET /api/v3/account (HMAC SHA256)

Use this endpoint to get current account information.

Weight: 10

Parameters:

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/sapi/v3/accountStatus?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/v3/accountStatus"
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 /sapi/v3/accountStatus (HMAC SHA256)

Use this endpoint to fetch account status details.

Weight: 1

Parameters:

Data Source: Database

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/sapi/v3/apiTradingStatus?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/v3/apiTradingStatus"
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 /sapi/v3/apiTradingStatus (HMAC SHA256)

Use this endpoint to fetch account API trading status details.

Weight: 1

Parameters:

Data Source: Database

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/assetDistributionHistory?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/assetDistributionHistory"
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,
            "category": "BHFT distribution",
            "tranId": 2968885920
        },
        {
            "amount": "10.00000000",
            "asset": "BHFT",
            "divTime": 1563189165000,
            "category": "BHFT distribution",
            "tranId": 2968885920
        }
    ],
    "total": 2
}

GET /sapi/v1/asset/assetDistributionHistory (HMAC SHA256)

Use this endpoint to query asset distribution records, including Market Maker Rebate, MM Streaks Rebate, API Partner Rebate and airdrop, etc.

Weight: 1

Parameters:

Data Source: database

Get Trade Fee

Example

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/query/trading-fee?timestamp=$timestamp&signature=$signature" \
    -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
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/query/trading-fee'
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

[
    {
        "symbol": "1INCHUSD",
        "makerCommission": "0.004",
        "takerCommission": "0.006"
    },
    {
        "symbol": "1INCHUSDT",
        "makerCommission": "0.004",
        "takerCommission": "0.006"
     }
]

GET /sapi/v1/asset/query/trading-fee (HMAC SHA256)

Use this endpoint to get your current maker & taker fee rates for spot trading based on your VIP level or manual fee adjustment. Discount for using BNB to pay fees (25% off) is not factored in.

Weight: 1

Parameters:

Data Source: Database

Get Past 30 days Trade Volume

Example

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/query/trading-volume?timestamp=$timestamp&signature=$signature" \
    -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
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>
uri_path = '/sapi/v1/asset/query/trading-volume'
data = {"timestamp": int(round(time.time() * 1000))}

result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))

Response

{
    "past30DaysTradingVolume": 100
}

GET /sapi/v1/asset/query/trading-volume (HMAC SHA256)

Use this endpoint to get total trade volume for the past 30 days, calculated on a rolling basis every day at 0:00 AM (UTC).

Weight: 1

Parameters: NONE

Data Source: Database

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/sapi/v3/sub-account/list?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/v3/sub-account/list"
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 /sapi/v3/sub-account/list (HMAC SHA256)

Use this endpoint to get your sub-account list.

Weight: 1

Parameters:

Data Source: Database

Get Sub-account Transfer 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/v3/sub-account/transfer/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/v3/sub-account/transfer/history"
data = {
    "timestamp": int(round(time.time() * 1000)),
}

result = binanceus_request(uri_path, data, api_key, secret_key)
print("GET {}: {}".format(uri_path, result))