Navbar
简体中文

Change Log

Important Documentation Notice

Binance has launched its new API Documentation Portal. The existing GitHub API documentation is now deprecated and set to go offline in the upcoming few months following user migration; the exact date will be determined and communicated in due course.

During this transition phase, both sites will be maintained. However, any new services will only be published in the new portal moving forward.

Here's a reference table of the links for the current and new API documentation:

Functionality Current Documentation New Documentation
Spot Trading Current Documentation New Documentation
Spot Websocket API Current Documentation New Documentation
Margin Trading Current Documentation New Documentation
Derivative UM Futures Current Documentation New Documentation
Derivative CM Futures Current Documentation New Documentation
Derivative Options Current Documentation New Documentation
Derivative Portfolio Margin Current Documentation New Documentation
Wallet Current Documentation New Documentation
Sub Account Current Documentation New Documentation
Simple Earn Current Documentation New Documentation
Dual Investment Current Documentation New Documentation
Auto Invest Current Documentation New Documentation
Staking Current Documentation New Documentation
Mining Current Documentation New Documentation
Algo Trading Current Documentation New Documentation
Copy Trading Current Documentation New Documentation
Derivative Porfolio Margin Pro Current Documentation New Documentation
Fiat Current Documentation New Documentation
C2C Current Documentation New Documentation
VIP Loan Current Documentation New Documentation
Crypto Loan Current Documentation New Documentation
Pay Current Documentation New Documentation
Convert Current Documentation New Documentation
Rebate Current Documentation New Documentation
NFT Current Documentation New Documentation
Gift Card Current Documentation New Documentation

2023-10-19

Binance Option is doing Websocket Service upgrade and the upgrade impacts the following:


2023-08-29

REST

Websocket User Data Stream


2023-07-21

REST


2023-07-13

Websocket Market Streams


2023-05-30

General Information on Endpoints


2023-02-02

REST


2023-01-11

REST


2022-12-13

WEBSOCKET


2022-12-09

REST


2022-11-18

REST

WEBSOCKET


2022-11-16

WEBSOCKET


2022-11-03

REST


2022-09-20

WEBSOCKET


2022-09-14

REST


2022-09-05

REST


2022-08-22

REST


General Info

General API Information

HTTP Return Codes

Error Codes and Messages

The error payload is as follows:

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

General Information on Endpoints

LIMITS

IP Limits

Order Rate 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 /eapi/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 dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
secretKey 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9
Parameter Value
symbol BTCUSDT
side BUY
type LIMIT
timeInForce GTC
quantity 1
price 9000
recvWindow 5000
timestamp 1591702613943

Example 1: As a query string

Example 1

HMAC SHA256 signature:

    $ echo -n "symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=2000&recvWindow=5000&timestamp=1611825601400" | openssl dgst -sha256 -hmac "YtP1BudNOWZE1ag5uzCkh4hIC7qSmQOu797r5EJBFGhxBYivjj8HIX0iiiPof5yG"
    (stdin)= 7c12045972f6140e765e0f2b67d28099718df805732676494238f50be830a7d7

curl command:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: 22BjeOROKiXJ3NxbR3zjh3uoGcaflPu3VMyBXAg8Jj2J1xVSnY0eB4dzacdE9IWn" -X POST 'https://eapi.binance.com/eapi/v1/order' -d 'symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=2000&recvWindow=5000&timestamp=1611825601400&signature=7c12045972f6140e765e0f2b67d28099718df805732676494238f50be830a7d7'

symbol=BTC-210129-40000-C
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=2000
&recvWindow=5000
&timestamp=1611825601400

Example 2: As a request body

Example 2

HMAC SHA256 signature:

    $ echo -n "symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=2000&recvWindow=5000&timestamp=1611825601400" | openssl dgst -sha256 -hmac "YtP1BudNOWZE1ag5uzCkh4hIC7qSmQOu797r5EJBFGhxBYivjj8HIX0iiiPof5yG"
    (stdin)= 7c12045972f6140e765e0f2b67d28099718df805732676494238f50be830a7d7

curl command:

    (HMAC SHA256)
   $ curl -H "X-MBX-APIKEY: 22BjeOROKiXJ3NxbR3zjh3uoGcaflPu3VMyBXAg8Jj2J1xVSnY0eB4dzacdE9IWn" -X POST 'https://eapi.binance.com/eapi/v1/order?symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=2000&recvWindow=5000&timestamp=1611825601400&signature=7c12045972f6140e765e0f2b67d28099718df805732676494238f50be830a7d7'

symbol=BTC-210129-40000-C
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=2000
&recvWindow=5000
&timestamp=1611825601400

Example 3: Mixed query string and request body

Example 3

HMAC SHA256 signature:

   $ echo -n "symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTCquantity=0.01&price=2000&recvWindow=5000&timestamp=1611825601400" | openssl dgst -sha256 -hmac "YtP1BudNOWZE1ag5uzCkh4hIC7qSmQOu797r5EJBFGhxBYivjj8HIX0iiiPof5yG"
    (stdin)= fa6045c54fb02912b766442be1f66fab619217e551a4fb4f8a1ee000df914d8e

curl command:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: 22BjeOROKiXJ3NxbR3zjh3uoGcaflPu3VMyBXAg8Jj2J1xVSnY0eB4dzacdE9IWn" -X POST 'https://eapi.binance.com/eapi/v1/order?symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=0.01&price=2000&recvWindow=5000&timestamp=1611825601400&signature=fa6045c54fb02912b766442be1f66fab619217e551a4fb4f8a1ee000df914d8e'

symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTC

quantity=1&price=2000&recvWindow=5000&timestamp=1611825601400

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

Public Endpoints Info

Terminology

ENUM definitions

Options contract type

Order side

Position side

Time in force

Response Type (newOrderRespType)

Order types (type)

Order status (status)

Kline/Candlestick chart intervals:

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

Rate limiters (rateLimitType)

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

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

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 Data Endpoints

Test Connectivity

Response:

{}

GET /eapi/v1/ping

Test connectivity to the Rest API.

Weight: 1

Parameters: NONE

Check Server Time

Response:

{
  "serverTime": 1499827319559
}

GET /eapi/v1/time

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

Weight: 1

Parameters: NONE

Exchange Information

Response:

