币安API基本信息

API 基本信息

  • 接口可能需要用户的 API Key,如何创建API-KEY请参考这里

  • 本篇列出接口的baseurl: https://api.binance.com

  • 所有接口的响应都是 JSON 格式。

  • 响应中如有数组,数组元素以时间升序排列,越早的数据越提前。

  • 所有时间、时间戳均为UNIX时间,单位为毫秒

HTTP 返回代码

  • HTTP 4XX 错误码用于指示错误的请求内容、行为、格式。问题在于请求者。

  • HTTP 403 错误码表示违反WAF限制(Web应用程序防火墙)。

  • HTTP 429 错误码表示警告访问频次超限,即将被封IP。

  • HTTP 418 表示收到429后继续访问,于是被封了。

  • HTTP 5XX 错误码用于指示Binance服务侧的问题。
    使用接口 /wapi/v3 时, HTTP 504 表示API服务端已经向业务核心提交了请求但未能获取响应,特别需要注意的是504代码不代表请求失败,而是未知。很可能已经得到了执行,也有可能执行失败,需要做进一步确认。

错误代码

  • 使用接口 /api/v3, 以及 /sapi/v1/margin时, 每个接口都有可能抛出异常;

API 与 SAPI 的错误代码返回形式如下:

{
  "code": -1121,
  "msg": "Invalid symbol."}
  • 当使用/wapi/v3, 任何接口都可能返回错误;

WAPI 的错误代码返回形式如下:

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

接口的基本信息

  • GET 方法的接口, 参数必须在 query string中发送。

  • POSTPUT, 和 DELETE 方法的接口,参数可以在内容形式为application/x-www-form-urlencoded的 query string 中发送,也可以在 request body 中发送。 如果你喜欢,也可以混合这两种方式发送参数。

  • 对参数的顺序不做要求。

  • 但如果同一个参数名在query string和request body中都有,query string中的会被优先采用。


访问限制

访问限制基本信息

  • 以下 是intervalLetter 作为头部值:

    • SECOND => S

    • MINUTE => M

    • HOUR => H

    • DAY => D

  • 在/api/v3/exchangeInfo`rateLimits数组中包含与交易的有关RAW_REQUEST,REQUEST_WEIGHT和ORDER速率限制相关的对象。这些在"Rate limiters(rateLimitType)"下的"ENUM definitions"部分中进一步定义。

  • 违反任何一个速率限制时,将返回429。

IP 访问限制

  • 每个请求将包含一个X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter)的头,其中包含当前IP所有请求的已使用权重。

  • 每个路由都有一个"权重",该权重确定每个接口计数的请求数。较重的接口和对多个交易对进行操作的接口将具有较重的"权重"。

  • 收到429时,您有责任作为API退回而不向其发送更多的请求。

  • 如果屡次违反速率限制和/或在收到429后未能退回,将导致API的IP被禁(http状态418)。

  • 频繁违反限制,封禁时间会逐渐延长 ,对于重复违反者,将会被封从2分钟到3天

  • Retry-After的头会与带有418或429的响应发送,并且会给出以秒为单位的等待时长(如果是429)以防止禁令,或者如果是418,直到禁令结束。

  • 访问限制是基于IP的,而不是API Key

下单频率限制

  • 每个成功的下单回报将包含一个X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter)的头,其中包含当前账户已用的下单限制数量。

  • 被拒绝或不成功的下单并不保证回报中包含以上头内容。

  • 下单频率限制是基于每个账户计数的。

WEB SOCKET 连接限制

  • Websocket服务器每秒最多接受5个消息。消息包括:

    • PING帧

    • PONG帧

    • JSON格式的消息, 比如订阅, 断开订阅.

  • 如果用户发送的消息超过限制,连接会被断开连接。反复被断开连接的IP有可能被服务器屏蔽。

  • 单个连接最多可以订阅 1024 个Streams。


接口鉴权类型

  • 每个接口都有自己的鉴权类型,鉴权类型决定了访问时应当进行何种鉴权。

  • 鉴权类型会在本文档中各个接口名称旁声明,如果没有特殊声明即默认为 NONE

  • 如果需要 API-keys,应当在HTTP头中以 X-MBX-APIKEY字段传递。

  • API-keys 与 secret-keys 是大小写敏感的

  • API-keys可以被配置为只拥有访问一些接口的权限。 例如, 一个 API-key 仅可用于发送交易指令, 而另一个 API-key 则可访问除交易指令外的所有路径。

  • 默认 API-keys 可访问所有鉴权路径.

鉴权类型描述
NONE不需要鉴权的接口
TRADE需要有效的 API-Key 和签名
USER_DATA需要有效的 API-Key 和签名
USER_STREAM需要有效的 API-Key
MARKET_DATA需要有效的 API-Key
  • TRADEMARGIN 和USER_DATA 接口是 签名(SIGNED)接口.


SIGNED (TRADE、USER_DATA AND MARGIN) Endpoint security

  • 调用SIGNED 接口时,除了接口本身所需的参数外,还需要在query string 或 request body中传递 signature, 即签名参数。

  • 签名使用HMAC SHA256算法. API-KEY所对应的API-Secret作为 HMAC SHA256 的密钥,其他所有参数作为HMAC SHA256的操作对象,得到的输出即为签名。

  • 签名 大小写不敏感.

  • "totalParams"定义为与"request body"串联的"query string"。

时间同步安全

  • 签名接口均需要传递 timestamp参数,其值应当是请求发送时刻的unix时间戳(毫秒)。

  • 服务器收到请求时会判断请求中的时间戳,如果是5000毫秒之前发出的,则请求会被认为无效。这个时间空窗值可以通过发送可选参数 recvWindow来定义。

逻辑伪代码如下:

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

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

POST /api/v3/order 的示例

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

KeyValue
apiKeyvmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKeyNhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
参数取值
symbolLTCBTC
sideBUY
typeLIMIT
timeInForceGTC
quantity1
price0.1
recvWindow5000
timestamp1499827319559

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

Example 1

HMAC SHA256 signature:

    $ 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)
    $ 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'
  • requestBody:

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

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

Example 2

HMAC SHA256 signature:

    $ 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)
   $ 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'
  • queryString:

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

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

Example 3

HMAC SHA256 signature: