币安Binance rest API

BitMex 100倍杠杆永续合约,注册BitMex请使用日本IP:

Binance币安 (2018-07-18)

General API Information

  • 基础URL地址: https://api.binance.com

  • 数据以Json或数组形式返回

  • 数据返回值以升序排列. 即老数据在前,新数据在后

  • 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 429codes.

  • HTTP 5XX return codes are used for internal errors; the issue is on Binance's side. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.

  • Any endpoint can return an ERROR; the error payload is as follows:

{  "code": -1121,  "msg": "Invalid symbol."}
  • Specific error codes and messages defined in another document.

  • For GET endpoints, parameters must be sent as a query string.

  • For POSTPUT, 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 /api/v1/exchangeInfo rateLimits array contains objects related to the exchange's REQUEST_WEIGHT and ORDERrate limits.

  • A 429 will be returned when either rate 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 TypeDescription
NONEEndpoint can be accessed freely.
TRADEEndpoint requires sending a valid API-Key and signature.
USER_DATAEndpoint requires sending a valid API-Key and signature.
USER_STREAMEndpoint requires sending a valid API-Key.
MARKET_DATAEndpoint 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

  • 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 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.

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

SIGNED Endpoint Examples for POST /api/v1/order

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

KeyValue
apiKeyvmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKeyNhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
ParameterValue
symbolLTCBTC
sideBUY
typeLIMIT
timeInForceGTC
quantity1
price0.1
recvWindow5000
timestamp1499827319559

Example 1: As a query string

  • queryString:symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

  • HMAC SHA256 signature:

    [linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
    (stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71
  • curl command:

    (HMAC SHA256)
    [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.com/api/v3/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'

Example 2: As a request body

  • requestBody:symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

  • HMAC SHA256 signature:

    [linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
    (stdin)= c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71
  • curl command:

    (HMAC SHA256)
    [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.com/api/v3/order' -d 'symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71'

Example 3: Mixed query string and request body

  • queryString: symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC

  • requestBody: quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

  • HMAC SHA256 signature:

    [linux]$ echo -n "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
    (stdin)= 0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77
  • curl command:

    (HMAC SHA256)
    [linux]$ curl -H "X-MBX-APIKEY: vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api.binance.com/api/v3/order?symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=0fd168b8ddb4876a0358a8d14d0c9f3da0e9b20c5d52b2a00fcf7d1c602f9a77'

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

Public API Endpoints

Terminology

  • base asset refers to the asset that is the quantity of a symbol.

  • quote asset refers to the asset that is the price of a symbol.

ENUM definitions

Symbol status:

  • PRE_TRADING

  • TRADING

  • POST_TRADING

  • END_OF_DAY

  • HALT

  • AUCTION_MATCH

  • BREAK

Symbol type:

  • SPOT

Order status:

  • NEW

  • PARTIALLY_FILLED

  • FILLED

  • CANCELED

  • PENDING_CANCEL (currently unused)

  • REJECTED

  • EXPIRED

Order types:

  • LIMIT

  • MARKET

  • STOP_LOSS

  • STOP_LOSS_LIMIT

  • TAKE_PROFIT

  • TAKE_PROFIT_LIMIT

  • LIMIT_MAKER

Order side:

  • BUY

  • SELL

Time in force:

  • GTC

  • IOC

  • FOK

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)

  • REQUESTS_WEIGHT

  • ORDERS

Rate limit intervals

  • SECOND

  • MINUTE

  • DAY

General endpoints

Test connectivity

GET /api/v1/ping

Test connectivity to the Rest API.

Weight: 1

Parameters: NONE

Response:

{}

Check server time

GET /api/v1/time

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

Weight: 1

Parameters: NONE

Response:

{  "serverTime": 1499827319559}

Exchange information

GET /api/v1/exchangeInfo

Current exchange trading rules and symbol information

Weight: 1

Parameters: NONE

Response:

<pre style="box-sizi


  admin   2018-7-26

Remark: