NAV
Shell Python

Introduction

Welcome to the Binance.US API Documentation!

Our REST APIs offer access to:

Our WebSocket Steams offer access to:

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 timestamp related fields are in milliseconds.

Making Requests

Data Sources

These are the three sources, ordered by which is has the most up-to-date response to the one with potential delays in updates.

Some endpoints can have more than 1 data source. (e.g. Memory => Database) This means that the endpoint will check the first Data Source, and if it cannot find the value it's looking for it will check the next one.

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.

Enum Definitions

Symbol status (status):

Symbol type:

Order status (status):

Status Description
NEW The order has been accepted by the engine.
PARTIALLY_FILLED A part of the order has been filled.
FILLED The order has been completed.
CANCELED The order has been canceled by the user.
PENDING_CANCEL Currently unused
REJECTED The order was not accepted by the engine and not processed.
EXPIRED The order was canceled according to the order type's rules (e.g. LIMIT FOK orders with no fill, LIMIT IOC or MARKET orders that partially fill)
or by the exchange, (e.g. orders canceled during liquidation, orders canceled during maintenance)

OCO Status (listStatusType):

Status Description
RESPONSE This is used when the ListStatus is responding to a failed action. (E.g. Orderlist placement or cancellation)
EXEC_STARTED The order list has been placed or there is an update to the order list status.
ALL_DONE The order list has finished executing and thus no longer active.

OCO Order Status (listOrderStatus):

Status Description
EXECUTING Either an order list has been placed or there is an update to the status of the list.
ALL_DONE An order list has completed execution and thus no longer active.
REJECT The List Status is responding to a failed action either during order placement or order canceled

ContingencyType

Order types (orderTypes, type):

Order side (side):

Time in force (timeInForce):

Status Description
GTC Good Til Canceled
An order will be on the book unless the order is canceled.
IOC Immediate Or Cancel
An order will try to fill the order as much as it can before the order expires.
FOK Fill or Kill
An order will expire if the full order cannot be filled upon execution.

Kline/Candlestick chart intervals:

m -> minutes; h -> hours; d -> days; w -> weeks; M -> months

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
}

Rate limit intervals (interval)

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, login to Binance.US with your account details and go to Settings > API management.

Authentication Types

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
}

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'

Here is a step-by-step example of how to send a vaild 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

Server/Network Errors

- 1000 UNKNOWN

- 1001 DISCONNECTED

- 1002 UNAUTHORIZED

- 1003 TOO_MANY_REQUESTS

- 1006 UNEXPECTED_RESP

- 1007 TIMEOUT

- 1014 UNKNOWN_ORDER_COMPOSITION

- 1015 TOO_MANY_ORDERS

- 1016 SERVICE_SHUTTING_DOWN

- 1020 UNSUPPORTED_OPERATION

- 1021 INVALID_TIMESTAMP

- 1022 INVALID_SIGNATURE

Request Errors

- 1100 ILLEGAL_CHARS

- 1101 TOO_MANY_PARAMETERS

- 1102 MANDATORY_PARAM_EMPTY_OR_MALFORMED

- 1103 UNKNOWN_PARAM

- 1104 UNREAD_PARAMETERS

- 1105 PARAM_EMPTY

- 1106 PARAM_NOT_REQUIRED

- 1111 BAD_PRECISION

- 1112 NO_DEPTH

- 1114 TIF_NOT_REQUIRED

- 1115 INVALID_TIF

- 1116 INVALID_ORDER_TYPE

- 1117 INVALID_SIDE

- 1118 EMPTY_NEW_CL_ORD_ID

- 1119 EMPTY_ORG_CL_ORD_ID

- 1120 BAD_INTERVAL

- 1121 BAD_SYMBOL

- 1125 INVALID_LISTEN_KEY

- 1127 MORE_THAN_XX_HOURS

- 1128 OPTIONAL_PARAMS_BAD_COMBO

- 1130 INVALID_PARAMETER

- 2010 NEW_ORDER_REJECTED

- 2011 CANCEL_REJECTED

- 2013 NO_SUCH_ORDER

- 2014 BAD_API_KEY_FMT

- 2015 REJECTED_MBX_KEY

- 2016 NO_TRADING_WINDOW

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 which 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 disabled is 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 when 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 is 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

IP Limits

Order Rate Limits

Withdrawal Rate Limits

Changelog

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

Test connectivity to the Rest API.

Weight: 1

Parameters: NONE

Data Source: Memory

Get Server Time

Example

curl 'https://api.binance.us/api/v3/time'

import requests

resp = requests.get('https://api.binance.us/api/v3/time')

print(resp.json())

Response

{
  "serverTime": 1499827319559
}

GET /api/v3/time

Test connectivity to the Rest API and get the current server time.

Weight: 1

Parameters: NONE

Data Source: Memory

Get System Status

Example

curl 'https://api.binance.us/wapi/v3/systemStatus.html'

import requests

resp = requests.get('https://api.binance.us/wapi/v3/systemStatus.html')

print(resp.json())

Response

{ 
    "status": 0,              // 0: normal，1：system maintenance
    "msg": "normal"           // normal or system maintenance
}

GET /wapi/v3/systemStatus.html

Fetch system status.

Exchange Information

Get Exchange Information

Example

curl 'https://api.binance.us/api/v3/exchangeInfo'

import requests

resp = requests.get('https://api.binance.us/api/v3/exchangeInfo')

print(resp.json())

Response

