Navbar
现货/杠杆 合约 合约testnet
简体中文

Change Log

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://testnet.binancefuture.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://testnet.binancefuture.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://testnet.binancefuture.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

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"
            ],
            "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

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

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

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

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

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

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

24hr Ticker Price Change Statistics

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

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

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://testnet.binancefuture.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://testnet.binancefuture.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 Order (TRADE)

Response:

{
    "accountId": 10012,
    "clientOrderId": "testOrder",
    "cumQuote": "0",
    "executedQty": "0",
    "orderId": 22542179,
    "origQty": "10",
    "price": "10000",
    "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
price DECIMAL NO
newClientOrderId STRING NO A unique id for the order. Automatically generated if not sent.
stopPrice DECIMAL NO Used with STOP 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

Query Order (USER_DATA)

Response:

{
  "symbol": "BTCUSDT",
  "orderId": 1,
  "clientOrderId": "myOrder1",
  "price": "0.1",
  "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",
  "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",
    "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",
    "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:

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:

[
  {
    "symbol": "BTCUSDT",
    "id": 28457,
    "orderId": 100234,
    "price": "4.00000100",
    "qty": "12.00000000",
    "quoteQty": "48.000012",
    "commission": "10.10000000",
    "commissionAsset": "USDT",
    "time": 1499865549590,
    "isBuyer": true,
    "isMaker": false,
  }
]

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
  }

}

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 ILLEGAL_MESSAGE

-1014 UNKNOWN_ORDER_COMPOSITION

-1015 TOO_MANY_ORDERS

-1016 SERVICE_SHUTTING_DOWN

-1020 UNSUPPORTED_OPERATION

-1021 INVALID_TIMESTAMP

-1022 INVALID_SIGNATURE

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

-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

-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

-4006 STOP_PRICE_GREATER_THAN_MAX_PRICE

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.