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

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

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

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

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 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 request is valid for. If recvWindow 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&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.

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

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 have X-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's REQUESTS and ORDER 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 heavier weight.
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

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

Support

Contact Support

To contact support please submit a ticket here.

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

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,
      "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.us/api/v3/exchangeInfo"
symbol	curl -X GET "https://api.binance.us/api/v3/exchangeInfo?symbol=BNBBTC"
symbols	curl -X GET "https://api.binance.us/api/v3/exchangeInfo?symbols=BNBBTC,BTCUSDT"
symbols	curl -g GET 'https://api.binance.us/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/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:

Name	Type	Mandatory	Description
timestamp	LONG	YES

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:

Name	Type	Mandatory	Description
recvWindow	LONG	NO
timestamp	LONG	YES

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 staking, referrals and airdrops etc.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
asset	STRING	NO	Distribution asset
category	STRING	NO	Distribution category
startTime	LONG	NO	Distribution start time
endTime	LONG	NO	Distribution end time
limit	INT	NO	Limit rows(default: 20, max: 500)
timestamp	LONG	YES	Current timestamp

Data Source: database

Quick Disable Crypto Withdrawal

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 "POST" "$api_url/sapi/v1/account/quickDisableWithdrawal?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) 
    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/account/quickDisableWithdrawal"
data = {
    "timestamp": int(round(time.time() * 1000))
}

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

Post /sapi/v1/account/quickDisableWithdrawal (HMAC SHA256)

Use this endpoint to disable crypto withdrawals.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
timestamp	LONG	YES

Data Source: Database

Quick Enable Crypto Withdrawal

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 "POST" "$api_url/sapi/v1/account/quickEnableWithdrawal?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) 
    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/account/quickEnableWithdrawal"
data = {
    "timestamp": int(round(time.time() * 1000))
}

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

Post /sapi/v1/account/quickEnableWithdrawal (HMAC SHA256)

Use this endpoint to enable crypto withdrawals.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
timestamp	LONG	YES

Data Source: Database

Get User’s Spot Asset Snapshot

Example

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>
type=<type>
startTime=<startTime>
endTime=<endTime>
limit=<limit>

api_url="https://api.binance.us"

signature=`echo -n "type=$type&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/sapi/v1/accountSnapshot?type=$type&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>
snapshot_type='SPOT'

uri_path = "/sapi/v1/accountSnapshot"
data = {
    "type": snapshot_type,
    "timestamp": int(round(time.time() * 1000))
}

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

Response

{
    "code": 200,
    "msg": "",
    "snapshotVos": []
}

GET /sapi/v1/accountSnapshot (HMAC SHA256)

Use this endpoint to get a snapshot of user’s assets in spot orders.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
type	STRING	YES	The unique value is 'SPOT'
startTime	LONG	NO
endTime	LONG	NO
limit	INT	NO
offset	INT	NO	default value: 5
timestamp	LONG	YES

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:

Name	Type	Mandatory	Description
email	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

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

Response

{
  "msg": "string",
  "success": true,
  "transfers": [
    {
      "asset": "BNB",
      "from": "aa.email.com",
      "qty": "10",
      "time": 1637789299,
      "to": "bb.email.com"
    }
  ]
}

GET /sapi/v3/sub-account/transfer/history (HMAC SHA256)

Use this endpoint to fetch sub-account asset transfer history.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
email	STRING	NO	Sub-account email
startTime	LONG	NO
endTime	LONG	NO
page	INT	NO	The transfer history batch number (each batch contains at most 500 transfer history records)
limit	INT	NO	Default value: 500
timestamp	LONG	YES

Data Source Database

Execute Sub-account Transfer

Example

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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "POST" "$api_url/sapi/v3/sub-account/transfer?fromEmail=$fromEmail&toEmail=$toEmail&asset=$asset&amount=$amount&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)
    print('postdata: {}', postdata)
    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)
    print('Signature: {}', signature)
    payload={
        **data,
        "signature": signature,
    }          
    req = requests.post((api_url + uri_path), params=payload, headers=headers)
    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 = "/sapi/v3/sub-account/transfer"
data = {
    "asset": asset,
    "amount": amount,
    "toEmail": toEmail,
    "fromEmail": fromEmail,
    "timestamp": int(round(time.time() * 1000))
}

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

Response

{
  "msg": "Success",
  "success": true,
  "txnId": "2966662589"
}

POST /sapi/v3/sub-account/transfer(HMAC SHA256)

Use this endpoint to execute an asset transfer between the master account and a sub-account.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
fromEmail	STRING	YES	Sender email
toEmail	STRING	YES	Recipient email
asset	STRING	YES
amount	DECIMAL	YES
timestamp	LONG	YES

Data Source: Database

Get Sub-account Assets

Example

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>

api_url="https://api.binance.us"

email="ios@mt.com"

signature=`echo -n "email=$email&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/sapi/v3/sub-account/assets?email=$email&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>

