Navbar
简体中文

Change Log

2019-10-14


2019-10-11


2019-10-08


2019-09-20

General Info

General API Information

The error payload is as follows:

{
  "code": -1121,
  "msg": "Invalid symbol."
}

LIMITS

Endpoint Security Type

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.

SIGNED (TRADE and USER_DATA) Endpoint Security

Timing Security

The logic is as follows:

  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.

SIGNED Endpoint Examples for POST /fapi/v1/order

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 BTCUSDT
side BUY
type LIMIT
timeInForce GTC
quantity 1
price 0.1
recvWindow 5000
timestamp 1499827319559

Example 1: As a query string

Example 1

HMAC SHA256 signature:

    $ echo -n "symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
    (stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71

curl command:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://fapi.binance.com/fapi/v1/order?symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'

Example 2: As a request body

Example 2

HMAC SHA256 signature:

    $ echo -n "symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
    (stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71

curl command:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://fapi.binance.com/fapi/v1/order' -d 'symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'

Example 3: Mixed query string and request body

Example 3

HMAC SHA256 signature:

    $ echo -n "symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
    (stdin)= 0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77

curl command:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://fapi.binance.com/fapi/v1/order?symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77'

Note that the signature is different in example 3.
There is no & between "GTC" and "quantity=1".

Public Endpoints Info

Terminology

ENUM definitions

Symbol type:

Order status (status):

Order types (orderTypes, type):

Order side (side):

Time in force (timeInForce):

Kline/Candlestick chart intervals:

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

Rate limiters (rateLimitType)

REQUEST_WEIGHT

  {
    "rateLimitType": "REQUEST_WEIGHT",
    "interval": "MINUTE",
    "intervalNum": 1,
    "limit": 1200
  }

ORDERS

  {
    "rateLimitType": "ORDERS",
    "interval": "SECOND",
    "intervalNum": 1,
    "limit": 10
   }

Rate limit intervals (interval)

Filters

Filters define trading rules on a symbol or an exchange.

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:

LOT_SIZE

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

MARKET_LOT_SIZE

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

MAX_NUM_ORDERS

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

PERCENT_PRICE

ExchangeInfo format:

  {
    "filterType": "PERCENT_PRICE",
    "multiplierUp": "1.1500",
    "multiplierDown": "0.8500",
    "multiplierDecimal": 4
  }

The PERCENT_PRICE filter defines valid range for a price based on the mark price.

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

Market Data Endpoints

Test Connectivity

Response:

{}

GET /fapi/v1/ping

Test connectivity to the Rest API.

Weight: 1

Parameters: NONE

Check Server Time

Response:

{
  "serverTime": 1499827319559
}

GET /fapi/v1/time

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

Weight: 1

Parameters: NONE

Exchange Information (MARKET_DATA)

Response:

{
    "exchangeFilters": [],
    "rateLimits": [
        {
            "interval": "MINUTE",
            "intervalNum": 1,
            "limit": 6000,
            "rateLimitType": "REQUEST_WEIGHT"
        },
        {
            "interval": "MINUTE",
            "intervalNum": 1,
            "limit": 6000,
            "rateLimitType": "ORDERS"
        }
    ],
    "serverTime": 1565613908500,
    "symbols": [
        {
            "filters": [
                {
                    "filterType": "PRICE_FILTER",
                    "maxPrice": "10000000",
                    "minPrice": "0.00000100",
                    "tickSize": "0.00000100"
                },
                {
                    "filterType": "LOT_SIZE",
                    "maxQty": "10000000",
                    "minQty": "0.00100000",
                    "stepSize": "0.00100000"
                },
                {
                    "filterType": "MARKET_LOT_SIZE",
                    "maxQty": "10000000",
                    "minQty": "0.00100000",
                    "stepSize": "0.00100000"
                },
                {
                    "filterType": "MAX_NUM_ORDERS",
                    "limit": 100
                }
                {
                    "filterType": "PERCENT_PRICE",
                    "multiplierUp": "1.1500",
                    "multiplierDown": "0.8500",
                    "multiplierDecimal": 4
                }
            ],
            "maintMarginPercent": "2.5000",
            "pricePrecision": 2,
            "quantityPrecision": 3,
            "requiredMarginPercent": "5.0000",
            "status": "TRADING",
            "OrderType": [
                "LIMIT", 
                "MARKET", 
                "STOP",
                "TAKE_PROFIT"
            ],
            "symbol": "BTCUSDT",
            "timeInForce": [
                "GTC",    // Good Till Cancel 
                "IOC",    // Immediate or Cancel
                "FOK",    // Fill or Kill
                "GTX"     // Good Till Crossing
            ]
        }
    ],
    "timezone": "UTC"
}

GET /fapi/v1/exchangeInfo

Current exchange trading rules and symbol information

Weight: 1

Parameters: NONE

Order Book (MARKET_DATA)

Response:

{
  "lastUpdateId": 1027024,
  "bids": [
    [
      "4.00000000",     // PRICE
      "431.00000000"    // QTY
    ]
  ],
  "asks": [
    [
      "4.00000200",
      "12.00000000"
    ]
  ]
}

GET /fapi/v1/depth

Weight:

Adjusted based on the limit:

Limit Weight
5, 10, 20, 50, 100 1
500 5
1000 10

Parameters:

Name Type Mandatory Description
symbol STRING YES
limit INT NO Default 100; max 1000. Valid limits:[5, 10, 20, 50, 100, 500, 1000]

Recent Trades List (MARKET_DATA)

Response:

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "quoteQty": "8000.00",
    "time": 1499865549590,
    "isBuyerMaker": true,
  }
]