{
  "timezone": "UTC",                    // Time zone used by the server
  "serverTime": 1592387337630,          // Current system time
  "optionContracts": [                  // Option contract underlying asset info
    {
      "id": 1,
      "baseAsset": "BTC",               // Base currency
      "quoteAsset": "USDT",             // Quotation asset
      "underlying": "BTCUSDT",          // Name of the underlying asset of the option contract
      "settleAsset": "USDT"             // Settlement currency
    }
  ],
  "optionAssets": [                     // Option asset info
    {
      "id": 1,
      "name": "USDT"                    // Asset name
    }
  ],
  "optionSymbols": [                    // Option trading pair info
    {
        "contractId": 2,
        "expiryDate": 1660521600000,    // expiry time
        "filters": [
            {
                "filterType": "PRICE_FILTER",
                "minPrice": "0.02",
                "maxPrice": "80000.01",
                "tickSize": "0.01"
            },
            {
                "filterType": "LOT_SIZE",
                "minQty": "0.01",
                "maxQty": "100",
                "stepSize": "0.01"
            }
        ],
        "id": 17,
        "symbol": "BTC-220815-50000-C",   // Trading pair name
        "side": "CALL",                   // Direction: CALL long, PUT short
        "strikePrice": "50000",           // Strike price
        "underlying": "BTCUSDT",          // Underlying asset of the contract
        "unit": 1,                        // Contract unit, the quantity of the underlying asset represented by a single contract.
        "makerFeeRate": "0.0002",         // maker commission rate
        "takerFeeRate": "0.0002",         // taker commission rate
        "minQty": "0.01",                 // Minimum order quantity
        "maxQty": "100",                  // Maximum order quantity
        "initialMargin": "0.15",          // Initial Magin Ratio
        "maintenanceMargin": "0.075",     // Maintenance Margin Ratio
        "minInitialMargin": "0.1",        // Min Initial Margin Ratio
        "minMaintenanceMargin": "0.05",   // Min Maintenance Margin Ratio
        "priceScale": 2,                  // price precision
        "quantityScale": 2,               // quantity precision
        "quoteAsset": "USDT"              // Quotation asset
    }
  ],
  "rateLimits": [
    {
        "rateLimitType": "REQUEST_WEIGHT",
        "interval": "MINUTE",
        "intervalNum": 1,
        "limit": 2400
    },
    {
        "rateLimitType": "ORDERS",
        "interval": "MINUTE",
        "intervalNum": 1,
        "limit": 1200
    },
    {
        "rateLimitType": "ORDERS",
        "interval": "SECOND",
        "intervalNum": 10,
        "limit": 300
    }
  ]
}

GET /eapi/v1/exchangeInfo

Current exchange trading rules and symbol information

Weight: 1

Parameters: NONE

Order Book

Response:

{
  "T": 1589436922972,   // transaction time
  "u": 37461            // update id
  "bids": [             // Buy order
    [
      "1000",            // Price
      "0.9"              // Quantity
    ]
  ],
  "asks": [              // Sell order
    [
      "1100",            // Price
      "0.1"              // Quantity
    ]
  ]
}  

GET /eapi/v1/depth

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES Option trading pair, e.g BTC-200730-9000-C
limit INT NO Default:100 Max:1000.Optional value:[10, 20, 50, 100, 500, 1000]

Recent Trades List

Response:

[
  { 
    "id":"1",             // TradeId
    "symbol": "BTC-220722-19000-C",
    "price": "1000",      // Completed trade price
    "qty": "-0.1",        // Completed trade quantity
    "quoteQty": "-100",   // Completed trade amount
    "side": -1            // Completed trade direction(-1 Sell,1 Buy)
    "time": 1592449455993,// Time 
  }
]  

GET /eapi/v1/trades

Get recent market trades

Weight: 5

Parameters:

Name Type Mandatory Description
symbol STRING YES Option trading pair, e.g BTC-200730-9000-C
limit INT NO Number of records Default:100 Max:500

Old Trades Lookup (MARKET_DATA)

Response:

[
  {
    "id":"1",             // UniqueId
    "tradeId": "159244329455993",    // TradeId
    "price": "1000",      // Completed trade price
    "qty": "-0.1",        // Completed trade Quantity
    "quoteQty": "-100",   // Completed trade amount
    "side": -1            // Completed trade direction(-1 Sell,1 Buy)
    "time": 1592449455993,// Time
  }
]

GET /eapi/v1/historicalTrades

Get older market historical trades.

Weight: 20

Parameters:

Name Type Mandatory Description
symbol STRING YES Option trading pair, e.g BTC-200730-9000-C
fromId LONG NO The UniqueId ID from which to return. The latest deal record is returned by default
limit INT NO Number of records Default:100 Max:500

Kline/Candlestick Data

Response:

[
  {
      "open": "950",              // Opening price
      "high": "1100",             // Highest price
      "low": "900",               // Lowest price
      "close": "1000",            // Closing price (latest price if the current candle has not closed)
      "volume": "100"             // Trading volume(contracts)       
      "amount": "2",              // Trading amount(in quote asset)
      "interval": "5m",           // Candle type
      "tradeCount": 10,           // Number of completed trades
      "takerVolume": "100",       // Taker trading volume(contracts)      
      "takerAmount": "10000",     // Taker trade amount(in quote asset)
      "openTime": 1499040000000,  // Opening time
      "closeTime": 1499644799999, // Closing time
  }
]

GET /eapi/v1/klines

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

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES Option trading pair, e.g BTC-200730-9000-C
interval STRING YES Time interval
startTime LONG NO Start Time 1592317127349
endTime LONG NO End Time
limit INT NO Number of records Default:500 Max:1500

Option Mark Price

Response:

[
  {
    "symbol": "BTC-200730-9000-C",
    "markPrice": "1343.2883",       // Mark price
    "bidIV": "1.40000077",          // Implied volatility Buy
    "askIV": "1.50000153",          // Implied volatility Sell
    "markIV": "1.45000000"          // Implied volatility mark  
    "delta": "0.55937056",          // delta
    "theta": "3739.82509871",       // theta
    "gamma": "0.00010969",          // gamma
    "vega": "978.58874732",         // vega
    "highPriceLimit": "1618.241",   // Current highest buy price
    "lowPriceLimit": "1068.3356"    // Current lowest sell price
  }
]

GET /eapi/v1/mark

Option mark price and greek info.

Weight: 5

Parameters:

Name Type Mandatory Description
symbol STRING NO Option trading pair, e.g BTC-200730-9000-C

24hr Ticker Price Change Statistics

Response:

[
  {
    "symbol": "BTC-200730-9000-C",
    "priceChange": "-16.2038",        //24-hour price change
    "priceChangePercent": "-0.0162",  //24-hour percent price change
    "lastPrice": "1000",              //Last trade price
    "lastQty": "1000",                //Last trade amount
    "open": "1016.2038",              //24-hour open price
    "high": "1016.2038",              //24-hour high
    "low": "0",                       //24-hour low
    "volume": "5",                    //Trading volume(contracts)
    "amount": "1",                    //Trade amount(in quote asset)
    "bidPrice":"999.34",              //The best buy price
    "askPrice":"1000.23",             //The best sell price
    "openTime": 1592317127349,        //Time the first trade occurred within the last 24 hours
    "closeTime": 1592380593516,       //Time the last trade occurred within the last 24 hours     
    "firstTradeId": 1,                //First trade ID
    "tradeCount": 5,                  //Number of trades
    "strikePrice": "9000",            //Strike price
    "exercisePrice": "3000.3356"      //return estimated settlement price one hour before exercise, return index price at other times
  }
]

GET /eapi/v1/ticker

24 hour rolling window price change statistics.

Weight:
5

Parameters:

Name Type Mandatory Description
symbol STRING NO Option trading pair, e.g BTC-200730-9000-C

Symbol Price Ticker

Response:

{
   "time": 1656647305000,
   "indexPrice": "9200" // Current spot index price
}

GET /eapi/v1/index

Get spot index price for option underlying.

Weight:
1

Parameters:

Name Type Mandatory Description
underlying STRING YES Spot pair(Option contract underlying asset, e.g BTCUSDT)

Historical Exercise Records

Response:

[
  { 
    "symbol": "BTC-220121-60000-P",            // symbol  
    "strikePrice": "60000",                    // strike price
    "realStrikePrice": "38844.69652571",       // real strike price
    "expiryDate": 1642752000000,               // Exercise time
    "strikeResult": "REALISTIC_VALUE_STRICKEN" // strike result
  }
]

GET /eapi/v1/exerciseHistory

REALISTIC_VALUE_STRICKEN -> Exercised

EXTRINSIC_VALUE_EXPIRED -> Expired OTM

Get historical exercise records.

Weight:
3

Parameters:

Name Type Mandatory Description
underlying STRING NO Underlying index like BTCUSDT
startTime LONG NO Start Time
endTime LONG NO End Time
limit INT NO Number of records Default:100 Max:100

Open interest

Response:

[
    {
        "symbol": "ETH-221119-1175-P",
        "sumOpenInterest": "4.01",
        "sumOpenInterestUsd": "4880.2985615624",
        "timestamp": "1668754020000"
    }
]

GET /eapi/v1/openInterest

Get open interest for specific underlying asset on specific expiration date.

Parameters:

Name Type Mandatory Description
underlyingAsset STRING YES underlying asset, e.g ETH/BTC
expiration STRING YES expiration date, e.g 221225

Account/Trades Endpoints

Option Account Information (TRADE)

Response:

{
  "asset": [                  
    {
      "asset": "USDT",                    // Asset type
      "marginBalance": "1877.52214415",   // Account balance
      "equity": "617.77711415",           // Account equity
      "available": "0",                   // Available funds
      "locked": "2898.92389933",          // locked balance for order and position 
      "unrealizedPNL": "222.23697000",    // Unrealized profit/loss        
   }
  ], 
  "greek": [
    {
      "underlying":"BTCUSDT"            // Option Underlying
      "delta": "-0.05"                  // Account delta
      "gamma": "-0.002"                 // Account gamma
      "theta": "-0.05"                  // Account theta
      "vega": "-0.002"                  // Account vega  
    }
  ], 
  "riskLevel": "NORMAL",                // Account risk level
  "time": 1592449455993                 // Time  
}

GET /eapi/v1/account (HMAC SHA256)

Get current account information.

Weight: 3

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Funds Transfer (TRADE)

Please find details from here.

New Order (TRADE)

Response ACK:

{
  "orderId": 4611875134427365377,     // System order number
  "clientOrderId": ""                 // Client order ID
  "symbol": "BTC-200730-9000-C",      // Option trading pair
  "price": "100",                     // Order Price
  "quantity": "1",                    // Order Quantity
  "side": "BUY",                      // Buy/sell direction
  "type": "LIMIT",                    // Order type
  "createDate": 1592465880683,        // Order Time
  "updateTime": 1566818724722,        // Update time
}

Response RESULT:

{
  "orderId": 4611875134427365377,     // System order number
  "symbol": "BTC-200730-9000-C",      // Option trading pair
  "price": "100",                     // Order Price
  "quantity": "1",                    // Order Quantity
  "executedQty": "0",                 // Number of executed quantity
  "fee": "0",                         // Fee 
  "side": "BUY",                      // Buy/sell direction
  "type": "LIMIT",                    // Order type
  "timeInForce": "GTC",               // Time in force method
  "reduceOnly": false,                // Order is reduce only Y/N
  "postOnly": false,                  // Order is post only
  "createTime": 1592465880683,        // Order Time
  "updateTime": 1566818724722,        // Update time
  "status": "ACCEPTED",               // Order status
  "avgPrice": "0",                    // Average price of completed trade
  "clientOrderId": ""                 // Client order ID
  "priceScale": 2,
  "quantityScale": 2,
  "optionSide": "CALL",
  "quoteAsset": "USDT",
  "mmp": false
}

POST /eapi/v1/order (HMAC SHA256)

Send a new order.

Parameters:

Name Type Mandatory Description
symbol STRING YES Option trading pair, e.g BTC-200730-9000-C
side ENUM YES Buy/sell direction: SELL, BUY
type ENUM YES Order Type: LIMIT(only support limit)
quantity DECIMAL YES Order Quantity
price DECIMAL NO Order Price
timeInForce ENUM NO Time in force method(Default GTC)
reduceOnly BOOLEAN NO Reduce Only(Default false)
postOnly BOOLEAN NO Post Only(Default false)
newOrderRespType ENUM NO "ACK", "RESULT", Default "ACK"
clientOrderId STRING NO User-defined order ID cannot be repeated in pending orders
isMmp BOOLEAN NO is market maker protection order, true/false
recvWindow LONG NO
timestamp LONG YES

Some parameters are mandatory depending on the order type as follows:

Type Mandatory parameters
LIMIT timeInForce, quantity, price

Place Multiple Orders (TRADE)

Response:

[
    {
        "orderId": 4612288550799409153,  // System order number
        "symbol": "ETH-220826-1800-C",   // Option trading pair
        "price": "100",                  // Order Price
        "quantity": "0.01",              // Order Quantity
        "side": "BUY",                   // Buy/sell direction
        "type": "LIMIT",                 // Order type
        "reduceOnly": false,             // Order is reduce only Y/N
        "postOnly": false,               // Post only or not 
        "clientOrderId": "1001",         // Client order ID
        "mmp": false                     // MMP     
    }
]

POST /eapi/v1/batchOrders

Send multiple option orders.

Weight: 5

Parameters:

Name Type Mandatory Description
orders LIST YES order list. Max 5 orders
recvWindow LONG NO
timestamp LONG YES

Where batchOrders is the list of order parameters in JSON:

Name Type Mandatory Description
symbol STRING YES Option trading pair, e.g BTC-200730-9000-C
side ENUM YES Buy/sell direction: SELL, BUY
type ENUM YES Order Type: LIMIT (Only support LIMIT)
quantity DECIMAL YES Order Quantity
price DECIMAL NO Order Price
timeInForce ENUM NO Time in force method(Default GTC)
reduceOnly BOOLEAN NO Reduce Only(Default false)
postOnly BOOLEAN NO Post Only(Default false)
clientOrderId STRING NO User-defined order ID cannot be repeated in pending orders
isMmp BOOLEAN NO is market maker protection order, true/false

  Some parameters are mandatory depending on the order type as follows:

Type Mandatory parameters
LIMIT timeInForce, quantity, price

Query Single Order (TRADE)

Response:

{
  "orderId": 4611875134427365377,     // System order id
  "symbol": "BTC-200730-9000-C",      // Option trading pair
  "price": "100",                     // Order Price
  "quantity": "1",                    // Order Quantity
  "executedQty": "0",                 // Number of executed quantity
  "fee": "0",                         // Fee 
  "side": "BUY",                      // Buy/sell direction
  "type": "LIMIT",                    // Order type
  "timeInForce": "GTC",               // Time in force method
  "reduceOnly": false,                // Order is reduce only Y/N
  "postOnly": false,                  // Order is post only
  "createTime": 1592465880683,        // Order Time
  "updateTime": 1566818724722,        // Update time
  "status": "ACCEPTED",               // Order status
  "avgPrice": "0",                    // Average price of completed trade
  "source": "API",                    // Order source
  "clientOrderId": ""                 // Client order ID
  "priceScale": 2,
  "quantityScale": 2,
  "optionSide": "CALL",
  "quoteAsset": "USDT",
  "mmp": false
}