your_email=<your_your_email>
uri_path = "/sapi/v3/sub-account/assets"
data = {
    "timestamp": int(round(time.time() * 1000)),"email": your_email
}

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

Response

{
    "balances":
    [
        {
            "asset":"BTC", //asset
            "Free":0, //free
            "Locked":0 //locked
        },
        {
            "asset":"BNB",
            "free":98,
            "locked":0
        },
        {
            "asset":"ETH",
            "free":0,
            "locked":0
        },
        {
            "asset":"LTC",
            "free":0,
            "locked":0
        },
        {
            "asset":"USDT",
            "free":0,
            "locked":0
        }
    ],
    "success":true
}

GET /sapi/v3/sub-account/assets (HMAC SHA256)

Use this endpoint to fetch sub-account assets.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
email	STRING	YES	Sub-account Email
timestamp	LONG	YES

Data Source: Database

Get Master Account's Total USD Value

Example

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>
email=<email>
page=<page>
size=<size>

api_url="https://api.binance.us"

signature=`echo -n "email=$email&page=$page&size=$size&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/sapi/v1/sub-account/spotSummary?email=$email&page=$page&size=$size&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>
email=<email>
page=<page>
size=<size>

uri_path = "/sapi/v1/sub-account/spotSummary"
data = {
    "email":email,
    "page":page,
    "size":size,
    "timestamp": int(round(time.time() * 1000))
}

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

Response

{
    "totalCount": 2,
    "masterAccountTotalAsset": 401,
    "spotSubUserAssetBtcVoList": [
        {
            "email": "test001@123.com",
            "totalAsset": 201
        }, 
        {
            "email": "test002@123.com",
            "totalAsset": 200
        }
    ]
}

GET /sapi/v1/sub-account/spotSummary (HMAC SHA256)

Use this endpoint to get the total value of assets in the master account in USD.

Weight: 1

Parameters:

Name	Type	Mandatory
email	STRING	NO
page	INT	NO
size	INT	NO
timestamp	LONG	YES

Data Source: Database

Get Sub-account Status List

Example

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>
email=<email>


api_url="https://api.binance.us"

signature=`echo -n "email=$email&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/sapi/v1/sub-account/status?email=$email&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>
email=<email>

uri_path = "/sapi/v1/sub-account/status"
data = {
    "email":email,
    "timestamp": int(round(time.time() * 1000))
}

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

Response

[
    {
        "email": "test001@123.com",
        "insertTime": 1652944721676,
        "mobile": "XXXXXXXXXX",
        "isUserActive": true,
        "isMarginEnabled": true,
        "isSubUserEnabled": false,
        "isFutureEnabled": false
    }, 
    {
        "email": "test002@123.com",
        "insertTime": 1652944721676,
        "mobile": "XXXXXXXXXX",
        "isUserActive": true,
        "isMarginEnabled": false,
        "isSubUserEnabled": true,
        "isFutureEnabled": false
    }
]

GET /sapi/v1/sub-account/status (HMAC SHA256)

Use this endpoint to get a status list of sub-accounts.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
email	STRING	YES
timestamp	LONG	YES

Data Source: Database

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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/api/v3/rateLimit/order?recvWindow=$recvWindow&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) 
    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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "POST" "$api_url/api/v3/order?symbol=$symbol&side=$side&type=$type&quantity=$quantity&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) 
    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 or LIMIT_MAKER type order can be made an iceberg order by sending an icebergQty.
Any order with an icebergQty MUST have timeInForce set to GTC.
MARKET orders using quoteOrderQty will not break LOT_SIZE filter rules; the order will execute a quantity with a notional value as close as possible to quoteOrderQty.

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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "POST" "$api_url/api/v3/order/test?symbol=$symbol&side=$side&type=$type&quantity=$quantity&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)   
    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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/api/v3/order?orderId=$orderId&symbol=$symbol&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>
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 or origClientOrderId 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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "DELETE" "$api_url/api/v3/order?orderId=$orderId&symbol=$symbol&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.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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "DELETE" "$api_url/api/v3/openOrders?symbol=$symbol&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.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 (HMAC SHA256)

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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/api/v3/myTrades?symbol=BNBBTC&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/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 >= that fromId. 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&timestamp=$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&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) 
    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 Price
- BUY: 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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/api/v3/orderList?orderListId=$orderListId&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>
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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "DELETE" "$api_url/api/v3/orderList?symbol=$symbol&orderListId=$orderListId&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.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/coinPairs?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/coinPairs"
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/coinPairs (HMAC SHA256)

Use this endpoint to get a list of supported coin pairs.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
fromCoin	STRING	NO	From coin name, e.g. BTC, SHIB
toCoin	STRING	NO	To coin name, e.g. USDT, KSHIB
timestamp	LONG	YES

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&timestamp=$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&timestamp=$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

{
    "symbol": "BTCUSDT", 
    "ratio": 50550.26,
    "inverseRatio": 0.00001978,
    "validTimestamp": 1641806714,
    "toAmount": 50550.26,
    "fromAmount": 1
}

POST /sapi/v1/otc/quotes (HMAC SHA256)

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. SHIB
toCoin	STRING	YES	To coin name, e.g. KSHIB
requestCoin	STRING	YES	Request coin name, e.g. SHIB
requestAmount	DECIMAL	YES	Amount of request coin, e.g. 50000
timestamp	LONG	YES

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&timestamp=$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&timestamp=$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 (HMAC SHA256)

Use this endpoint to place an order using an acquired quote.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
quoteId	STRING	YES	Quote ID, e.g. 15848701022
timestamp	LONG	YES

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} (HMAC SHA256)

Use this endpoint to query OTC trade order details.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
orderId	STRING	YES	Order ID, e.g., 10002349
timestamp	LONG	YES

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 (HMAC SHA256)

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	Description: Default: 10; max: 100
timestamp	LONG	YES

Data Source: Database

Get All OCBS 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/ocbs/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/ocbs/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

{
   "total": 2,
   "dataList": [
      {
        "quoteId": "4e5446f2cc6f44ab86ab02abf19a7654",
        "orderId": "10090821212", 
        "orderStatus": "SUCCESS",
        "fromCoin": "BTC",
        "fromAmount": 1,
        "toCoin": "USD",
        "toAmount": 50550.26,
        "feeCoin": "USD",
        "feeAmount": 0.26,
        "ratio": 50550.26,
        "createTime": 1641806714
      },
      {
        "quoteId": "4e5446f2cc6f44ab86ab02abf19abvd",
        "orderId": "1000238000", 
        "orderStatus": "FAIL",
        "fromCoin": "USD",
        "fromAmount": 1000.5,
        "toCoin": "ETH",
        "toAmount": 0.5,
        "feeCoin": "USD",
        "feeAmount": 0.5,
        "ratio": 2000,
        "createTime": 1641916714
      }
  ]
}

GET /sapi/v1/ocbs/orders (HMAC SHA256)

Use this endpoint to query all OCBS orders by condition.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
orderId	STRING	NO	Order ID
startTime	LONG	NO	Start timestamp
endTime	LONG	NO	End timestamp
limit	INT	NO	default: 10; max: 100
timestamp	LONG	YES

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

#!/bin/bash
# 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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

payload="coin=$coin&network=$network&address=$address&amount=$amount&timestamp=$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&timestamp=$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&timestamp=$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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/sapi/v1/capital/deposit/address?coin=$coin&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>
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
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&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/sapi/v1/capital/deposit/hisrec?coin=$coin&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>
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.

Get Sub-account Deposit Address

Example

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>

api_url="https://api.binance.us"

email="ios@mt.com"
coin="BNB"

signature=`echo -n "email=$email&coin=$coin&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/sapi/v1/capital/sub-account/deposit/address?email=$email&coin=$coin&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>
your_email=<your_your_email>
uri_path = "/sapi/v1/capital/sub-account/deposit/address"
data = {
    "timestamp": int(round(time.time() * 1000)), "email": your_email, "coin": "ETH"
}

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

Response

{
    "coin": "BNB", // coin
    "address": "0xf79b6274f18425441b8f05c0a711d171c0fe119f", // address
    "tag": "", //memo
    "url": "https://etherscan.io/address/0xf79b6274f18425441b8f05c0a711d171c0fe119f" //Blockchain browser address
}

GET /sapi/v1/capital/sub-account/deposit/address (HMAC SHA256)

Use this endpoint to fetch a sub-account’s deposit address.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
email	STRING	YES	Sub-account Email
coin	STRING	YES	coin
network	STRING	NO	Network (If empty, returns the default network)

Data Source: Database

Get Sub-account 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"

email="ios@mt.com"

signature=`echo -n "email=$email&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/sapi/v1/capital/sub-account/deposit/history?email=$email&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>
your_email=<your_your_email>
uri_path = "/sapi/v1/capital/sub-account/deposit/history"
data = {
    "timestamp": int(round(time.time() * 1000)), "email": your_email
}

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

