Public WAPI for Binance (2017-12-01)

General API Information

The base endpoint is: https://api.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 4XX return codes are used for for malformed requests; the issue is on the sender's side.
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 receiving 429 codes.
HTTP 5XX return codes are used for internal errors; the issue is on Binance's side.
HTTP 504 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; the execution status is UNKNOWN and could have been a success.
Any endpoint can retun an ERROR; the error payload is as follows:

{
  "success": false,
  "msg": "Invalid symbol."
}

Specific error codes and messages defined in another document.
For GET endpoints, parameters must be sent as a query string.
For POST, PUT, and DELETE endpoints, the parameters may be sent as a query string or in the request body with content type application/x-www-form-urlencoded. You may mix parameters between both the query string and request body if you wish to do so.
Parameters may be sent in any order.
If a parameter sent in both the query string and request body, the query string parameter will be used.

LIMITS

The /wapi/v3 rateLimits array contains objects related to the exchange's REQUESTS and ORDER rate limits.
A 429 will be returned when either rather limit is violated.
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 heavier weight.
When a 429 is recieved, 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.

Endpoint security type

Each endpoint has a security type that determines the how you will interact with it.
API-keys are passed into the Rest API via the X-MBX-APIKEY header.
API-keys and secret-keys are case sensitive.
API-keys can be configured to only access certain types of secure endpoints. For example, one API-key could be used for TRADE only, while another API-key can access everything except for TRADE routes.
By default, API-keys can access all secure routes.

Security Type	Description
NONE	Endpoint can be accessed freely.
TRADE	Endpoint requires sending a valid API-Key and signature.
USER_DATA	Endpoint requires sending a valid API-Key and signature.
USER_STREAM	Endpoint requires sending a valid API-Key.
MARKET_DATA	Endpoint requires sending a valid API-Key.

TRADE and USER_DATA endpoints are SIGNED endpoints.

SIGNED (TRADE and USER_DATA) Endpoint security

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

Timing security

A SIGNED endpoint also requires a parameter, timestamp, to be sent which should be the millisecond timestamp of when the request was created and sent.
An additional parameter, recvWindow, may be sent to specific the number of milliseconds after timestamp the request is valid for. If recvWindow is not sent, it defaults to 5000.

The logic is as follows:

if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
  // process request
} else {
  // reject request
}

Serious trading is about timing. Networks can be unstable and unreliable, which can lead to requests taking varying amounts of time to reach the servers. With recvWindow, you can specify that the request must be processed within a certain number of milliseconds or be rejected by the server.

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

SIGNED Endpoint Examples for POST /wapi/v3/withdraw.html

Here is a step-by-step example of how to send a vaild signed payload from the Linux command line using echo, openssl, and curl.

Key	Value
apiKey	vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKey	NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j

Parameter	Value
asset	ETH
address	0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b
addressTag	1 (Secondary address identifier for coins like XRP,XMR etc.)
amount	1
recvWindow	5000
name	addressName (Description of the address)
timestamp	1508396497000
signature	157fb937ec848b5f802daa4d9f62bea08becbf4f311203bda2bd34cd9853e320

Example 1: As a query string

queryString: asset=ETH&address=0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b&amount=1&recvWindow=5000&name=test&timestamp=1510903211000

HMAC SHA256 signature:

[linux]$ echo -n "asset=ETH&address=0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b&amount=1&recvWindow=5000&timestamp=1510903211000" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= 157fb937ec848b5f802daa4d9f62bea08becbf4f311203bda2bd34cd9853e320

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://www.binance.com/wapi/v3/withdraw.html?asset=ETH&address=0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b&amount=1&recvWindow=5000&name=addressName&timestamp=1510903211000&signature=157fb937ec848b5f802daa4d9f62bea08becbf4f311203bda2bd34cd9853e320'

Example 2: As a request body

requestBody: asset=ETH&address=0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b&amount=1&recvWindow=5000&name=test&timestamp=1510903211000

HMAC SHA256 signature:

[linux]$ echo -n "asset=ETH&address=0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b&amount=1&recvWindow=5000&timestamp=1510903211000" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= 157fb937ec848b5f802daa4d9f62bea08becbf4f311203bda2bd34cd9853e320

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://www.binance.com/wapi/v3/withdraw.html' -d 'asset=ETH&address=0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b&amount=1&recvWindow=5000&name=addressName&timestamp=1510903211000&signature=157fb937ec848b5f802daa4d9f62bea08becbf4f311203bda2bd34cd9853e320'

Example 3: Mixed query string and request body

queryString: asset=ETH&address=0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b
requestBody: amount=1&recvWindow=5000&name=test&timestamp=1510903211000

HMAC SHA256 signature:

[linux]$ echo -n "asset=ETH&address=0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b&amount=1&recvWindow=5000&timestamp=1510903211000" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= 157fb937ec848b5f802daa4d9f62bea08becbf4f311203bda2bd34cd9853e320

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://www.binance.com/wapi/v3/withdraw.html?asset=ETH&address=0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b' -d 'amount=1&recvWindow=5000&name=addressName&timestamp=1510903211000&signature=157fb937ec848b5f802daa4d9f62bea08becbf4f311203bda2bd34cd9853e320'

Note that the signature is different in example 3. There is no & between "address=0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b" and "amount=1".

Withdraw

POST /wapi/v3/withdraw.html (HMAC SHA256)

