Change Log

2019-11-05

  • New order type:
    • STOP_MARKET
    • TAKE_PROFIT_MARKET.
  • New parameter workingType in POST /fapi/v1/order
    order with stop price can be triggered by “CONTRACT_PRICE” or “MARK_PRICE”
  • New keys in USER-DATA-STREAMS:
    • in ORDER_TRADE_UPDATE
      • “T” as trasaction time
      • “wt” as workingType
    • in ACCOUNT_UPDATE:
      • “T” as trasaction time

2019-10-28

  • New rest endpoint for income flow history GET /fapi/v1/income

2019-10-25

  • Added "up" in event ACCOUNT_UPDATE in user data stream: the unrealized PnL of the position.
  • Added "R" in event ORDER_TRADE_UPDATE in user data stream, showing if the trade is reduce only.

2019-10-24

  • New WebSocket streams for booktickers added: <symbol>@bookTicker and !bookTicker.
  • New WebSocket streams for partial orderbook added: <symbol>@depth<levels> and <symbol>@depth<levels>@100ms
  • Faster diff. depth data with 100ms updates: <symbol>@depth@100ms
  • Added Update Speed: to Websocket Market Streams

2019-10-18

  • New endpoint POST /fapi/v1/leverage for changing user's initial leverage in specific symbol market.
  • Added "leverage" for current initial leverage and "maxNotionalValue" for notional value limit of current initial leverage in response to GET /fapi/v1/positionRisk.
  • reduceOnly now is supported in the MARKET orders.

2019-10-14

  • Added GET /fapi/v1/fundingRate for getting funding fee rate history.

2019-10-11

  • Added "m" in event ORDER_TRADE_UPDATE in user data stream, showing if the trade is the maker side.

2019-10-08

  • New order parameter reduceOnly for LIMIT orders.
  • New order type TAKE_PROFIT.

2019-09-20

  • New retured values in response to GET /fapi/v1/account:
    maxWithdrawAmount, openOrderInitialMargin, positionInitialMargin

  • New retured values in response to GET /fapi/v1/positionRisk:
    liquidationPrice

General Rest-API Information

  • The base endpoint is: https://fapi.binance.com
  • 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.
  • HTTP 4XX return codes are used for for malformed requests; the issue is on the sender's side.
  • HTTP 429 return code is used when breaking a request rate limit.
  • HTTP 418 return code is used when an IP has been auto-banned for continuing to send requests after receiving 429 codes.
  • HTTP 5XX return codes are used for internal errors; the issue is on Binance's side. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.
  • Any endpoint can return an ERROR; the error payload is as follows:
{
  "code": -1121,
  "msg": "Invalid symbol."
}
  • Specific error codes and messages defined in ERROR INFO.
  • For GET endpoints, parameters must be sent as a query string.
  • For POST, PUT, and DELETE endpoints, the parameters may be sent as a query string or in the request body with content type application/x-www-form-urlencoded. You may mix parameters between both the query string and request body if you wish to do so.
  • Parameters may be sent in any order.
  • If a parameter sent in both the query string and request body, the query string parameter will be used.

LIMITS

  • The /fapi/v1/exchangeInfo rateLimits array contains objects related to the exchange's RAW_REQUEST, REQUEST_WEIGHT, and ORDER rate limits. These are further defined in the ENUM definitions section under Rate limiters (rateLimitType).
  • A 429 will be returned when either rate limit is violated.
  • Each route has a weight which determines for the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavier weight.
  • Every request will contain a X-MBX-USED-WEIGHT header which has the current used weight for the IP for the current minute.
  • When a 429 returned, it's your obligation as an API to back off and not spam the API.
  • Repeatedly violating rate limits and/or failing to back off after receiving 429 will result in an automated IP ban (http status 418).
  • IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.
  • A Retry-After header is sent with a 418 or 429 responses and will give the number of seconds required to wait, in the case of a 418, to prevent a ban, or, in the case of a 429, until the ban is over.

Public API Endpoints

Terminology

  • base asset refers to the asset that is the quantity of a symbol.
  • quote asset refers to the asset that is the price of a symbol.

ENUM definitions

Symbol type:

  • FUTURE

Order Status (status):

  • NEW
  • PARTIALLY_FILLED
  • FILLED
  • CANCELED
  • PENDING_CANCEL (currently unused)
  • REJECTED
  • EXPIRED

Order Types (orderTypes, type):

  • LIMIT
  • MARKET
  • STOP
  • STOP_MARKET
  • TAKE_RPOFIT
  • TAKE_RPOFIT_MARKET

Order Side (side):

  • BUY
  • SELL

Time In Force (timeInForce):

  • GTC - Good Till Cancel
  • IOC - Immediate or Cancel
  • FOK - Fill or Kill
  • GTX - Post only or kill

Working Type (workingType)

  • MARK_PRICE
  • CONTRACT_PRICE

Kline/Candlestick chart intervals:

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

  • 1m
  • 3m
  • 5m
  • 15m
  • 30m
  • 1h
  • 2h
  • 4h
  • 6h
  • 8h
  • 12h
  • 1d
  • 3d
  • 1w
  • 1M

Rate Limiters (rateLimitType)

  • REQUEST_WEIGHT
  {
    "rateLimitType": "REQUEST_WEIGHT",
    "interval": "MINUTE",
    "intervalNum": 1,
    "limit": 1200
  }
  • ORDERS
  {
    "rateLimitType": "ORDERS",
    "interval": "SECOND",
    "intervalNum": 1,
    "limit": 10
   }

Rate limit intervals (interval)

  • SECOND
  • MINUTE
  • DAY

Filters

Filters define trading rules on a symbol or an exchange.

Symbol filters

PRICE_FILTER

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

  • minPrice defines the minimum price/stopPrice allowed; disabled on minPrice == 0.
  • maxPrice defines the maximum price/stopPrice allowed; disabled on maxPrice == 0.
  • tickSize defines the intervals that a price/stopPrice can be increased/decreased by; disabled on tickSize == 0.

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

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

/exchangeInfo format:

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

LOT_SIZE

The LOT_SIZE filter defines the quantity (aka "lots" in auction terms) rules for a symbol. There are 3 parts:

  • minQty defines the minimum quantity allowed.
  • maxQty defines the maximum quantity allowed.
  • stepSize defines the intervals that a quantity can be increased/decreased by.

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

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

/exchangeInfo format:

  {
    "filterType": "LOT_SIZE",
    "minQty": "0.00100000",
    "maxQty": "100000.00000000",
    "stepSize": "0.00100000"
  }

MARKET_LOT_SIZE

The MARKET_LOT_SIZE filter defines the quantity (aka "lots" in auction terms) rules for MARKET orders on a symbol. There are 3 parts:

  • minQty defines the minimum quantity allowed.
  • maxQty defines the maximum quantity allowed.
  • stepSize defines the intervals that a quantity can be increased/decreased by.

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

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

/exchangeInfo format:

  {
    "filterType": "MARKET_LOT_SIZE",
    "minQty": "0.00100000",
    "maxQty": "100000.00000000",
    "stepSize": "0.00100000"
  }

MAX_NUM_ORDERS

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.

/exchangeInfo format:

  {
    "filterType": "MAX_NUM_ORDERS",
    "limit": 25
  }