No Order Response:

{
    "code": -2013,
    "msg": "Order does not exist"
}

GET /eapi/v1/order (HMAC SHA256)

Check an order status.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES Option trading pair, e.g BTC-200730-9000-C
orderId LONG NO Order id
clientOrderId STRING NO User-defined order ID cannot be repeated in pending orders
recvWindow LONG NO
timestamp LONG YES

Cancel Option Order (TRADE)

Response:

{
  "orderId": 4611875134427365377,     // System order number
  "symbol": "BTC-200730-9000-C",      // Option trading pair
  "price": "100",                     // Order Price
  "quantity": "1",                    // Order Quantity
  "executedQty": "0",                 // Number of executed quantity
  "fee": "0",                         // Fee 
  "side": "BUY",                      // Buy/sell direction
  "type": "LIMIT",                    // Order type
  "timeInForce": "GTC",               // Time in force method
  "reduceOnly": false,                // Order is reduce only Y/N
  "postOnly": false, 
  "createDate": 1592465880683,        // Order Time
  "updateTime": 1566818724722,        // Update time 
  "status": "ACCEPTED",               // Order status
  "avgPrice": "0",                    // Average price of completed trade
  "source": "API",
  "clientOrderId": "",                // Client order ID
  "priceScale": 4,
  "quantityScale": 4,
  "optionSide": "CALL",
  "quoteAsset": "USDT",
  "mmp": false
}

DELETE /eapi/v1/order (HMAC SHA256)

Cancel an active order.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES Option trading pair, e.g BTC-200730-9000-C
orderId LONG NO Order ID, e.g 4611875134427365377
clientOrderId STRING NO User-defined order ID, e.g 10000
recvWindow LONG NO
timestamp LONG YES

At least one instance of orderId and clientOrderId must be sent.

Cancel Multiple Option Orders (TRADE)

Response:

[
  {
    "orderId": 4611875134427365377,     // System order number
    "symbol": "BTC-200730-9000-C",      // Option trading pair
    "price": "100",                     // Order Price
    "quantity": "1",                    // Order Quantity
    "executedQty": "0",                 // Number of completed quantity
    "fee": 0,                           // Fee 
    "side": "BUY",                      // Buy/sell direction
    "type": "LIMIT",                    // Order type
    "timeInForce": "GTC",               // Time in force method
    "createTime": 1592465880683,        // Order Time
    "status": "ACCEPTED",               // Order status
    "avgPrice": "0",                    // Average price of completed trade
    "reduceOnly": false,                // Order is reduce only Y/N
    "clientOrderId": ""                 // Client order ID
    "updateTime": 1566818724722,        // Update time 
  }
]

DELETE /eapi/v1/batchOrders (HMAC SHA256)

Cancel an active order.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES Option trading pair, e.g BTC-200730-9000-C
orderIds LIST<LONG> NO Order ID, e.g [4611875134427365377,4611875134427365378]
clientOrderIds LIST<STRING> NO User-defined order ID, e.g ["my_id_1","my_id_2"]
recvWindow LONG NO
timestamp LONG YES

At least one instance of orderId and clientOrderId must be sent.

Cancel all Option orders on specific symbol (TRADE)

Response:

{
  "code": 0,
  "msg": "success"
}

DELETE /eapi/v1/allOpenOrders (HMAC SHA256)

Cancel all active order on a symbol.

Weight: 1

Parameters:

Name Type Mandatory Description
symbol STRING YES Option trading pair, e.g BTC-200730-9000-C
recvWindow LONG NO
timestamp LONG YES

Cancel All Option Orders By Underlying (TRADE)

Response:

{
    "code": 0,
    "msg": "success",
    "data": 0
}

DELETE /eapi/v1/allOpenOrdersByUnderlying (HMAC SHA256)

Cancel all active orders on specified underlying.

Weight: 1

Parameters:

Name Type Mandatory Description
underlying STRING YES Option underlying, e.g BTCUSDT
recvWindow LONG NO
timestamp LONG YES

Query Current Open Option Orders (USER_DATA)

Response:

[
  {
    "orderId": 4611875134427365377,     // System order number
    "symbol": "BTC-200730-9000-C",      // Option trading pair
    "price": "100",                     // Order Price
    "quantity": "1",                    // Order Quantity
    "executedQty": "0",                 // Number of completed trades
    "fee": "0",                         // Fee 
    "side": "BUY",                      // Buy/sell direction
    "type": "LIMIT",                    // Order type
    "timeInForce": "GTC",               // Time in force method
    "reduceOnly": false,                // Order is reduce only Y/N
    "postOnly": false,
    "createTime": 1592465880683,        // Order Time
    "updateTime": 1592465880683,        // Update Time
    "status": "ACCEPTED",               // Order status
    "avgPrice": "0",                    // Average price of completed trade
    "clientOrderId": ""                 // Client order ID         
    "priceScale": 2,
    "quantityScale": 2,
    "optionSide": "CALL",
    "quoteAsset": "USDT",
    "mmp": false
  }
]

GET /eapi/v1/openOrders (HMAC SHA256)

Query current all open orders, status: ACCEPTED PARTIALLY_FILLED

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

Parameters:

Name Type Mandatory Description
symbol STRING NO return all orders if don't pass, Option trading pair, e.g BTC-200730-9000-C,
orderId LONG NO Returns the orderId and subsequent orders, the most recent order is returned by default
startTime LONG NO Start Time
endTime LONG NO End Time
limit INT NO Number of result sets returned Default:100 Max:1000
recvWindow LONG NO
timestamp LONG YES

Query Option Order History (TRADE)

Response:

[
    {
        "orderId": 4611922413427359795,
        "symbol": "BTC-220715-2000-C",
        "price": "18000.00000000",
        "quantity": "-0.50000000",
        "executedQty": "-0.50000000",
        "fee": "3.00000000",
        "side": "SELL",
        "type": "LIMIT",
        "timeInForce": "GTC",
        "reduceOnly": false,
        "postOnly": false,
        "createTime": 1657867694244,
        "updateTime": 1657867888216,
        "status": "FILLED",
        "reason": "0",
        "avgPrice": "18000.00000000",
        "source": "API",
        "clientOrderId": "",
        "priceScale": 2,
        "quantityScale": 2,
        "optionSide": "CALL",
        "quoteAsset": "USDT",
        "mmp": false
    }
]

GET /eapi/v1/historyOrders (HMAC SHA256)

Query all finished orders within 5 days, finished status: CANCELLED FILLED REJECTED.

Weight: 3

Parameters:

Name Type Mandatory Description
symbol STRING YES Option trading pair
orderId LONG NO Returns the orderId and subsequent orders, the most recent order is returned by default
startTime LONG NO Start Time, e.g 1593511200000
endTime LONG NO End Time, e.g 1593512200000
limit INT NO Number of result sets returned Default:100 Max:1000
recvWindow LONG NO
timestamp LONG YES

Option Position Information (USER_DATA)

Response:

[
  {
    "entryPrice": "1000",               // Average entry price
    "symbol": "BTC-200730-9000-C",      // Option trading pair
    "side": "SHORT",                    // Position direction
    "quantity": "-0.1",                 // Number of positions (positive numbers represent long positions, negative number represent short positions)
    "reducibleQty": "0",                // Number of positions that can be reduced
    "markValue": "105.00138",           // Current market value
    "ror": "-0.05",                     // Rate of return
    "unrealizedPNL": "-5.00138",        // Unrealized profit/loss
    "markPrice": "1050.0138",           // Mark price
    "strikePrice": "9000",              // Strike price
    "positionCost": "1000.0000",        // Position cost
    "expiryDate": 1593511200000         // Exercise time
    "priceScale": 2,
    "quantityScale": 2,
    "optionSide": "CALL",
    "quoteAsset": "USDT" 
   }
]

GET /eapi/v1/position (HMAC SHA256)

Get current position information.

Weight: 5

Parameters:

Name Type Mandatory Description
symbol STRING NO Option trading pair, e.g BTC-200730-9000-C
recvWindow LONG NO
timestamp LONG YES

Account Trade List (USER_DATA)

Response:

[
  {
    "id": 4611875134427365377,          // unique id
    "tradeId": 239,                     // trade id
    "orderId": 4611875134427365377,     // order id
    "symbol": "BTC-200730-9000-C",      // option symbol
    "price": "100",                     // trade price
    "quantity": "1",                    // trade quantity
    "fee": "0",                         // fee
    "realizedProfit": "0.00000000",     // realized profit/loss
    "side": "BUY",                      // order side
    "type": "LIMIT",                    // order type  
    "volatility": "0.9",                // volatility
    "liquidity": "TAKER",               // TAKER or MAKER      
    "quoteAsset": "USDT",               // quote asset
    "time": 1592465880683               // trade time
    "priceScale": 2,
    "quantityScale": 2,
    "optionSide": "CALL",
    "quoteAsset": "USDT"
  } 
]

GET /eapi/v1/userTrades (HMAC SHA256)

Get trades for a specific account and symbol.

Weight: 5

Parameters:

Name Type Mandatory Description
symbol STRING NO Option symbol, e.g BTC-200730-9000-C
fromId LONG NO Trade id to fetch from. Default gets most recent trades, e.g 4611875134427365376
startTime LONG NO Start time, e.g 1593511200000
endTime LONG NO End time, e.g 1593512200000
limit INT NO Default 100; max 1000
recvWindow LONG NO
timestamp LONG YES

User Exercise Record (USER_DATA)

Response:

[
    {
        "id": "1125899906842624042",
        "currency": "USDT",
        "symbol": "BTC-220721-25000-C",
        "exercisePrice": "25000.00000000",
        "markPrice": "25000.00000000",
        "quantity": "1.00000000",
        "amount": "0.00000000",
        "fee": "0.00000000",
        "createDate": 1658361600000,
        "priceScale": 2,
        "quantityScale": 2,
        "optionSide": "CALL",
        "positionSide": "LONG",
        "quoteAsset": "USDT"
    }
] 

GET /eapi/v1/exerciseRecord (HMAC SHA256)

Get account exercise records.

Weight: 5

Parameters:

Name Type Mandatory Description
symbol STRING NO Option trading pair, e.g BTC-200730-9000-C
startTime LONG NO startTime
endTime LONG NO endTime
limit INT NO default 1000, max 1000
recvWindow LONG NO
timestamp LONG YES

Account Funding Flow (USER_DATA)

Response:

[
  {
    "id": 1125899906842624000,
    "asset": "USDT",              // Asset type
    "amount": "-0.552",           // Amount (positive numbers represent inflow, negative numbers represent outflow)
    "type": "FEE",                // type (fees)
    "createDate": 1592449456000,  // Time
  },
  {
    "id": 1125899906842624000,
    "asset": "USDT",              // Asset type
    "amount": "100",              // Amount (positive numbers represent inflow, negative numbers represent outflow)
    "type": "CONTRACT",           // type (buy/sell contracts)
    "createDate": 1592449456000,  // Time
  },
  {
    "id": 1125899906842624000,
    "asset": "USDT",              // Asset type
    "amount": "10000",            // Amount (positive numbers represent inflow, negative numbers represent outflow)
    "type": "TRANSFER",           // type(Funds transfer)
    "createDate": 1592448410000,  // Time
  }
]

GET /eapi/v1/bill (HMAC SHA256)

Query account funding flows.

Weight: 1

Parameters:

Name Type Mandatory Description
currency STRING YES Asset type, e.g USDT
recordId LONG NO Return the recordId and subsequent data, the latest data is returned by default, e.g 100000
startTime LONG NO Start Time, e.g 1593511200000
endTime LONG NO End Time, e.g 1593512200000
limit INT NO Number of result sets returned Default:100 Max:1000
recvWindow LONG NO
timestamp LONG YES

Get Download Id For Option Transaction History (USER_DATA)

Response:

{
    "avgCostTimestampOfLast30d":7241837, // Average time taken for data download in the past 30 days
    "downloadId":"546975389218332672",
}

GET /eapi/v1/income/asyn (HMAC SHA256)

Weight: 5

Parameters:

Name Type Mandatory Description
startTime LONG YES Timestamp in ms
endTime LONG YES Timestamp in ms
recvWindow LONG NO
timestamp LONG YES

Response:

{
    "downloadId":"545923594199212032",
    "status":"completed",     // Enum:completed,processing
    "url":"www.binance.com",  // The link is mapped to download id
    "notified":true,          // ignore
    "expirationTimestamp":1645009771000,  // The link would expire after this timestamp
    "isExpired":null,
}

OR (Response when server is processing)

{
    "downloadId":"545923594199212032",
    "status":"processing",
    "url":"", 
    "notified":false,
    "expirationTimestamp":-1
    "isExpired":null,

}

GET /eapi/v1/income/asyn/id (HMAC SHA256)

Weight: 5

Parameters:

Name Type Mandatory Description
downloadId STRING YES get by download id api
recvWindow LONG NO
timestamp LONG YES

Websocket Market Streams

Live Subscribing/Unsubscribing to streams

Subscribe to a stream

Response

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

{
"method": "SUBSCRIBE",
"params":
[
"BTC-210630-9000-P@ticker",
"BTC-210630-9000-P@depth"
],
"id": 1
}

Unsubscribe to a stream

Response

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

{
"method": "UNSUBSCRIBE",
"params":
[
"BTC-210630-9000-P@ticker"
],
"id": 312
}

Listing Subscriptions

Response

  {
    "result": [
      "BTC-210630-9000-P@ticker"
    ],
    "id": 3
  }

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

Setting Properties

Currently, the only property can be set is to set whether combined stream payloads are enabled are not. The combined property is set to false when connecting using /ws/ ("raw streams") and true when connecting using /stream/.

Response

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

{
"method": "SET_PROPERTY",
"params":
[
"combined",
true
],
"id": 5
}