Response

[
    {
        "amount": "9.9749",//deposit amount
        "coin": "BTC", //coin
        "network": "btc", //network
        "status": 4, 
        "address": "bc1qxurvdd7tzn09agdvg3j8xpm3f7e978y07wg83s",
        "addressTag": "",
        "txId": "0x1b4b8c8090d15e3c1b0476b1c19118b1f00066e01de567cd7bc5b6e9c100193f",
        "insertTime": 1652942429211,
        "transferType": 0,
        "confirmTimes": "0/0"
    }
]

GET /sapi/v1/capital/sub-account/deposit/history (HMAC SHA256)

Use this endpoint to fetch sub-account deposit history.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
email	STRING	YES	Sub-account Email
coin	STRING	NO	coin
status	INT	NO	0 (0:pending, 6:credited but cannot withdraw, 1:success)
startTime	LONG	NO
endTime	LONG	NO
limit	INT	NO
offset	INT	NO	default: 0

Data Source: Database

Referral Endpoints

Get Referral Reward History

Example


# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>
userBizType=<your userBizType>
page=<page>
rows=<row>

api_url="https://api.binance.us"

signature=`echo -n "userBizType=$userBizType&page=$page&rows=$rows&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "GET" "$api_url/sapi/v1/marketing/referral/reward/history?userBizType=$userBizType&page=$page&rows=$rows&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>
userBizType=<your userBizType>
page=<page>
rows=<row>

uri_path = "/sapi/v1/marketing/referral/reward/history"
data = {
    "userBizType": userBizType,
    "page": page,
    "rows": rows,
    "timestamp": int(round(time.time() * 1000))
}

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

Response

{
    "total": 1,
    "rows": [
        {
            "userId": 350991652,
            "rewardAmount": "8",
            "receiveDateTime": 1651131084091,
            "rewardType": "USD"
        }
    ]
}

GET /sapi/v1/marketing/referral/reward/history (HMAC SHA256)

Use this endpoint to get the user’s referral reward history.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
userBizType	INT	YES	user business type(0: referrer, 1: referee)
page	INT	YES
rows	INT	YES	min: 1, max: 200
timestamp	LONG	YES

Data Source: Database

Filters

Filters define trading rules on a symbol or an exchange.

Filters come in two forms: symbol filters and exchange filters.

Symbol Filters

/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 minimum price/stopPrice allowed; disabled on minPrice == 0.
maxPrice defines the maximum price/stopPrice allowed; disabled on maxPrice == 0.
tickSize defines the intervals that a price/stopPrice can be increased/decreased by; disabled on tickSize == 0.

Any of the above variables can be set to 0, which disables that rule in the price filter. In order to pass the price filter, the following must be true for price/stopPrice of the enabled rules:

price >= minPrice
price <= maxPrice
(price-minPrice) % tickSize == 0

/exchangeInfo format:

{
  "filterType": "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 minimum quantity/icebergQty allowed;
maxQty defines the maximum quantity/icebergQty allowed;
stepSize defines the intervals that a quantity/icebergQty can be increased/decreased by.

In order to pass the lot size, the following must be true for quantity/icebergQty:

quantity >= minQty
quantity <= maxQty
(quantity-minQty) % stepSize == 0

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 minimum quantity allowed;
maxQty defines the maximum quantity allowed;
stepSize defines the intervals that a quantity can be increased/decreased by.

In order to pass the market lot size, the following must be true for quantity:

quantity >= minQty
quantity <= maxQty
(quantity-minQty) % stepSize == 0

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 a pong frame back from the connection within a 10-minute period, the connection will be disconnected. Unsolicited pong 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 is null which means the request sent was a success for non-query requests (e.g., subscribing/unsubscribing).

Request

{
    "method": "SUBSCRIBE",
    "params": [
      "btcusdt@aggTrade",
      "btcusdt@depth"
    ],
    "id": 1
}

Response

{
    "result": null,
    "id": 1
}

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 a pong frame back from the connection within a 10-minute period, the connection will be disconnected. Unsolicited pong 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

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 AND u >= lastUpdateId+1
While listening to the stream, each new event's U should be equal to the previous event's u+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 a listenKey will extend its validity for 60 minutes.
Doing a DELETE on a listenKey will close the stream and invalidate the listenKey.
Doing a POST on an account with an active listenKey will return the currently active listenKey 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" </span>
    -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.