Loading
- FAQ
- TOS
- Privacy
Go to binance
r/binance
r/binance
A place to interact with the community, and discuss all things crypto and Binance!
Members
Online
•
by
Toplerrr
Anyone getting a 503 service temporarily unavailable when trying to access website or app
Binance.US
service temporarily unavailable when trying to access website or app
Change Log
2020-12-30
REST
-
Following DAPI endpoints will use new weight rule based on the paremeter «LIMIT» in the request:
- GET /dapi/v1/klines
- GET /dapi/v1/continuousKlines
- GET /dapi/v1/indexPriceKlines
- GET /dapi/v1/markPriceKlines
-
Following DAPI endpoints’ weights will be updated to 20:
- GET /dapi/v1/historicalTrades
- GET /dapi/v1/allForceOrders
- GET /dapi/v1/forceOrders
- GET /dapi/v1/aggTrades
2020-11-27
- New endpoint
GET /dapi/v1/commissionRate
to get user commission rate.
2020-08-14
WEBSOCKET
- Websocket Request for user data:
<listenKey>@account
request for user’s account information<listenKey>@balance
request for user’s account balance<listenKey>@balance
request for user’s position information
REST
- * New endpoint
GET /dapi/v1/adlQuantile
to get the positions’ ADL quantile estimation values
2020-08-12
- New endpoint
GET /dapi/v1/forceOrders
to get the user’s force orderes.
2020-07-30
COIN MARGINED PERPETUAL FUTURES
-
New contract type («contractType»)
PERPETUAL
for coin margined perpetual futures countract. -
New fields in the reponse to endpoint
GET /dapi/v1/premiumIndex
:-
lastFundingRate
for the lasted funding rate of the perpetual futures contract -
nextFundingTime
for the next funding time of the perpetual futures contract
-
-
New endpoint
GET /dapi/v1/fundingRate
to get funding rate history of perpetual futures -
New fields in the payload of WSS
<symbol>@markPrice
,<symbol>@markPrice@1s
,<pair>@markPrice
, and<pair>@markPrice@1s
:r
for the lasted funding rate of the perpetual futures contractT
for the next funding time of the perpetual futures contract
2020-07-17
- Weights of endpoint
GET /dapi/v1/income
has been changed as 20
General Info
General API Information
- The base endpoint is: https://testnet.binancefuture.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.
- All data types adopt definition in JAVA.
HTTP Return Codes
- HTTP
4XX
return codes are used for for malformed requests;
the issue is on the sender’s side. - HTTP
403
return code is used when the WAF Limit (Web Application Firewall) has been violated. - 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 receiving429
codes. - HTTP
5XX
return codes are used for internal errors; the issue is on
Binance’s side.
HTTP503
return code is used when the API successfully sent the message but not get a response within the timeout period.
It is important to NOT treat this as a failure operation; the execution status is
UNKNOWN and could have been a success.
Error Codes
- 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 Codes.
General Information on Endpoints
- For
GET
endpoints, parameters must be sent as aquery string
. - For
POST
,PUT
, andDELETE
endpoints, the parameters may be sent as a
query string
or in therequest body
with content type
application/x-www-form-urlencoded
. You may mix parameters between both the
query string
andrequest body
if you wish to do so. - Parameters may be sent in any order.
- If a parameter sent in both the
query string
andrequest body
, the
query string
parameter will be used.
LIMITS
- The
/dapi/v1/exchangeInfo
rateLimits
array contains objects related to the exchange’sRAW_REQUEST
,REQUEST_WEIGHT
, andORDER
rate limits. These are further defined in theENUM definitions
section underRate limiters (rateLimitType)
. - A
429
will be returned when either rate limit is violated.
IP Limits
- Every request will contain
X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)
in the response headers which has the current used weight for the IP for all request rate limiters defined. - 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 heavierweight
. - When a 429 is received, 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 429s 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.
- The limits on the API are based on the IPs, not the API keys.
Order Rate Limits
- Every order response will contain a
X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)
header which has the current order count for the account for all order rate limiters defined. - Rejected/unsuccessful orders are not guaranteed to have
X-MBX-ORDER-COUNT-**
headers in the response. - The order rate limit is counted against each account.
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
andUSER_DATA
endpoints areSIGNED
endpoints.
SIGNED (TRADE and USER_DATA) Endpoint Security
SIGNED
endpoints require an additional parameter,signature
, to be
sent in thequery string
orrequest body
.- Endpoints use
HMAC SHA256
signatures. TheHMAC SHA256 signature
is a keyedHMAC SHA256
operation.
Use yoursecretKey
as the key andtotalParams
as the value for the HMAC operation. - The
signature
is not case sensitive. - Please make sure the
signature
is the end part of yourquery string
orrequest body
. totalParams
is defined as thequery 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 aftertimestamp
the request is valid for. IfrecvWindow
is not sent, it defaults to 5000. - If the server determines that the timestamp sent by the client is more than one second in the future of the server time, the request will also be rejected.
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 /dapi/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 | BTCUSD_200925 |
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=BTCUSD_200925&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000×tamp=1591702613943" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
(stdin)= 21fd819734bf0e5c68740eed892909414d693635c5f7fffab1313925ae13556a
curl command:
(HMAC SHA256)
$ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://testnet.binancefuture.com/dapi/v1/order?symbol=BTCUSD_200925&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000×tamp=1591702613943&signature= 21fd819734bf0e5c68740eed892909414d693635c5f7fffab1313925ae13556a'
-
queryString:
symbol=BTCUSD_200925
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=9000
&recvWindow=5000
×tamp=1591702613943
Example 2: As a request body
Example 2
HMAC SHA256 signature:
$ echo -n "symbol=BTCUSD_200925&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000×tamp=1591702613943" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
(stdin)= 21fd819734bf0e5c68740eed892909414d693635c5f7fffab1313925ae13556a
curl command:
(HMAC SHA256)
$ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://testnet.binancefuture.com/dapi/v1/order' -d 'symbol=BTCUSD_200925&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000×tamp=1591702613943&signature= 21fd819734bf0e5c68740eed892909414d693635c5f7fffab1313925ae13556a'
-
requestBody:
symbol=BTCUSD_200925
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=9000
&recvWindow=5000
×tamp=1591702613943
Example 3: Mixed query string and request body
Example 3
HMAC SHA256 signature:
$ echo -n "symbol=BTCUSD_200925&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000×tamp=1591702613943" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
(stdin)= 21fd819734bf0e5c68740eed892909414d693635c5f7fffab1313925ae13556a
curl command:
(HMAC SHA256)
$ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://testnet.binancefuture.com/dapi/v1/order?symbol=BTCUSD_200925&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=9000&recvWindow=5000×tamp=1591702613943&signature=21fd819734bf0e5c68740eed892909414d693635c5f7fffab1313925ae13556a'
- queryString: symbol=BTCUSD_200925&side=BUY&type=LIMIT&timeInForce=GTC
- requestBody: quantity=1&price=9000&recvWindow=5000×tamp= 1591702613943
27319559
Note that the signature is different in example 3.
There is no & between «GTC» and «quantity=1».
Public Endpoints Info
Terminology
symbol
refers to the symbol name of a contract symbolpair
refers to the underlying symbol of a contracrt symbolbase asset
refers to the asset that is thequantity
of a symbol.quote asset
refers to the asset that is theprice
of a symbol.margin asset
refers to the asset that is themargin
of a symbol
ENUM definitions
Symbol type:
- DELIVERY_CONTRACT
- PERPETUAL_CONTRACT
Contract type (contractType):
- PERPETUAL
- CURRENT_QUARTER
- NEXT_QUARTER
Contract status (contractStatus):
- PENDING_TRADING
- TRADING
- PRE_DELIVERING
- DELIVERING
- DELIVERED
Order status (status):
- NEW
- PARTIALLY_FILLED
- FILLED
- CANCELED
- EXPIRED
Order types (type):
- LIMIT
- MARKET
- STOP
- STOP_MARKET
- TAKE_PROFIT
- TAKE_PROFIT_MARKET
- TRAILING_STOP_MARKET
Order side (side):
- BUY
- SELL
Position side (positionSide):
- BOTH
- LONG
- SHORT
Time in force (timeInForce):
- GTC — Good Till Cancel
- IOC — Immediate or Cancel
- FOK — Fill or Kill
- GTX — Good Till Crossing (Post Only)
Working Type (workingType)
- MARK_PRICE
- CONTRACT_PRICE
Response Type (newOrderRespType)
- ACK
- RESULT
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": 6000
}
ORDERS
{
"rateLimitType": "ORDERS",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 1200
}
-
REQUEST_WEIGHT
-
ORDERS
Rate limit intervals (interval)
- MINUTE
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:
minPrice
defines the minimumprice
/stopPrice
allowed; disabled onminPrice
== 0.maxPrice
defines the maximumprice
/stopPrice
allowed; disabled onmaxPrice
== 0.tickSize
defines the intervals that aprice
/stopPrice
can be increased/decreased by; disabled ontickSize
== 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
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:
minQty
defines the minimumquantity
allowed.maxQty
defines the maximumquantity
allowed.stepSize
defines the intervals that aquantity
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
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:
minQty
defines the minimumquantity
allowed.maxQty
defines the maximumquantity
allowed.stepSize
defines the intervals that aquantity
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
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
:
- BUY:
price
<=markPrice
*multiplierUp
- SELL:
price
>=markPrice
*multiplierDown
Market Data Endpoints
Test Connectivity
Response:
{}
GET /dapi/v1/ping
Test connectivity to the Rest API.
Weight:
1
Parameters:
NONE
Check Server time
Response:
{
"serverTime": 1499827319559
}
GET /dapi/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": [ // contract symbols
{
"filters": [
{
"filterType": "PRICE_FILTER",
"maxPrice": "100000",
"minPrice": "0.1",
"tickSize": "0.1"
},
{
"filterType": "LOT_SIZE",
"maxQty": "100000",
"minQty": "1",
"stepSize": "1"
},
{
"filterType": "MARKET_LOT_SIZE",
"maxQty": "100000",
"minQty": "1",
"stepSize": "1"
},
{
"filterType": "MAX_NUM_ORDERS",
"limit": 200
},
{
"filterType": "PERCENT_PRICE",
"multiplierUp": "1.0500",
"multiplierDown": "0.9500",
"multiplierDecimal": 4
}
],
"OrderType": [
"LIMIT",
"MARKET",
"STOP",
"TAKE_PROFIT",
"TRAILING_STOP_MARKET"
],
"timeInForce": [
"GTC",
"IOC",
"FOK",
"GTX"
],
"symbol": "BTCUSD_200925", // contract symbol name
"pair": "BTCUSD", // underlying symbol
"contractType": "CURRENT_QUARTER",
"deliveryDate": 1601020800000,
"onboardDate": 1590739200000,
"contractStatus": "TRADING",
"contractSize": 100,
"quoteAsset": "USD",
"baseAsset": "BTC",
"marginAsset": "BTC",
"pricePrecision": 1,
"quantityPrecision": 0,
"baseAssetPrecision": 8,
"quotePrecision": 8,
"equalQtyPrecision": 4, // ignore
"triggerProtect": "0.0500", // threshold for algo order with "priceProtect"
"maintMarginPercent": "2.5000", // ignore
"requiredMarginPercent": "5.0000", // ignore
"underlyingType": "COIN",
"underlyingSubType": []
}
],
"timezone": "UTC"
}
GET /dapi/v1/exchangeInfo
Current exchange trading rules and symbol information
Weight:
1
Parameters:
NONE
Order Book
Response:
{
"lastUpdateId": 16769853,
"symbol": "BTCUSD_PERP", // Symbol
"pair": "BTCUSD", // Pair
"E": 1591250106370, // Message output time
"T": 1591250106368, // Transaction time
"bids": [
[
"9638.0", // PRICE
"431" // QTY
]
],
"asks": [
[
"9638.2",
"12"
]
]
}
GET /dapi/v1/depth
Weight:
Adjusted based on the limit:
Limit | Weight |
---|---|
5, 10, 20, 50 | 2 |
100 | 5 |
500 | 10 |
1000 | 20 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 500; Valid limits:[5, 10, 20, 50, 100, 500, 1000] |
Recent Trades List
Response:
[
{
"id": 28457,
"price": "9635.0",
"qty": "1",
"baseQty": "0.01037883",
"time": 1591250192508,
"isBuyerMaker": true,
}
]
GET /dapi/v1/trades
Get recent trades
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
limit | INT | NO | Default 500; max 1000. |
Old Trades Lookup (MARKET_DATA)
Response:
[
{
"id": 595103,
"price": "9642.2",
"qty": "1",
"baseQty": "0.01037108",
"time": 1499865549590,
"isBuyerMaker": true,
}
]
GET /dapi/v1/historicalTrades
Get older market historical trades.
Weight:
20
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": 416690, // Aggregate tradeId
"p": "9642.4", // Price
"q": "3", // Quantity
"f": 595259, // First tradeId
"l": 595259, // Last tradeId
"T": 1591250548649, // Timestamp
"m": false, // Was the buyer the maker?
}
]
GET /dapi/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:
20
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. |
- If fromId, startTime, and endTime are not sent, the most recent aggregate trades will be returned.
Index Price and Mark Price
Response:
[
{
"symbol": "BTCUSD_PERP",
"pair": "BTCUSD",
"markPrice": "11029.69574559", // mark price
"indexPrice": "10979.14437500", // index price
"estimatedSettlePrice": "10981.74168236", // Estimated Settle Price, only useful in the last hour before the settlement starts.
"lastFundingRate": "0.00071003", // the lasted funding rate, for perpetual contract symbols only. For delivery symbols, "" will be shown.
"interestRate": "0.00010000", // the base asset interest rate, for perpetual contract symbols only. For delivery symbols, "" will be shown.
"nextFundingTime": 1596096000000, // For perpetual contract symbols only. For delivery symbols, 0 will be shown
"time": 1596094042000
},
{
"symbol": "BTCUSD_200925",
"pair": "BTCUSD",
"markPrice": "12077.01343750",
"indexPrice": "10979.10312500",
"estimatedSettlePrice": "10981.74168236",
"lastFundingRate": "",
"interestRate": "",
"nextFundingTime": 0,
"time": 1596094042000
}
]
GET /dapi/v1/premiumIndex
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | |
pair | STRING | NO |
Get Funding Rate History of Perpetual Futures
Response:
[
{
"symbol": "BTCUSD_PERP",
"fundingTime": 1596038400000,
"fundingRate": "-0.00300000"
},
{
"symbol": "BTCUSD_PERP",
"fundingTime": 1596067200000,
"fundingRate": "-0.00300000"
}
]
GET /dapi/v1/fundingRate
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
startTime | LONG | NO | Timestamp in ms to get funding rate from INCLUSIVE. |
endTime | LONG | NO | Timestamp in ms to get funding rate until INCLUSIVE. |
limit | INT | NO | Default 100; max 1000 |
- empty array will be returned for delivery symbols.
Kline/Candlestick Data
Response:
[
[
1591258320000, // Open time
"9640.7", // Open
"9642.4", // High
"9640.6", // Low
"9642.0", // Close (or latest price)
"206", // Volume
1591258379999, // Close time
"2.13660389", // Base asset volume
48, // Number of trades
"119", // Taker buy volume
"1.23424865", // Taker buy base asset volume
"0" // Ignore.
]
]
GET /dapi/v1/klines
Kline/candlestick bars for a symbol.
Klines are uniquely identified by their open time.
Weight: based on parameter LIMIT
LIMIT | weight |
---|---|
[1,100) | 1 |
[100, 500) | 2 |
[500, 1000] | 5 |
> 1000 | 10 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
interval | ENUM | YES | |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | Default 500; max 1500. |
-
If startTime and endTime are not sent, the most recent klines are returned.
-
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
Continues Contract Kline/Candlestick Data
Response:
[
[
1591258320000, // Open time
"9640.7", // Open
"9642.4", // High
"9640.6", // Low
"9642.0", // Close (or latest price)
"206", // Volume
1591258379999, // Close time
"2.13660389", // Base asset volume
48, // Number of trades
"119", // Taker buy volume
"1.23424865", // Taker buy base asset volume
"0" // Ignore.
]
]
GET /dapi/v1/continuousKlines
Kline/candlestick bars for a specific contract type.
Klines are uniquely identified by their open time.
Weight: based on parameter LIMIT
LIMIT | weight |
---|---|
[1,100) | 1 |
[100, 500) | 2 |
[500, 1000] | 5 |
> 1000 | 10 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
pair | STRING | YES | |
contractType | ENUM | YES | |
interval | ENUM | YES | |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | Default 500; max 1500. |
-
If startTime and endTime are not sent, the most recent klines are returned.
-
Contract type:
- PERPETUAL
- CURRENT_QUARTER
- NEXT_QUARTER
Index Price Kline/Candlestick Data
Response:
[
[
1591256400000, // Open time
"9653.69440000", // Open
"9653.69640000", // High
"9651.38600000", // Low
"9651.55200000", // Close (or latest price)
"0 ", // Ignore
1591256459999, // Close time
"0", // Ignore
60, // Number of bisic data
"0", // Ignore
"0", // Ignore
"0" // Ignore
]
]
GET /dapi/v1/indexPriceKlines
Kline/candlestick bars for the index price of a pair.
Klines are uniquely identified by their open time.
Weight: based on parameter LIMIT
LIMIT | weight |
---|---|
[1,100) | 1 |
[100, 500) | 2 |
[500, 1000] | 5 |
> 1000 | 10 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
pair | STRING | YES | |
interval | ENUM | YES | |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | Default 500; max 1500. |
Mark Price Kline/Candlestick Data
Response:
[
[
1591256460000, // Open time
"9653.29201333", // Open
"9654.56401333", // High
"9653.07367333", // Low
"9653.07367333", // Close (or latest price)
"0 ", // Ignore
1591256519999, // Close time
"0", // Ignore
60, // Number of bisic data
"0", // Ignore
"0", // Ignore
"0" // Ignore
]
]
GET /dapi/v1/markPriceKlines
Kline/candlestick bars for the mark price of a symbol.
Klines are uniquely identified by their open time.
Weight: based on parameter LIMIT
LIMIT | weight |
---|---|
[1,100) | 1 |
[100, 500) | 2 |
[500, 1000] | 5 |
> 1000 | 10 |
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
interval | ENUM | YES | |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | Default 500; max 1500. |
24hr Ticker Price Change Statistics
Response:
[
{
"symbol": "BTCUSD_200925",
"pair": "BTCUSD",
"priceChange": "136.6",
"priceChangePercent": "1.436",
"weightedAvgPrice": "9547.3",
"lastPrice": "9651.6",
"lastQty": "1",
"openPrice": "9515.0",
"highPrice": "9687.0",
"lowPrice": "9499.5",
"volume": "494109",
"baseVolume": "5192.94797687",
"openTime": 1591170300000,
"closeTime": 1591256718418,
"firstId": 600507, // First tradeId
"lastId": 697803, // Last tradeId
"count": 97297 // Trade count
}
]
GET /dapi/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 | |
pair | STRING | NO |
- Symbol and pair cannot be sent together
- If a pair is sent,tickers for all symbols of the pair will be returned
- If either a pair or symbol is sent, tickers for all symbols of all pairs will be returned
Symbol Price Ticker
Response:
[
{
"symbol": "BTCUSD_200626",
"ps": "9647.8", // pair
"price": "9647.8",
"time": 1591257246176
}
]
GET /dapi/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 | |
pair | STRING | NO |
- Symbol and pair cannot be sent together
- If a pair is sent,tickers for all symbols of the pair will be returned
- If either a pair or symbol is sent, tickers for all symbols of all pairs will be returned
Symbol Order Book Ticker
[
{
"symbol": "BTCUSD_200626",
"pair": "BTCUSD",
"bidPrice": "9650.1",
"bidQty": "16",
"askPrice": "9650.3",
"askQty": "7",
"time": 1591257300345
}
]
GET /dapi/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 | |
pair | STRING | NO |
- Symbol and pair cannot be sent together
- If a pair is sent,tickers for all symbols of the pair will be returned
- If either a pair or symbol is sent, tickers for all symbols of all pairs will be returned
Get all Liquidation Orders
Response:
[
{
"symbol": "BTCUSD_200925", // SYMBOL
"price": "9425.5", // ORDER_PRICE
"origQty": "1", // ORDER_AMOUNT
"executedQty": "1", // FILLED_AMOUNT
"avragePrice": "9496.5", // AVG_PRICE
"status": "FILLED", // STATUS
"timeInForce": "IOC", // TIME_IN_FORCE
"type": "LIMIT", // ORDER TYPE
"side": "SELL", // DIRECTION
"time": 1591154240949
},
]
GET /dapi/v1/allForceOrders
Weight: 20
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | |
pair | STRING | NO | |
startTime | LONG | NO | |
endTime | LONG | NO | Default precent timestamp |
limit | LONG | NO | Max returned data number from endTime; Default:100 Max:1000 |
- Symbol and pair cannot be sent together
- If a pair is sent,tickers for all symbols of the pair will be returned
- If either a pair or symbol is sent, tickers for all symbols of all pairs will be returned
Open Interest
Response:
{
"symbol": "BTCUSD_200626",
"pair": "BTCUSD",
"openInterest": "15004",
"contractType": "CURRENT_QUARTER",
"time": 1591261042378
}
Get present open interest of a specific symbol.
GET /dapi/v1/openInterest
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES |
Websocket Market Streams
- The base endpoint is: wss://dstream.binancefuture.com
- Streams can be access either in a single raw stream or a combined stream
- Raw streams are accessed at /ws/<streamName>
- Combined streams are accessed at /stream?streams=<streamName1>/<streamName2>/<streamName3>
- Combined stream events are wrapped as follows: {«stream»:»<streamName>»,»data»:<rawPayload>}
- All symbols, pairs, and contract types for streams are lowercase
- A single connection is only valid for 24 hours; expect to be disconnected at the 24 hour mark
- The websocket server will send a
ping frame
every 5 minutes. If the websocket server does not receive apong frame
back from the connection within a 15 minute period, the connection will be disconnected. Unsolicitedpong frames
are allowed. - WebSocket connections have a limit of 10 incoming messages per second.
- A connection that goes beyond the limit will be disconnected; IPs that are repeatedly disconnected may be banned.
- A single connection can listen to a maximum of 200 streams.
Live Subscribing/Unsubscribing to streams
- The following data can be sent through the websocket instance in order to subscribe/unsubscribe from streams. Examples can be seen below.
- The
id
used in the JSON payloads is an unsigned INT used as an identifier to uniquely identify the messages going back and forth.
Subscribe to a stream
Response
{
"result": null,
"id": 1
}
-
Request
{
«method»: «SUBSCRIBE»,
«params»:
[
«btcusd_200925@aggTrade»,
«btcusd_200925@depth»
],
«id»: 1
}
Unsubscribe to a stream
Response
{
"result": null,
"id": 312
}
- Request
{
«method»: «UNSUBSCRIBE»,
«params»:
[
«btcusd_200925@depth»
],
«id»: 312
}
Listing Subscriptions
Response
{
"result": [
"btcusd_200925@aggTrade"
],
"id": 3
}
- Request
{
«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
}
- Request
{
«method»: «SET_PROPERTY»,
«params»:
[
«combined»,
true
],
«id»: 5
}
Retrieving Properties
Response
{
"result": true, // Indicates that combined is set to true.
"id": 2
}
- Request
{
«method»: «GET_PROPERTY»,
«params»:
[
«combined»
],
«id»: 2
}
Aggregate Trade Streams
Payload:
{
"e":"aggTrade", // Event type
"E":1591261134288, // Event time
"a":424951, // Aggregate trade ID
"s":"BTCUSD_200626", // Symbol
"p":"9643.5", // Price
"q":"2", // Quantity
"f":606073, // First trade ID
"l":606073, // Last trade ID
"T":1591261134199, // Trade time
"m":false / 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
Update Speed: 100ms
Index Price Stream
Payload:
{
"e": "indexPriceUpdate", // Event type
"E": 1591261236000, // Event time
"i": "BTCUSD", // Pair
"p": "9636.57860000", // Index Price
}
Stream Name:
<pair>@indexPrice
OR <pair>@indexPrice@1s
Update Speed: 3000ms OR 1000ms
Mark Price Stream
Payload:
{
"e":"markPriceUpdate", // Event type
"E":1596095725000, // Event time
"s":"BTCUSD_201225", // Symbol
"p":"10934.62615417", // Mark Price
"P":"10962.17178236", // Estimated Settle Price, only useful in the last hour before the settlement starts.
"r":"", // funding rate for perpetual symbol, "" will be shown for delivery symbol
"T":0 // next funding time for perpetual symbol, 0 will be shown for delivery symbol
}
Stream Name:
<symbol>@markPrice
OR <symbol>@markPrice@1s
Update Speed: 3000ms OR 1000ms
Mark Price of All Symbols of a Pair
Payload:
[
{
"e":"markPriceUpdate", // Event type
"E":1596095725000, // Event time
"s":"BTCUSD_201225", // Symbol
"p":"10934.62615417", // Mark Price
"P":"10962.17178236", // Estimated Settle Price, only useful in the last hour before the settlement starts.
"r":"", // funding rate for perpetual symbol, "" will be shown for delivery symbol
"T":0 // next funding time for perpetual symbol, 0 will be shown for delivery symbol
},
{
"e":"markPriceUpdate",
"E":1596095725000,
"s":"BTCUSD_PERP",
"p":"11012.31359011",
"P":"10962.17178236",
"r":"0.00000000",
"T":1596096000000
}
]
Stream Name:
<pair>@markPrice
OR <pair>@markPrice@1s
Update Speed: 3000ms OR 1000ms
Kline/Candlestick Streams
Payload:
{
"e":"kline", // Event type
"E":1591261542539, // Event time
"s":"BTCUSD_200626", // Symbol
"k":{
"t":1591261500000, // Kline start time
"T":1591261559999, // Kline close time
"s":"BTCUSD_200626", // Symbol
"i":"1m", // Interval
"f":606400, // First trade ID
"L":606430, // Last trade ID
"o":"9638.9", // Open price
"c":"9639.8", // Close price
"h":"9639.8", // High price
"l":"9638.6", // Low price
"v":"156", // volume
"n":31, // Number of trades
"x":false, // Is this kline closed?
"q":"1.61836886", // Base asset volume
"V":"73", // Taker buy volume
"Q":"0.75731156", // Taker buy base asset volume
"B":"0" // 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
- 1m
- 3m
- 5m
- 15m
- 30m
- 1h
- 2h
- 4h
- 6h
- 8h
- 12h
- 1d
- 3d
- 1w
- 1M
Stream Name:
<symbol>@kline_<interval>
e.g. «btcusd_200626@kline_1m»
Update Speed: 250ms
Continues Contract Kline/Candlestick Streams
Payload:
{
"e":"continuous_kline", // Event type
"E":1591261542539, // Event time
"ps":"BTCUSD", // Pair
"ct":"NEXT_QUARTER" // Contract type
"k":{
"t":1591261500000, // Kline start time
"T":1591261559999, // Kline close time
"i":"1m", // Interval
"f":606400, // First trade ID
"L":606430, // Last trade ID
"o":"9638.9", // Open price
"c":"9639.8", // Close price
"h":"9639.8", // High price
"l":"9638.6", // Low price
"v":"156", // volume
"n":31, // Number of trades
"x":false, // Is this kline closed?
"q":"1.61836886", // Base asset volume
"V":"73", // Taker buy volume
"Q":"0.75731156", // Taker buy base asset volume
"B":"0" // Ignore
}
}
Contract type:
- PERPETUAL
- CURRENT_QUARTER
- NEXT_QUARTER
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
Stream Name:
<pair>_<contractType>@continuousKline_<interval>
e.g. «btcusd_next_quarter@continuousKline_1m»
Update Speed: 250ms
Index Kline/Candlestick Streams
Payload:
{
"e":"indexPrice_kline", // Event Name
"E":1591267070033, // Event Time
"ps":"BTCUSD", // Pair
"k":{
"t":1591267020000, // Kline start time
"T":1591267079999, // Kline close time
"s":"0", // ignore
"i":"1m", // Interval
"f":1591267020000, // ignore
"L":1591267070000, // ignore
"o":"9542.21900000", // Open price
"c":"9542.50440000", // Close price
"h":"9542.71640000", // High price
"l":"9542.21040000", // Low price
"v":"0", // ignore
"n":51, // Number of basic data
"x":false, // Is this kline closed?
"q":"0", // ignore
"V":"0", // ignore
"Q":"0", // ignore
"B":"0" // ignore
}
}
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
Stream Name:
<pair>@indexPriceKline_<interval>
e.g. «btcusd@indexPriceKline_1m»
Update Speed: 250ms
Mark Price Kline/Candlestick Streams
Payload:
{
"e":"markPrice_kline", // Event Name
"E":1591267398004, // Event Time
"ps":"BTCUSD", // Pair
"k":{
"t":1591267380000, // Kline start time
"T":1591267439999, // Kline close time
"s":"BTCUSD_200626", // Symbol
"i":"1m", // Interval
"f":1591267380000, // ignore
"L":1591267398000, // ignore
"o":"9539.67161333", // Open price
"c":"9540.82761333", // Close price
"h":"9540.82761333", // High price
"l":"9539.66961333", // Low price
"v":"0", // ignore
"n":19, // Number of basic data
"x":false, // Is this kline closed?
"q":"0", // ignore
"V":"0", // ignore
"Q":"0", // ignore
"B":"0" // ignore
}
}
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
Stream Name:
<symbol>@markPriceKline_<interval>
e.g. «btcusd_200626@markPriceKline_1m»
Update Speed: 250ms
Individual Symbol Mini Ticker Stream
Payload:
{
"e":"24hrMiniTicker", // Event type
"E":1591267704450, // Event time
"s":"BTCUSD_200626", // Symbol
"ps":"BTCUSD", // Pair
"c":"9561.7", // Close price
"o":"9580.9", // Open price
"h":"10000.0", // High price
"l":"7000.0", // Low price
"v":"487476", // Total traded volume
"q":"33264343847.22378500" // Total traded base asset volume
}
24hr rolling window mini-ticker statistics for a single symbol. These are NOT the statistics of the UTC day, but a 24hr rolling window from requestTime to 24hrs before.
Stream Name:
<symbol>@miniTicker
Update Speed: 500ms
All Market Mini Tickers Stream
Payload:
[
{
"e":"24hrMiniTicker", // Event type
"E":1591267704450, // Event time
"s":"BTCUSD_200626", // Symbol
"ps":"BTCUSD", // Pair
"c":"9561.7", // Close price
"o":"9580.9", // Open price
"h":"10000.0", // High price
"l":"7000.0", // Low price
"v":"487476", // Total traded volume
"q":"33264343847.22378500" // Total traded base asset volume
}
]
24hr rolling window mini-ticker statistics for all symbols. These are NOT the statistics of the UTC day, but a 24hr rolling window from requestTime to 24hrs before. Note that only tickers that have changed will be present in the array.
Stream Name:
!miniTicker@arr
Update Speed: 1000ms
Individual Symbol Ticker Streams
Payload:
{
"e":"24hrTicker", // Event type
"E":1591268262453, // Event time
"s":"BTCUSD_200626", // Symbol
"ps":"BTCUSD", // Pair
"p":"-43.4", // Price change
"P":"-0.452", // Price change percent
"w":"0.00147974", // Weighted average price
"c":"9548.5", // Last price
"Q":"2", // Last quantity
"o":"9591.9", // Open price
"h":"10000.0", // High price
"l":"7000.0", // Low price
"v":"487850", // Total traded volume
"q":"32968676323.46222700", // Total traded base asset volume
"O":1591181820000, // Statistics open time
"C":1591268262442, // Statistics close time
"F":512014, // First trade ID
"L":615289, // Last trade Id
"n":103272 // Total number of trades
}
24hr rollwing window ticker statistics for a single symbol. These are NOT the statistics of the UTC day, but a 24hr rolling window from requestTime to 24hrs before.
Stream Name:
<symbol>@ticker
Update Speed: 500ms
All Market Tickers Streams
Payload:
[
{
"e":"24hrTicker", // Event type
"E":1591268262453, // Event time
"s":"BTCUSD_200626", // Symbol
"ps":"BTCUSD", // Pair
"p":"-43.4", // Price change
"P":"-0.452", // Price change percent
"w":"0.00147974", // Weighted average price
"c":"9548.5", // Last price
"Q":"2", // Last quantity
"o":"9591.9", // Open price
"h":"10000.0", // High price
"l":"7000.0", // Low price
"v":"487850", // Total traded volume
"q":"32968676323.46222700", // Total traded base asset volume
"O":1591181820000, // Statistics open time
"C":1591268262442, // Statistics close time
"F":512014, // First trade ID
"L":615289, // Last trade Id
"n":103272 // Total number of trades
}
]
24hr rollwing window ticker statistics for all symbols. These are NOT the statistics of the UTC day, but a 24hr rolling window from requestTime to 24hrs before. Note that only tickers that have changed will be present in the array.
Stream Name:
!ticker@arr
Update Speed: 1000ms
Individual Symbol Book Ticker Streams
Payload:
{
"e":"bookTicker", // Event type
"u":17242169, // Order book update Id
"s":"BTCUSD_200626", // Symbol
"ps":"BTCUSD", // Pair
"b":"9548.1", // Best bid price
"B":"52", // Best bid qty
"a":"9548.5", // Best ask price
"A":"11", // Best ask qty
"T":1591268628155, // Transaction time
"E":1591268628166 // Event time
}
Pushes any update to the best bid or ask’s price or quantity in real-time for a specified symbol.
Stream Name: <symbol>@bookTicker
Update Speed: Real-time
All Book Tickers Stream
Payload:
{
// Same as <symbol>@bookTicker payload
}
Pushes any update to the best bid or ask’s price or quantity in real-time for all symbols.
Stream Name: !bookTicker
Update Speed: Real-time
Liquidation Order Streams
Payload:
{
"e":"forceOrder", // Event Type
"E": 1591154240950, // Event Time
"o":{
"s":"BTCUSD_200925", // Symbol
"ps": "BTCUSD", // Pair
"S":"SELL", // Side
"o":"LIMIT", // Order Type
"f":"IOC", // Time in Force
"q":"1", // Original Quantity
"p":"9425.5", // Price
"ap":"9496.5", // Average Price
"X":"FILLED", // Order Status
"l":"1", // Order Last Filled Quantity
"z":"1", // Order Filled Accumulated Quantity
"T": 1591154240949, // Order Trade Time
}
}
The Liquidation Order Streams push force liquidation order information for specific symbol
Stream Name: <symbol>@forceOrder
Update Speed: Real-time
All Market Liquidation Order Streams
Payload:
{
"e":"forceOrder", // Event Type
"E": 1591154240950, // Event Time
"o":{
"s":"BTCUSD_200925", // Symbol
"ps": "BTCUSD", // Pair
"S":"SELL", // Side
"o":"LIMIT", // Order Type
"f":"IOC", // Time in Force
"q":"1", // Original Quantity
"p":"9425.5", // Price
"ap":"9496.5", // Average Price
"X":"FILLED", // Order Status
"l":"1", // Order Last Filled Quantity
"z":"1", // Order Filled Accumulated Quantity
"T": 1591154240949, // Order Trade Time
}
}
The All Liquidation Order Streams push force liquidation order information for all symbols in the market.
Stream Name: !forceOrder@arr
Update Speed: Real-time
Partial Book Depth Streams
Payload:
{
"e":"depthUpdate", // Event type
"E":1591269996801, // Event time
"T":1591269996646, // Transaction time
"s":"BTCUSD_200626", // Symbol
"ps":"BTCUSD", // Pair
"U":17276694,
"u":17276701,
"pu":17276678,
"b":[ // Bids to be updated
[
"9523.0", // Price Level
"5" // Quantity
],
[
"9522.8",
"8"
],
[
"9522.6",
"2"
],
[
"9522.4",
"1"
],
[
"9522.0",
"5"
]
],
"a":[ // Asks to be updated
[
"9524.6", // Price level to be
"2" // Quantity
],
[
"9524.7",
"3"
],
[
"9524.9",
"16"
],
[
"9525.1",
"10"
],
[
"9525.3",
"6"
]
]
}
Top bids and asks, Valid are 5, 10, or 20.
Stream Names: <symbol>@depth<levels>
OR <symbol>@depth<levels>@500ms
OR <symbol>@depth<levels>@100ms
.
Update Speed: 250ms, 500ms or 100ms
Diff. Book Depth Streams
Payload:
{
"e": "depthUpdate", // Event type
"E": 1591270260907, // Event time
"T": 1591270260891, // Transction time
"s": "BTCUSD_200626", // Symbol
"ps": "BTCUSD", // Pair
"U": 17285681, // First update ID in event
"u": 17285702, // Final update ID in event
"pu": 17285675, // Final update Id in last stream(ie `u` in last stream)
"b": [ // Bids to be updated
[
"9517.6", // Price level to be updated
"10" // Quantity
]
],
"a": [ // Asks to be updated
[
"9518.5", // Price level to be updated
"45" // Quantity
]
]
}
Bids and asks, pushed every 250 milliseconds, 500 milliseconds, or 100 milliseconds
Stream Name:
<symbol>@depth
OR <symbol>@depth@500ms
OR <symbol>@depth@100ms
Update Speed: 250ms, 500ms, 100ms
How to manage a local order book correctly
- Open a stream to wss://dstream.binancefuture.com/stream?streams=btcusd_200925@depth.
- Buffer the events you receive from the stream. For same price, latest received update covers the previous one.
- Get a depth snapshot from https://testnet.binancefuture.com/dapi/v1/depth?symbol=BTCUSD_200925&limit=1000 .
- Drop any event where
u
is <lastUpdateId
in the snapshot - The first processed event should have
U
<=lastUpdateId
ANDu
>=lastUpdateId
- While listening to the stream, each new event’s
pu
should be equal to the previous event’su
, otherwise initialize the process from step 3. - The data in each event is the absolute quantity for a price level
- If the quantity is 0, remove the price level
- Receiving an event that removes a price level that is not in your local order book can happen and is normal.
Account/Trades Endpoints
Change Position Mode(TRADE)
Response:
{
"code": 200,
"msg": "success"
}
POST /dapi/v1/positionSide/dual (HMAC SHA256)
Change user’s position mode (Hedge Mode or One-way Mode ) on EVERY symbol
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
dualSidePosition | STRING | YES | «true»: Hedge Mode mode; «false»: One-way Mode |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Get Current Position Mode(USER_DATA)
Response:
{
"dualSidePosition": true // "true": Hedge Mode mode; "false": One-way Mode
}
GET /dapi/v1/positionSide/dual (HMAC SHA256)
Get user’s position mode (Hedge Mode or One-way Mode ) on EVERY symbol
Weight:
30
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | |
timestamp | LONG | YES |
New Order (TRADE)
Response:
{
"clientOrderId": "testOrder",
"cumQty": "0",
"cumBase": "0",
"executedQty": "0",
"orderId": 22542179,
"avgPrice": "0.0",
"origQty": "10",
"price": "0",
"reduceOnly": false,
"side": "BUY",
"positionSide": "SHORT",
"status": "NEW",
"stopPrice": "9300", // please ignore when order type is TRAILING_STOP_MARKET
"closePosition": false, // if Close-All
"symbol": "BTCUSD_200925",
"pair": "BTCUSD",
"timeInForce": "GTC",
"type": "TRAILING_STOP_MARKET",
"origType": "TRAILING_STOP_MARKET",
"activatePrice": "9020", // activation price, only return with TRAILING_STOP_MARKET order
"priceRate": "0.3", // callback rate, only return with TRAILING_STOP_MARKET order
"updateTime": 1566818724722,
"workingType": "CONTRACT_PRICE",
"priceProtect": false // if conditional order trigger is protected
}
POST /dapi/v1/order (HMAC SHA256)
Send in a new order.
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
side | ENUM | YES | |
positionSide | ENUM | NO | Default BOTH for One-way Mode ; LONG or SHORT for Hedge Mode. It must be sent in Hedge Mode. |
type | ENUM | YES | |
timeInForce | ENUM | NO | |
quantity | DECIMAL | NO | Cannot be sent with closePosition =true |
reduceOnly | STRING | NO | «true» or «false». default «false». Cannot be sent in Hedge Mode; cannot be sent with closePosition =true (Close-All) |
price | DECIMAL | NO | |
newClientOrderId | STRING | NO | A unique id among open orders. Automatically generated if not sent. |
stopPrice | DECIMAL | NO | Used with STOP/STOP_MARKET or TAKE_PROFIT/TAKE_PROFIT_MARKET orders. |
closePosition | STRING | NO | true , false ;Close-All,used with STOP_MARKET or TAKE_PROFIT_MARKET . |
activationPrice | DECIMAL | NO | Used with TRAILING_STOP_MARKET orders, default as the latest price(supporting different workingType ) |
callbackRate | DECIMAL | NO | Used with TRAILING_STOP_MARKET orders, min 0.1, max 5 where 1 for 1% |
workingType | ENUM | NO | stopPrice triggered by: «MARK_PRICE», «CONTRACT_PRICE». Default «CONTRACT_PRICE» |
priceProtect | STRING | NO | «TRUE» or «FALSE», default «FALSE». Used with STOP/STOP_MARKET or TAKE_PROFIT/TAKE_PROFIT_MARKET orders. |
newOrderRespType | ENUM | NO | «ACK», «RESULT», default «ACK» |
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 |
price , stopPrice |
STOP_MARKET/TAKE_PROFIT_MARKET |
stopPrice |
TRAILING_STOP_MARKET |
callbackRate |
- Order with type
STOP
, parametertimeInForce
can be sent ( defaultGTC
). - Order with type
TAKE_PROFIT
, parametertimeInForce
can be sent ( defaultGTC
). -
Condition orders will be triggered when:
- If parameter
priceProtect
is sent as true:- when price reaches the
stopPrice
,the difference rate between «MARK_PRICE» and «CONTRACT_PRICE» cannot be larger than the «triggerProtect» of the symbol - «triggerProtect» of a symbol can be got from
GET /dapi/v1/exchangeInfo
- when price reaches the
STOP
,STOP_MARKET
:- BUY: latest price («MARK_PRICE» or «CONTRACT_PRICE») >=
stopPrice
- SELL: latest price («MARK_PRICE» or «CONTRACT_PRICE») <=
stopPrice
- BUY: latest price («MARK_PRICE» or «CONTRACT_PRICE») >=
TAKE_PROFIT
,TAKE_PROFIT_MARKET
:- BUY: latest price («MARK_PRICE» or «CONTRACT_PRICE») <=
stopPrice
- SELL: latest price («MARK_PRICE» or «CONTRACT_PRICE») >=
stopPrice
- BUY: latest price («MARK_PRICE» or «CONTRACT_PRICE») <=
TRAILING_STOP_MARKET
:- BUY: the lowest price after order placed <=
activationPrice
, and the latest price >= the lowest price * (1 +callbackRate
) - SELL: the highest price after order placed >=
activationPrice
, and the latest price <= the highest price * (1 —callbackRate
)
- BUY: the lowest price after order placed <=
- If parameter
-
For
TRAILING_STOP_MARKET
, if you got such error code.
{"code": -2021, "msg": "Order would immediately trigger."}
means that the parameters you send do not meet the following requirements:- BUY:
activationPrice
should be smaller than latest price. - SELL:
activationPrice
should be larger than latest price.
- BUY:
-
If
newOrderRespType
is sent asRESULT
:MARKET
order: the final FILLED result of the order will be return directly.LIMIT
order with sepcialtimeInForce
: the final status result of the order(FILLED or EXPIRED) will be returned directly.
-
STOP_MARKET
,TAKE_PROFIT_MARKET
withclosePosition
=true
:- Follow the same rules for condition orders.
- If triggered,close all current long position( if
SELL
) or current short position( ifBUY
). - Cannot be used with
quantity
paremeter - Cannot be used with
reduceOnly
parameter - In Hedge Mode,cannot be used with
BUY
orders inLONG
position side. and cannot be used withSELL
orders inSHORT
position side
Place Multiple Orders (TRADE)
Response:
[
{
"clientOrderId": "testOrder",
"cumQty": "0",
"cumBase": "0",
"executedQty": "0",
"orderId": 22542179,
"avgPrice": "0.0",
"origQty": "10",
"price": "0",
"reduceOnly": false,
"side": "BUY",
"positionSide": "SHORT",
"status": "NEW",
"stopPrice": "9300", // please ignore when order type is TRAILING_STOP_MARKET
"symbol": "BTCUSD_200925",
"pair": "BTCUSD",
"timeInForce": "GTC",
"type": "TRAILING_STOP_MARKET",
"origType": "TRAILING_STOP_MARKET",
"activatePrice": "9020", // activation price, only return with TRAILING_STOP_MARKET order
"priceRate": "0.3", // callback rate, only return with TRAILING_STOP_MARKET order
"updateTime": 1566818724722,
"workingType": "CONTRACT_PRICE",
"priceProtect": false // if conditional order trigger is protected
},
{
"code": -2022,
"msg": "ReduceOnly Order is rejected."
}
]
POST /dapi/v1/batchOrders (HMAC SHA256)
Weight:
5
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
batchOrders | 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 | |
side | ENUM | YES | |
positionSide | ENUM | NO | Default BOTH for One-way Mode ; LONG or SHORT for Hedge Mode. It must be sent with Hedge Mode. |
type | ENUM | YES | |
timeInForce | ENUM | NO | |
quantity | DECIMAL | YES | |
reduceOnly | STRING | NO | «true» or «false». default «false». |
price | DECIMAL | NO | |
newClientOrderId | STRING | NO | A unique id among open orders. Automatically generated if not sent. |
stopPrice | DECIMAL | NO | Used with STOP/STOP_MARKET or TAKE_PROFIT/TAKE_PROFIT_MARKET orders. |
activationPrice | DECIMAL | NO | Used with TRAILING_STOP_MARKET orders, default as the latest price(supporting different workingType ) |
callbackRate | DECIMAL | NO | Used with TRAILING_STOP_MARKET orders, min 0.1, max 4 where 1 for 1% |
workingType | ENUM | NO | stopPrice triggered by: «MARK_PRICE», «CONTRACT_PRICE». Default «CONTRACT_PRICE» |
priceProtect | STRING | NO | «TRUE» or «FALSE», default «FALSE». Used with STOP/STOP_MARKET or TAKE_PROFIT/TAKE_PROFIT_MARKET orders. |
newOrderRespType | ENUM | NO | «ACK», «RESULT», default «ACK» |
- Paremeter rules are same with
New Order
- Batch orders are processed concurrently, and the order of matching is not guaranteed.
- The order of returned contents for batch orders is the same as the order of the order list.
Query Order (USER_DATA)
Response:
{
"avgPrice": "0.0",
"clientOrderId": "abc",
"cumBase": "0",
"executedQty": "0",
"orderId": 1917641,
"origQty": "0.40",
"origType": "TRAILING_STOP_MARKET",
"price": "0",
"reduceOnly": false,
"side": "BUY",
"status": "NEW",
"stopPrice": "9300", // please ignore when order type is TRAILING_STOP_MARKET
"closePosition": false, // if Close-All
"symbol": "BTCUSD_200925",
"pair": "BTCUSD",
"time": 1579276756075, // order time
"timeInForce": "GTC",
"type": "TRAILING_STOP_MARKET",
"activatePrice": "9020", // activation price, only return with TRAILING_STOP_MARKET order
"priceRate": "0.3", // callback rate, only return with TRAILING_STOP_MARKET order
"updateTime": 1579276756075, // update time
"workingType": "CONTRACT_PRICE",
"priceProtect": false // if conditional order trigger is protected
}
GET /dapi/v1/order (HMAC SHA256)
Check an order’s status.
Weight:
1
- These orders will not be found:
- order status is
CANCELED
orEXPIRED
, AND - order has NO filled trade, AND
- created time + 30 days < current time
- order status is
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | LONG | NO | |
origClientOrderId | STRING | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Notes:
- Either
orderId
ororigClientOrderId
must be sent.
Cancel Order (TRADE)
Response:
{
"avgPrice": "0.0",
"clientOrderId": "myOrder1",
"cumQty": "0",
"cumBase": "0",
"executedQty": "0",
"orderId": 283194212,
"origQty": "11",
"origType": "TRAILING_STOP_MARKET",
"price": "0",
"reduceOnly": false,
"side": "BUY",
"positionSide": "SHORT",
"status": "CANCELED",
"stopPrice": "9300", // please ignore when order type is TRAILING_STOP_MARKET
"closePosition": false, // if Close-All
"symbol": "BTCUSD_200925",
"pair": "BTCUSD",
"timeInForce": "GTC",
"type": "TRAILING_STOP_MARKET",
"activatePrice": "9020", // activation price, only return with TRAILING_STOP_MARKET order
"priceRate": "0.3", // callback rate, only return with TRAILING_STOP_MARKET order
"updateTime": 1571110484038,
"workingType": "CONTRACT_PRICE",
"priceProtect": false // if conditional order trigger is protected
}
DELETE /dapi/v1/order (HMAC SHA256)
Cancel an active order.
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | LONG | NO | |
origClientOrderId | STRING | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Either orderId
or origClientOrderId
must be sent.
Cancel All Open Orders (TRADE)
Response:
{
"code": "200",
"msg": "The operation of cancel all open order is done."
}
DELETE /dapi/v1/allOpenOrders (HMAC SHA256)
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Cancel Multiple Orders (TRADE)
Response:
[
{
"avgPrice": "0.0",
"clientOrderId": "myOrder1",
"cumQty": "0",
"cumBase": "0",
"executedQty": "0",
"orderId": 283194212,
"origQty": "11",
"origType": "TRAILING_STOP_MARKET",
"price": "0",
"reduceOnly": false,
"side": "BUY",
"positionSide": "SHORT",
"status": "CANCELED",
"stopPrice": "9300", // please ignore when order type is TRAILING_STOP_MARKET
"closePosition": false, // if Close-All
"symbol": "BTCUSD_200925",
"timeInForce": "GTC",
"type": "TRAILING_STOP_MARKET",
"activatePrice": "9020", // activation price, only return with TRAILING_STOP_MARKET order
"priceRate": "0.3", // callback rate, only return with TRAILING_STOP_MARKET order
"workingType": "CONTRACT_PRICE",
"priceProtect": false, // if conditional order trigger is protected
"updateTime": 1571110484038
},
{
"code": -2011,
"msg": "Unknown order sent."
}
]
DELETE /dapi/v1/batchOrders (HMAC SHA256)
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderIdList | LIST<LONG> | NO | max length 10 e.g. [1234567,2345678] |
origClientOrderIdList | LIST<STRING> | NO | max length 10 e.g. [«my_id_1″,»my_id_2»], encode the double quotes. No space after comma. |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Either orderIdList
or origClientOrderIdList
must be sent.
Auto-Cancel All Open Orders (TRADE)
Response:
{
"symbol": "BTCUSD_200925",
"countdownTime": "100000"
}
Cancel all open orders of the specified symbol at the end of the specified countdown.
POST /dapi/v1/countdownCancelAll (HMAC SHA256)
Weight:
10
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
countdownTime | LONG | YES | countdown time, 1000 for 1 second. 0 to cancel the timer |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
-
This rest endpoint means to ensure your open orders are canceled in case of an outage. The endpoint should be called repeatedly as heartbeats so that the existing countdown time can be canceled and repalced by a new one.
-
Example usage:
Call this endpoint at 30s intervals with an countdownTime of 120000 (120s).
If this endpoint is not called within 120 seconds, all your orders of the specified symbol will be automatically canceled.
If this endpoint is called with an countdownTime of 0, the countdown timer will be stopped. -
The system will check all countdowns approximately every 10 milliseconds, so please note that sufficient redundancy should be considered when using this function. We do not recommend setting the countdown time to be too precise or too small.
Query Current Open Order (USER_DATA)
Response:
{
"avgPrice": "0.0",
"clientOrderId": "abc",
"cumBase": "0",
"executedQty": "0",
"orderId": 1917641,
"origQty": "0.40",
"origType": "TRAILING_STOP_MARKET",
"price": "0",
"reduceOnly": false,
"side": "BUY",
"positionSide": "SHORT",
"status": "NEW",
"stopPrice": "9300", // please ignore when order type is TRAILING_STOP_MARKET
"closePosition": false, // if Close-All
"symbol": "BTCUSD_200925",
"pair": "BTCUSD"
"time": 1579276756075, // order time
"timeInForce": "GTC",
"type": "TRAILING_STOP_MARKET",
"activatePrice": "9020", // activation price, only return with TRAILING_STOP_MARKET order
"priceRate": "0.3", // callback rate, only return with TRAILING_STOP_MARKET order
"updateTime": 1579276756075,
"workingType": "CONTRACT_PRICE",
"priceProtect": false // if conditional order trigger is protected
}
GET /dapi/v1/openOrder (HMAC SHA256)
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
orderId | LONG | NO | |
origClientOrderId | STRING | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
- Either
orderId
ororigClientOrderId
must be sent - If the queried order has been filled or cancelled, the error message «Order does not exist» will be returned.
Current All Open Orders (USER_DATA)
Response:
[
{
"avgPrice": "0.0",
"clientOrderId": "abc",
"cumBase": "0",
"executedQty": "0",
"orderId": 1917641,
"origQty": "0.40",
"origType": "TRAILING_STOP_MARKET",
"price": "0",
"reduceOnly": false,
"side": "BUY",
"positionSide": "SHORT",
"status": "NEW",
"stopPrice": "9300", // please ignore when order type is TRAILING_STOP_MARKET
"closePosition": false, // if Close-All
"symbol": "BTCUSD_200925",
"time": 1579276756075, // order time
"timeInForce": "GTC",
"type": "TRAILING_STOP_MARKET",
"activatePrice": "9020", // activation price, only return with TRAILING_STOP_MARKET order
"priceRate": "0.3", // callback rate, only return with TRAILING_STOP_MARKET order
"updateTime": 1579276756075, // update time
"workingType": "CONTRACT_PRICE",
"priceProtect": false // if conditional order trigger is protected
}
]
GET /dapi/v1/openOrders (HMAC SHA256)
Get all open orders on a symbol. Careful when accessing this with no symbol.
Weight:
1 for a single symbol;
5 for multiple symbols
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | |
pair | STRING | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
All Orders (USER_DATA)
Response:
[
{
"avgPrice": "0.0",
"clientOrderId": "abc",
"cumBase": "0",
"executedQty": "0",
"orderId": 1917641,
"origQty": "0.40",
"origType": "TRAILING_STOP_MARKET",
"price": "0",
"reduceOnly": false,
"side": "BUY",
"positionSide": "SHORT",
"status": "NEW",
"stopPrice": "9300", // please ignore when order type is TRAILING_STOP_MARKET
"closePosition": false, // if Close-All
"symbol": "BTCUSD_200925",
"pair": "BTCUSD",
"time": 1579276756075, // order time
"timeInForce": "GTC",
"type": "TRAILING_STOP_MARKET",
"activatePrice": "9020", // activation price, only return with TRAILING_STOP_MARKET order
"priceRate": "0.3", // callback rate, only return with TRAILING_STOP_MARKET order
"updateTime": 1579276756075, // update time
"workingType": "CONTRACT_PRICE",
"priceProtect": false // if conditional order trigger is protected
}
]
GET /dapi/v1/allOrders (HMAC SHA256)
Get all account orders; active, canceled, or filled.
- These orders will not be found:
- order status is
CANCELED
orEXPIRED
, AND - order has NO filled trade, AND
- created time + 30 days < current time
- order status is
Weight:
20 with symbol
40 with pair
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | |
pair | STRING | NO | |
orderId | LONG | NO | |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | Default 50; max 100. |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Notes:
- Either symbol or pair must be sent.
- If
orderId
is set, it will get orders >= thatorderId
. Otherwise most recent orders are returned.
Futures Account Balance (USER_DATA)
Response:
[
{
"accountAlias": "SgsR", // unique account code
"asset": "BTC",
"balance": "0.00250000",
"withdrawAvailable": "0.00250000",
"crossWalletBalance": "0.00241969",
"crossUnPnl": "0.00000000",
"availableBalance": "0.00241969",
"updateTime": 1592468353979
}
]
GET /dapi/v1/balance (HMAC SHA256)
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Account Information (USER_DATA)
Response:
{
"assets": [
{
"asset": "BTC", // asset name
"walletBalance": "0.00241969", // total wallet balance
"unrealizedProfit": "0.00000000", // unrealized profit or loss
"marginBalance": "0.00241969", // margin balance
"maintMargin": "0.00000000", // maintenance margin
"initialMargin": "0.00000000", // total intial margin required with the latest mark price
"positionInitialMargin": "0.00000000", // positions" margin required with the latest mark price
"openOrderInitialMargin": "0.00000000", // open orders" intial margin required with the latest mark price
"maxWithdrawAmount": "0.00241969", // available amount for transfer out
"crossWalletBalance": "0.00241969", // wallet balance for crossed margin
"crossUnPnl": "0.00000000", // total unrealized profit or loss of crossed positions
"availableBalance": "0.00241969" // available margin balance
}
],
"positions": [
{
"symbol": "BTCUSD_201225",
"initialMargin": "0",
"maintMargin": "0",
"unrealizedProfit": "0.00000000",
"positionInitialMargin": "0",
"openOrderInitialMargin": "0",
"leverage": "125",
"isolated": false,
"positionSide": "BOTH", // BOTH means that it is the position of One-way Mode
"entryPrice": "0.0",
"maxQty": "50"
},
{
"symbol": "BTCUSD_201225",
"initialMargin": "0",
"maintMargin": "0",
"unrealizedProfit": "0.00000000",
"positionInitialMargin": "0",
"openOrderInitialMargin": "0",
"leverage": "125",
"isolated": false,
"positionSide": "LONG", // LONG or SHORT means that it is the position of Hedge Mode
"entryPrice": "0.0",
"maxQty": "50"
},
{
"symbol": "BTCUSD_201225",
"initialMargin": "0",
"maintMargin": "0",
"unrealizedProfit": "0.00000000",
"positionInitialMargin": "0",
"openOrderInitialMargin": "0",
"leverage": "125",
"isolated": false,
"positionSide": "SHORT", // LONG or SHORT means that it is the position of Hedge Mode
"entryPrice": "0.0",
"maxQty": "50"
}
],
"canDeposit": true,
"canTrade": true,
"canWithdraw": true,
"feeTier": 2,
"updateTime": 0
}
GET /dapi/v1/account (HMAC SHA256)
Get current account information.
Weight:
5
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
recvWindow | LONG | NO | |
timestamp | LONG | YES |
- for One-way Mode user, the «positions» will only show the «BOTH» positions
- for Hedge Mode user, the «positions» will show «BOTH», «LONG», and «SHORT» positions.
Change Initial Leverage (TRADE)
Response:
{
"leverage": 21,
"maxQty": "1000", // maximum quantity of base asset
"symbol": "BTCUSD_200925"
}
POST /dapi/v1/leverage (HMAC SHA256)
Change user’s initial leverage in the specific symbol market.
For Hedge Mode, LONG and SHORT positions of one symbol use the same initial leverage and share a total notional value.
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 |
Change Margin Type (TRADE)
Response:
{
"code": 200,
"msg": "success"
}
Change user’s margin type in the specific symbol market.For Hedge Mode, LONG and SHORT positions of one symbol use the same margin type.
With ISOLATED margin type, margins of the LONG and SHORT positions are isolated from each other.
POST /dapi/v1/marginType (HMAC SHA256)
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
marginType | ENUM | YES | ISOLATED, CROSSED |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Modify Isolated Position Margin (TRADE)
Response:
{
"amount": 100.0,
"code": 200,
"msg": "Successfully modify position margin.",
"type": 1
}
POST /dapi/v1/positionMargin (HMAC SHA256)
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
positionSide | ENUM | NO | Default BOTH for One-way Mode ; LONG or SHORT for Hedge Mode. It must be sent with Hedge Mode. |
amount | DECIMAL | YES | |
type | INT | YES | 1: Add position margin,2: Reduce position margin |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
- Only for isolated symbol
Get Position Margin Change History (TRADE)
Response:
[
{
"amount": "23.36332311",
"asset": "BTC",
"symbol": "BTCUSD_200925",
"time": 1578047897183,
"type": 1,
"positionSide": "BOTH"
},
{
"amount": "100",
"asset": "BTC",
"symbol": "BTCUSD_200925",
"time": 1578047900425,
"type": 1,
"positionSide": "LONG"
}
]
GET /dapi/v1/positionMargin/history (HMAC SHA256)
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
type | INT | NO | 1: Add position margin,2: Reduce position margin |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | 默认值: 50 |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
Position Information (USER_DATA)
Response:
[
{
"symbol": "BTCUSD_201225",
"positionAmt": "0",
"entryPrice": "0.0",
"markPrice": "0.00000000",
"unRealizedProfit": "0.00000000",
"liquidationPrice": "0",
"leverage": "125",
"maxQty": "50", // maximum quantity of base asset
"marginType": "cross",
"isolatedMargin": "0.00000000",
"isAutoAddMargin": "false",
"positionSide": "BOTH"
},
{
"symbol": "BTCUSD_201225",
"positionAmt": "1",
"entryPrice": "11707.70000003",
"markPrice": "11788.66626667",
"unRealizedProfit": "0.00005866",
"liquidationPrice": "11667.63509587",
"leverage": "125",
"maxQty": "50",
"marginType": "cross",
"isolatedMargin": "0.00012357",
"isAutoAddMargin": "false",
"positionSide": "LONG"
},
{
"symbol": "BTCUSD_201225",
"positionAmt": "0",
"entryPrice": "0.0",
"markPrice": "0.00000000",
"unRealizedProfit": "0.00000000",
"liquidationPrice": "0",
"leverage": "125",
"maxQty": "50",
"marginType": "cross",
"isolatedMargin": "0.00000000",
"isAutoAddMargin": "false",
"positionSide": "SHORT"
}
]
GET /dapi/v1/positionRisk (HMAC SHA256)
Get current account information.
Weight:
1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
marginAsset | STRING | NO | |
pair | STRING | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
-
If neither
marginAsset
norpair
is sent, positions of all symbols withTRADING
status will be returned. -
for One-way Mode user, the response will only show the «BOTH» positions
-
for Hedge Mode user, the response will show «BOTH», «LONG», and «SHORT» positions.
Note
Please use with user data stream ACCOUNT_UPDATE
to meet your timeliness and accuracy needs.
Account Trade List (USER_DATA)
Response:
[
{
'symbol': 'BTCUSD_200626',
'id': 6,
'orderId': 28,
'pair': 'BTCUSD',
'side': 'SELL',
'price': '8800',
'qty': '1',
'realizedPnl': '0',
'marginAsset': 'BTC',
'baseQty': '0.01136364',
'commission': '0.00000454',
'commissionAsset': 'BTC',
'time': 1590743483586,
'positionSide': 'BOTH',
'buyer': false,
'maker': false
}
]
GET /dapi/v1/userTrades (HMAC SHA256)
Get trades for a specific account and symbol.
Weight:
20 with symbol
40 with pair
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | |
pair | STRING | NO | |
startTime | LONG | NO | |
endTime | LONG | NO | |
fromId | LONG | NO | Trade id to fetch from. Default gets most recent trades. |
limit | INT | NO | Default 50; max 100. |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
- Either symbol or pair must be sent
- Symbol and pair cannot be sent together
- Pair and fromId cannot be sent together
- If a pair is sent,tickers for all symbols of the pair will be returned
Get Income History(USER_DATA)
Response:
[
{
"symbol": "", // trade symbol, if existing
"incomeType": "TRANSFER", // income type
"income": "-0.37500000", // income amount
"asset": "BTC", // income asset
"info":"WITHDRAW", // extra information
"time": 1570608000000,
"tranId":"9689322392", // transaction id
"tradeId":"" // trade id, if existing
},
{
"symbol": "BTCUSD_200925",
"incomeType": "COMMISSION",
"income": "-0.01000000",
"asset": "BTC",
"info":"",
"time": 1570636800000,
"tranId":"9689322392",
"tradeId":"2059192"
}
]
GET /dapi/v1/income (HMAC SHA256)
Weight:
20
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | |
incomeType | STRING | NO | «TRANSFER», «FUNDING_FEE», «REALIZED_PNL», «COMMISSION», «INSURANCE_CLEAR», and «DELIVERED_SETTELMENT» |
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 -
«trandId» is unique in the same «incomeType» for a user
Notional Bracket (USER_DATA)
Response:
[
{
"pair": "BTCUSD",
"brackets": [
{
"bracket": 1, // bracket level
"initialLeverage": 125, // the maximum leverage
"qtyCap": 50, // upper edge of base asset quantity
"qtylFloor": 0, // lower edge of base asset quantity
"maintMarginRatio": 0.004 // maintenance margin rate
},
]
}
]
GET /dapi/v1/leverageBracket
Weight: 1
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
pair | STRING | NO | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
User’s Force Orders (USER_DATA)
Response:
[
{
"orderId": 165123080,
"symbol": "BTCUSD_200925",
"pair": "BTCUSD",
"status": "FILLED",
"clientOrderId": "autoclose-1596542005017000006",
"price": "11326.9",
"avgPrice": "11326.9",
"origQty": "1",
"executedQty": "1",
"cumBase": "0.00882854",
"timeInForce": "IOC",
"type": "LIMIT",
"reduceOnly": false,
"closePosition": false,
"side": "SELL",
"positionSide": "BOTH",
"stopPrice": "0",
"workingType": "CONTRACT_PRICE",
"priceProtect": false,
"origType": "LIMIT",
"time": 1596542005019,
"updateTime": 1596542005050
},
{
"orderId": 207251986,
"symbol": "BTCUSD_200925",
"pair": "BTCUSD",
"status": "FILLED",
"clientOrderId": "autoclose-1597307316020000006",
"price": "11619.4",
"avgPrice": "11661.2",
"origQty": "1",
"executedQty": "1",
"cumBase": "0.00857544",
"timeInForce": "IOC",
"type": "LIMIT",
"reduceOnly": false,
"closePosition": false,
"side": "SELL",
"positionSide": "LONG",
"stopPrice": "0",
"workingType": "CONTRACT_PRICE",
"priceProtect": false,
"origType": "LIMIT",
"time": 1597307316022,
"updateTime": 1597307316035
}
]
GET /dapi/v1/forceOrders
Weight: 20
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | NO | |
autoCloseType | ENUM | NO | «LIQUIDATION» for liquidation orders, «ADL» for ADL orders. |
startTime | LONG | NO | |
endTime | LONG | NO | |
limit | INT | NO | Default 50; max 100. |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
- If «autoCloseType» is not sent, orders with both of the types will be returned
- If «startTime» is not sent, data within 200 days before «endTime» can be queried
Position ADL Quantile Estimation (USER_DATA)
Response:
[
{
"symbol": "BTCUSD_200925",
"adlQuantile":
{
// if the positions of the symbol are crossed margined in Hedge Mode, "LONG" and "SHORT" will be returned a same quantile value, and "HEDGE" will be returned instead of "BOTH".
"LONG": 3,
"SHORT": 3,
"HEDGE": 0 // only a sign, ignore the value
}
},
{
"symbol": "BTCUSD_201225",
"adlQuantile":
{
// for positions of the symbol are in One-way Mode or isolated margined in Hedge Mode
"LONG": 1, // adl quantile for "LONG" position in hedge mode
"SHORT": 2, // adl qauntile for "SHORT" position in hedge mode
"BOTH": 0 // adl qunatile for position in one-way mode
}
}
]
GET /dapi/v1/adlQuantile
User Commission Rate (USER_DATA)
Response:
{
"symbol": "BTCUSD_PERP",
"makerCommissionRate": "0.00015", // 0.015%
"takerCommissionRate": "0.00040" // 0.040%
}
GET /dapi/v1/commissionRate (HMAC SHA256)
Weight:
20
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
User Data Streams
- The base API endpoint is: https://testnet.binancefuture.com
- A User Data Stream
listenKey
is valid for 60 minutes after creation. - Doing a
PUT
on alistenKey
will extend its validity for 60 minutes. - Doing a
DELETE
on alistenKey
will close the stream and invalidate thelistenKey
. - Doing a
POST
on an account with an activelistenKey
will return the currently activelistenKey
and extend its validity for 60 minutes. - The base websocket endpoint is: wss://dstream.binancefuture.com
- User Data Streams are accessed at /ws/<listenKey>
- User data stream payloads are not guaranteed to be in order during heavy periods; make sure to order your updates using E
- A single connection to dstream.binancefuture.com is only valid for 24 hours; expect to be disconnected at the 24 hour mark
Start User Data Stream (USER_STREAM)
Response:
{
"listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}
POST /dapi/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 /dapi/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 /dapi/v1/listenKey
Close out a user data stream.
Weight:
1
Parameters:
None
Event: Margin Call
Payload:
{
"e":"MARGIN_CALL", // Event Type
"E":1587727187525, // Event Time
"i": "SfsR", // Account Alias
"cw":"3.16812045", // Cross Wallet Balance. Only pushed with crossed position margin call
"p":[ // Position(s) of Margin Call
{
"s":"BTCUSD_200925", // Symbol
"ps":"LONG", // Position Side
"pa":"132", // Position Amount
"mt":"CROSSED", // Margin Type
"iw":"0", // Isolated Wallet (if isolated position)
"mp":"9187.17127000", // Mark Price
"up":"-1.166074", // Unrealized PnL
"mm":"1.614445" // Maintenance Margin Required
}
]
}
- When the user’s position risk ratio is too high, this stream will be pushed.
- This message is only used as risk guidance information and is not recommended for investment strategies.
- In the case of a highly volatile market, there may be the possibility that the user’s position has been liquidated at the same time when this stream is pushed out.
Event: Balance and Position Update
Payload:
{
"e": "ACCOUNT_UPDATE", // Event Type
"E": 1564745798939, // Event Time
"T": 1564745798938 , // Transaction
"i": "SfsR", // Account Alias
"a": // Update Data
{
"m":"ORDER", // Event reason type
"B":[ // Balances
{
"a":"BTC", // Asset
"wb":"122624.12345678", // Wallet Balance
"cw":"100.12345678" // Cross Wallet Balance
},
{
"a":"ETH",
"wb":"1.00000000",
"cw":"0.00000000"
}
],
"P":[
{
"s":"BTCUSD_200925", // Symbol
"pa":"0", // Position Amount
"ep":"0.0", // Entry Price
"cr":"200", // (Pre-fee) Accumulated Realized
"up":"0", // Unrealized PnL
"mt":"isolated", // Margin Type
"iw":"0.00000000", // Isolated Wallet (if isolated position)
"ps":"BOTH" // Position Side
},
{
"s":"BTCUSD_200925",
"pa":"20",
"ep":"6563.6",
"cr":"0",
"up":"2850.21200000",
"mt":"isolated",
"iw":"13200.70726908",
"ps":"LONG"
},
{
"s":"BTCUSD_200925",
"pa":"-10",
"ep":"6563.8",
"cr":"-45.04000000",
"up":"-1423.15600000",
"mt":"isolated",
"iw":"6570.42511771",
"ps":"SHORT"
}
]
}
}
Event type is ACCOUNT_UPDATE
.
-
When balance or position get updated, this event will be pushed.
ACCOUNT_UPDATE
will be pushed only when update happens on user’s account, including changes on balances, positions, or margin type.- Unfilled orders or cancelled orders will not make the event
ACCOUNT_UPDATE
pushed, since there’s no change on positions. - Only positions of symbols with non-zero isolatd wallet or non-zero position amount will be pushed in the «position» part of the event
ACCOUNT_UPDATE
when any position changes.
-
When «FUNDING FEE» changes to the user’s balance, the event will be pushed with the brief message:
- When «FUNDING FEE» occurs in a crossed position,
ACCOUNT_UPDATE
will be pushed with only the balanceB
(including the «FUNDING FEE» asset only), without any positionP
message. - When «FUNDING FEE» occurs in an isolated position,
ACCOUNT_UPDATE
will be pushed with only the balanceB
(including the «FUNDING FEE» asset only) and the relative position messageP
( including the isolated position on which the «FUNDING FEE» occurs only, without any other position message).
- When «FUNDING FEE» occurs in a crossed position,
-
The field «m» represents the reason type for the event and may shows the following possible types:
- DEPOSIT
- WITHDRAW
- ORDER
- ADJUSTMENT
- INSURANCE_CLEAR
- ADMIN_DEPOSIT
- ADMIN_WITHDRAW
- MARGIN_TRANSFER
- MARGIN_TYPE_CHANGE
- ASSET_TRANSFER
- FUNDING_FEE
Event: Order Update
Payload:
{
"e":"ORDER_TRADE_UPDATE", // Event Type
"E":1591274595442, // Event Time
"T":1591274595453, // Trasaction Time
"i":"SfsR", // Account Alias
"o":{
"s":"BTCUSD_200925", // Symbol
"c":"TEST", // Client Order Id
// special client order id:
// starts with "autoclose-": liquidation order
// "adl_autoclose": ADL auto close order
"S":"SELL", // Side
"o":"TRAILING_STOP_MARKET", // Order Type
"f":"GTC", // Time in Force
"q":"2", // Original Quantity
"p":"0", // Original Price
"ap":"0", // Average Price
"sp":"9103.1", // Stop Price. Please ignore with TRAILING_STOP_MARKET order
"x":"NEW", // Execution Type
"X":"NEW", // Order Status
"i":8888888, // Order Id
"l":"0", // Order Last Filled Quantity
"z":"0", // Order Filled Accumulated Quantity
"L":"0", // Last Filled Price
"ma": "BTC", // Margin Asset
"N":"BTC", // Commission Asset of the trade, will not push if no commission
"n":"0", // Commission of the trade, will not push if no commission
"T":1591274595442, // Order Trade Time
"t":0, // Trade Id
"rp": "0", // Realized Profit of the trade
"b":"0", // Bid quantity of base asset
"a":"0", // Ask quantity of base asset
"m":false, // Is this trade the maker side?
"R":false, // Is this reduce only
"wt":"CONTRACT_PRICE", // Stop Price Working Type
"ot":"TRAILING_STOP_MARKET", // Original Order Type
"ps":"LONG", // Position Side
"cp":false, // If Close-All, pushed with conditional order
"AP":"9476.8", // Activation Price, only puhed with TRAILING_STOP_MARKET order
"cr":"5.0", // Callback Rate, only puhed with TRAILING_STOP_MARKET order
"pP": false // If conditional order trigger is protected
}
}
When new order created, order status changed will push such event.
event type is ORDER_TRADE_UPDATE
.
Side
- BUY
- SELL
Position side:
- BOTH
- LONG
- SHORT
Order Type
- MARKET
- LIMIT
- STOP
- TAKE_PROFIT
- LIQUIDATION
Execution Type
- NEW
- PARTIAL_FILL
- FILL
- CANCELED
- CALCULATED — Liquidation Execution
- EXPIRED
- TRADE
Order Status
- NEW
- PARTIALLY_FILLED
- FILLED
- CANCELED
- EXPIRED
- NEW_INSURANCE — Liquidation with Insurance Fund
- NEW_ADL — Counterparty Liquidation`
Time in force
- GTC
- IOC
- FOK
- GTX
Websocket User Data Request
- User data request need a successful connection with the user data stream with a listenKey.
- The following data can be sent through the websocket instance in order to request for user data. Examples can be seen below.
- The
id
used in the JSON payloads is an unsigned INT used as an identifier to uniquely identify the messages going back and forth.
Request Form
Response
{
"result"[
{
"req":"<listenKey>@account", // request name 1
"res": // response to the request name 1
...
},
{
"req":"<listenKey>@balance", // request name 2, if existing
"res": // response to the request name 2, if existing
...
}
]
"id": 12 // request ID
}
-
Request
{
«method»: «REQUEST»,
«params»:
[
«@account», // request name 1
«@balance» // request name 2, if existing
],
«id»: 12 // request ID.
}
Request: User’s Account Information
Response
{
"id":1, // request ID
"result":[
{
"req":"gN0SiRrevtS4O0ufdCpzd4N0MzHu2lVmwbHh6hj4g9eTT9Yfe55eUc4klmsEhnwC@account", // request name
"res":{
"feeTier":0, // account fee tier
"canTrade":true, // if can trade
"canDeposit":true, // if can transfer in asset
"canWithdraw":true, // if can transfer out asset
"accountAlias":"fsR" // the unique account alias
}
}
]
}
Request Name <listenKey>@account
Request: User’s Account Balance
Response
{
"id":2, // request ID
"result":[
{
"req":"gN0SiRrevtS4O0ufdCpzd4N0MzHu2lVmwbHh6hj4g9eTT9Yfe55eUc4klmsEhnwC@balance", // request name
"res":{
"accountAlias":"fsR", // unique account alias
"balances":[ // account balance
{
"asset":"BTC", // asset name
"balance":"0.00241628", // asset wallet balance
"crossWalletBalance":"0.00235137", // wallet balance for cross margin
"crossUnPnl":"0.00000000", // unrealized profit of cross margin positions
"availableBalance":"0.00235137", // available margin balance for order
"maxWithdrawAmount":"0.00235137" // available balance for transfer out
}
]
}
}
]
}
Request Name <listenKey>@balance
Request: User’s Position
Response
{
"id":3,
"result":[
{
"req":"gN0SiRrevtS4O0ufdCpzd4N0MzHu2lVmwbHh6hj4g9eTT9Yfe55eUc4klmsEhnwC@position",
"res":{
"positions":[
{
"entryPrice":"12044.90000003",
"marginType":"ISOLATED", // margin type, "CROSSED" or "ISOLATED"
"isAutoAddMargin":false,
"isolatedMargin":"0.00006388", // isolated margin balance
"leverage":125, // current leverage
"liquidationPrice":"12002.39091452", // estimated liquidation price
"markPrice":"12046.06021667", // current mark price
"maxQty":"50", // maximum quantity of base asset
"positionAmt":"1", // position amount
"symbol":"BTCUSD_200925", // symbol
"unRealizedProfit":"0.00000079", // unrealized PnL
"positionSide":"LONG" // position side
},
{
"entryPrice":"0.0",
"marginType":"ISOLATED",
"isAutoAddMargin":false,
"isolatedMargin":"0",
"leverage":125,
"liquidationPrice":"0",
"markPrice":"12046.06021667",
"maxQty":"50",
"positionAmt":"0",
"symbol":"BTCUSD_200925",
"unRealizedProfit":"0.00000000",
"positionSide":"SHORT"
}
]
}
}
]
}
Request Name <listenKey>@position
-
for One-way Mode user, the response will only show the «BOTH» positions
-
for Hedge Mode user, the response will show «LONG» and «SHORT» positions.
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
- An unknown error occured while processing the request.
-1001 DISCONNECTED
- Internal error; unable to process your request. Please try again.
- You are not authorized to execute this request.
-1003 TOO_MANY_REQUESTS
- Too many requests queued.
- Too many requests; please use the websocket for live updates.
- Too many requests; current limit is %s requests per minute. Please use the websocket for live updates to avoid polling the API.
- Way too many requests; IP banned until %s. Please use the websocket for live updates to avoid bans.
-1004 DUPLICATE_IP
- This IP is already on the white list
-1005 NO_SUCH_IP
- No such IP has been white listed
-1006 UNEXPECTED_RESP
- An unexpected response was received from the message bus. Execution status unknown.
-1007 TIMEOUT
- Timeout waiting for response from backend server. Send status unknown; execution status unknown.
-1010 ERROR_MSG_RECEIVED
- ERROR_MSG_RECEIVED.
-1011 NON_WHITE_LIST
- This IP cannot access this route.
-1013 INVALID_MESSAGE
- INVALID_MESSAGE.
-1014 UNKNOWN_ORDER_COMPOSITION
- Unsupported order combination.
-1015 TOO_MANY_ORDERS
- Too many new orders.
- Too many new orders; current limit is %s orders per %s.
-1016 SERVICE_SHUTTING_DOWN
- This service is no longer available.
-1020 UNSUPPORTED_OPERATION
- This operation is not supported.
-1021 INVALID_TIMESTAMP
- Timestamp for this request is outside of the recvWindow.
- Timestamp for this request was 1000ms ahead of the server’s time.
-1022 INVALID_SIGNATURE
- Signature for this request is not valid.
-1023 START_TIME_GREATER_THAN_END_TIME
- Start time is greater than end time.
11xx — Request issues
-1100 ILLEGAL_CHARS
- Illegal characters found in a parameter.
- Illegal characters found in parameter ‘%s’; legal range is ‘%s’.
-1101 TOO_MANY_PARAMETERS
- Too many parameters sent for this endpoint.
- Too many parameters; expected ‘%s’ and received ‘%s’.
- Duplicate values for a parameter detected.
-1102 MANDATORY_PARAM_EMPTY_OR_MALFORMED
- A mandatory parameter was not sent, was empty/null, or malformed.
- Mandatory parameter ‘%s’ was not sent, was empty/null, or malformed.
- Param ‘%s’ or ‘%s’ must be sent, but both were empty/null!
-1103 UNKNOWN_PARAM
- An unknown parameter was sent.
-1104 UNREAD_PARAMETERS
- Not all sent parameters were read.
- Not all sent parameters were read; read ‘%s’ parameter(s) but was sent ‘%s’.
-1105 PARAM_EMPTY
- A parameter was empty.
- Parameter ‘%s’ was empty.
-1106 PARAM_NOT_REQUIRED
- A parameter was sent when not required.
- Parameter ‘%s’ sent when not required.
-1108 BAD_ASSET
- Invalid asset.
-1109 BAD_ACCOUNT
- Invalid account.
-1110 BAD_INSTRUMENT_TYPE
- Invalid symbolType.
-1111 BAD_PRECISION
- Precision is over the maximum defined for this asset.
-1112 NO_DEPTH
- No orders on book for symbol.
-1113 WITHDRAW_NOT_NEGATIVE
- Withdrawal amount must be negative.
-1114 TIF_NOT_REQUIRED
- TimeInForce parameter sent when not required.
-1115 INVALID_TIF
- Invalid timeInForce.
-1116 INVALID_ORDER_TYPE
- Invalid orderType.
-1117 INVALID_SIDE
- Invalid side.
-1118 EMPTY_NEW_CL_ORD_ID
- New client order ID was empty.
-1119 EMPTY_ORG_CL_ORD_ID
- Original client order ID was empty.
-1120 BAD_INTERVAL
- Invalid interval.
-1121 BAD_SYMBOL
- Invalid symbol.
-1125 INVALID_LISTEN_KEY
- This listenKey does not exist.
-1127 MORE_THAN_XX_HOURS
- Lookup interval is too big.
- More than %s hours between startTime and endTime.
-1128 OPTIONAL_PARAMS_BAD_COMBO
- Combination of optional parameters invalid.
-1130 INVALID_PARAMETER
- Invalid data sent for a parameter.
- Data sent for paramter ‘%s’ is not valid.
-1136 INVALID_NEW_ORDER_RESP_TYPE
- Invalid newOrderRespType.
20xx — Processing Issues
-2010 NEW_ORDER_REJECTED
- NEW_ORDER_REJECTED
-2011 CANCEL_REJECTED
- CANCEL_REJECTED
-2013 NO_SUCH_ORDER
- Order does not exist.
-2014 BAD_API_KEY_FMT
- API-key format invalid.
-2015 REJECTED_MBX_KEY
- Invalid API-key, IP, or permissions for action.
-2016 NO_TRADING_WINDOW
- No trading window could be found for the symbol. Try ticker/24hrs instead.
-2018 BALANCE_NOT_SUFFICIENT
- Balance is insufficient.
-2019 MARGIN_NOT_SUFFICIEN
- Margin is insufficient.
-2020 UNABLE_TO_FILL
- Unable to fill.
-2021 ORDER_WOULD_IMMEDIATELY_TRIGGER
- Order would immediately trigger.
-2022 REDUCE_ONLY_REJECT
- ReduceOnly Order is rejected.
-2023 USER_IN_LIQUIDATION
- User in liquidation mode now.
-2024 POSITION_NOT_SUFFICIENT
- Position is not sufficient.
-2025 MAX_OPEN_ORDER_EXCEEDED
- Reach max open order limit.
-2026 REDUCE_ONLY_ORDER_TYPE_NOT_SUPPORTED
- This OrderType is not supported when reduceOnly.
-2027 MAX_LEVERAGE_RATIO
- Exceeded the maximum allowable position at current leverage.
-2028 MIN_LEVERAGE_RATIO
- Leverage is smaller than permitted: insufficient margin balance.
40xx — Filters and other Issues
-4000 INVALID_ORDER_STATUS
- Invalid order status.
-4001 PRICE_LESS_THAN_ZERO
- Price less than 0.
-4002 PRICE_GREATER_THAN_MAX_PRICE
- Price greater than max price.
-4003 QTY_LESS_THAN_ZERO
- Quantity less than zero.
-4004 QTY_LESS_THAN_MIN_QTY
- Quantity less than min quantity.
-4005 QTY_GREATER_THAN_MAX_QTY
- Quantity greater than max quantity.
-4006 STOP_PRICE_LESS_THAN_ZERO
- Stop price less than zero.
-4007 STOP_PRICE_GREATER_THAN_MAX_PRICE
- Stop price greater than max price.
-4008 TICK_SIZE_LESS_THAN_ZERO
- Tick size less than zero.
-4009 MAX_PRICE_LESS_THAN_MIN_PRICE
- Max price less than min price.
-4010 MAX_QTY_LESS_THAN_MIN_QTY
- Max qty less than min qty.
-4011 STEP_SIZE_LESS_THAN_ZERO
- Step size less than zero.
-4012 MAX_NUM_ORDERS_LESS_THAN_ZERO
- Max mum orders less than zero.
-4013 PRICE_LESS_THAN_MIN_PRICE
- Price less than min price.
-4014 PRICE_NOT_INCREASED_BY_TICK_SIZE
- Price not increased by tick size.
-4015 INVALID_CL_ORD_ID_LEN
- Client order id is not valid.
- Client order id length should be less than 32 chars
-4016 PRICE_HIGHTER_THAN_MULTIPLIER_UP
- Price is higher than mark price multiplier cap.
-4017 MULTIPLIER_UP_LESS_THAN_ZERO
- Multiplier up less than zero.
-4018 MULTIPLIER_DOWN_LESS_THAN_ZERO
- Multiplier down less than zero.
-4019 COMPOSITE_SCALE_OVERFLOW
- Composite scale too large.
-4020 TARGET_STRATEGY_INVALID
- Target strategy invalid for orderType ‘%s’,reduceOnly ‘%b’.
-4021 INVALID_DEPTH_LIMIT
- Invalid depth limit.
- ‘%s’ is not valid depth limit.
-4022 WRONG_MARKET_STATUS
- market status sent is not valid.
-4023 QTY_NOT_INCREASED_BY_STEP_SIZE
- Qty not increased by step size.
-4024 PRICE_LOWER_THAN_MULTIPLIER_DOWN
- Price is lower than mark price multiplier floor.
-4025 MULTIPLIER_DECIMAL_LESS_THAN_ZERO
- Multiplier decimal less than zero.
-4026 COMMISSION_INVALID
- Commission invalid.
%s
less than zero.%s
absolute value greater than%s
-4027 INVALID_ACCOUNT_TYPE
- Invalid account type.
-4028 INVALID_LEVERAGE
- Invalid leverage
- Leverage
%s
is not valid - Leverage
%s
already exist with%s
-4029 INVALID_TICK_SIZE_PRECISION
- Tick size precision is invalid.
-4030 INVALID_STEP_SIZE_PRECISION
- Step size precision is invalid.
-4031 INVALID_WORKING_TYPE
- Invalid parameter working type
- Invalid parameter working type:
%s
-4032 EXCEED_MAX_CANCEL_ORDER_SIZE
- Exceed maximum cancel order size.
- Invalid parameter working type:
%s
-4033 INSURANCE_ACCOUNT_NOT_FOUND
- Insurance account not found.
-4044 INVALID_BALANCE_TYPE
- Balance Type is invalid.
-4045 MAX_STOP_ORDER_EXCEEDED
- Reach max stop order limit.
-4046 NO_NEED_TO_CHANGE_MARGIN_TYPE
- No need to change margin type.
-4047 THERE_EXISTS_OPEN_ORDERS
- Margin type cannot be changed if there exists open orders.
-4048 THERE_EXISTS_QUANTITY
- Margin type cannot be changed if there exists position.
-4049 ADD_ISOLATED_MARGIN_REJECT
- Add margin only support for isolated position.
-4050 CROSS_BALANCE_INSUFFICIENT
- Cross balance insufficient.
-4051 ISOLATED_BALANCE_INSUFFICIENT
- Isolated balance insufficient.
-4052 NO_NEED_TO_CHANGE_AUTO_ADD_MARGIN
- No need to change auto add margin.
-4053 AUTO_ADD_CROSSED_MARGIN_REJECT
- Auto add margin only support for isolated position.
-4054 ADD_ISOLATED_MARGIN_NO_POSITION_REJECT
- Cannot add position margin: position is 0.
-4055 AMOUNT_MUST_BE_POSITIVE
- Amount must be positive.
-4056 INVALID_API_KEY_TYPE
- Invalid api key type.
-4057 INVALID_RSA_PUBLIC_KEY
- Invalid api public key
-4058 MAX_PRICE_TOO_LARGE
- maxPrice and priceDecimal too large,please check.
-4059 NO_NEED_TO_CHANGE_POSITION_SIDE
- No need to change position side.
-4060 INVALID_POSITION_SIDE
- Invalid position side.
-4061 POSITION_SIDE_NOT_MATCH
- Order’s position side does not match user’s setting.
-4062 REDUCE_ONLY_CONFLICT
- Invalid or improper reduceOnly value.
-4067 POSITION_SIDE_CHANGE_EXISTS_OPEN_ORDERS
- Position side cannot be changed if there exists open orders.
-4068 POSITION_SIDE_CHANGE_EXISTS_QUANTITY
- Position side cannot be changed if there exists position.
-4082 INVALID_BATCH_PLACE_ORDER_SIZE
- Invalid number of batch place orders.
- Invalid number of batch place orders: %s
-4083 PLACE_BATCH_ORDERS_FAIL
- Fail to place batch orders.
-4084 UPCOMING_METHOD
- Method is not allowed currently. Upcoming soon.
-4086 INVALID_PRICE_SPREAD_THRESHOLD
- Invalid price spread threshold.
-4087 INVALID_PAIR
- Invalid pair.
-4088 INVALID_TIME_INTERVAL
- Invalid time interval.
- Maximum time interval is %s days.
-4089 REDUCE_ONLY_ORDER_PERMISSION
- User can only place reduce only order.
-4090 NO_PLACE_ORDER_PERMISSION
- User can not place order currently.
-4104 INVALID_CONTRACT_TYPE
- Invalid contract type.
-4110 INVALID_CLIENT_TRAN_ID_LEN
- clientTranId is not valid.
- Client tran id length should be less than 64 chars.
-4111 DUPLICATED_CLIENT_TRAN_ID
- clientTranId is duplicated.
- Client tran id should be unique within 7 days.
-4112 REDUCE_ONLY_MARGIN_CHECK_FAILED
- ReduceOnly Order Failed. Please check your existing position and open orders.
-4113 MARKET_ORDER_REJECT
- The counterparty’s best price does not meet the PERCENT_PRICE filter limit.
-4135 INVALID_ACTIVATION_PRICE
- Invalid activation price.
Change Log
2023-02-02
REST
- Endpoint
POST /eapi/v1/transfer
is disabled.
2023-01-11
REST
- Add endpoint
GET /eapi/v1/order
to check order status.
2022-12-13
WEBSOCKET
- Add
u
andpu
in stream<symbol>@depth1000
to get diff orderbook update.
2022-12-09
REST
- Add updateId field
u
inGET /eapi/v1/depth
- Add parameter
underlying
inGET /eapi/v1/exerciseHistory
to query exercise histroy by underlying
2022-11-18
REST
- New endpoint
GET /eapi/v1/openInterest
is added to get options open interest for specific underlying on certain expiration date.
WEBSOCKET
- New stream
<underlyingAsset>@openInterest@<expirationDate>
is added for real-time option open interest feed.
2022-11-16
WEBSOCKET
- New trade stream
<underlyingAsset>@trade
is added for all option trades on specific underlying asset. - Adjust format in stream
option_pair
.
2022-11-03
REST
- New endpoint for Auto-Cancel All Open Orders will be added on 2022-11-07:
POST /eapi/v1/countdownCancelAll
:Set Auto-Cancel All Open Orders (Kill-Switch) ConfigGET /eapi/v1/countdownCancelAll
:Get Auto-Cancel All Open Orders (Kill-Switch) ConfigPOST /eapi/v1/countdownCancelAllHeartBeat
:Auto-Cancel All Open Orders (Kill-Switch) Heartbeat
2022-09-20
WEBSOCKET
- New streams
<underlyingAsset>@markPrice
and<underlyingAsset>@ticker@<expirationDate>
are added. - Streams
<!miniTicker@arr>
will be deprecated on 2022/10/30.
2022-09-14
REST
- Adjust endpoint field
strikePrice
,makerFeeRate
,takerFeeRate
,minQty
,maxQty
,initialMargin
,maintenanceMargin
,minInitialMargin
,minMaintenanceMargin
to string in endpointGET /eapi/v1/exchangeInfo
- Only finished orders within 5 days can be queried in
GET /eapi/v1/historyOrders
2022-09-05
REST
- Adjust response result in endpoint
DELETE /eapi/v1/allOpenOrdersByUnderlying
2022-08-22
REST
- Add
rateLimits
information in endpointGET /eapi/v1/exchangeInfo
- Parameters
symbol
set to not mandatory inGET /eapi/v1/userTrades
General Info
General API Information
- Some endpoints will require an API Key. Please refer to this page
- The base endpoint is: **https://eapi.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 Return Codes
- HTTP
4XX
return codes are used for for malformed requests;
the issue is on the sender’s side. - HTTP
403
return code is used when the WAF Limit (Web Application Firewall) has been violated. - 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 receiving429
codes. - HTTP
5XX
return codes are used for internal errors; the issue is on
Binance’s side. - HTTP
503
return code is used when:- If there is an error message «Unknown error, please check your request or try again later.» returned in the response, the API successfully sent the request but not get a response within the timeout period.
It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success; - If there is an error message «Service Unavailable.» returned in the response, it means this is a failure API operation and the service might be unavailable at the moment, you need to retry later.
- If there is an error message «Internal error; unable to process your request. Please try again.» returned in the response, it means this is a failure API operation and you can resend your request if you need.
- If there is an error message «Unknown error, please check your request or try again later.» returned in the response, the API successfully sent the request but not get a response within the timeout period.
Error Codes and Messages
- 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 Codes.
General Information on Endpoints
- For
GET
endpoints, parameters must be sent as aquery string
. - For
POST
,PUT
, andDELETE
endpoints, the parameters may be sent as a
query string
or in therequest body
with content type
application/x-www-form-urlencoded
. You may mix parameters between both the
query string
andrequest body
if you wish to do so. - Parameters may be sent in any order.
- If a parameter sent in both the
query string
andrequest body
, the
query string
parameter will be used.
LIMITS
- The
/eapi/v1/exchangeInfo
rateLimits
array contains objects related to the exchange’sRAW_REQUEST
,REQUEST_WEIGHT
, andORDER
rate limits. These are further defined in theENUM definitions
section underRate limiters (rateLimitType)
. - A
429
will be returned when either rate limit is violated.
IP Limits
- Every request will contain
X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)
in the response headers which has the current used weight for the IP for all request rate limiters defined. - 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 heavierweight
. - When a 429 is received, 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 429s 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.
- The limits on the API are based on the IPs, not the API keys.
Order Rate Limits
- Every order response will contain a
X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)
header which has the current order count for the account for all order rate limiters defined. - Rejected/unsuccessful orders are not guaranteed to have
X-MBX-ORDER-COUNT-**
headers in the response. - The order rate limit is counted against each account.
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
andUSER_DATA
endpoints areSIGNED
endpoints.
SIGNED (TRADE and USER_DATA) Endpoint Security
SIGNED
endpoints require an additional parameter,signature
, to be
sent in thequery string
orrequest body
.- Endpoints use
HMAC SHA256
signatures. TheHMAC SHA256 signature
is a keyedHMAC SHA256
operation.
Use yoursecretKey
as the key andtotalParams
as the value for the HMAC operation. - The
signature
is not case sensitive. - Please make sure the
signature
is the end part of yourquery string
orrequest body
. totalParams
is defined as thequery 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 aftertimestamp
the request is valid for. IfrecvWindow
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.
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×tamp=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×tamp=1611825601400&signature=7c12045972f6140e765e0f2b67d28099718df805732676494238f50be830a7d7'
- requestBody:
symbol=BTC-210129-40000-C
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=2000
&recvWindow=5000
×tamp=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×tamp=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×tamp=1611825601400&signature=7c12045972f6140e765e0f2b67d28099718df805732676494238f50be830a7d7'
- queryString:
symbol=BTC-210129-40000-C
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=2000
&recvWindow=5000
×tamp=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×tamp=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×tamp=1611825601400&signature=fa6045c54fb02912b766442be1f66fab619217e551a4fb4f8a1ee000df914d8e'
- queryString:
symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTC
- requestBody:
quantity=1&price=2000&recvWindow=5000×tamp=1611825601400
Note that the signature is different in example 3.
There is no & between «GTC» and «quantity=1».
Public Endpoints Info
Terminology
symbol
refers to the symbol name of a options contract symbolunderlying
refers to the underlying symbol of a options contract symbolquoteAsset
refers to the asset that is the price of a symbol.settleAsset
refers to the settlement asset when options are exercised
ENUM definitions
Options contract type
- CALL
- PUT
Order side
- BUY
- SELL
Position side
- LONG
- SHORT
Time in force
- GTC — Good Till Cancel
- IOC — Immediate or Cancel
- FOK — Fill or Kill
Response Type (newOrderRespType)
- ACK
- RESULT
Order types (type)
- LIMIT
Order status (status)
- ACCEPTED
- REJECTED
- PARTIALLY_FILLED
- FILLED
- CANCELLED
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
javascript
{
"rateLimitType": "REQUEST_WEIGHT",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 2400
}
ORDERS
javascript
{
"rateLimitType": "ORDERS",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 1200
}
-
REQUEST_WEIGHT
-
ORDERS
Rate limit intervals (interval)
- MINUTE
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:
minPrice
defines the minimumprice
/stopPrice
allowed; disabled onminPrice
== 0.maxPrice
defines the maximumprice
/stopPrice
allowed; disabled onmaxPrice
== 0.tickSize
defines the intervals that aprice
/stopPrice
can be increased/decreased by; disabled ontickSize
== 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:
- sell order
price
>=minPrice
- buy order
price
<=maxPrice
- (
price
—minPrice
) %tickSize
== 0
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:
minQty
defines the minimumquantity
allowed.maxQty
defines the maximumquantity
allowed.stepSize
defines the intervals that aquantity
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
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 |
- If startTime and endTime are not sent, the most recent klines are returned.
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
}
],
"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 (HMAC SHA256)
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:
- example: /eapi/v1/batchOrders?orders=[{«symbol»:»BTC-210115-35000-C»,
«price»:»100″,»quantity»:»0.0002″,»side»:»BUY»,»type»:»LIMIT»}]
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 |
Some parameters are mandatory depending on the order type as follows:
Type | Mandatory parameters |
---|---|
LIMIT | timeInForce, quantity, price |
- Parameter rules are same with New Order
- Batch orders are processed concurrently, and the order of matching is not guaranteed.
- The order of returned contents for batch orders is the same as the order of the order list.
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
- These orders will not be found:
- order status is
CANCELED
orREJECTED
, AND - order has NO filled trade, AND
- created time + 3 days < current time
- order status is
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | Option trading pair, e.g BTC-200730-9000-C |
orderId | STRING | NO | Order id |
clientOrderId | STRING | NO | User-defined order ID cannot be repeated in pending orders |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
- Either
orderId
orclientOrderId
must be sent.
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 |
Websocket Market Streams
- The baseurl of the websocket interface is: *wss://nbstream.binance.com/eoptions/*
- Streams can be access either in a single raw stream or a combined stream
- Raw streams are accessed at /ws/<streamName>
- Combined streams are accessed at /stream?streams=<streamName1>/<streamName2>/<streamName3>
- Example:
wss://nbstream.binance.com/eoptions/ws/BTC-210630-9000-P@ticker
-
wss://nbstream.binance.com/eoptions/stream?streams=BTC-210630-9000-P@trade/BTC-210630-9000-P@ticker
-
A single connection is only valid for 24 hours; expect to be disconnected at the 24 hour mark
-
The websocket server will send a
ping frame
every 5 minutes. If the websocket server does not receive apong frame
back from the connection within a 15 minute period, the connection will be disconnected. Unsolicitedpong frames
are allowed. -
WebSocket connections have a limit of 10 incoming messages per second.
-
A connection that goes beyond the limit will be disconnected; IPs that are repeatedly disconnected may be banned.
-
A single connection can listen to a maximum of 200 streams.
-
Considering the possible data latency from RESTful endpoints during an extremely volatile market, it is highly recommended to get the order status, position, etc from the Websocket user data stream.
-
Combined stream events are wrapped as follows: {«stream»:»<streamName>»,»data»:<rawPayload>}
-
All symbols for streams are uppercase
-
A single connection is only valid for 24 hours; expect to be disconnected at the 24 hour mark
-
The websocket server will send a
ping frame
every 5 minutes. If the websocket server does not receive apong frame
back from the connection within a 15 minute period, the connection will be disconnected. Unsolicitedpong frames
are allowed. -
WebSocket connections have a limit of 10 incoming messages per second.
-
A connection that goes beyond the limit will be disconnected; IPs that are repeatedly disconnected may be banned.
-
A single connection can listen to a maximum of 200 streams.
-
Considering the possible data latency from RESTful endpoints during an extremely volatile market, it is highly recommended to get the order status, position, etc from the Websocket user data stream.
Live Subscribing/Unsubscribing to streams
- The following data can be sent through the websocket instance in order to subscribe/unsubscribe from streams. Examples can be seen below.
- The
id
used in the JSON payloads is an unsigned INT used as an identifier to uniquely identify the messages going back and forth.
Subscribe to a stream
Response
{
"result": null,
"id": 1
}
- Request
{
«method»: «SUBSCRIBE»,
«params»:
[
«BTC-210630-9000-P@ticker»,
«BTC-210630-9000-P@depth»
],
«id»: 1
}
Unsubscribe to a stream
Response
{
"result": null,
"id": 312
}
- Request
{
«method»: «UNSUBSCRIBE»,
«params»:
[
«BTC-210630-9000-P@ticker»
],
«id»: 312
}
Listing Subscriptions
Response
{
"result": [
"BTC-210630-9000-P@ticker"
],
"id": 3
}
- Request
{
«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
}
- Request
{
«method»: «SET_PROPERTY»,
«params»:
[
«combined»,
true
],
«id»: 5
}
Retrieving Properties
Response
javascript
{
"result": true, // Indicates that combined is set to true.
"id": 2
}
- Request
{
«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
}
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
"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
"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
"T":1591695934010, // 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)
Diff. Book Depth Streams
** Payload: **
{
"e":"depth", // event type
"T":1591695934010, // transaction time
"s":"BTC-200630-9000-P", // option symbol
"u":62610, // final update id in event
"pu":62609, // final update id in last stream (ie. `u` in last stream event)
"b":[ // buy order
[
"200", // price
"3", // quantity
],
[
"101",
"1"
],
[
"100",
"2"
]
],
"a":[ // sell order
[
"1000",
"89"
]
]
}
When depth level is set to 1000, stream returns diff book depth pushed every 50ms. Please follow the subsequent instructions on how to manage a local order book correctly.
Stream Names: <symbol>@depth1000
Update Speed: 50ms
How to manage a local order book correctly
- Open a diff. Book depth stream to wss://nbstream.binance.com/eoptions/stream?streams=ETH-221230-1200-P@depth1000.
- Buffer the events you receive from the stream. For same price, latest received update covers the previous one.
- Get a depth snapshot from https://eapi.binance.com/eapi/v1/depth?symbol=ETH-221230-1200-P&limit=1000 .
- Drop any event from the websocket stream where
u
is <= theu
from the step 3 - The first processed event should have
u
>u
from step 3 ANDpu
=u
from step 3 - While listening to the stream, each new event’s
pu
should be equal to the previous event’su
, otherwise initialize the process from step 3. - The data in each event is the absolute quantity for a price level.
- If the quantity is 0, remove the price level.
- Receiving an event that removes a price level that is not in your local order book can happen and is normal.
User Data Streams
- The base API endpoint is: https://eapi.binance.com
- A User Data Stream
listenKey
is valid for 60 minutes after creation. - Doing a
PUT
on alistenKey
will extend its validity for 60 minutes. - Doing a
DELETE
on alistenKey
will close the stream and invalidate thelistenKey
. - Doing a
POST
on an account with an activelistenKey
will return the currently activelistenKey
and extend its validity for 60 minutes. - Connection method for Websocket:
- Base Url: wss://nbstream.binance.com/eoptions/
- User Data Streams are accessed at /ws/<listenKey>
- Example:
wss://nbstream.binance.com/eoptions/ws/XaEAKTsQSRLZAGH9tuIu37plSRsdjmlAVBoNYPUITlTAko1WI22PgmBMpI1rS8Yh
- A single connection is only valid for 24 hours; expect to be disconnected at the 24 hour mark
Start User Data Stream (USER_STREAM)
Response:
{
"listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}
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: 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
}
- Update Speed: 50ms
- Update under the following conditions:
- Account deposit or withdrawal
- Position info change. Includes a P attribute if there are changes, otherwise does not include a P attribute.
- Greek update
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)
}
]
}
]
}
- Update Speed: 50ms
- Update under the following conditions:
- Order fills
- Order placed
- Order cancelled
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
}
],
"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 |
- This rest endpoint sets up the parameters to cancel your open orders in case of an outage or disconnection.
- Example usage:
Call this endpoint with a countdownTime value of 10000 (10 seconds) to turn on the auto-cancel feature. If the corresponding countdownCancelAllHeartBeat endpoint is not called within 10 seconds with the specified underlying symbol, all open orders of the specified symbol will be automatically canceled. If this endpoint is called with an countdownTime of 0, the countdown timer will be stopped. - The system will check all countdowns approximately every 1000 milliseconds, please note that sufficient redundancy should be considered when using this function. We do not recommend setting the countdown time to be too precise or too small.
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 |
- countdownTime = 0 means the function is disabled.
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 |
- The response will only include underlying symbols where the heartbeat has been successfully updated.
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
- An unknown error occurred while processing the request.
-1001 DISCONNECTED
- Internal error; unable to process your request. Please try again.
- You are not authorized to execute this request.
-1008 TOO_MANY_REQUESTS
- Too many requests queued.
- Too much request weight used; please use the websocket for live updates to avoid polling the API.
- Too much request weight used; current limit is %s request weight per %s %s. Please use the websocket for live updates to avoid polling the API.
- Way too much request weight used; IP banned until %s. Please use the websocket for live updates to avoid bans.
-1014 UNKNOWN_ORDER_COMPOSITION
- Unsupported order combination.
-1015 TOO_MANY_ORDERS
- Too many new orders.
- Too many new orders; current limit is %s orders per %s.
-1016 SERVICE_SHUTTING_DOWN
- This service is no longer available.
-1020 UNSUPPORTED_OPERATION
- This operation is not supported.
-1021 INVALID_TIMESTAMP
- Timestamp for this request is outside of the recvWindow.
- Timestamp for this request was 1000ms ahead of the server’s time.
-1022 INVALID_SIGNATURE
- Signature for this request is not valid.
11xx — 2xxx Request issues
-1100 ILLEGAL_CHARS
- Illegal characters found in a parameter.
- Illegal characters found in a parameter. %s
- Illegal characters found in parameter
%s
; legal range is%s
.
-1101 TOO_MANY_PARAMETERS
- Too many parameters sent for this endpoint.
- Too many parameters; expected
%s
and received%s
. - Duplicate values for a parameter detected.
-1102 MANDATORY_PARAM_EMPTY_OR_MALFORMED
- A mandatory parameter was not sent, was empty/null, or malformed.
- Mandatory parameter
%s
was not sent, was empty/null, or malformed. - Param
%s
or%s
must be sent, but both were empty/null!
-1103 UNKNOWN_PARAM
- An unknown parameter was sent.
-1104 UNREAD_PARAMETERS
- Not all sent parameters were read.
- Not all sent parameters were read; read
%s
parameter(s) but was sent%s
.
-1105 PARAM_EMPTY
- A parameter was empty.
- Parameter
%s
was empty.
-1106 PARAM_NOT_REQUIRED
- A parameter was sent when not required.
- Parameter
%s
sent when not required.
-1111 BAD_PRECISION
- Precision is over the maximum defined for this asset.
-1115 INVALID_TIF
- Invalid timeInForce.
-1116 INVALID_ORDER_TYPE
- Invalid orderType.
-1117 INVALID_SIDE
- Invalid side.
-1118 EMPTY_NEW_CL_ORD_ID
- New client order ID was empty.
-1119 EMPTY_ORG_CL_ORD_ID
- Original client order ID was empty.
-1120 BAD_INTERVAL
- Invalid interval.
-1121 BAD_SYMBOL
- Invalid symbol.
-1125 INVALID_LISTEN_KEY
- This listenKey does not exist.
-1127 MORE_THAN_XX_HOURS
- Lookup interval is too big.
- More than %s hours between startTime and endTime.
-1128 BAD_CONTRACT
- Invalid underlying
-1129 BAD_CURRENCY
- Invalid asset。
-1130 INVALID_PARAMETER
- Invalid data sent for a parameter.
- Data sent for paramter
%s
is not valid.
-1131 BAD_RECV_WINDOW
- recvWindow must be less than 60000
-2010 NEW_ORDER_REJECTED
- NEW_ORDER_REJECTED
-2013 NO_SUCH_ORDER
- Order does not exist.
-2014 BAD_API_KEY_FMT
- API-key format invalid.
-2015 INVALID_API_KEY
- Invalid API-key, IP, or permissions for action.
-2018 BALANCE_NOT_SUFFICIENT
- Balance is insufficient.
-2027 OPTION_MARGIN_NOT_SUFFICIENT
- Option margin is insufficient.
3xxx-5xxx Filters and other issues
-3029 TRANSFER_FAILED
- Asset transfer fail.
-4001 PRICE_LESS_THAN_ZERO
- Price less than 0.
-4002 PRICE_GREATER_THAN_MAX_PRICE
- Price greater than max price.
-4003 QTY_LESS_THAN_ZERO
- Quantity less than zero.
-4004 QTY_LESS_THAN_MIN_QTY
- Quantity less than min quantity.
-4005 QTY_GREATER_THAN_MAX_QTY
- Quantity greater than max quantity.
-4013 PRICE_LESS_THAN_MIN_PRICE
- Price less than min price.
-4029 INVALID_TICK_SIZE_PRECISION
- Tick size precision is invalid.
-4030 INVALID_QTY_PRECISION
- Step size precision is invalid.
-4055 AMOUNT_MUST_BE_POSITIVE
- Amount must be positive.
Change Log
2023-02-02
REST
- Endpoint
POST /eapi/v1/transfer
is disabled.
2023-01-11
REST
- Add endpoint
GET /eapi/v1/order
to check order status.
2022-12-13
WEBSOCKET
- Add
u
andpu
in stream<symbol>@depth1000
to get diff orderbook update.
2022-12-09
REST
- Add updateId field
u
inGET /eapi/v1/depth
- Add parameter
underlying
inGET /eapi/v1/exerciseHistory
to query exercise histroy by underlying
2022-11-18
REST
- New endpoint
GET /eapi/v1/openInterest
is added to get options open interest for specific underlying on certain expiration date.
WEBSOCKET
- New stream
<underlyingAsset>@openInterest@<expirationDate>
is added for real-time option open interest feed.
2022-11-16
WEBSOCKET
- New trade stream
<underlyingAsset>@trade
is added for all option trades on specific underlying asset. - Adjust format in stream
option_pair
.
2022-11-03
REST
- New endpoint for Auto-Cancel All Open Orders will be added on 2022-11-07:
POST /eapi/v1/countdownCancelAll
:Set Auto-Cancel All Open Orders (Kill-Switch) ConfigGET /eapi/v1/countdownCancelAll
:Get Auto-Cancel All Open Orders (Kill-Switch) ConfigPOST /eapi/v1/countdownCancelAllHeartBeat
:Auto-Cancel All Open Orders (Kill-Switch) Heartbeat
2022-09-20
WEBSOCKET
- New streams
<underlyingAsset>@markPrice
and<underlyingAsset>@ticker@<expirationDate>
are added. - Streams
<!miniTicker@arr>
will be deprecated on 2022/10/30.
2022-09-14
REST
- Adjust endpoint field
strikePrice
,makerFeeRate
,takerFeeRate
,minQty
,maxQty
,initialMargin
,maintenanceMargin
,minInitialMargin
,minMaintenanceMargin
to string in endpointGET /eapi/v1/exchangeInfo
- Only finished orders within 5 days can be queried in
GET /eapi/v1/historyOrders
2022-09-05
REST
- Adjust response result in endpoint
DELETE /eapi/v1/allOpenOrdersByUnderlying
2022-08-22
REST
- Add
rateLimits
information in endpointGET /eapi/v1/exchangeInfo
- Parameters
symbol
set to not mandatory inGET /eapi/v1/userTrades
General Info
General API Information
- Some endpoints will require an API Key. Please refer to this page
- The base endpoint is: **https://eapi.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 Return Codes
- HTTP
4XX
return codes are used for for malformed requests;
the issue is on the sender’s side. - HTTP
403
return code is used when the WAF Limit (Web Application Firewall) has been violated. - 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 receiving429
codes. - HTTP
5XX
return codes are used for internal errors; the issue is on
Binance’s side. - HTTP
503
return code is used when:- If there is an error message «Unknown error, please check your request or try again later.» returned in the response, the API successfully sent the request but not get a response within the timeout period.
It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success; - If there is an error message «Service Unavailable.» returned in the response, it means this is a failure API operation and the service might be unavailable at the moment, you need to retry later.
- If there is an error message «Internal error; unable to process your request. Please try again.» returned in the response, it means this is a failure API operation and you can resend your request if you need.
- If there is an error message «Unknown error, please check your request or try again later.» returned in the response, the API successfully sent the request but not get a response within the timeout period.
Error Codes and Messages
- 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 Codes.
General Information on Endpoints
- For
GET
endpoints, parameters must be sent as aquery string
. - For
POST
,PUT
, andDELETE
endpoints, the parameters may be sent as a
query string
or in therequest body
with content type
application/x-www-form-urlencoded
. You may mix parameters between both the
query string
andrequest body
if you wish to do so. - Parameters may be sent in any order.
- If a parameter sent in both the
query string
andrequest body
, the
query string
parameter will be used.
LIMITS
- The
/eapi/v1/exchangeInfo
rateLimits
array contains objects related to the exchange’sRAW_REQUEST
,REQUEST_WEIGHT
, andORDER
rate limits. These are further defined in theENUM definitions
section underRate limiters (rateLimitType)
. - A
429
will be returned when either rate limit is violated.
IP Limits
- Every request will contain
X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)
in the response headers which has the current used weight for the IP for all request rate limiters defined. - 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 heavierweight
. - When a 429 is received, 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 429s 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.
- The limits on the API are based on the IPs, not the API keys.
Order Rate Limits
- Every order response will contain a
X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)
header which has the current order count for the account for all order rate limiters defined. - Rejected/unsuccessful orders are not guaranteed to have
X-MBX-ORDER-COUNT-**
headers in the response. - The order rate limit is counted against each account.
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
andUSER_DATA
endpoints areSIGNED
endpoints.
SIGNED (TRADE and USER_DATA) Endpoint Security
SIGNED
endpoints require an additional parameter,signature
, to be
sent in thequery string
orrequest body
.- Endpoints use
HMAC SHA256
signatures. TheHMAC SHA256 signature
is a keyedHMAC SHA256
operation.
Use yoursecretKey
as the key andtotalParams
as the value for the HMAC operation. - The
signature
is not case sensitive. - Please make sure the
signature
is the end part of yourquery string
orrequest body
. totalParams
is defined as thequery 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 aftertimestamp
the request is valid for. IfrecvWindow
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.
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×tamp=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×tamp=1611825601400&signature=7c12045972f6140e765e0f2b67d28099718df805732676494238f50be830a7d7'
- requestBody:
symbol=BTC-210129-40000-C
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=2000
&recvWindow=5000
×tamp=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×tamp=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×tamp=1611825601400&signature=7c12045972f6140e765e0f2b67d28099718df805732676494238f50be830a7d7'
- queryString:
symbol=BTC-210129-40000-C
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=2000
&recvWindow=5000
×tamp=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×tamp=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×tamp=1611825601400&signature=fa6045c54fb02912b766442be1f66fab619217e551a4fb4f8a1ee000df914d8e'
- queryString:
symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTC
- requestBody:
quantity=1&price=2000&recvWindow=5000×tamp=1611825601400
Note that the signature is different in example 3.
There is no & between «GTC» and «quantity=1».
Public Endpoints Info
Terminology
symbol
refers to the symbol name of a options contract symbolunderlying
refers to the underlying symbol of a options contract symbolquoteAsset
refers to the asset that is the price of a symbol.settleAsset
refers to the settlement asset when options are exercised
ENUM definitions
Options contract type
- CALL
- PUT
Order side
- BUY
- SELL
Position side
- LONG
- SHORT
Time in force
- GTC — Good Till Cancel
- IOC — Immediate or Cancel
- FOK — Fill or Kill
Response Type (newOrderRespType)
- ACK
- RESULT
Order types (type)
- LIMIT
Order status (status)
- ACCEPTED
- REJECTED
- PARTIALLY_FILLED
- FILLED
- CANCELLED
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
javascript
{
"rateLimitType": "REQUEST_WEIGHT",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 2400
}
ORDERS
javascript
{
"rateLimitType": "ORDERS",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 1200
}
-
REQUEST_WEIGHT
-
ORDERS
Rate limit intervals (interval)
- MINUTE
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:
minPrice
defines the minimumprice
/stopPrice
allowed; disabled onminPrice
== 0.maxPrice
defines the maximumprice
/stopPrice
allowed; disabled onmaxPrice
== 0.tickSize
defines the intervals that aprice
/stopPrice
can be increased/decreased by; disabled ontickSize
== 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:
- sell order
price
>=minPrice
- buy order
price
<=maxPrice
- (
price
—minPrice
) %tickSize
== 0
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:
minQty
defines the minimumquantity
allowed.maxQty
defines the maximumquantity
allowed.stepSize
defines the intervals that aquantity
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
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 |
- If startTime and endTime are not sent, the most recent klines are returned.
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
}
],
"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 (HMAC SHA256)
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:
- example: /eapi/v1/batchOrders?orders=[{«symbol»:»BTC-210115-35000-C»,
«price»:»100″,»quantity»:»0.0002″,»side»:»BUY»,»type»:»LIMIT»}]
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 |
Some parameters are mandatory depending on the order type as follows:
Type | Mandatory parameters |
---|---|
LIMIT | timeInForce, quantity, price |
- Parameter rules are same with New Order
- Batch orders are processed concurrently, and the order of matching is not guaranteed.
- The order of returned contents for batch orders is the same as the order of the order list.
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
- These orders will not be found:
- order status is
CANCELED
orREJECTED
, AND - order has NO filled trade, AND
- created time + 3 days < current time
- order status is
Parameters:
Name | Type | Mandatory | Description |
---|---|---|---|
symbol | STRING | YES | Option trading pair, e.g BTC-200730-9000-C |
orderId | STRING | NO | Order id |
clientOrderId | STRING | NO | User-defined order ID cannot be repeated in pending orders |
recvWindow | LONG | NO | |
timestamp | LONG | YES |
- Either
orderId
orclientOrderId
must be sent.
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 |
Websocket Market Streams
- The baseurl of the websocket interface is: *wss://nbstream.binance.com/eoptions/*
- Streams can be access either in a single raw stream or a combined stream
- Raw streams are accessed at /ws/<streamName>
- Combined streams are accessed at /stream?streams=<streamName1>/<streamName2>/<streamName3>
- Example:
wss://nbstream.binance.com/eoptions/ws/BTC-210630-9000-P@ticker
-
wss://nbstream.binance.com/eoptions/stream?streams=BTC-210630-9000-P@trade/BTC-210630-9000-P@ticker
-
A single connection is only valid for 24 hours; expect to be disconnected at the 24 hour mark
-
The websocket server will send a
ping frame
every 5 minutes. If the websocket server does not receive apong frame
back from the connection within a 15 minute period, the connection will be disconnected. Unsolicitedpong frames
are allowed. -
WebSocket connections have a limit of 10 incoming messages per second.
-
A connection that goes beyond the limit will be disconnected; IPs that are repeatedly disconnected may be banned.
-
A single connection can listen to a maximum of 200 streams.
-
Considering the possible data latency from RESTful endpoints during an extremely volatile market, it is highly recommended to get the order status, position, etc from the Websocket user data stream.
-
Combined stream events are wrapped as follows: {«stream»:»<streamName>»,»data»:<rawPayload>}
-
All symbols for streams are uppercase
-
A single connection is only valid for 24 hours; expect to be disconnected at the 24 hour mark
-
The websocket server will send a
ping frame
every 5 minutes. If the websocket server does not receive apong frame
back from the connection within a 15 minute period, the connection will be disconnected. Unsolicitedpong frames
are allowed. -
WebSocket connections have a limit of 10 incoming messages per second.
-
A connection that goes beyond the limit will be disconnected; IPs that are repeatedly disconnected may be banned.
-
A single connection can listen to a maximum of 200 streams.
-
Considering the possible data latency from RESTful endpoints during an extremely volatile market, it is highly recommended to get the order status, position, etc from the Websocket user data stream.
Live Subscribing/Unsubscribing to streams
- The following data can be sent through the websocket instance in order to subscribe/unsubscribe from streams. Examples can be seen below.
- The
id
used in the JSON payloads is an unsigned INT used as an identifier to uniquely identify the messages going back and forth.
Subscribe to a stream
Response
{
"result": null,
"id": 1
}
- Request
{
«method»: «SUBSCRIBE»,
«params»:
[
«BTC-210630-9000-P@ticker»,
«BTC-210630-9000-P@depth»
],
«id»: 1
}
Unsubscribe to a stream
Response
{
"result": null,
"id": 312
}
- Request
{
«method»: «UNSUBSCRIBE»,
«params»:
[
«BTC-210630-9000-P@ticker»
],
«id»: 312
}
Listing Subscriptions
Response
{
"result": [
"BTC-210630-9000-P@ticker"
],
"id": 3
}
- Request
{
«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
}
- Request
{
«method»: «SET_PROPERTY»,
«params»:
[
«combined»,
true
],
«id»: 5
}
Retrieving Properties
Response
javascript
{
"result": true, // Indicates that combined is set to true.
"id": 2
}
- Request
{
«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
}
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
"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
"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
"T":1591695934010, // 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)
Diff. Book Depth Streams
** Payload: **
{
"e":"depth", // event type
"T":1591695934010, // transaction time
"s":"BTC-200630-9000-P", // option symbol
"u":62610, // final update id in event
"pu":62609, // final update id in last stream (ie. `u` in last stream event)
"b":[ // buy order
[
"200", // price
"3", // quantity
],
[
"101",
"1"
],
[
"100",
"2"
]
],
"a":[ // sell order
[
"1000",
"89"
]
]
}
When depth level is set to 1000, stream returns diff book depth pushed every 50ms. Please follow the subsequent instructions on how to manage a local order book correctly.
Stream Names: <symbol>@depth1000
Update Speed: 50ms
How to manage a local order book correctly
- Open a diff. Book depth stream to wss://nbstream.binance.com/eoptions/stream?streams=ETH-221230-1200-P@depth1000.
- Buffer the events you receive from the stream. For same price, latest received update covers the previous one.
- Get a depth snapshot from https://eapi.binance.com/eapi/v1/depth?symbol=ETH-221230-1200-P&limit=1000 .
- Drop any event from the websocket stream where
u
is <= theu
from the step 3 - The first processed event should have
u
>u
from step 3 ANDpu
=u
from step 3 - While listening to the stream, each new event’s
pu
should be equal to the previous event’su
, otherwise initialize the process from step 3. - The data in each event is the absolute quantity for a price level.
- If the quantity is 0, remove the price level.
- Receiving an event that removes a price level that is not in your local order book can happen and is normal.
User Data Streams
- The base API endpoint is: https://eapi.binance.com
- A User Data Stream
listenKey
is valid for 60 minutes after creation. - Doing a
PUT
on alistenKey
will extend its validity for 60 minutes. - Doing a
DELETE
on alistenKey
will close the stream and invalidate thelistenKey
. - Doing a
POST
on an account with an activelistenKey
will return the currently activelistenKey
and extend its validity for 60 minutes. - Connection method for Websocket:
- Base Url: wss://nbstream.binance.com/eoptions/
- User Data Streams are accessed at /ws/<listenKey>
- Example:
wss://nbstream.binance.com/eoptions/ws/XaEAKTsQSRLZAGH9tuIu37plSRsdjmlAVBoNYPUITlTAko1WI22PgmBMpI1rS8Yh
- A single connection is only valid for 24 hours; expect to be disconnected at the 24 hour mark
Start User Data Stream (USER_STREAM)
Response:
{
"listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}
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: 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
}
- Update Speed: 50ms
- Update under the following conditions:
- Account deposit or withdrawal
- Position info change. Includes a P attribute if there are changes, otherwise does not include a P attribute.
- Greek update
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)
}
]
}
]
}
- Update Speed: 50ms
- Update under the following conditions:
- Order fills
- Order placed
- Order cancelled
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
}
],
"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 |
- This rest endpoint sets up the parameters to cancel your open orders in case of an outage or disconnection.
- Example usage:
Call this endpoint with a countdownTime value of 10000 (10 seconds) to turn on the auto-cancel feature. If the corresponding countdownCancelAllHeartBeat endpoint is not called within 10 seconds with the specified underlying symbol, all open orders of the specified symbol will be automatically canceled. If this endpoint is called with an countdownTime of 0, the countdown timer will be stopped. - The system will check all countdowns approximately every 1000 milliseconds, please note that sufficient redundancy should be considered when using this function. We do not recommend setting the countdown time to be too precise or too small.
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 |
- countdownTime = 0 means the function is disabled.
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 |
- The response will only include underlying symbols where the heartbeat has been successfully updated.
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
- An unknown error occurred while processing the request.
-1001 DISCONNECTED
- Internal error; unable to process your request. Please try again.
- You are not authorized to execute this request.
-1008 TOO_MANY_REQUESTS
- Too many requests queued.
- Too much request weight used; please use the websocket for live updates to avoid polling the API.
- Too much request weight used; current limit is %s request weight per %s %s. Please use the websocket for live updates to avoid polling the API.
- Way too much request weight used; IP banned until %s. Please use the websocket for live updates to avoid bans.
-1014 UNKNOWN_ORDER_COMPOSITION
- Unsupported order combination.
-1015 TOO_MANY_ORDERS
- Too many new orders.
- Too many new orders; current limit is %s orders per %s.
-1016 SERVICE_SHUTTING_DOWN
- This service is no longer available.
-1020 UNSUPPORTED_OPERATION
- This operation is not supported.
-1021 INVALID_TIMESTAMP
- Timestamp for this request is outside of the recvWindow.
- Timestamp for this request was 1000ms ahead of the server’s time.
-1022 INVALID_SIGNATURE
- Signature for this request is not valid.
11xx — 2xxx Request issues
-1100 ILLEGAL_CHARS
- Illegal characters found in a parameter.
- Illegal characters found in a parameter. %s
- Illegal characters found in parameter
%s
; legal range is%s
.
-1101 TOO_MANY_PARAMETERS
- Too many parameters sent for this endpoint.
- Too many parameters; expected
%s
and received%s
. - Duplicate values for a parameter detected.
-1102 MANDATORY_PARAM_EMPTY_OR_MALFORMED
- A mandatory parameter was not sent, was empty/null, or malformed.
- Mandatory parameter
%s
was not sent, was empty/null, or malformed. - Param
%s
or%s
must be sent, but both were empty/null!
-1103 UNKNOWN_PARAM
- An unknown parameter was sent.
-1104 UNREAD_PARAMETERS
- Not all sent parameters were read.
- Not all sent parameters were read; read
%s
parameter(s) but was sent%s
.
-1105 PARAM_EMPTY
- A parameter was empty.
- Parameter
%s
was empty.
-1106 PARAM_NOT_REQUIRED
- A parameter was sent when not required.
- Parameter
%s
sent when not required.
-1111 BAD_PRECISION
- Precision is over the maximum defined for this asset.
-1115 INVALID_TIF
- Invalid timeInForce.
-1116 INVALID_ORDER_TYPE
- Invalid orderType.
-1117 INVALID_SIDE
- Invalid side.
-1118 EMPTY_NEW_CL_ORD_ID
- New client order ID was empty.
-1119 EMPTY_ORG_CL_ORD_ID
- Original client order ID was empty.
-1120 BAD_INTERVAL
- Invalid interval.
-1121 BAD_SYMBOL
- Invalid symbol.
-1125 INVALID_LISTEN_KEY
- This listenKey does not exist.
-1127 MORE_THAN_XX_HOURS
- Lookup interval is too big.
- More than %s hours between startTime and endTime.
-1128 BAD_CONTRACT
- Invalid underlying
-1129 BAD_CURRENCY
- Invalid asset。
-1130 INVALID_PARAMETER
- Invalid data sent for a parameter.
- Data sent for paramter
%s
is not valid.
-1131 BAD_RECV_WINDOW
- recvWindow must be less than 60000
-2010 NEW_ORDER_REJECTED
- NEW_ORDER_REJECTED
-2013 NO_SUCH_ORDER
- Order does not exist.
-2014 BAD_API_KEY_FMT
- API-key format invalid.
-2015 INVALID_API_KEY
- Invalid API-key, IP, or permissions for action.
-2018 BALANCE_NOT_SUFFICIENT
- Balance is insufficient.
-2027 OPTION_MARGIN_NOT_SUFFICIENT
- Option margin is insufficient.
3xxx-5xxx Filters and other issues
-3029 TRANSFER_FAILED
- Asset transfer fail.
-4001 PRICE_LESS_THAN_ZERO
- Price less than 0.
-4002 PRICE_GREATER_THAN_MAX_PRICE
- Price greater than max price.
-4003 QTY_LESS_THAN_ZERO
- Quantity less than zero.
-4004 QTY_LESS_THAN_MIN_QTY
- Quantity less than min quantity.
-4005 QTY_GREATER_THAN_MAX_QTY
- Quantity greater than max quantity.
-4013 PRICE_LESS_THAN_MIN_PRICE
- Price less than min price.
-4029 INVALID_TICK_SIZE_PRECISION
- Tick size precision is invalid.
-4030 INVALID_QTY_PRECISION
- Step size precision is invalid.
-4055 AMOUNT_MUST_BE_POSITIVE
- Amount must be positive.