{
  "timezone": "UTC",
  "serverTime": 1565246363776,
  "rateLimits": [
    {
      //These are defined in the `ENUM definitions` section under `Rate Limiters (rateLimitType)`.
      //All limits are optional
    }
  ],
  "exchangeFilters": [
    //These are the defined filters in the `Filters` section.
    //All filters are optional.
  ],
  "symbols": [
    {
      "symbol": "ETHBTC",
      "status": "TRADING",
      "baseAsset": "ETH",
      "baseAssetPrecision": 8,
      "quoteAsset": "BTC",
      "quotePrecision": 8,
      "quoteAssetPrecision": 8,
      "baseCommissionPrecision": 8,
      "quoteCommissionPrecision": 8,
      "orderTypes": [
        "LIMIT",
        "LIMIT_MAKER",
        "MARKET",
        "STOP_LOSS",
        "STOP_LOSS_LIMIT",
        "TAKE_PROFIT",
        "TAKE_PROFIT_LIMIT"
      ],
      "icebergAllowed": true,
      "ocoAllowed": true,
      "quoteOrderQtyMarketAllowed": true,
      "isSpotTradingAllowed": true,
      "isMarginTradingAllowed": false,
      "filters": [
        //These are defined in the Filters section.
        //All filters are optional
      ]
    }
  ],
  "permissions": [
     "SPOT"
  ]
}

GET /api/v3/exchangeInfo

Current exchange trading rules and symbol information

Weight: 10

Parameters:

There are 3 possible options:

Options Example
No parameter curl -X GET "https://api.binance.com/api/v3/exchangeInfo"
symbol curl -X GET "https://api.binance.com/api/v3/exchangeInfo?symbol=BNBBTC"
symbols curl -X GET "https://api.binance.com/api/v3/exchangeInfo?symbols=BNBBTC,BTCUSDT"
symbols curl -g GET 'https://api.binance.com/api/v3/exchangeInfo?symbols=["BTCUSDT","BNBBTC"]'

Data Source: Memory

Market Data Endpoints

Trade Data

Get Recent Trades

Example

curl -X "GET" "https://api.binance.us/api/v3/trades?symbol=LTCBTC"

import requests

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

print(resp.json())

Response

[
  {
    "id": 981492,
    "price": "0.00380100",
    "qty": "0.22000000",
    "quoteQty": "0.00083622",
    "time": 1637128016269,
    "isBuyerMaker": false,
    "isBestMatch": true
  },
]

GET /api/v3/trades

Get recent trades (up to last 500).

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

Get older trades.

Weight: 5

Parameters:

Name Type Mandatory Description
symbol STRING YES
limit INT NO Default 500; max 1000.
fromId LONG NO TradeId to fetch from. Default gets most recent trades.

Data Source: Database

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

Get compressed, aggregate trades. Trades that fill at the time, from the same order, with the same price will have the quantity aggregated.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
fromId LONG NO ID to get aggregate trades from INCLUSIVE.
startTime LONG NO Timestamp in ms to get aggregate trades from INCLUSIVE.
endTime LONG NO Timestamp in ms to get aggregate trades until INCLUSIVE.
limit INT NO Default 500; max 1000.

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

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

Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
interval ENUM YES
startTime LONG NO
endTime LONG NO
limit INT NO Default 500; max 1000.

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

Latest price for a symbol or symbols.

Weight: 1 for a single symbol; 2 when the symbol parameter is omitted

Parameters:

Name Type Mandatory Description
symbol STRING NO

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

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

Best price/qty on the order book for a symbol or symbols.

Weight: 1 for a single symbol; 2 when the symbol parameter is omitted

Parameters:

Name Type Mandatory Description
symbol STRING NO

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

24 hour rolling window price change statistics. Careful when accessing this with no symbol.

Weight: 1 for a single symbol; 40 when the symbol parameter is omitted

Parameters:

Name Type Mandatory Description
symbol STRING NO

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)

Get current account information.

Weight: 10

Parameters:

Name Type Mandatory Description
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Data Source: Database

Get User Account Status

Example

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>

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

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

curl -X "GET" "$api_url/wapi/v3/accountStatus.html?timestamp=$timestamp&signature=$signature" \
     -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
import base64
import requests
import time

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

# get binanceus signature
def get_binanceus_signature(data, secret):
    postdata = urllib.parse.urlencode(data)
    message = postdata.encode()
    byte_key = bytes(secret, 'UTF-8')
    mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
    return mac

# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
    headers = {}
    headers['X-MBX-APIKEY'] = api_key
    signature = get_binanceus_signature(data, api_sec) 
    params={
        **data,
        "signature": signature,
        }           
    req = requests.get((api_url + uri_path), params=params, headers=headers)
    return req.text

api_key=<your_api_key>
secret_key=<your_secret_key>

uri_path = "/wapi/v3/accountStatus.html"
data = {
    "timestamp": int(round(time.time() * 1000)),
}

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

Response

// Response A
{
    "msg": "Order failed:Low Order fill rate! Will be reactivated after 5 minutes.",
    "success": true,
    "objs": [
        "5"
    ]
}

// Response B
{
    "msg":"Normal",
    "success":true
}

GET /wapi/v3/accountStatus.html

Fetch account status detail.

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Get User API Trading Status

Example 

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>

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

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

curl -X "GET" "$api_url/wapi/v3/apiTradingStatus.html?timestamp=$timestamp&signature=$signature" \
     -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
import base64
import requests
import time

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

# get binanceus signature
def get_binanceus_signature(data, secret):
    postdata = urllib.parse.urlencode(data)
    message = postdata.encode()
    byte_key = bytes(secret, 'UTF-8')
    mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
    return mac

# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
    headers = {}
    headers['X-MBX-APIKEY'] = api_key
    signature = get_binanceus_signature(data, api_sec) 
    params={
        **data,
        "signature": signature,
        }           
    req = requests.get((api_url + uri_path), params=params, headers=headers)
    return req.text

api_key=<your_api_key>
secret_key=<your_secret_key>

