Rest API Endpoints

Endpoint Security Type

  • Each endpoint has a security type that determines the how you will interact with it.
  • API-keys are passed into the Rest API via the X-MBX-APIKEY header.
  • API-keys and secret-keys are case sensitive.
  • API-keys can be configured to only access certain types of secure endpoints. For example, one API-key could be used for TRADE only, while another API-key can access everything except for TRADE routes.
  • By default, API-keys can access all secure routes.
Security Type Description
NONE Endpoint can be accessed freely.
TRADE Endpoint requires sending a valid API-Key and signature.
USER_DATA Endpoint requires sending a valid API-Key and signature.
USER_STREAM Endpoint requires sending a valid API-Key.
MARKET_DATA Endpoint requires sending a valid API-Key.
  • TRADE and USER_DATA endpoints are SIGNED endpoints.

SIGNED (TRADE and USER_DATA) Endpoint security

  • SIGNED endpoints require an additional parameter, signature, to be sent in the query string or request body.
  • Endpoints use HMAC SHA256 signatures. The HMAC SHA256 signature is a keyed HMAC SHA256 operation. Use your secretKey as the key and totalParams as the value for the HMAC operation.
  • The signature is not case sensitive.
  • Please make sure the signature is the end part of your query string or request body.
  • totalParams is defined as the query string concatenated with the request body.

Timing Security

  • A SIGNED endpoint also requires a parameter, timestamp, to be sent which should be the millisecond timestamp of when the request was created and sent.
  • An additional parameter, recvWindow, may be sent to specify the number of milliseconds after timestamp the request is valid for. If recvWindow is not sent, it defaults to 5000.
  • 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.

It recommended to use a small recvWindow of 5000 or less!


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

  • queryString: symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559
  • HMAC SHA256 signature:
    [linux]$ 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)
    [linux]$ 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

  • requestBody: symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559
  • HMAC SHA256 signature:
    [linux]$ 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)
    [linux]$ 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

  • queryString: symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC
  • requestBody: quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559
  • HMAC SHA256 signature:
    [linux]$ 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)
    [linux]$ 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".


New Future Account Transfer

POST https://api.binance.com/sapi/v1/futures/transfer  (HMAC SHA256)
  • NOTICE: base url for fapi is not avalible here

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

Response:

{
    "tranId": 100000001    //transaction id
}

Get Future Account Trans History List

GET https://api.binance.com/sapi/v1/futures/transfer (HMAC SHA256)
  • NOTICE: base url for fapi is not avalible here

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

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
}

New Order (TRADE)

POST /fapi/v1/order  (HMAC SHA256)

Send in a new order.

Weight: 1

Parameters:

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/MARKET 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/STOP_MARKET or TAKE_PROFIT/TAKE_PROFIT_MARKET orders.
workingType ENUM NO stopPrice triggered by: "MARK_PRICE", "CONTRACT_PRICE". Default "CONTRACT_PRICE"
recvWindow LONG NO
timestamp LONG YES

Additional mandatory parameters based on type:

Type Additional mandatory parameters
LIMIT timeInForce, quantity, price
MARKET quantity
STOP/TAKE_PROFIT quantity, price, stopPrice
STOP_MARKET/TAKE_PROFIT_MARKET quantity, stopPrice
  • Order with type MARKET, parameter timeInForce cannot be sent.
  • Order with type STOP, parameter timeInForce can be sent ( default GTC).
  • Order with type TAKE_PROFIT, parameter timeInForce can be sent ( default GTC).

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,
    "workingType": "CONTRACT_PRICE"
 }

Query Order (USER_DATA)

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:

  • Either orderId or origClientOrderId must be sent.

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,
  "workingType": "CONTRACT_PRICE"
}

Cancel Order (TRADE)

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.

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",
  "workingType": "CONTRACT_PRICE"
}

Current Open Orders (USER_DATA)

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

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,
    "workingType": "CONTRACT_PRICE"
  }
]
  • If the symbol is not sent, orders for all symbols will be returned in an array.

All Orders (USER_DATA)

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:

  • If orderId is set, it will get orders >= that orderId. Otherwise most recent orders are returned.

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,
    "workingType": "CONTRACT_PRICE"
  }
]

Future Account Balance (USER_DATA)

GET /fapi/v1/balance (HMAC SHA256)

Weight: 1

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Response:

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

Account Information (USER_DATA)

GET /fapi/v1/account (HMAC SHA256)

Get current account information.

Weight: 5

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES
{
    "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

}

Change Initial Leverage (TRADE)

POST /fapi/v1/leverage (HMAC SHA256)

Change user's initial leverage of specific symbol market.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES
leverage INT YES target initial leverage: int from 1 to 125
recvWindow LONG NO
timestamp LONG YES

Response:

{
    "accountId": 26,
    "leverage": 21,
    "maxNotionalValue": "1000000",
    "symbol": "BTCUSDT"
}

Position Information (USER_DATA)

GET /fapi/v1/positionRisk (HMAC SHA256)

Get current account information.

Weight: 5

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Response:

[
    {
        "entryPrice": "9975.12000",
        "leverage": "50",                   // current initial leverage
        "maxNotionalValue": "1000000",      // notional value limit of current initial leverage
        "liquidationPrice": "7963.54",
        "markPrice": "9973.50770517",
        "positionAmt": "0.010",
        "symbol": "BTCUSDT",
        "unRealizedProfit": "-0.01612295"
    }
]

Account Trade List (USER_DATA)

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:

  • If fromId is set, it will get orders >= that fromId. Otherwise most recent orders are returned.

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 Income History(USER_DATA)

GET /fapi/v1/income (HMAC SHA256)

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING NO
incomeType STRING NO "TRANSFER","WELCOME_BONUS", "REALIZED_PNL","FUNDING_FEE", "COMMISSION", and "INSURANCE_CLEAR"
startTime LONG NO Timestamp in ms to get funding from INCLUSIVE.
endTime LONG NO Timestamp in ms to get funding until INCLUSIVE.
limit INT NO Default 100; max 1000
recvWindow LONG NO
timestamp LONG YES
  • If incomeType is not sent, all kinds of flow will be returned
  • If startTime and endTime are not sent, the most recent limit datas will be returned.
  • If the number of data between startTime and endTime is larger than limit, response will be return as startTime + limit.

Response:

[
    {
        "symbol": "",
        "incomeType": "TRANSFER"
        "income": "-0.37500000",
        "asset": "USDT",
        "time": 1570608000000,
    },
    {
        "symbol": "BTCUSDT",
        "incomeType": "COMMISSION" 
        "income": "-0.01000000",
        "asset": "USDT",
        "time": 1570636800000,
    }
]