Submit a withdraw request.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
asset	STRING	YES
address	STRING	YES
addressTag	STRING	NO	Secondary address identifier for coins like XRP,XMR etc.
amount	DECIMAL	YES
name	STRING	NO	Description of the address
recvWindow	LONG	NO
timestamp	LONG	YES
Response:

[
{
    "msg": "success",
    "success": true,
    "id":"7213fea8e94b4a5593d507237e5a555b"
}
]

Deposit History (USER_DATA)

GET /wapi/v3/depositHistory.html (HMAC SHA256)

Fetch deposit history.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
asset	STRING	NO
status	INT	NO	0(0:pending,1:success)
startTime	LONG	NO
endTime	LONG	NO
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

{
    "depositList": [
        {
            "insertTime": 1508198532000,
            "amount": 0.04670582,
            "asset": "ETH",
            "address": "0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b",
            "txId": "0xdf33b22bdb2b28b1f75ccd201a4a4m6e7g83jy5fc5d5a9d1340961598cfcb0a1",
            "status": 1
        },
        {
            "insertTime": 1508298532000,
            "amount": 1000,
            "asset": "XMR",
            "address": "463tWEBn5XZJSxLU34r6g7h8jtxuNcDbjLSjkn3XAXHCbLrTTErJrBWYgHJQyrCwkNgYvyV3z8zctJLPCZy24jvb3NiTcTJ",
            "addressTag": "342341222",
            "txId": "b3c6219639c8ae3f9cf010cdc24fw7f7yt8j1e063f9b4bd1a05cb44c4b6e2509",
            "status": 1
        }
    ],
    "success": true
}

Withdraw History (USER_DATA)

GET /wapi/v3/withdrawHistory.html (HMAC SHA256)

Fetch withdraw history.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
asset	STRING	NO
status	INT	NO	0(0:Email Sent,1:Cancelled 2:Awaiting Approval 3:Rejected 4:Processing 5:Failure 6Completed)
startTime	LONG	NO
endTime	LONG	NO
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

{
    "withdrawList": [
        {
            "id":"7213fea8e94b4a5593d507237e5a555b"
            "amount": 1,
            "address": "0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b",
            "asset": "ETH",
            "txId": "0xdf33b22bdb2b28b1f75ccd201a4a4m6e7g83jy5fc5d5a9d1340961598cfcb0a1",
            "applyTime": 1508198532000 
            "status": 4
        },
        {
            "id":"7213fea8e94b4a5534ggsd237e5a555b"
            "amount": 1000,
            "address": "463tWEBn5XZJSxLU34r6g7h8jtxuNcDbjLSjkn3XAXHCbLrTTErJrBWYgHJQyrCwkNgYvyV3z8zctJLPCZy24jvb3NiTcTJ",
            "addressTag": "342341222",
            "txId": "b3c6219639c8ae3f9cf010cdc24fw7f7yt8j1e063f9b4bd1a05cb44c4b6e2509",
            "asset": "XMR",
            "applyTime": 1508198532000,
            "status": 4
        }
    ],
    "success": true
}

Deposit Address (USER_DATA)

GET  /wapi/v3/depositAddress.html (HMAC SHA256)

Fetch deposit address.

Weight: 1

Parameters:

Name	Type	Mandatory
asset	STRING	YES
status	Boolean	NO
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

[
{
    "address": "0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b",
    "success": true,
    "addressTag": "1231212",
    "asset": "BNB"
}
]

Withdraw Fee (USER_DATA)

GET  /wapi/v3/withdrawFee.html (HMAC SHA256)

Fetch deposit address.

Weight: 1

Parameters:

Name	Type	Mandatory
asset	STRING	YES
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

[
{
    "withdrawFee": "0.0005",
    "success": true
}
]

Account Status (USER_DATA)

GET /wapi/v3/accountStatus.html

Fetch account status detail.

Weight: 1

Parameters:

Name	Type	Mandatory	Description
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

{
    "msg": "Order failed:Low Order fill rate! Will be reactivated after 5 minutes.",
    "success": true,
    "objs": [
        "5"
    ]
}

System Status (System)

GET /wapi/v3/systemStatus.html

Fetch system status. Response:

{ 
    "status": 0,              // 0: normal，1：system maintenance
    "msg": "normal"           // normal or system maintenance
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

wapi-api.md

wapi-api.md

Public WAPI for Binance (2017-12-01)

General API Information

LIMITS

Endpoint security type

SIGNED (TRADE and USER_DATA) Endpoint security

Timing security

SIGNED Endpoint Examples for POST /wapi/v3/withdraw.html

Example 1: As a query string

Example 2: As a request body

Example 3: Mixed query string and request body

Withdraw

Deposit History (USER_DATA)

Withdraw History (USER_DATA)

Deposit Address (USER_DATA)

Withdraw Fee (USER_DATA)

Account Status (USER_DATA)

System Status (System)

Files

wapi-api.md

Latest commit

History

wapi-api.md

File metadata and controls

Public WAPI for Binance (2017-12-01)

General API Information

LIMITS

Endpoint security type

SIGNED (TRADE and USER_DATA) Endpoint security

Timing security

SIGNED Endpoint Examples for POST /wapi/v3/withdraw.html

Example 1: As a query string

Example 2: As a request body

Example 3: Mixed query string and request body

Withdraw

Deposit History (USER_DATA)

Withdraw History (USER_DATA)

Deposit Address (USER_DATA)

Withdraw Fee (USER_DATA)

Account Status (USER_DATA)

System Status (System)