GET /fapi/v1/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.

Old Trades Lookup (MARKET_DATA)

Response:

[
  {
    "id": 28457,
    "price": "4.00000100",
    "qty": "12.00000000",
    "quoteQty": "8000.00",
    "time": 1499865549590,
    "isBuyerMaker": true,
  }
]

GET /fapi/v1/historicalTrades

Get older market historical 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.

Compressed/Aggregate Trades List (MARKET_DATA)

Response:

[
  {
    "a": 26129,         // Aggregate tradeId
    "p": "0.01633102",  // Price
    "q": "4.70443515",  // Quantity
    "f": 27781,         // First tradeId
    "l": 27781,         // Last tradeId
    "T": 1498793709153, // Timestamp
    "m": true,          // Was the buyer the maker?
  }
]

GET /fapi/v1/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.

Kline/Candlestick Data (MARKET_DATA)

Response:

[
  [
    1499040000000,      // Open time
    "0.01634790",       // Open
    "0.80000000",       // High
    "0.01575800",       // Low
    "0.01577100",       // Close
    "148976.11427815",  // Volume
    1499644799999,      // Close time
    "2434.19055334",    // Quote asset volume
    308,                // Number of trades
    "1756.87402397",    // Taker buy base asset volume
    "28.46694368",      // Taker buy quote asset volume
    "17928899.62484339" // Ignore.
  ]
]

GET /fapi/v1/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 1500.

Mark Price (MARKET_DATA)

Response:

{
    "symbol": "BTCUSDT",
    "markPrice": "11012.80409769",
    "lastFundingRate": "-0.03750000",
    "nextFundingTime": 1562569200000,
    "time": 1562566020000
}

GET /fapi/v1/premiumIndex

Mark Price and Funding Rate

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES

Get Funding Rate History (MARKET_DATA)

Response:

[
    {
        "symbol": "BTCUSDT",
        "fundingRate": "-0.03750000",
        "fundingTime": 1570608000000,
        "time": 1576566020000
    },
    {
        "symbol": "BTCUSDT",
        "fundingRate": "0.00010000",
        "fundingTime": 1570636800000,
        "time": 1576566020000
    }
]

GET /fapi/v1/fundingRate

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
startTime LONG NO Timestamp in ms to get funding rate from INCLUSIVE.
endTime LONG NO Timestamp in ms to get funding rate until INCLUSIVE.
limit INT NO Default 100; max 1096

24hr Ticker Price Change Statistics (MARKET_DATA)

Response:

{
  "symbol": "BTCUSDT",
  "priceChange": "-94.99999800",
  "priceChangePercent": "-95.960",
  "weightedAvgPrice": "0.29628482",
  "prevClosePrice": "0.10002000",
  "lastPrice": "4.00000200",
  "lastQty": "200.00000000",
  "openPrice": "99.00000000",
  "highPrice": "100.00000000",
  "lowPrice": "0.10000000",
  "volume": "8913.30000000",
  "quoteVolume": "15.30000000",
  "openTime": 1499783499040,
  "closeTime": 1499869899040,
  "firstId": 28385,   // First tradeId
  "lastId": 28460,    // Last tradeId
  "count": 76         // Trade count
}

OR

[
    {
        "symbol": "BTCUSDT",
        "priceChange": "-94.99999800",
        "priceChangePercent": "-95.960",
        "weightedAvgPrice": "0.29628482",
        "prevClosePrice": "0.10002000",
        "lastPrice": "4.00000200",
        "lastQty": "200.00000000",
        "openPrice": "99.00000000",
        "highPrice": "100.00000000",
        "lowPrice": "0.10000000",
        "volume": "8913.30000000",
        "quoteVolume": "15.30000000",
        "openTime": 1499783499040,
        "closeTime": 1499869899040,
        "firstId": 28385,   // First tradeId
        "lastId": 28460,    // Last tradeId
        "count": 76         // Trade count
    }
]

GET /fapi/v1/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

Symbol Price Ticker (MARKET_DATA)

Response:

{
  "symbol": "BTCUSDT",
  "price": "6000.01"
}

OR

[
    {
        "symbol": "BTCUSDT",
        "price": "6000.01"
    }
]

GET /fapi/v1/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

Symbol Order Book Ticker (MARKET_DATA)

Response:

{
  "symbol": "BTCUSDT",
  "bidPrice": "4.00000000",
  "bidQty": "431.00000000",
  "askPrice": "4.00000200",
  "askQty": "9.00000000"
}

OR

[
    {
        "symbol": "BTCUSDT",
        "bidPrice": "4.00000000",
        "bidQty": "431.00000000",
        "askPrice": "4.00000200",
        "askQty": "9.00000000"
    }
]

GET /fapi/v1/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

Websocket Market Streams

Aggregate Trade Streams

Payload:

{
  "e": "aggTrade",  // Event type
  "E": 123456789,   // Event time
  "s": "BTCUSDT",    // Symbol
  "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?
}

The Aggregate Trade Streams push trade information that is aggregated for a single taker order every 100 milliseconds.

Stream Name:
<symbol>@aggTrade

Mark Price Stream

Payload:

  {
    "e": "markPriceUpdate",  // Event type
    "E": 1562305380000,      // Event time
    "s": "BTCUSDT",          // Symbol
    "p": "11185.87786614",   // Mark price
    "r": "0.00030000",       // Funding rate
    "T": 1562306400000       // Next funding time
  }

Mark price for a single symbol pushed every 3 secends.

Stream Name:
<symbol>@markPrice

Kline/Candlestick Streams

Payload:

{
  "e": "kline",     // Event type
  "E": 123456789,   // Event time
  "s": "BTCUSDT",    // Symbol
  "k": {
    "t": 123400000, // Kline start time
    "T": 123460000, // Kline close time
    "s": "BTCUSDT",  // Symbol
    "i": "1m",      // Interva\
    "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 250 milliseconds (if existing).

Kline/Candlestick chart intervals:

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

Stream Name:
<symbol>@kline_<interval>

Individual Symbol Mini Ticker Stream

Payload:

  {
    "e": "24hrMiniTicker",  // Event type
    "E": 123456789,         // Event time
    "s": "BTCUSDT",         // Symbol
    "c": "0.0025",          // Close price
    "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
  }

24hr rolling window mini-ticker statistics for a single symbol pushed every 3 seconds. These are NOT the statistics of the UTC day, but a 24hr rolling window from requestTime to 24hrs before.

Stream Name:
<symbol>@miniTicker

Individual Symbol Ticker Streams

Payload:

{
  "e": "24hrTicker",  // Event type
  "E": 123456789,     // Event time
  "s": "BTCUSDT",     // Symbol
  "p": "0.0015",      // Price change
  "P": "250.00",      // Price change percent
  "w": "0.0018",      // Weighted average price
  "c": "0.0025",      // Last price
  "Q": "10",          // Last 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 rollwing window ticker statistics for a single symbol pushed every 3 seconds. These are NOT the statistics of the UTC day, but a 24hr rolling window from requestTime to 24hrs before.

Stream Name:
<symbol>@ticker

Partial Book Depth Streams

Payload:

{
  "e": "depthUpdate", // Event type
  "E": 123456789,     // Event time
  "s": "BTCUSDT",      // Symbol
  "U": 157,           // first update Id from last stream
  "u": 160,           // last update Id from last stream
  "pu": 149,          // last update Id in last stream(ie ‘u’ in last stream)
  "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
    ]
  ]
}

Bids and asks, pushed every 250 milliseconds (if existing)

Stream Name:
<symbol>@depth

How to manage a local order book correctly

  1. Open a stream to wss://fstream.binance.com/stream?streams=btcusdt@depth.
  2. Buffer the events you receive from the stream. For same price, latest received update covers the previous one.
  3. Get a depth snapshot from https://fapi.binance.com/fapi/v1/depth?symbol=BTCUSDT&limit=1000 .
  4. Drop any event where u is < lastUpdateId in the snapshot.
  5. The first processed event should have U <= lastUpdateId AND u >= lastUpdateId
  6. While listening to the stream, each new event's pu should be equal to the previous event's u, otherwise initialize the process from step 3.
  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.

Account/Trades Endpoints

New Future Account Transfer

Response:

{
    "tranId": 100000001    //transaction id
}

POST https://api.binance.com/sapi/v1/futures/transfer (HMAC SHA256)

Execute transfer between spot account and margin account.

Weight: 1

Parameters:

Name Type Mandatory Description
asset STRING YES The asset being transferred, e.g., USDT
amount DECIMAL YES The amount to be transferred
type INT YES 1: transfer from spot main account to future account 2: transfer from future account to spot main account
recvWindow LONG NO
timestamp LONG YES

Get Future Account Transaction History List (USER_DATA)

Response:

{
  "rows": [
    {
      "asset": "USDT",
      "tranId": 100000001
      "amount": "40.84624400",
      "type": "1"
      "timestamp": 1555056425000,
      "status": "CONFIRMED".          //one of PENDING (pending to execution), CONFIRMED (successfully transfered), FAILED (execution failed, nothing happened to your account);
    }
  ],
  "total": 1
}

GET https://api.binance.com/sapi/v1/futures/transfer (HMAC SHA256)

Weight: 5

Parameters:

Name Type Mandatory Description
asset STRING YES
startTime LONG YES
endTime LONG NO
current LONG NO Currently querying page. Start from 1. Default:1
size LONG NO Default:10 Max:100
recvWindow LONG NO
timestamp LONG YES

New Order (TRADE)

Response:

{
    "accountId": 10012,
    "clientOrderId": "testOrder",
    "cumQuote": "0",
    "executedQty": "0",
    "orderId": 22542179,
    "origQty": "10",
    "price": "10000",
    "reduceOnly": False,
    "side": "SELL",
    "status": "NEW",
    "stopPrice": "0",
    "symbol": "BTCUSDT",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "updateTime": 1566818724722
 }

POST /fapi/v1/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 YES
reduceOnly STRING NO Used with LIMIT orders: "true" or "false". Defalt "false".
price DECIMAL NO
newClientOrderId STRING NO A unique id for the order. Automatically generated if not sent.
stopPrice DECIMAL NO Used with STOP or TAKE_PROFIT orders.
recvWindow LONG NO
timestamp LONG YES

Additional mandatory parameters based on type:

Type Additional mandatory parameters
LIMIT timeInForce, quantity, price
MARKET quantity
STOP quantity, price, stopPrice
TAKE_PROFIT quantity, price, stopPrice

Query Order (USER_DATA)

Response:

{
  "symbol": "BTCUSDT",
  "orderId": 1,
  "clientOrderId": "myOrder1",
  "price": "0.1",
  "reduceOnly": False,
  "origQty": "1.0",
  "executedQty": "0.0",
  "cumQuote": "0.0",
  "status": "NEW",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "BUY",
  "stopPrice": "0.0",
  "time": 1499827319559,
  "updateTime": 1499827319559
}

GET /fapi/v1/order (HMAC SHA256)

Check an order's status.

Weight: 1

Parameters:

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

Notes:

Cancel Order (TRADE)

Response:

{
  "symbol": "BTCUSDT",
  "orderId": 28,
  "origClientOrderId": "myOrder1",
  "clientOrderId": "cancelMyOrder1",
  "transactTime": 1507725176595,
  "price": "1.00000000",
  "reduceOnly": False,
  "origQty": "10.00000000",
  "executedQty": "8.00000000",
  "cumQuote": "8.00000000",
  "status": "CANCELED",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "SELL"
}

DELETE /fapi/v1/order (HMAC SHA256)

Cancel an active order.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO
origClientOrderId STRING NO Automatically generated by default.
recvWindow LONG NO
timestamp LONG YES

Either orderId or origClientOrderId must be sent.

Current Open Orders (USER_DATA)

Response:

[
  {
    "symbol": "BTCUSDT",
    "orderId": 1,
    "clientOrderId": "myOrder1",
    "accountId": 1,
    "price": "0.1",
    "reduceOnly": False,
    "origQty": "1.0",
    "cumQty": "1.0",
    "cumQuote": "1.0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "updateTime": 1499827319559
  }
]

GET /fapi/v1/openOrders (HMAC SHA256)

Get all open orders on a symbol. 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
recvWindow LONG NO
timestamp LONG YES

All Orders (USER_DATA)

Response:

[
  {
    "symbol": "BTCUSDT",
    "orderId": 1,
    "clientOrderId": "myOrder1",
    "price": "0.1",
    "reduceOnly": False,
    "origQty": "1.0",
    "executedQty": "1.0",
    "cumQuote": "10.0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "updateTime": 1499827319559
  }
]

GET /fapi/v1/allOrders (HMAC SHA256)

Get all account orders; active, canceled, or filled.

Weight: 5 with symbol

Parameters:

Name Type Mandatory Description
symbol STRING YES
orderId LONG NO
startTime LONG NO
endTime LONG NO
limit INT NO Default 500; max 1000.
recvWindow LONG NO
timestamp LONG YES

Notes:

Future Account Balance (USER_DATA)

Response:

[
    {
        "accountId": 26
        "asset": "USDT"
        "balance": "122607.35137903"
        "withdrawAvailable": "102333.54137903"
    }
]

Get /fapi/v1/balance (HMAC SHA256)

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Account Information (USER_DATA)

Response:

{
    "assets": [
        {
            "asset": "USDT",
            "initialMargin": "9.00000000",
            "maintMargin": "0.00000000",
            "marginBalance": "22.12659734",
            "maxWithdrawAmount": "13.12659734",
            "openOrderInitialMargin": "9.00000000",
            "positionInitialMargin": "0.00000000",
            "unrealizedProfit": "0.00000000",
            "walletBalance": "22.12659734"
        }
    ],
    "canDeposit": True,
    "canTrade": True,
    "canWithdraw": True,
    "feeTier": 0,
    "maxWithdrawAmount": "13.12659734",
    "totalInitialMargin": "9.00000000",
    "totalMaintMargin": "0.00000000",
    "totalMarginBalance": "22.12659734",
    "totalOpenOrderInitialMargin": u"9.00000000",
    "totalPositionInitialMargin": u"0.00000000",
    "totalUnrealizedProfit": u"0.00000000",
    "totalWalletBalance": u"22.12659734",
    "updateTime": 0

}

GET /fapi/v1/account (HMAC SHA256)

Get current account information.

Weight: 5

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Position Information (USER_DATA)

Response:

[
    {
        "entryPrice": "9975.12000",
        "liquidationPrice": "7963.54",
        "markPrice": "9973.50770517",
        "positionAmt": "0.010",
        "symbol": "BTCUSDT",
        "unRealizedProfit": "-0.01612295"
    }
]

GET /fapi/v1/positionRisk (HMAC SHA256) Get current account information.

Weight: 5

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Account Trade List (USER_DATA)

Response:

[
  {
    "accountId": 20,
    "buyer": False,
    "commission": "-0.07819010",
    "commissionAsset": "USDT",
    "counterPartyId": 653,
    "id": 698759,
    "maker": False,
    "orderId": 25851813,
    "price": "7819.01",
    "qty": "0.002",
    "quoteQty": "0.01563",
    "realizedPnl": "-0.91539999",
    "side": "SELL",
    "symbol": "BTCUSDT",
    "time": 1569514978020
  }
]

GET /fapi/v1/userTrades (HMAC SHA256)

Get trades for a specific account and symbol.

Weight: 5 with symbol

Parameters:

Name Type Mandatory Description
symbol STRING YES
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
timestamp LONG YES

Notes:

User Data Streams

Start User Data Stream (USER_STREAM)

Response:

{
  "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}

POST /fapi/v1/listenKey (HMAC SHA256)

Start a new user data stream. The stream will close after 30 minutes unless a keepalive is sent.

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Keepalive User Data Stream (USER_STREAM)

Response:

{}

PUT /fapi/v1/listenKey (HMAC SHA256)

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

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Close User Data Stream (USER_STREAM)

Response:

{}

DELETE /fapi/v1/listenKey (HMAC SHA256)

Close out a user data stream.

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Event: Balance and Position Update

Payload:

{
  "e": "ACCOUNT_UPDATE",         // Event Type
  "E": 1564745798939             // Event Time
  "a": [                        
    {
      "B":[                      // Balances
        {
          "a":"USDT",            // Asset
          "wb":"122624"          // Wallet Balance
        },
        {
          "a":"BTC",           
          "wb":"0"         
        }
      ],
      "P":[                      // Positions
        {
          "s":"BTCUSDT",         // Symbol
          "pa":"1",              // Position Amount
          "ep":"9000",           // Entry Price
          "cr":"200"             // (Pre-fee) accumulated realized
        }
      ]
    }
  ]
}

Event type is ACCOUNT_UPDATE. When balance or position get updated, will push this event.

Event: Order Update

Payload:

{

  "e":"ORDER_TRADE_UPDATE",     // Event Type
  "E":1568879465651,            // Event Time
  "o":{                             
    "s":"BTCUSDT",          // Symbol
    "c":"TEST",             // Client Order Id
    "S":"SELL",             // Side
    "o":"LIMIT",            // Order Type
    "f":"GTC",              // Time in Force
    "q":"0.001",            // Original Quantity
    "p":"9910",             // Price
    "ap":"0",               // Average Price
    "sp":"0",               // Stop Price
    "x":"NEW",              // Execution Type
    "X":"NEW",              // Order Status
    "i":8886774,            // Order Id
    "l":"0",                // Order Last Filled Quantity
    "z":"0",                // Order Filled Accumulated Quantity
    "L":"0",                // Last Filled Price
    "N": "USDT",            // Commission Asset, will not push if no commission
    "n": "0",               // Commission, will not push if no commission
    "T":1568879465651,      // Order Trade Time
    "t":0,                  // Trade Id
    "b":"0",                // Bids Notional
    "a":"9.91"              // Ask Notional
    "m": False              // Is this trade the maker side?
  }

}

When new order created, order status changed will push such event. event type is ORDER_TRADE_UPDATE.

Side

Order Type

Execution Type

Order Status

Time in force

Error Codes

Here is the error JSON payload:

{
  "code":-1121,
  "msg":"Invalid symbol."
}

Errors consist of two parts: an error code and a message.
Codes are universal,but messages can vary.

10xx - General Server or Network issues

-1000 UNKNOWN

-1001 DISCONNECTED

-1002 UNAUTHORIZED

-1003 TOO_MANY_REQUESTS

-1004 DUPLICATE_IP

-1005 NO_SUCH_IP

-1006 UNEXPECTED_RESP

-1007 TIMEOUT

-1010 ERROR_MSG_RECEIVED

-1011 NON_WHITE_LIST

-1013 INVALID_MESSAGE

-1014 UNKNOWN_ORDER_COMPOSITION

-1015 TOO_MANY_ORDERS

-1016 SERVICE_SHUTTING_DOWN

-1020 UNSUPPORTED_OPERATION

-1021 INVALID_TIMESTAMP

-1022 INVALID_SIGNATURE

-1023 START_TIME_GREATER_THAN_END_TIME

11xx - Request issues

-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

-1108 BAD_ASSET

-1109 BAD_ACCOUNT

-1110 BAD_INSTRUMENT_TYPE

-1111 BAD_PRECISION

-1112 NO_DEPTH

-1113 WITHDRAW_NOT_NEGATIVE

-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

20xx - Processing Issues

-2008 BAD_API_ID

-2010 NEW_ORDER_REJECTED

-2011 CANCEL_REJECTED

-2013 NO_SUCH_ORDER

-2014 BAD_API_KEY_FMT

-2015 REJECTED_MBX_KEY

-2016 NO_TRADING_WINDOW

-2018 BALANCE_NOT_SUFFICIENT

-2019 MARGIN_NOT_SUFFICIEN

-2020 UNABLE_TO_FILL

-2021 ORDER_WOULD_IMMEDIATELY_TRIGGER

-2022 REDUCE_ONLY_REJECT

-2023 USER_IN_LIQUIDATION

-2024 POSITION_NOT_SUFFICIENT

-2025 MAX_OPEN_ORDER_EXCEEDED

-2026 REDUCE_ONLY_ORDER_TYPE_NOT_SUPPORTED

40xx - Filters and other Issues

-4000 INVALID_ORDER_STATUS

-4001 PRICE_LESS_THAN_ZERO

-4002 PRICE_GREATER_THAN_MAX_PRICE

-4003 QTY_LESS_THAN_ZERO

-4004 QTY_LESS_THAN_MIN_QTY

-4005 QTY_GREATER_THAN_MAX_QTY

-4006 STOP_PRICE_LESS_THAN_ZERO

-4007 STOP_PRICE_GREATER_THAN_MAX_PRICE

-4008 TICK_SIZE_LESS_THAN_ZERO

-4009 MAX_PRICE_LESS_THAN_MIN_PRICE

-4010 MAX_QTY_LESS_THAN_MIN_QTY

-4011 STEP_SIZE_LESS_THAN_ZERO

-4012 MAX_NUM_ORDERS_LESS_THAN_ZERO

-4013 PRICE_LESS_THAN_MIN_PRICE

-4014 PRICE_NOT_INCREASED_BY_TICK_SIZE

-4015 INVALID_CL_ORD_ID_LEN

-4016 PRICE_HIGHTER_THAN_MULTIPLIER_UP

-4017 MULTIPLIER_UP_LESS_THAN_ZERO

-4018 MULTIPLIER_DOWN_LESS_THAN_ZERO

-4019 COMPOSITE_SCALE_OVERFLOW

-4020 TARGET_STRATEGY_INVALID

-4021 INVALID_DEPTH_LIMIT

-4022 WRONG_MARKET_STATUS

-4023 QTY_NOT_INCREASED_BY_STEP_SIZE

-4024 PRICE_LOWER_THAN_MULTIPLIER_DOWN

-4025 MULTIPLIER_DECIMAL_LESS_THAN_ZERO

-4026 COMMISSION_INVALID

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, clientOrderId, origClientOrderId) could not be found
"Duplicate order sent." The clientOrderId 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
"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
"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 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 origClientOrderId and orderId." No origClientOrderId 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.

-9xxx Filter failures

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: LOT_SIZE" quantity is too high, too low, and/or not following the step size rule for the symbol.
"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: PERCENT_PRICE" price is X% too high or X% too low from the average weighted price over the last Y minutes.