Retrieving Properties

Response javascript { "result": true, // Indicates that combined is set to true. "id": 2 }

{
"method": "GET_PROPERTY",
"params":
[
"combined"
],
"id": 2
}      

Error Messages

Error Message Description
{"code": 0, "msg": "Unknown property"} Parameter used in the SET_PROPERTY or GET_PROPERTY was invalid
{"code": 1, "msg": "Invalid value type: expected Boolean"} Value should only be true or false
{"code": 2, "msg": "Invalid request: property name must be a string"} Property name provided was invalid
{"code": 2, "msg": "Invalid request: request ID must be an unsigned integer"} Parameter id had to be provided or the value provided in the id parameter is an unsupported type
{"code": 2, "msg": "Invalid request: unknown variant %s, expected one of SUBSCRIBE, UNSUBSCRIBE, LIST_SUBSCRIPTIONS, SET_PROPERTY, GET_PROPERTY at line 1 column 28"} Possible typo in the provided method or provided method was neither of the expected values
{"code": 2, "msg": "Invalid request: too many parameters"} Unnecessary parameters provided in the data
{"code": 2, "msg": "Invalid request: property name must be a string"} Property name was not provided
{"code": 2, "msg": "Invalid request: missing field method at line 1 column 73"} method was not provided in the data
{"code":3,"msg":"Invalid JSON: expected value at line %s column %s"} JSON data sent has incorrect syntax.    ## Trade Streams

Trade Streams

** Payload: **

{
    "e":"trade",                        // event type   
    "E":1591677941092,                  // event time   
    "s":"BTC-200630-9000-P",            // Option trading symbol   
    "t":1,                              // trade ID   
    "p":"1000",                         // price   
    "q":"-2",                           // quantity   
    "b":4611781675939004417,            // buy order ID   
    "a":4611781675939004418,            // sell order ID   
    "T":1591677567872,                  // trade completed time  
    "S":"-1"                            // direction, -1 for taker sell, 1 for taker buy   
}

The Trade Streams push raw trade information for specific symbol or underlying asset. E.g.ETH@trade

Stream Name:
<symbol>@trade or <underlyingAsset>@trade

Update Speed: 50ms

Index Price Streams

** Payload: **

{
    "e":"index",         // event type
    "E":1661415480351,   // time
    "s":"ETHUSDT",       // underlying symbol
    "p":"1707.89008607"  // index price
}

Underlying(e.g ETHUSDT) index stream.

Stream Name:
<symbol>@index

Update Speed: 1000ms

Mark Price

** Payload: **

[
    {
      "e":"markPrice",         // Event Type
      "E":1663684594227,       // Event time
      "s":"ETH-220930-1500-C", // Symbol
      "mp":"30.3"              // Option mark price
    },
    {
      "e":"markPrice",
      "E":1663684594228,
      "s":"ETH-220923-1000-C",
      "mp":"341.5"
    }

The mark price for all option symbols on specific underlying asset. E.g.ETH@markPrice

Stream Name:
<underlyingAsset>@markPrice

Update Speed: 1000ms

Kline/Candlestick Streams

** Payload: **

{
    "e":"kline",                        // event type   
    "E":1638747660000,                  // event time   
    "s":"BTC-200630-9000-P",            // Option trading symbol   
    "k":{                             
        "t":1638747660000,              // kline start time   
        "T":1638747719999,              // kline end time  
        "s":"BTC-200630-9000-P",        // Option trading symbol   
        "i":"1m",                       // candle period   
        "F":0,                          // first trade ID  
        "L":0,                          // last trade ID   
        "o":"1000",                     // open   
        "c":"1000",                     // close   
        "h":"1000",                     // high    
        "l":"1000",                     // low   
        "v":"0",                        // volume(in contracts)   
        "n":0,                          // number of trades   
        "x":false,                      // current candle has been completed Y/N   
        "q":"0",                        // completed trade amount   (in quote asset)            
        "V":"0",                        // taker completed trade volume (in contracts)             
        "Q":"0"                         // taker trade amount(in quote asset)   
    }
}

The Kline/Candlestick Stream push updates to the current klines/candlestick every 1000 milliseconds (if existing).

Kline/Candlestick chart intervals:

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

"1m", "3m", "5m", "15m" "30m" "1h", "2h", "4h", "6h", "12h", "1d", "3d", "1w",

Stream Name:
<symbol>@kline_<interval>

Update Speed: 1000ms

24-hour TICKER

** Payload: **

{
    "e":"24hrTicker",           // event type
    "E":1657706425200,          // event time  
    "T":1657706425220,          // transaction time  
    "s":"BTC-220930-18000-C",   // Option symbol    
    "o":"2000",                 // 24-hour opening price
    "h":"2020",                 // Highest price
    "l":"2000",                 // Lowest price
    "c":"2020",                 // latest price
    "V":"1.42",                 // Trading volume(in contracts)  
    "A":"2841",                 // trade amount(in quote asset)   
    "P":"0.01",                 // price change percent
    "p":"20",                   // price change 
    "Q":"0.01",                 // volume of last completed trade(in contracts)  
    "F":"27",                   // first trade ID
    "L":"48",                   // last trade ID  
    "n":22,                     // number of trades
    "bo":"2012",                // The best buy price
    "ao":"2020",                // The best sell price
    "bq":"4.9",                 // The best buy quantity
    "aq":"0.03",                // The best sell quantity
    "b":"0.1202",               // BuyImplied volatility   
    "a":"0.1318",               // SellImplied volatility
    "d":"0.98911",              // delta
    "t":"-0.16961",             // theta 
    "g":"0.00004",              // gamma  
    "v":"2.66584",              // vega
    "vo":"0.10001",             // Implied volatility 
    "mp":"2003.5102",           // Mark price  
    "hl":"2023.511",            // Buy Maximum price
    "ll":"1983.511",            // Sell Minimum price 
    "eep":"0"                   // Estimated strike price (return estimated strike price half hour before exercise)
  }

24hr ticker info for all symbols. Only symbols whose ticker info changed will be sent.

Stream Name:
<symbol>@ticker

Update Speed: 1000ms  

24-hour TICKER by underlying asset and expiration data

** Payload: **

[
{
      "e":"24hrTicker",           // event type
      "E":1657706425200,          // event time 
      "T":1657706425220,          // transaction time  
      "s":"ETH-220930-1600-C",    // Option symbol    
      "o":"2000",                 // 24-hour opening price
      "h":"2020",                 // Highest price
      "l":"2000",                 // Lowest price
      "c":"2020",                 // latest price
      "V":"1.42",                 // Trading volume(in contracts)  
      "A":"2841",                 // trade amount(in quote asset)   
      "P":"0.01",                 // price change percent
      "p":"20",                   // price change 
      "Q":"0.01",                 // volume of last completed trade(in contracts)  
      "F":"27",                   // first trade ID
      "L":"48",                   // last trade ID  
      "n":22,                     // number of trades
      "bo":"2012",                // The best buy price
      "ao":"2020",                // The best sell price
      "bq":"4.9",                 // The best buy quantity
      "aq":"0.03",                // The best sell quantity
      "b":"0.1202",               // BuyImplied volatility   
      "a":"0.1318",               // SellImplied volatility
      "d":"0.98911",              // delta
      "t":"-0.16961",             // theta 
      "g":"0.00004",              // gamma  
      "v":"2.66584",              // vega
      "vo":"0.10001",             // Implied volatility 
      "mp":"2003.5102",           // Mark price  
      "hl":"2023.511",            // Buy Maximum price
      "ll":"1983.511",            // Sell Minimum price 
      "eep":"0"                   // Estimated strike price (return estimated strike price half hour before exercise)
    },
    {
      "e":"24hrTicker",
      "E":1663685112123,
      "s":"ETH-220930-1500-C",
      "o":"34.9",
      "h":"44.6",
      "l":"26.8",
      "c":"26.8",
      "V":"11.84",
      "A":"444.37",
      "P":"-0.232",
      "p":"-8.1",
      "Q":"0",
      "F":"91",
      "L":"129",
      "n":39,
      "bo":"26.8",
      "ao":"33.9",
      "bq":"0.65",
      "aq":"0.01",
      "b":"0.88790536",
      "a":"0.98729014",
      "d":"0.2621153",
      "t":"-3.44806807",
      "g":"0.00158298",
      "v":"0.7148147",
      "vo":"0.93759775",
      "mp":"30.3",
      "hl":"228.7",
      "ll":"0.1",
      "eep":"0"
    } 
]

24hr ticker info by underlying asset and expiration date. E.g.ETH@ticker@220930

Stream Name:
<underlyingAsset>@ticker@<expirationDate>

Update Speed: 1000ms  

Open Interest

[
    {
      "e":"openInterest",         // Event type
      "E":1668759300045,          // Event time
      "s":"ETH-221125-2700-C",    // option symbol
      "o":"1580.87",              // Open interest in contracts
      "h":"1912992.178168204"     // Open interest in USDT
    }
]

Option open interest for specific underlying asset on specific expiration date. E.g.ETH@openInterest@221125

Stream Name:
<underlyingAsset>@openInterest@<expirationDate>

Update Speed: 60s

New Symbol Info

{
    "e":"OPTION_PAIR",         //eventType   
    "E":1668573571842,         //eventTime   
    "id":652,                  //option id   
    "cid":2,                   //underlying asset id 
    "u":"BTCUSDT",             //Underlying index of the contract
    "qa":"USDT",               //Quotation asset 
    "s":"BTC-221116-21000-C",  //Trading pair name 
    "unit":1,                  //Conversion ratio, the quantity of the underlying asset represented by a single contract. 
    "mq":"0.01",               //Minimum trade volume of the underlying asset  
    "d":"CALL",                //Option type
    "sp":"21000",              //Strike price  
    "ed":1668585600000         //expiration time  
}

New symbol listing stream.

Stream Name:
option_pair

Update Speed: 50ms  

Partial Book Depth Streams

** Payload: **

{
    "e":"depth",                    // event type 
    "E":1591695934010,              // event time
    "T":1591695934000,              // transaction time 
    "s":"BTC-200630-9000-P",        // Option symbol  
    "u":162,                                    // update id in event
    "pu":162,                                   // same as update id in event    
    "b":[                           // Buy order   
      [
          "200",                    // Price
          "3",                      // quantity
      ],
      [
          "101",
          "1"
      ],
      [
          "100",
          "2"
      ]
    ],
    "a":[                           // Sell order   
        [
            "1000",
            "89"
        ]
    ]
}

Top bids and asks, Valid levels are are 10, 20, 50, 100.

Stream Names: <symbol>@depth<levels> OR <symbol>@depth<levels>@100ms OR <symbol>@depth<levels>@1000ms.

Update Speed: 100ms or 1000ms, 500ms(default when update speed isn't used)

User Data Streams

Start User Data Stream (USER_STREAM)

Response:

{
  "listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1",
  "expiration":1710140106000
}

POST /eapi/v1/listenKey

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

Weight: 1

Parameters:

None

Keepalive User Data Stream (USER_STREAM)

Response:

{}

PUT /eapi/v1/listenKey

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

Weight: 1

Parameters:

None

Close User Data Stream (USER_STREAM)

Response:

{}

DELETE /eapi/v1/listenKey

Close out a user data stream.

Weight: 1

Parameters:

None

Event: Risk level change

Payload:

{ 
    "e":"RISK_LEVEL_CHANGE", //Event Type 
    "E":1587727187525, //Event Time 
    "s":"REDUCE_ONLY", //risk level
    "mb":"1534.11708371", //margin balance 
    "mm":"254789.11708371" //maintenance margin 
} 

Event: Account data

Payload:

{
    "e":"ACCOUNT_UPDATE",                 // Event type
    "E":1591696384141,                    // Event time
    "B":[
        {
          "b":"100007992.26053177",       // Account balance   
          "m":"0",                        // Position value    
          "u":"458.782655111111",         // Unrealized profit/loss   
          "U":200,                        // Positive unrealized profit for long position 
          "M":"-15452.328456",            // Maintenance margin   
          "i":"-18852.328456",            // Initial margin   
          "a":"USDT",                     // Margin asset  
        }
    ],
    "G":[
        {
         "ui":"SOLUSDT",                  // Underlying
         "d":-33.2933905,                 // Delta  
         "t":35.5926375,                  // Theta 
         "g":-14.3023855,                 // Gamma 
         "v":-0.1929375                   // Vega    
        }
    ],
    "P":[
      {
       "s":"SOL-220912-35-C",             // Contract symbol   
       "c":"-50",                         // Number of current positions   
       "r":"-50",                         // Number of positions that can be reduced    
       "p":"-100",                        // Position value   
       "a":"2.2",                         // Average entry price    
      }
    ],
    "uid":1000006559949
} 

Event: Order update

Payload:

{
  "e":"ORDER_TRADE_UPDATE",           //Event Type
  "E":1657613775883,                  //Event Time 
  "o":[
    {
      "T":1657613342918,              //Order Create Time
      "t":1657613342918,              //Order Update Time
      "s":"BTC-220930-18000-C",       //Symbol
      "c":"",                         //clientOrderId
      "oid":"4611869636869226548",    //order id
      "p":"1993",                     //order price
      "q":"1",                        //order quantity
      "stp":0,                        //not used for now
      "r":false,                      //reduce only
      "po":true,                      //post only
      "S":"PARTIALLY_FILLED",         //status
      "e":"0.1",                      //completed trade volume(in contracts)       
      "ec":"199.3",                   //completed trade amount(in quote asset) 
      "f":"2",                        //fee 
      "tif": "GTC",                   //time in force 
      "oty":"LIMIT",                  //order type
      "fi":[
        {
          "t":"20",                   //tradeId
          "p":"1993",                 //trade price
          "q":"0.1",                  //trade quantity
          "T":1657613774336,          //trade time
          "m":"TAKER"                 //taker or maker
          "f":"0.0002"                //commission(>0) or rebate(<0)
        }
      ]
    }
  ]
}

Market Maker Endpoints

Market maker endpoints only work for option market makers, api users will get error when send requests to these endpoints.

Option Margin Account Information (USER_DATA)

Response:

{
  "asset": [                  
    {
      "asset": "USDT",                  // Asset type
      "marginBalance": "10099.448"      // Account balance
      "equity": "10094.44662",          // Account equity
      "available": "8725.92524",        // Available funds
      "initialMargin": "1084.52138",    // Initial margin
      "maintMargin": "151.00138",       // Maintenance margin
      "unrealizedPNL": "-5.00138",      // Unrealized profit/loss
      "lpProfit": "-5.00138",           // Unrealized profit for long position 
     }
  ], 
  "greek": [
    {
      "underlying":"BTCUSDT"            // Option Underlying
      "delta": "-0.05"                  // Account delta
      "gamma": "-0.002"                 // Account gamma
      "theta": "-0.05"                  // Account theta
      "vega": "-0.002"                  // Account vega  
    }
  ],
  "riskLevel": "NORMAL",                // Account risk level
  "time": 1592449455993                 // Time  
}   

GET /eapi/v1/marginAccount (HMAC SHA256)

Get current account information.

Weight: 3

Parameters:

Name Type Mandatory Description
recvWindow LONG NO
timestamp LONG YES

Set Market Maker Protection Config (TRADE)

{
    "underlyingId": 2,
    "underlying": "BTCUSDT",
    "windowTimeInMilliseconds": 3000,
    "frozenTimeInMilliseconds": 300000,
    "qtyLimit": "2",
    "deltaLimit": "2.3",
    "lastTriggerTime": 0

}

POST /eapi/v1/mmpSet (HMAC SHA256)

Set config for MMP. Market Maker Protection(MMP) is a set of protection mechanism for option market maker, this mechanism is able to prevent mass trading in short period time. Once market maker's account branches the threshold, the Market Maker Protection will be triggered. When Market Maker Protection triggers, all the current MMP orders will be canceled, new MMP orders will be rejected. Market maker can use this time to reevaluate market and modify order price.

Weight: 1

Parameters:

Name Type Mandatory Description
underlying STRING TRUE underlying, e.g BTCUSDT
windowTimeInMilliseconds LONG TRUE MMP Interval in milliseconds; Range (0,5000]
frozenTimeInMilliseconds LONG TRUE MMP frozen time in milliseconds, if set to 0 manual reset is required
qtyLimit DECIMAL TRUE quantity limit
deltaLimit DECIMAL TRUE net delta limit
recvWindow LONG NO
timestamp LONG YES

Get Market Maker Protection Config (TRADE)

{
    "underlyingId": 2,
    "underlying": "BTCUSDT",
    "windowTimeInMilliseconds": 3000,
    "frozenTimeInMilliseconds": 300000,
    "qtyLimit": "2",
    "deltaLimit": "2.3",
    "lastTriggerTime": 0
}

Get /eapi/v1/mmp (HMAC SHA256)

Get config for MMP.

Weight: 1

Parameters:

Name Type Mandatory Description
underlying STRING TRUE underlying, e.g BTCUSDT
recvWindow LONG NO
timestamp LONG YES

Reset Market Maker Protection Config (TRADE)

{
    "underlyingId": 2,
    "underlying": "BTCUSDT",
    "windowTimeInMilliseconds": 3000,
    "frozenTimeInMilliseconds": 300000,
    "qtyLimit": "2",
    "deltaLimit": "2.3",
    "lastTriggerTime": 0
}

POST /eapi/v1/mmpReset (HMAC SHA256)

Reset MMP, start MMP order again.

Weight: 1

Parameters:

Name Type Mandatory Description
underlying STRING TRUE underlying, e.g BTCUSDT
recvWindow LONG NO
timestamp LONG YES

Set Auto-Cancel All Open Orders (Kill-Switch) Config (TRADE)

Response:

{
  "underlying": "ETHUSDT",
  "countdownTime": 30000
}

POST /eapi/v1/countdownCancelAll (HMAC SHA256)  

This endpoint sets the parameters of the auto-cancel feature which cancels all open orders (both market maker protection and non market maker protection order types) of the underlying symbol at the end of the specified countdown time period if no heartbeat message is sent. After the countdown time period, all open orders will be cancelled and new orders will be rejected with error code -2010 until either a heartbeat message is sent or the auto-cancel feature is turned off by setting countdownTime to 0.

Weight: 1

Parameters:

Name Type Mandatory Description
underlying STRING YES Option underlying, e.g BTCUSDT
countdownTime LONG YES Countdown time in milliseconds (ex. 1,000 for 1 second). 0 to disable the timer. Negative values (ex. -10000) are not accepted. Minimum acceptable value is 5,000 
recvWindow LONG NO
timestamp LONG YES

Get Auto-Cancel All Open Orders (Kill-Switch) Config (TRADE)

Response:

{
  "underlying": "ETHUSDT",
  "countdownTime": 100000
}

GET /eapi/v1/countdownCancelAll (HMAC SHA256)  

This endpoint returns the auto-cancel parameters for each underlying symbol. Note only active auto-cancel parameters will be returned, if countdownTime is set to 0 (ie. countdownTime has been turned off), the underlying symbol and corresponding countdownTime parameter will not be returned in the response.

Weight: 1

Parameters:

Name Type Mandatory Description
underlying STRING NO Option underlying, e.g BTCUSDT
recvWindow LONG NO
timestamp LONG YES

Auto-Cancel All Open Orders (Kill-Switch) Heartbeat (TRADE)

Response:

{
 "underlyings":["BTCUSDT","ETHUSDT"]
}

POST /eapi/v1/countdownCancelAllHeartBeat (HMAC SHA256)

This endpoint resets the time from which the countdown will begin to the time this messaged is received. It should be called repeatedly as heartbeats. Multiple heartbeats can be updated at once by specifying the underlying symbols as a list (ex. BTCUSDT,ETHUSDT) in the underlyings parameter.

Weight: 10

Parameters:

Name Type Mandatory Description
underlyings STRING YES Option Underlying Symbols, e.g BTCUSDT,ETHUSDT
recvWindow LONG NO
timestamp LONG YES

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

-1008 TOO_MANY_REQUESTS

-1014 UNKNOWN_ORDER_COMPOSITION

-1015 TOO_MANY_ORDERS

-1016 SERVICE_SHUTTING_DOWN

-1020 UNSUPPORTED_OPERATION

-1021 INVALID_TIMESTAMP

-1022 INVALID_SIGNATURE

11xx - 2xxx 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

-1111 BAD_PRECISION

-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 BAD_CONTRACT

-1129 BAD_CURRENCY

-1130 INVALID_PARAMETER

-1131 BAD_RECV_WINDOW

-2010 NEW_ORDER_REJECTED

-2013 NO_SUCH_ORDER

-2014 BAD_API_KEY_FMT

-2015 INVALID_API_KEY

-2018 BALANCE_NOT_SUFFICIENT

-2027 OPTION_MARGIN_NOT_SUFFICIENT

3xxx-5xxx Filters and other issues

-3029 TRANSFER_FAILED

-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

-4013 PRICE_LESS_THAN_MIN_PRICE

-4029 INVALID_TICK_SIZE_PRECISION

-4030 INVALID_QTY_PRECISION

-4055 AMOUNT_MUST_BE_POSITIVE