uri_path = "/wapi/v3/apiTradingStatus.html"
data = {
    "timestamp": int(round(time.time() * 1000)),
}

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

Response

{
    "success": true,     // Query result
    "status": {          // API trading status detail
        "isLocked": false,   // API trading function is locked or not
        "plannedRecoverTime": 0,  // If API trading function is locked, this is the planned recover time
        "triggerCondition": { 
            "GCR": 150,  // Number of GTC orders
            "IFER": 150, // Number of FOK/IOC orders
            "UFR": 300   // Number of orders
        },
        "indicators": {  // The indicators updated every 30 seconds
           "BTCUSDT": [  // The symbol
            {
            "i": "UFR",  // Unfilled Ratio (UFR)
            "c": 20,     // Count of all orders
            "v": 0.05,   // Current UFR value
            "t": 0.995   // Trigger UFR value
            },
            {
            "i": "IFER", // IOC/FOK Expiration Ratio (IFER)
            "c": 20,     // Count of FOK/IOC orders
            "v": 0.99,   // Current IFER value
            "t": 0.99    // Trigger IFER value
            },
            {
            "i": "GCR",  // GTC Cancellation Ratio (GCR)
            "c": 20,     // Count of GTC orders
            "v": 0.99,   // Current GCR value
            "t": 0.99    // Trigger GCR value
            }
            ],
            "ETHUSDT": [ 
            {
            "i": "UFR",
            "c": 20,
            "v": 0.05,
            "t": 0.995
            },
            {
            "i": "IFER",
            "c": 20,
            "v": 0.99,
            "t": 0.99
            },
            {
            "i": "GCR",
            "c": 20,
            "v": 0.99,
            "t": 0.99
            }
            ]
        },
        "updateTime": 1547630471725   // The query result return time
    }
}

GET /wapi/v3/apiTradingStatus.html

Fetch account api trading status detail.

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Get User Maker/Taker Rates

Example 

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>

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

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

curl -X "GET" "$api_url/wapi/v3/tradeFee.html?timestamp=$timestamp&signature=$signature" \
     -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
import base64
import requests
import time

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

# get binanceus signature
def get_binanceus_signature(data, secret):
    postdata = urllib.parse.urlencode(data)
    message = postdata.encode()
    byte_key = bytes(secret, 'UTF-8')
    mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
    return mac

# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
    headers = {}
    headers['X-MBX-APIKEY'] = api_key
    signature = get_binanceus_signature(data, api_sec) 
    params={
        **data,
        "signature": signature,
        }           
    req = requests.get((api_url + uri_path), params=params, headers=headers)
    return req.text

api_key=<your_api_key>
secret_key=<your_secret_key>

uri_path = "/wapi/v3/tradeFee.html"
data = {
    "timestamp": int(round(time.time() * 1000)),
}

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

Response

{
    "tradeFee": [{
        "symbol": "ADABNB",
        "maker": 0.9000,
        "taker": 1.0000
    }, {
        "symbol": "BNBBTC",
        "maker": 0.3000,
        "taker": 0.3000
    }],
    "success": true
}

GET /wapi/v3/tradeFee.html (HMAC SHA256)

Fetch trade fee.

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES
symbol STRING NO

Convert Small Balances to BNB

Example

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>
asset=<asset>

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

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

curl -X "POST" "$api_url/sapi/v1/asset/dust" \
    -H "X-MBX-APIKEY: $api_key" \
    -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
    --data-urlencode "asset=$asset&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>
asset=<asset>

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

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

Response

{
    "totalServiceCharge":"0.02102542",
    "totalTransfered":"1.05127099",
    "transferResult":[
        {
            "amount":"0.03000000",
            "fromAsset":"ETH",
            "operateTime":1563368549307,
            "serviceChargeAmount":"0.00500000",
            "tranId":2970932918,
            "transferedAmount":"0.25000000"
        },
        {
            "amount":"0.09000000",
            "fromAsset":"LTC",
            "operateTime":1563368549404,
            "serviceChargeAmount":"0.01548000",
            "tranId":2970932918,
            "transferedAmount":"0.77400000"
        },
        {
            "amount":"248.61878453",
            "fromAsset":"TRX",
            "operateTime":1563368549489,
            "serviceChargeAmount":"0.00054542",
            "tranId":2970932918,
            "transferedAmount":"0.02727099"
        }
    ]
}

POST /sapi/v1/asset/dust (HMAC SHA256)

Convert dust assets to BNB.

Weight: 1

Parameters:

Name Type Mandatory Description
asset ARRAY YES The asset being converted. For example: asset=BTC&asset=USDT
recvWindow LONG NO
timestamp LONG YES

Query Convert Small Balances to BNB 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/wapi/v3/userAssetDribbletLog.html?timestamp=$timestamp&signature=$signature" \
     -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
import base64
import requests
import time

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

# get binanceus signature
def get_binanceus_signature(data, secret):
    postdata = urllib.parse.urlencode(data)
    message = postdata.encode()
    byte_key = bytes(secret, 'UTF-8')
    mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
    return mac

# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
    headers = {}
    headers['X-MBX-APIKEY'] = api_key
    signature = get_binanceus_signature(data, api_sec) 
    params={
        **data,
        "signature": signature,
        }           
    req = requests.get((api_url + uri_path), params=params, headers=headers)
    return req.text

api_key=<your_api_key>
secret_key=<your_secret_key>

uri_path = "/wapi/v3/userAssetDribbletLog.html"
data = {
    "timestamp": int(round(time.time() * 1000)),
}

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

Response

