Request security
- Each method has a security type indicating required API key permissions, shown next to the method name (e.g., Place new order (TRADE)).
- If unspecified, the security type is
NONE
. - Except for
NONE
, all methods with a security type are consideredSIGNED
requests (i.e. including asignature
), except for listenKey management. - Secure methods require a valid API key to be specified and authenticated.
- API keys can be created on the SPOT Test Network upon logging in with your Github account.
- Both API key and secret key are sensitive. Never share them with anyone. If you notice unusual activity in your account, immediately revoke all the keys and contact Binance support.
- API keys can be configured to allow access only to certain types of secure methods.
- For example, you can have an API key with
TRADE
permission for trading, while using a separate API key withUSER_DATA
permission to monitor your order status. - By default, an API key cannot
TRADE
. You need to enable trading in API Management first.
- For example, you can have an API key with
Security type | Description |
---|---|
NONE | Public market data |
TRADE | Trading on the exchange, placing and canceling orders |
USER_DATA | Private account information, such as order status and your trading history |
USER_STREAM | Managing User Data Stream subscriptions |
SIGNED request security
SIGNED
requests require an additional parameter:signature
, authorizing the request.- Please consult SIGNED request example (HMAC), SIGNED request example (RSA), and SIGNED request example (Ed25519) on how to compute signature, depending on which API key type you are using.
Timing security
SIGNED
requests also require atimestamp
parameter which should be the current timestamp either in milliseconds or microseconds. (See General API Information)- An additional optional parameter,
recvWindow
, specifies for how long the request stays valid and may only be specified in milliseconds.- If
recvWindow
is not sent, it defaults to 5000 milliseconds. - Maximum
recvWindow
is 60000 milliseconds.
- If
- Request processing logic is as follows:
serverTime = getCurrentTime()
if (timestamp < (serverTime + 1 second) && (serverTime - timestamp) <= recvWindow) {
// begin processing request
serverTime = getCurrentTime()
if (serverTime - timestamp) <= recvWindow {
// forward request to Matching Engine
} else {
// reject request
}
// finish processing request
} else {
// reject request
}
Serious trading is about timing. Networks can be unstable and unreliable,
which can lead to requests taking varying amounts of time to reach the
servers. With recvWindow
, you can specify that the request must be
processed within a certain number of milliseconds or be rejected by the
server.
It is recommended to use a small recvWindow
of 5000 or less!
SIGNED request example (HMAC)
Here is a step-by-step guide on how to sign requests using HMAC secret key.
Example API key and secret key:
Key | Value |
---|---|
apiKey | vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A |
secretKey | NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j |
WARNING: DO NOT SHARE YOUR API KEY AND SECRET KEY WITH ANYONE.
The example keys are provided here only for illustrative purposes.
Example of request:
{
"id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
"method": "order.place",
"params": {
"symbol": "BTCUSDT",
"side": "SELL",
"type": "LIMIT",
"timeInForce": "GTC",
"quantity": "0.01000000",
"price": "52000.00",
"newOrderRespType": "ACK",
"recvWindow": 100,
"timestamp": 1645423376532,
"apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
"signature": "------ FILL ME ------"
}
}
As you can see, the signature
parameter is currently missing.
Step 1. Construct the signature payload
Take all request params
except for the signature
, sort them by name in alphabetical order:
Parameter | Value |
---|---|
apiKey | vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A |
newOrderRespType | ACK |
price | 52000.00 |
quantity | 0.01000000 |
recvWindow | 100 |
side | SELL |
symbol | BTCUSDT |
timeInForce | GTC |
timestamp | 1645423376532 |
type | LIMIT |
Format parameters as parameter=value
pairs separated by &
.
Resulting signature payload:
apiKey=vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A&newOrderRespType=ACK&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC×tamp=1645423376532&type=LIMIT
Step 2. Compute the signature
- Interpret
secretKey
as ASCII data, using it as a key for HMAC-SHA-256. - Sign signature payload as ASCII data.
- Encode HMAC-SHA-256 output as a hex string.
Note that apiKey
, secretKey
, and the payload are case-sensitive, while resulting signature value is case-insensitive.
You can cross-check your signature algorithm implementation with OpenSSL:
$ echo -n 'apiKey=vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A&newOrderRespType=ACK&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC×tamp=1645423376532&type=LIMIT' \
| openssl dgst -hex -sha256 -hmac 'NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j'
cc15477742bd704c29492d96c7ead9414dfd8e0ec4a00f947bb5bb454ddbd08a
Step 3. Add signature
to request params
Finally, complete the request by adding the signature
parameter with the signature string.
{
"id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
"method": "order.place",
"params": {
"symbol": "BTCUSDT",
"side": "SELL",
"type": "LIMIT",
"timeInForce": "GTC",
"quantity": "0.01000000",
"price": "52000.00",
"newOrderRespType": "ACK",
"recvWindow": 100,
"timestamp": 1645423376532,
"apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
"signature": "cc15477742bd704c29492d96c7ead9414dfd8e0ec4a00f947bb5bb454ddbd08a"
}
}