跳到主要内容

基本信息

Rest 基本信息​

  • 接口可能需要用户的 API Key，如何创建API-KEY请参考这里
  • 本篇列出REST接口的baseurl https://eapi.binance.com
  • 所有接口的响应都是JSON格式
  • 响应中如有数组，数组元素以时间升序排列，越早的数据越提前。
  • 所有时间、时间戳均为UNIX时间，单位为毫秒

HTTP 返回代码​

  • HTTP 4XX 错误码用于指示错误的请求内容、行为、格式。
  • HTTP 403 错误码表示违反WAF限制(Web应用程序防火墙)。
  • HTTP 429 错误码表示警告访问频次超限，即将被封IP
  • HTTP 418 表示收到429后继续访问，于是被封了。
  • HTTP 5XX 错误码用于指示Binance服务侧的问题。
  • HTTP 503 表示三种可能：
    1. 如果返回内容里包含了报错信息 "Unknown error, please check your request or try again later."，则表示API服务端已经向业务核心提交了请求但未能获取响应，特别需要注意的是其不代表请求失败，而是未知。很可能已经得到了执行，也有可能执行失败，需要做进一步确认。
    2. 如果返回内容里包含了报错信息 "Service Unavailable."，则表示本次API请求失败。这种情况下可能是服务暂不可用，您需要稍后重试。
    3. 如果返回内容里包含了报错信息 "Internal error; unable to process your request. Please try again."，则表示本次API请求失败。这种情况下您如果需要的话可以选择立即重试。

接口错误代码​

  • 每个接口都有可能抛出异常

异常响应格式如下：

{
  "code": -1121,
  "msg": "Invalid symbol."
}

接口的基本信息​

  • GET方法的接口, 参数必须在query string中发送且HTTP头中不设置content type.
  • POST, PUT, 和 DELETE 方法的接口, 参数可以在 query string中发送，也可以在 request body中发送(content type application/x-www-form-urlencoded)。允许混合这两种方式发送参数。但如果同一个参数名在query string和request body中都有，query string中的会被优先采用。
  • 对参数的顺序不做要求。

访问限制​

  • 在 /eapi/v1/exchangeInfo接口中rateLimits数组里包含有REST接口(不限于本篇的REST接口)的访问限制。包括带权重的访问频次限制、下单速率限制。本篇枚举定义章节有限制类型的进一步说明。
  • 违反上述任何一个访问限制都会收到HTTP 429，这是一个警告.

IP 访问限制​

  • 每个请求将包含一个X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)的头，其中包含当前IP所有请求的已使用权重。
  • 每个路由都有一个"权重"，该权重确定每个接口计数的请求数。较重的接口和对多个交易对进行操作的接口将具有较重的"权重"。
  • 收到429时，您有责任作为API退回而不向其发送更多的请求。
  • 如果屡次违反速率限制和/或在收到429后未能退回，将导致API的IP被禁(http状态418)。
  • 频繁违反限制，封禁时间会逐渐延长 ，对于重复违反者，将会被封从2分钟到3天。
  • 访问限制是基于IP的，而不是API Key

下单频率限制​

  • 每个下单请求回报将包含一个X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)的头，其中包含当前账户已用的下单限制数量。
  • 被拒绝或不成功的下单并不保证回报中包含以上头内容。
  • 下单频率限制是基于每个账户计数的。

接口鉴权类型​

  • 每个接口都有自己的鉴权类型，鉴权类型决定了访问时应当进行何种鉴权
  • 如果需要 API-key，应当在HTTP头中以X-MBX-APIKEY字段传递
  • API-key 与 API-secret 是大小写敏感的
  • 可以在网页用户中心修改API-key 所具有的权限，例如读取账户信息、发送交易指令、发送提现指令
鉴权类型描述
NONE不需要鉴权的接口
TRADE需要有效的API-KEY和签名
USER_DATA需要有效的API-KEY和签名
USER_STREAM需要有效的API-KEY
MARKET_DATA需要有效的API-KEY

需要签名的接口 (TRADE 与 USER_DATA)​

  • 调用这些接口时，除了接口本身所需的参数外，还需要传递signature即签名参数。
  • 签名使用HMAC SHA256算法. API-KEY所对应的API-Secret作为 HMAC SHA256 的密钥，其他所有参数作为HMAC SHA256的操作对象，得到的输出即为签名。
  • 签名大小写不敏感。
  • 当同时使用query string和request body时，HMAC SHA256的输入query string在前，request body在后

时间同步安全​

  • 签名接口均需要传递timestamp参数, 其值应当是请求发送时刻的unix时间戳(毫秒)
  • 服务器收到请求时会判断请求中的时间戳，如果是5000毫秒之前发出的，则请求会被认为无效。这个时间窗口值可以通过发送可选参数recvWindow来自定义。
  • 另外，如果服务器计算得出客户端时间戳在服务器时间的‘未来’一秒以上，也会拒绝请求。

逻辑伪代码：

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

关于交易时效性 互联网状况并不100%可靠，不可完全依赖,因此你的程序本地到币安服务器的时延会有抖动. 这是我们设置recvWindow的目的所在，如果你从事高频交易，对交易时效性有较高的要求，可以灵活设置recvWindow以达到你的要求。

POST /eapi/v1/order 的示例​

以下是在linux bash环境下使用 echo openssl 和curl工具实现的一个调用接口下单的示例 apikey、secret仅供示范

KeyValue
apiKeydbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
secretKey2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9
参数取值
symbolBTC-210129-40000-C
sideBUY
typeLIMIT
timeInForceGTC
quantity1
price2000
recvWindow5000
timestamp1611825601400

示例 1: 所有参数通过 query string 发送​

示例1:

HMAC SHA256 签名:

    $ echo -n "symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&quantity=1&price=2000&timeInForce=GTC&recvWindow=5000&timestamp=1611825601400" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
    (stdin)= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9

curl 调用:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://eapi.binance.com/eapi/v1/order?symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000&timestamp=1611825601400&signature= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9'

  • queryString:

    symbol=BTC-210129-40000-C
    &side=BUY
    &type=LIMIT
    &timeInForce=GTC
    &quantity=1
    &price=2000 &recvWindow=5000
    &timestamp=1611825601400

示例 2: 所有参数通过 request body 发送​

示例2:

HMAC SHA256 签名:

    $ echo -n "symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000&timestamp=1611825601400" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
    (stdin)= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9

curl 调用:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://eapi.binance.com/eapi/v1/order' -d 'symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&quantity=1&price=9000&timeInForce=GTC&recvWindow=5000&timestamp=1611825601400&signature= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9'

  • requestBody:

    symbol=BTC-210129-40000-C
    &side=BUY
    &type=LIMIT
    &timeInForce=GTC
    &quantity=1
    &price=2000
    &recvWindow=5000
    &timestamp=1611825601400

示例 3: 混合使用 query string 与 request body​

示例3:

HMAC SHA256 签名:

    $ echo -n "symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&quantity=1&price=2000&timeInForce=GTC&recvWindow=5000&timestamp=1611825601400" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
    (stdin)= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9

curl 调用:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://eapi.binance.com/eapi/v1/order?symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=2000&recvWindow=5000&timestamp=1611825601400&signature=3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9'
  • queryString: symbol=BTC-210129-40000-C&side=BUY&type=LIMIT&timeInForce=GTC
  • requestBody: quantity=1&price=2000&recvWindow=5000&timestamp= 1611825601400

请注意，示例3中的签名有些许不同，在"GTC"和"quantity=1"之间没有"&"字符。