{
    "success": true, 
    "results": {
        "total": 2,   //Total counts of exchange
        "rows": [
            {
                "transfered_total": "0.00132256",//Total transfered BNB amount for this exchange.
                "service_charge_total": "0.00002699",   //Total service charge amount for this exchange.
                "tran_id": 4359321,
                "logs": [           //Details of  this exchange.
                    {
                        "tranId": 4359321,
                        "serviceChargeAmount": "0.000009",
                        "uid": "10000015",
                        "amount": "0.0009",
                        "operateTime": "2018-05-03 17:07:04",
                        "transferedAmount": "0.000441",
                        "fromAsset": "USDT"
                    },
                    {
                        "tranId": 4359321,
                        "serviceChargeAmount": "0.00001799",
                        "uid": "10000015",
                        "amount": "0.0009",
                        "operateTime": "2018-05-03 17:07:04",
                        "transferedAmount": "0.00088156",
                        "fromAsset": "ETH"
                    }
                ],
                "operate_time": "2018-05-03 17:07:04" //The time of this exchange.
            },
            {
                "transfered_total": "0.00058795",
                "service_charge_total": "0.000012",
                "tran_id": 4357015,
                "logs": [       // Details of  this exchange.
                    {
                        "tranId": 4357015,
                        "serviceChargeAmount": "0.00001",
                        "uid": "10000015",
                        "amount": "0.001",
                        "operateTime": "2018-05-02 13:52:24",
                        "transferedAmount": "0.00049",
                        "fromAsset": "USDT"
                    },
                    {
                        "tranId": 4357015,
                        "serviceChargeAmount": "0.000002",
                        "uid": "10000015",
                        "amount": "0.0001",
                        "operateTime": "2018-05-02 13:51:11",
                        "transferedAmount": "0.00009795",
                        "fromAsset": "ETH"
                    }
                ],
                "operate_time": "2018-05-02 13:51:11"
            }
        ]
    }
}

GET /wapi/v3/userAssetDribbletLog.html (HMAC SHA256)

Fetch small amounts of assets exchanged BNB records.

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Query Asset Dividend History

Example 

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>

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

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

curl -X "GET" "$api_url/sapi/v1/asset/assetDividend?timestamp=$timestamp&signature=$signature" \
     -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
import base64
import requests
import time

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

# get binanceus signature
def get_binanceus_signature(data, secret):
    postdata = urllib.parse.urlencode(data)
    message = postdata.encode()
    byte_key = bytes(secret, 'UTF-8')
    mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
    return mac

# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
    headers = {}
    headers['X-MBX-APIKEY'] = api_key
    signature = get_binanceus_signature(data, api_sec) 
    params={
        **data,
        "signature": signature,
        }           
    req = requests.get((api_url + uri_path), params=params, headers=headers)
    return req.text

api_key=<your_api_key>
secret_key=<your_secret_key>

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

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

Response

{
    "rows":[
        {
            "amount":"10.00000000",
            "asset":"BHFT",
            "divTime":1563189166000,
            "enInfo":"BHFT distribution",
            "tranId":2968885920
        },
        {
            "amount":"10.00000000",
            "asset":"BHFT",
            "divTime":1563189165000,
            "enInfo":"BHFT distribution",
            "tranId":2968885920
        }
    ],
    "total":2
}

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

Query asset dividend record.

Weight: 1

Parameters:

Name Type Mandatory Description
asset STRING NO
startTime LONG NO
endTime LONG NO
recvWindow LONG NO
timestamp LONG YES

Sub-account Data

Query Sub-account Information

Example 

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>

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

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

curl -X "GET" "$api_url/wapi/v3/sub-account/list.html?timestamp=$timestamp&signature=$signature" \
     -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
import base64
import requests
import time

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

# get binanceus signature
def get_binanceus_signature(data, secret):
    postdata = urllib.parse.urlencode(data)
    message = postdata.encode()
    byte_key = bytes(secret, 'UTF-8')
    mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
    return mac

# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
    headers = {}
    headers['X-MBX-APIKEY'] = api_key
    signature = get_binanceus_signature(data, api_sec) 
    params={
        **data,
        "signature": signature,
        }           
    req = requests.get((api_url + uri_path), params=params, headers=headers)
    return req.text

api_key=<your_api_key>
secret_key=<your_secret_key>

uri_path = "/wapi/v3/sub-account/list.html"
data = {
    "timestamp": int(round(time.time() * 1000)),
}

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

Response

{
    "success":true,
    "subAccounts":[
        {
            "email":"123@test.com",
            "status":"enabled",
            "activated":true,
            "mobile":"91605290",
            "gAuth":true,
            "createTime":1544433328000
        },
        {
            "email":"321@test.com",
            "status":"disabled",
            "activated":true,
            "mobile":"22501238",
            "gAuth":true,
            "createTime":1544433328000
        }
    ]
}

GET /wapi/v3/sub-account/list.html (HMAC SHA256)

Fetch 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

Query Sub-account Transfer History

Example 

# Get HMAC SHA256 signature

timestamp=`date +%s000`
email=<your_email>

api_key=<your_api_key>
secret_key=<your_secret_key>

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

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

curl -X "GET" "$api_url/wapi/v3/sub-account/transfer/history.html?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=<your_email>

uri_path = "/wapi/v3/sub-account/transfer/history.html"
data = {
    "timestamp": int(round(time.time() * 1000)),
    "email": email
}

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

Response

{
    "success":true,
    "transfers":[
        {
            "from":"aaa@test.com",
            "to":"bbb@test.com",
            "asset":"BTC",
            "qty":"1",
            "time":1544433328000
        },
        {
            "from":"bbb@test.com",
            "to":"ccc@test.com",
            "asset":"ETH",
            "qty":"2",
            "time":1544433328000
        }
    ]
}

GET /wapi/v3/sub-account/transfer/history.html (HMAC SHA256)

Fetch transfer history list

Weight: 1

Parameters:

Name Type Mandatory Description
email STRING YES Sub-account email
startTime LONG NO Default return the history with in 100 days
endTime LONG NO Default return the history with in 100 days
page INT NO Default value: 1
limit INT NO Default value: 500
recvWindow LONG NO
timestamp LONG YES

Execute Sub-account Transfer

Example 

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>

fromEmail=<your_from_email>
toEmail=<your_to_email>
asset=<asset>
amount=<amount>

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

signature=`echo -n "fromEmail=$fromEmail&toEmail=$toEmail&asset=$asset&amount=$amount&timestamp=$timestamp" | openssl dgst -sha256 -hmac $secret_key`

curl -X "POST" "$api_url/wapi/v3/sub-account/transfer.html" \
    -H "X-MBX-APIKEY: $api_key" \
    -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
    --data-urlencode "fromEmail=$fromEmail&toEmail=$toEmail&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>
fromEmail=<your_from_email>
toEmail=<your_to_email>
asset=<asset>
amount=<amount>

uri_path = "/wapi/v3/sub-account/transfer.html"
data = {
    "timestamp": int(round(time.time() * 1000)),
    "asset": asset,
    "amount": amount,
    "fromEmail": fromEmail,
    "toEmail": toEmail
}

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

Response

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

POST /wapi/v3/sub-account/transfer.html (HMAC SHA256)

Execute sub-account transfer

Weight: 1

Parameters:

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

Query Sub-account Assets

Example 

# Get HMAC SHA256 signature

timestamp=`date +%s000`

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

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

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

curl -X "GET" "$api_url/wapi/v3/sub-account/assets.html?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=<your_email>

uri_path = "/wapi/v3/sub-account/assets.html"
data = {
    "timestamp": int(round(time.time() * 1000)),
    "email": email
}

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

Response

{
    "success":true,
    "balances":[
        {
            "asset":"ADA",
            "free":10000,
            "locked":0
        },
        {
            "asset":"BNB",
            "free":10003,
            "locked":0
        },
        {
            "asset":"BTC",
            "free":11467.6399,
            "locked":0
        },
        {
            "asset":"ETH",
            "free":10004.995,
            "locked":0
        },
        {
            "asset":"USDT",
            "free":11652.14213,
            "locked":0
        }
    ]
}

GET /wapi/v3/sub-account/assets.html (HMAC SHA256)

Fetch sub-account assets

Weight: 1

Parameters:

Name Type Mandatory Description
email STRING YES Sub account email
recvWindow LONG NO
timestamp LONG YES
symbol STRING NO

Trade Order Endpoints

General Orders

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)

Send in a new order.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
side ENUM YES
type ENUM YES
timeInForce ENUM NO
quantity DECIMAL NO
quoteOrderQty DECIMAL NO
price DECIMAL NO
newClientOrderId STRING NO A unique id among open orders. Automatically generated if not sent.
Orders with the same newClientOrderID can be accepted only when the previous one is filled, otherwise the order will be rejected.
stopPrice DECIMAL NO Used with STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.
icebergQty DECIMAL NO Used with LIMIT, STOP_LOSS_LIMIT, and TAKE_PROFIT_LIMIT to create an iceberg order.
newOrderRespType ENUM NO Set the response JSON. ACK, RESULT, or FULL; MARKET and LIMIT order types default to FULL, all other orders default to ACK.
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Some additional mandatory parameters based on order type:

Type Additional mandatory parameters Additional Information
LIMIT timeInForce, quantity, price
MARKET quantity or quoteOrderQty MARKET orders using the quantity field specifies the amount of the base asset the user wants to buy or sell at the market price.
E.g. MARKET order on BTCUSDT will specify how much BTC the user is buying or selling.

MARKET orders using quoteOrderQty specifies the amount the user wants to spend (when buying) or receive (when selling) the quote asset; the correct quantity will be determined based on the market liquidity and quoteOrderQty.
E.g. Using the symbol BTCUSDT:
BUY side, the order will buy as many BTC as quoteOrderQty USDT can.
SELL side, the order will sell as much BTC needed to receive quoteOrderQty USDT.
STOP_LOSS quantity, stopPrice This will execute a MARKET order when the stopPrice is reached.
STOP_LOSS_LIMIT timeInForce, quantity, price, stopPrice
TAKE_PROFIT quantity, stopPrice This will execute a MARKET order when the stopPrice is reached.
TAKE_PROFIT_LIMIT timeInForce, quantity, price, stopPrice
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:

Trigger order price rules against market price for both MARKET and LIMIT versions:

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)

Test new order creation and signature/recvWindow long. Creates and validates a new order but does not send it into the matching engine.

Weight: 1

Parameters:

Same as POST /api/v3/order

Data Source: Memory

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

Check an order's status.

Weight: 2

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO
origClientOrderId STRING NO
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Notes:

Data Source: Database

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

Get all open orders on a symbol. Careful when accessing this with no symbol.

Weight: 3 for a single symbol; 40 when the symbol parameter is omitted

Parameters:

Name Type Mandatory Description
symbol STRING NO
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

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)

Cancel an active order.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO
origClientOrderId STRING NO
newClientOrderId STRING NO Used to uniquely identify this cancel. Automatically generated by default.
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Either orderId or origClientOrderId must be sent.

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

Cancels all active orders on a 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

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

Get trades for a specific account and symbol.

Weight: 10 with symbol

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO This can only be used in combination with symbol.
startTime LONG NO
endTime LONG NO
fromId LONG NO TradeId to fetch from. Default gets most recent trades.
limit INT NO Default 500; max 1000.
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Notes: * If fromId is set, it will get 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

Send in a new OCO

Parameters:

Name Type Mandatory Description
symbol STRING YES
listClientOrderId STRING NO A unique Id for the entire orderList
side ENUM YES
quantity DECIMAL YES
limitClientOrderId STRING NO A unique Id for the limit order
price DECIMAL YES
limitIcebergQty DECIMAL NO
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:

Data Source: Matching Engine

Query 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

Retrieves a specific OCO based on provided optional parameters

Parameters:

Name Type Mandatory Description
orderListId LONG NO Either orderListId or listClientOrderId must be provided
origClientOrderId STRING NO Either orderListId or listClientOrderId must be provided
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Data Source: Database

Query 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

Retrieves all OCO based on provided optional parameters

Parameters

Name Type Mandatory Description
fromId LONG NO If supplied, neither startTime or endTime can be provided
startTime LONG NO
endTime LONG NO
limit INT NO Default Value: 500; Max Value: 1000
recvWindow LONG NO The value cannot be greater than 60000
timestamp LONG YES

Data Source: Database

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

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

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:

Data Source: Matching Engine

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/wapi/v3/assetDetail.html?timestamp=$timestamp&signature=$signature" \
     -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
import base64
import requests
import time

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

# get binanceus signature
def get_binanceus_signature(data, secret):
    postdata = urllib.parse.urlencode(data)
    message = postdata.encode()
    byte_key = bytes(secret, 'UTF-8')
    mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
    return mac

# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
    headers = {}
    headers['X-MBX-APIKEY'] = api_key
    signature = get_binanceus_signature(data, api_sec) 
    params={
        **data,
        "signature": signature,
        }           
    req = requests.get((api_url + uri_path), params=params, headers=headers)
    return req.text

api_key=<your_api_key>
secret_key=<your_secret_key>

uri_path = "/wapi/v3/assetDetail.html"
data = {
    "timestamp": int(round(time.time() * 1000))
}

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

Response

{
    "success": true,
    "assetDetail": {
        "CTR": {
            "minWithdrawAmount": "70.00000000", //min withdraw amount
            "depositStatus": false,//deposit status
            "withdrawFee": 35, // withdraw fee
            "withdrawStatus": true, //withdraw status
            "depositTip": "Delisted, Deposit Suspended" //reason
        },
        "SKY": {
            "minWithdrawAmount": "0.02000000",
            "depositStatus": true,
            "withdrawFee": 0.01,
            "withdrawStatus": true
        }   
    }
}

GET /wapi/v3/assetDetail.html (HMAC SHA256)

Fetch asset detail.

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Withdrawals

Withdraw Crypto

Example 

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>
asset=<asset>
address=<address>
amount=<amount>

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

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

curl -X "POST" "$api_url/wapi/v3/withdraw.html" \
    -H "X-MBX-APIKEY: $api_key" \
    -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
    --data-urlencode "asset=$asset&address=$address&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>
asset=<asset>
address=<address>
amount=<amount>

uri_path = "/wapi/v3/withdraw.html"
data = {
    "asset": asset,
    "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

{
    "msg": "success",
    "success": true,
    "id":"7213fea8e94b4a5593d507237e5a555b"
}

POST /wapi/v3/withdraw.html (HMAC SHA256)

Submit a crypto withdraw request.

Weight: 1

Parameters:

Name Type Mandatory Description
asset STRING YES
address STRING YES
addressTag STRING NO Secondary address identifier for coins like XRP,XMR etc.
amount DECIMAL YES
name STRING NO Description of the address
recvWindow LONG NO
timestamp LONG YES

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)

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

Query 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/wapi/v3/withdrawHistory.html?timestamp=$timestamp&signature=$signature" \
     -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
import base64
import requests
import time

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

# get binanceus signature
def get_binanceus_signature(data, secret):
    postdata = urllib.parse.urlencode(data)
    message = postdata.encode()
    byte_key = bytes(secret, 'UTF-8')
    mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
    return mac

# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
    headers = {}
    headers['X-MBX-APIKEY'] = api_key
    signature = get_binanceus_signature(data, api_sec) 
    params={
        **data,
        "signature": signature,
        }           
    req = requests.get((api_url + uri_path), params=params, headers=headers)
    return req.text

api_key=<your_api_key>
secret_key=<your_secret_key>

uri_path = "/wapi/v3/withdrawHistory.html"
data = {
    "timestamp": int(round(time.time() * 1000))
}

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

Response

{
    "withdrawList": [
        {
            "id":"7213fea8e94b4a5593d507237e5a555b",
            "amount": 1,
            "address": "0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b",
            "asset": "ETH",
            "txId": "0xdf33b22bdb2b28b1f75ccd201a4a4m6e7g83jy5fc5d5a9d1340961598cfcb0a1",
            "applyTime": 1508198532000,
            "status": 4
        },
        {
            "id":"7213fea8e94b4a5534ggsd237e5a555b",
            "amount": 1000,
            "address": "463tWEBn5XZJSxLU34r6g7h8jtxuNcDbjLSjkn3XAXHCbLrTTErJrBWYgHJQyrCwkNgYvyV3z8zctJLPCZy24jvb3NiTcTJ",
            "addressTag": "342341222",
            "txId": "b3c6219639c8ae3f9cf010cdc24fw7f7yt8j1e063f9b4bd1a05cb44c4b6e2509",
            "asset": "XMR",
            "applyTime": 1508198532000,
            "status": 4
        }
    ]
    "success": true
}

GET /wapi/v3/withdrawHistory.html (HMAC SHA256)

Fetch crypto withdraw history.

Weight: 1

Parameters:

Name Type Mandatory Description
asset STRING NO
status INT NO 0(0:Email Sent,1:Cancelled 2:Awaiting Approval 3:Rejected 4:Processing 5:Failure 6Completed)
startTime LONG NO
endTime LONG NO
recvWindow LONG NO
timestamp LONG YES

Query Fiat(USD) 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)

Fetch USD withdraw 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

Deposits

Get Deposit Address

Example 

# Get HMAC SHA256 signature

timestamp=`date +%s000`

api_key=<your_api_key>
secret_key=<your_secret_key>
asset=<asset>

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

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

curl -X "GET" "$api_url/wapi/v3/depositAddress.html?asset=$asset&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>
asset=<asset>

uri_path = "/wapi/v3/depositAddress.html"
data = {
    "asset": asset,
    "timestamp": int(round(time.time() * 1000))
}

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

Response

{
    "address": "0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b",
    "success": true,
    "addressTag": "1231212",
    "asset": "BNB"
}

GET /wapi/v3/depositAddress.html (HMAC SHA256)

Fetch deposit address.

Weight: 1

Parameters:

Name Type Mandatory Description
asset STRING YES
status Boolean NO
recvWindow LONG NO
timestamp LONG YES

Query Crypto 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/wapi/v3/depositHistory.html?timestamp=$timestamp&signature=$signature" \
     -H "X-MBX-APIKEY: $api_key"

import urllib.parse
import hashlib
import hmac
import base64
import requests
import time

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

# get binanceus signature
def get_binanceus_signature(data, secret):
    postdata = urllib.parse.urlencode(data)
    message = postdata.encode()
    byte_key = bytes(secret, 'UTF-8')
    mac = hmac.new(byte_key, message, hashlib.sha256).hexdigest()
    return mac

# Attaches auth headers and returns results of a POST request
def binanceus_request(uri_path, data, api_key, api_sec):
    headers = {}
    headers['X-MBX-APIKEY'] = api_key
    signature = get_binanceus_signature(data, api_sec) 
    params={
        **data,
        "signature": signature,
        }           
    req = requests.get((api_url + uri_path), params=params, headers=headers)
    return req.text

api_key=<your_api_key>
secret_key=<your_secret_key>

uri_path = "/wapi/v3/depositHistory.html"
data = {
    "timestamp": int(round(time.time() * 1000))
}

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

Response

{
    "depositList": [
        {
            "insertTime": 1508198532000,
            "amount": 0.04670582,
            "asset": "ETH",
            "address": "0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b",
            "txId": "0xdf33b22bdb2b28b1f75ccd201a4a4m6e7g83jy5fc5d5a9d1340961598cfcb0a1",
            "status": 1
        },
        {
            "insertTime": 1508298532000,
            "amount": 1000,
            "asset": "XMR",
            "address": "463tWEBn5XZJSxLU34r6g7h8jtxuNcDbjLSjkn3XAXHCbLrTTErJrBWYgHJQyrCwkNgYvyV3z8zctJLPCZy24jvb3NiTcTJ",
            "addressTag": "342341222",
            "txId": "b3c6219639c8ae3f9cf010cdc24fw7f7yt8j1e063f9b4bd1a05cb44c4b6e2509",
            "status": 1
        }
    ],
    "success": true
}

GET /wapi/v3/depositHistory.html (HMAC SHA256)

Fetch deposit history.

Weight: 1

Parameters:

Name Type Mandatory Description
asset STRING NO
status INT NO 0(0:pending,6: credited but cannot withdraw, 1:success)
startTime LONG NO
endTime LONG NO
recvWindow LONG NO
timestamp LONG YES

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

Fetch 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

Filters

Filters define trading rules on a symbol or an exchange.

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

Symbol Filters

Price Filter

/exchangeInfo format:

{
  "filterType": "PRICE_FILTER",
  "minPrice": "0.00000100",
  "maxPrice": "100000.00000000",
  "tickSize": "0.00000100"
}

The PRICE_FILTER defines the price rules for a symbol. There are 3 parts:

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:

Percent Price Filter

/exchangeInfo format:

{
  "filterType": "PERCENT_PRICE",
  "multiplierUp": "1.3000",
  "multiplierDown": "0.7000",
  "avgPriceMins": 5
}

The PERCENT_PRICE filter defines valid range for a price based on the average of the previous trades. avgPriceMins is the number of minutes the average price is calculated over. 0 means the last price is used.

In order to pass the percent price, the following must be true for price:

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 3 parts:

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

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 3 parts:

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

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 defined as the sum of the account's:

  1. free balance of the base asset
  2. locked balance of the base asset
  3. 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

WebSocket Rate Limits

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

Subscribe to a Stream

Request

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

Response

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

Unsubscribe to a Stream

Request

  {
    "method": "UNSUBSCRIBE",
    "params": [
      "btcusdt@depth"
    ],
    "id": 312
  }

Response

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

List Subscriptions

Request

  {
    "method": "LIST_SUBSCRIPTIONS",
    "id": 3
  }

Response

  {
    "result": [
      "btcusdt@aggTrade"
    ],
    "id": 3
  }

Set Properties

Currently, the only property can be set is to set 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

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 push 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 used to locally manage an order book.

Stream Name: <symbol>@depth OR <symbol>@depth@100ms

Update Speed: 1000ms or 100ms

Managing a Local Order Book

  1. Open a stream to wss://stream.binance.us:9443/ws/bnbbtc@depth
  2. Buffer the events you receive from the stream
  3. Get a depth snapshot from https://www.binance.us/api/v1/depth?symbol=BNBBTC&limit=1000
  4. Drop any event where u is <= lastUpdateId in the snapshot
  5. The first processed should have U <= lastUpdateId+1 AND u >= lastUpdateId+1
  6. While listening to the stream, each new event's U should be equal to the previous event's u+1
  7. The data in each event is the absolute quantity for a price level
  8. If the quantity is 0, remove the price level
  9. Receiving an event that removes a price level that is not in your local order book can happen and is normal.

User Data Streams

User Data Endpoints

Create User Data Stream

Example

curl -X "POST" "https://api.binance.us/api/v3/userDataStream" \
    -H "X-MBX-APIKEY: <your_api_key>" 

import requests

headers = {}
headers['X-MBX-APIKEY'] = <your_api_key>

resp = requests.post('https://api.binance.us/api/v3/userDataStream', headers=headers)
print(resp.json())

Response

{
  "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}

POST /api/v3/userDataStream

Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent. If the account has an active listenKey, that listenKey will be returned and its validity will be extended for 60 minutes.

Weight: 1

Parameters: NONE

Extend User Data Stream

Example 

curl -X "PUT" "https://api.binance.us/api/v3/userDataStream" \
    -H "X-MBX-APIKEY: <your_api_key>"  \
    -d 'listenKey=<listen_key>'

import requests

headers = {}
headers['X-MBX-APIKEY'] = <your_api_key>

data={
  "listenKey": <listen_key>
}

resp = requests.put('https://api.binance.us/api/v3/userDataStream', params=data, headers=headers)

print(resp.json())

Response

{}

PUT /api/v3/userDataStream

Keepalive a user data stream to prevent a time out. User data streams will close after 60 minutes. It's recommended to send a ping about every 30 minutes.

Weight: 1

Parameters:

Name Type Mandatory Description
listenKey STRING YES

Close User Data Stream

Example 

curl -X "DELETE" "https://api.binance.us/api/v3/userDataStream" \
    -H "X-MBX-APIKEY: <your_api_key>" \
    -d 'listenKey=<listen_key>'

import requests

headers = {}
headers['X-MBX-APIKEY'] = <your_api_key>

data={
  "listenKey": <listen_key>
}

resp = requests.delete('https://api.binance.us/api/v3/userDataStream', data=data, headers=headers)

print(resp.json())

Response

{}

DELETE /api/v3/userDataStream

Close out a user data stream.

Weight: 1

Parameters:

Name Type Mandatory Description
listenKey STRING YES

User Data Stream Payloads

Account Update

{
  "e": "outboundAccountPosition", //Event type
  "E": 1564034571105,             //Event Time
  "u": 1564034571073,             //Time of last account update
  "B": [                          //Balances Array
    {
      "a": "ETH",                 //Asset
      "f": "10000.000000",        //Free
      "l": "0.000000"             //Locked
    }
  ]
}

The event outboundAccountPosition is sent any time an account balance has changed and contains the assets that were possibly changed by the event that generated the balance change.

Order Update

Payload A

{
  "e": "executionReport",        // Event type
  "E": 1499405658658,            // Event time
  "s": "ETHBTC",                 // Symbol
  "c": "mUvoqJxFIILMdfAW5iGSOW", // Client order ID
  "S": "BUY",                    // Side
  "o": "LIMIT",                  // Order type
  "f": "GTC",                    // Time in force
  "q": "1.00000000",             // Order quantity
  "p": "0.10264410",             // Order price
  "P": "0.00000000",             // Stop price
  "F": "0.00000000",             // Iceberg quantity
  "g": -1,                       // OrderListId
  "C": "",                       // Original client order ID; This is the ID of the order being canceled
  "x": "NEW",                    // Current execution type
  "X": "NEW",                    // Current order status
  "r": "NONE",                   // Order reject reason; will be an error code.
  "i": 4293153,                  // Order ID
  "l": "0.00000000",             // Last executed quantity
  "z": "0.00000000",             // Cumulative filled quantity
  "L": "0.00000000",             // Last executed price
  "n": "0",                      // Commission amount
  "N": null,                     // Commission asset
  "T": 1499405658657,            // Transaction time
  "t": -1,                       // Trade ID
  "I": 8641984,                  // Ignore
  "w": true,                     // Is the order on the book?
  "m": false,                    // Is this trade the maker side?
  "M": false,                    // Ignore
  "O": 1499405658657,            // Order creation time
  "Z": "0.00000000",             // Cumulative quote asset transacted quantity
  "Y": "0.00000000",             // Last quote asset transacted quantity (i.e. lastPrice * lastQty)
  "Q": "0.00000000"              //Quote Order Quantity
}

Payload B

{
  "e": "listStatus",                //Event Type
  "E": 1564035303637,               //Event Time
  "s": "ETHBTC",                    //Symbol
  "g": 2,                           //OrderListId
  "c": "OCO",                       //Contingency Type
  "l": "EXEC_STARTED",              //List Status Type
  "L": "EXECUTING",                 //List Order Status
  "r": "NONE",                      //List Reject Reason
  "C": "F4QN4G8DlFATFlIUQ0cjdD",    //List Client Order ID
  "T": 1564035303625,               //Transaction Time
  "O": [                            //An array of objects
    {
      "s": "ETHBTC",                //Symbol
      "i": 17,                      // orderId
      "c": "AJYsMjErWJesZvqlJCTUgL" //ClientOrderId
    },
    {
      "s": "ETHBTC",
      "i": 18,
      "c": "bfYPSQdLoqAJeNrOr9adzq"
    }
  ]
}

Orders are updated with the executionReport event.

Check the Rest API Documentation and below for relevant enum definitions.

Average price can be found by doing Z divided by z.

Execution types:

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 deposit or withdrawals from the account.

placeholder

Get API Keys

Creating a private API key provides access to markets and real-time trading services on Binance.US via a third-party site or application.

To create an API key, login to Binance.US with your account details and go to Settings > API management.

Support

Contact Support

To contact support please submit a ticket here.

Shell Python