General Info
#
testnet- Most of the endpoints can be also used in the testnet platform.
- The REST baseurl for testnet is "https://testnet.binancefuture.com"
- The Websocket baseurl for testnet is "wss://dstream.binancefuture.com"
#
General API Information- The base endpoint is: https://dapi.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.
- 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.- If there is an error message "Request occur unknown error.", please retry later.
- 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:
- 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 aquery string
or in therequest body
with content typeapplication/x-www-form-urlencoded
. You may mix parameters between both thequery 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
, thequery 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 SecuritySIGNED
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 therequest 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:
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 - HMAC KeysHere 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 stringExample 1
HMAC SHA256 signature:
curl command:
queryString:
symbol=BTCUSD_200925
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=9000
&recvWindow=5000
×tamp=1591702613943
#
Example 2: As a request bodyExample 2
HMAC SHA256 signature:
curl command:
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 bodyExample 3
HMAC SHA256 signature:
curl command:
- queryString: symbol=BTCUSD_200925&side=BUY&type=LIMIT&timeInForce=GTC
- requestBody: quantity=1&price=9000&recvWindow=5000×tamp= 1591702613943
Note that the signature is different in example 3.
There is no & between "GTC" and "quantity=1".
#
SIGNED Endpoint Examples for POST /dapi/v1/order - RSA Keys- This will be a step by step process how to create the signature payload to send a valid signed payload.
- We support
PKCS#8
currently. - To get your API key, you need to upload your RSA Public Key to your account and a corresponding API key will be provided for you.
For this example, the private key will be referenced as test-prv-key.pem
Key | Value |
---|---|
apiKey | vE3BDAL1gP1UaexugRLtteaAHg3UO8Nza20uexEuW1Kh3tVwQfFHdAiyjjY428o2 |
Parameter | Value |
---|---|
symbol | BTCUSD_PERP |
side | SELL |
type | MARKET |
quantity | 100 |
recvWindow | 9999999 |
timestamp | 1671090801999 |
Signature payload (with the listed parameters):
Step 1: Construct the payload
Arrange the list of parameters into a string. Separate each parameter with a &
.
Step 2: Compute the signature:
2.1 - Encode signature payload as ASCII data.
Step 2.2
2.2 - Sign payload using RSASSA-PKCS1-v1_5 algorithm with SHA-256 hash function.
Step 2.3
2.3 - Encode output as base64 string.
Step 2.4
2.4 - Delete any newlines in the signature.
Step 2.5
2.5 - Since the signature may contain /
and =
, this could cause issues with sending the request. So the signature has to be URL encoded.
Step 2.6
2.6 - curl command
Bash script
A sample Bash script containing similar steps is available in the right side.