基本信息
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
表示三种可能:- 如果返回内容里包含了报错信息 "Unknown error, please check your request or try again later.",则表示API服务端已经向业务核心提交了请求但未能获取响应,特别需要注意的是其不代表请求失败,而是未知。很可能已经得到了执行,也有可能执行失败,需要做进一步确认。
- 如果返回内容里包含了报错信息 "Service Unavailable.",则表示本次API请求失败。这种情况下可能是服务暂不可用,您需要稍后重试。
- 如果返回内容里包含了报错信息 "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 typeapplication/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仅供示范
Key | Value |
---|---|
apiKey | dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83 |
secretKey | 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9 |
参数 | 取值 |
---|---|
symbol | BTC-210129-40000-C |
side | BUY |
type | LIMIT |
timeInForce | GTC |
quantity | 1 |
price | 2000 |
recvWindow | 5000 |
timestamp | 1611825601400 |
示例 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×tamp=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×tamp=1611825601400&signature= 3c661234138461fcc7a7d8746c6558c9842d4e10870d2ecbedf7777cad694af9'
-
queryString:
symbol=BTC-210129-40000-C
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=2000 &recvWindow=5000
×tamp=1611825601400