基本信息

SDK和代码示例

免责声明:

以下SDK由合作方和用户提供，非官方制作行为。仅做熟悉api接口和学习使用，请广大用户谨慎使用并根据自身情况自行拓展研发。
Binance 官方不对SDK的安全和性能做任何承诺，亦不会对使用SDK引起的风险甚至损失承担责任。

Python3

SDK: 可以通过以下方式获取Binance Futures Connector SDK：

访问 https://github.com/binance/binance-connector-python
执行以下命令：
pip install binance-sdk-derivatives-trading-usds-futures

Java

可以通过以下方式获取SDK：

访问 https://github.com/binance/binance-connector-java,
执行以下命令：
git clone https://github.com/binance/binance-connector-java.git

Rest 基本信息

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

testnet

本篇接口亦可接入testnet测试平台使用
testnet的 REST baseurl 为 "https://testnet.binancefuture.com"
testnet的 Websocket baseurl 为 "wss://fstream.binancefuture.com"

HTTP 返回代码

HTTP 4XX 错误码用于指示错误的请求内容、行为、格式。
HTTP 403 错误码表示违反WAF限制(Web应用程序防火墙)。
HTTP 408 返回代码表示在等待后端服务器响应时发生了超时。
HTTP 429 错误码表示警告访问频次超限，即将被封IP
HTTP 418 表示收到429后继续访问，于是被封了。
HTTP 5XX 错误码用于指示Binance服务侧的问题。
1. 如果返回内容里包含了报错信息 "Request occur unknown error."，请稍后重试请求。
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请求失败。这种情况下您如果需要的话可以选择立即重试。
4. 如果返回内容里包含了报错信息 "Server is currently overloaded with other requests. Please try again in a few minutes." (1008)。这表示节点已超出最大并发限制，正在临时限流。平仓、仅减仓与取消订单均予以豁免，不会触发该错误。

HTTP 503 状态码：错误类型与处理

A. “Unknown error, please check your request or try again later.”（执行状态未知）

语义：API 成功接收请求，但在超时前未返回结果；执行状态未知（可能已成功）。
处理：
- 不要直接当失败重试；先通过 WebSocket 回报或 orderId 查询确认是否已执行，避免重复下单。
- 高峰期尽量使用单笔下单替代批量下单以降低不确定性。
是否计入限速：可能计入，也可能不计入, 请参考header中的rate计数信息

B. “Service Unavailable.”（失败）

语义：服务暂不可用；100% 失败。
处理：退避重试（如 200ms → 400ms → 800ms，上限 3–5 次）。
是否计入限速：不计入

C. “Server is currently overloaded with other requests. Please try again in a few minutes.”（1008，失败）

语义：系统过载；100% 失败。
处理：退避重试并降低并发；
适用接口：
- POST /fapi/v1/order、PUT /fapi/v1/order
- POST /fapi/v1/batchOrders、PUT /fapi/v1/batchOrders
- POST /fapi/v1/order/test
仅适用于 C 的豁免说明：当请求满足只减仓/平仓条件时（closePosition = true，或 positionSide = BOTH 且 reduceOnly = true，或 LONG+SELL，或 SHORT+BUY），不会受 1008 过载的影响或享有优先处理，以保障风险收敛。
- 覆盖接口：POST /fapi/v1/order、PUT /fapi/v1/batchOrders（当参数满足只减仓/平仓判定）

接口错误代码

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

异常响应格式如下：

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

具体的错误码及其解释在错误代码

接口的基本信息

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

访问限制

在 /fapi/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的操作对象，得到的输出即为签名。
签名大小写不敏感。
请确保signature在query string或request body的最后
当同时使用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 /fapi/v1/order 的示例 - HMAC Keys

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

Key	Value
apiKey	dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83
secretKey	2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9

参数	取值
symbol	BTCUSDT
side	BUY
type	LIMIT
timeInForce	GTC
quantity	1
price	9000
recvWindow	5000
timestamp	1591702613943

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

示例1:

HMAC SHA256 签名:

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

curl 调用:

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

queryString:

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

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

示例2:

HMAC SHA256 签名:

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

curl 调用:

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

requestBody:

symbol=BTCUSDT
&side=BUY
&type=LIMIT
&timeInForce=GTC
&quantity=1
&price=9000
&recvWindow=5000
&timestamp=1591702613943

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

示例3:

HMAC SHA256 签名:

    $ echo -n "symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=9000&recvWindow=5000&timestamp= 1591702613943" | openssl dgst -sha256 -hmac "2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9"
    (stdin)= f9d0ae5e813ef6ccf15c2b5a434047a0181cb5a342b903b367ca6d27a66e36f2

curl 调用:

    (HMAC SHA256)
    $ curl -H "X-MBX-APIKEY: dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83" -X POST 'https://fapi.binance.com/fapi/v1/order?symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=9000&recvWindow=5000&timestamp=1591702613943&signature=f9d0ae5e813ef6ccf15c2b5a434047a0181cb5a342b903b367ca6d27a66e36f2'

queryString: symbol=BTCUSDT&side=BUY&type=LIMIT&timeInForce=GTC
requestBody: quantity=1&price=9000&recvWindow=5000&timestamp= 1591702613943

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

POST /fapi/v1/order 的示例 - RSA Keys

这将逐步介绍如何通过有效的签名发送 payload。
我们接受 PKCS#8 格式的 RSA Key。
要获取 API Key，您需要在您的账户上上传您的 RSA Public Key。

对于这个例子，Private Key 将被引用为test-prv-key.pem。

Key	Value
apiKey	vE3BDAL1gP1UaexugRLtteaAHg3UO8Nza20uexEuW1Kh3tVwQfFHdAiyjjY428o2

参数	取值
symbol	BTCUSDT
side	SELL
type	MARKET
quantity	1.23
recvWindow	9999999
timestamp	1671090801999

有列出参数的签名 payload：

timestamp=1671090801999&recvWindow=9999999&symbol=BTCUSDT&side=SELL&type=MARKET&quantity=1.23

第1步: Payload

将参数列表排列成一个 string。用 & 分隔每个参数。对于上述参数，签名 payload 如右所示。

第2步: 计算签名

2.1 - 将签名有效负载编码为 ASCII 数据。

第2.2步

 $ echo -n 'timestamp=1671090801999&recvWindow=9999999&symbol=BTCUSDT&side=SELL&type=MARKET&quantity=1.23' | openssl dgst -keyform PEM -sha256 -sign ./test-prv-key.pem

2.2 - 使用带有 SHA-256 hash 函数的 RSASSA-PKCS1-v1_5 算法对 payload 进行签名。

第2.3步

$ echo -n 'timestamp=1671090801999&recvWindow=9999999&symbol=BTCUSDT&side=SELL&type=MARKET&quantity=1.23' | openssl dgst -keyform PEM -sha256 -sign ./test-prv-key.pem | openssl enc -base64
aap36wD5loVXizxvvPI3wz9Cjqwmb3KVbxoym0XeWG1jZq8umqrnSk8H8dkLQeySjgVY91Ufs%2BBGCW%2B4sZjQEpgAfjM76riNxjlD3coGGEsPsT2lG39R%2F1q72zpDs8pYcQ4A692NgHO1zXcgScTGgdkjp%2Brp2bcddKjyz5XBrBM%3D

2.3 - 将输出编码为 base64 string。

第2.4步

$  echo -n 'timestamp=1671090801999&recvWindow=9999999&symbol=BTCUSDT&side=SELL&type=MARKET&quantity=1.23' | openssl dgst -keyform PEM -sha256 -sign ./test-prv-key.pem | openssl enc -base64 | tr -d '\n'
aap36wD5loVXizxvvPI3wz9Cjqwmb3KVbxoym0XeWG1jZq8umqrnSk8H8dkLQeySjgVY91Ufs%2BBGCW%2B4sZjQEpgAfjM76riNxjlD3coGGEsPsT2lG39R%2F1q72zpDs8pYcQ4A692NgHO1zXcgScTGgdkjp%2Brp2bcddKjyz5XBrBM%3D

2.4 - 删除签名中的所有 \n。

第2.5步

aap36wD5loVXizxvvPI3wz9Cjqwmb3KVbxoym0XeWG1jZq8umqrnSk8H8dkLQeySjgVY91Ufs%2BBGCW%2B4sZjQEpgAfjM76riNxjlD3coGGEsPsT2lG39R%2F1q72zpDs8pYcQ4A692NgHO1zXcgScTGgdkjp%2Brp2bcddKjyz5XBrBM%3D

2.5 - 由于签名可能包含 / 和 =，这可能会导致发送请求时出现问题。所以签名必须是 URL 编码的。

第2.6步

 curl -H "X-MBX-APIKEY: vE3BDAL1gP1UaexugRLtteaAHg3UO8Nza20uexEuW1Kh3tVwQfFHdAiyjjY428o2" -X POST 'https://fapi.binance.com/fapi/v1/order?timestamp=1671090801999&recvWindow=9999999&symbol=BTCUSDT&side=SELL&type=MARKET&quantity=1.23&signature=aap36wD5loVXizxvvPI3wz9Cjqwmb3KVbxoym0XeWG1jZq8umqrnSk8H8dkLQeySjgVY91Ufs%2BBGCW%2B4sZjQEpgAfjM76riNxjlD3coGGEsPsT2lG39R%2F1q72zpDs8pYcQ4A692NgHO1zXcgScTGgdkjp%2Brp2bcddKjyz5XBrBM%3D'

2.6 - curl 命令

Bash 脚本

#!/usr/bin/env bash
# 设置身份验证：
apiKey="vE3BDAL1gP1UaexugRLtteaAHg3UO8Nza20uexEuW1Kh3tVwQfFHdAiyjjY428o2"   ### 替换成您的 API Key
# 设置您的请求:
apiMethod="POST"
apiCall="v1/order"
apiParams="timestamp=1671090801999&recvWindow=9999999&symbol=BTCUSDT&side=SELL&type=MARKET&quantity=1.23"
function rawurlencode {
    local value="$1"
    local len=${#value}
    local encoded=""
    local pos c o
    for (( pos=0 ; pos<len ; pos++ ))
    do
        c=${value:$pos:1}
        case "$c" in
            [-_.~a-zA-Z0-9] ) o="${c}" ;;
            * )   printf -v o '%%%02x' "'$c"
        esac
        encoded+="$o"
    done
    echo "$encoded"
}
ts=$(date +%s000)
paramsWithTs="$apiParams&timestamp=$ts"
rawSignature=$(echo -n "$paramsWithTs" \
               | openssl dgst -keyform PEM -sha256 -sign ./test-prv-key.pem \  ### 替换成您的 Private Key。不要与任何人共享此文件。
               | openssl enc -base64 \
               | tr -d '\n')
signature=$(rawurlencode "$rawSignature")
curl -H "X-MBX-APIKEY: $apiKey" -X $apiMethod \
    "https://fapi.binance.com/fapi/$apiCall?$paramsWithTs&signature=$signature"

右边有示例 Bash 脚本执行上述类似的步骤.

WebSocket API基本信息

Base url为：'wss://ws-fapi.binance.com/ws-fapi/v1'
- 测试网的Base url为：wss://testnet.binancefuture.com/ws-fapi/v1
单次连接API有效期仅为24小时;预计在 24 小时标记后断开连接。
Websocket服务器每3分钟发送一个ping消息。
- 如果 websocket 服务器在10分钟内没有收到来自连接的pong frame，则连接将断开。
- 当客户收到ping消息，必需尽快回复pong消息，同时payload需要和ping消息一致。
- 未经请求的pong消息是被允许的，但是不会保证连接不断开。对于这些pong消息，建议payload为空。
必须通过获取除签名之外的所有请求参数并按字母顺序按名称排序来生成签名payload
除非另有说明，否则列表按时间顺序返回。
除非另有说明，否则所有时间戳均以 UTC 中的毫秒为单位。
除非另有说明，否则所有字段名称和值均区分大小写。
INT 参数（如时间戳）应为 JSON 整数，而不是字符串。
DECIMAL参数（如 price）应为 JSON 字符串，而不是浮点数。
用户数据流请求 - 您需要建立单独的WebSocket连接来获得 [账户信息推送]（https://binance-docs.github.io/apidocs/futures/cn/#websocket-2）

请求示例:

{
  "id": "9ca10e58-7452-467e-9454-f669bb9c764e",
  "method": "order.place",
  "params": {
    "apiKey": "yeqKcXjtA9Eu4Tr3nJk61UJAGzXsEmFqqfVterxpMpR4peNfqE7Zl7oans8Qj089",
    "price": "42088.0",
    "quantity": "0.1",
    "recvWindow": 5000,
    "side": "BUY",
    "signature": "996962a19802b5a09d7bc6ab1524227894533322a2f8a1f8934991689cabf8fe",
    "symbol": "BTCUSDT",
    "timeInForce": "GTC",
    "timestamp": 1705311512994,
    "type": "LIMIT"
  }
}

请求字段:

名称	类型	是否必需	描述
`id`	INT / STRING / `null`	YES	任意的 ID 用于匹配对请求的响应
`method`	STRING	YES	请求函数名称
`params`	OBJECT	NO	请求参数。如果没有参数可以省略

请求 id 是任意的。可以使用 UUID、顺次 ID、当前时间戳等。服务器不会以任何方式解释 id，只是在响应中回显它。

可以在一个会话中自由重复使用 ID，不过请注意不要一次发送多个具有相同 ID 的请求，因为否则可能无法区分响应。
请求函数名称可以以显式版本为前缀，例如："v3/order.place"
params 的顺序不重要。

WebSocket API响应格式

响应在 text 帧 中以 JSON 格式返回，每帧一个响应。

成功响应示例:

{
  "id": "43a3843a-2321-4e45-8f79-351e5c354563",
  "status": 200,
  "result": {
    "orderId": 336829446,
    "symbol": "BTCUSDT",
    "status": "NEW",
    "clientOrderId": "FqEw6cn0vDhrkmfiwLYPeo",
    "price": "42088.00",
    "avgPrice": "0.00",
    "origQty": "0.100",
    "executedQty": "0.000",
    "cumQty": "0.000",
    "cumQuote": "0.00000",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "reduceOnly": false,
    "closePosition": false,
    "side": "BUY",
    "positionSide": "BOTH",
    "stopPrice": "0.00",
    "workingType": "CONTRACT_PRICE",
    "priceProtect": false,
    "origType": "LIMIT",
    "priceMatch": "NONE",
    "selfTradePreventionMode": "NONE",
    "goodTillDate": 0,
    "updateTime": 1705385954229
  },
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 2400,
      "count": 1
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 10,
      "limit": 300,
      "count": 1
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 1200,
      "count": 0
    }
  ]
}

失败响应示例:

{
  "id": "5761b939-27b1-4948-ab87-4a372a3f6b72",
  "status": 400,
  "error": {
    "code": -1102,
    "msg": "Mandatory parameter 'quantity' was not sent, was empty/null, or malformed."
  },
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 2400,
      "count": 1
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 10,
      "limit": 300,
      "count": 1
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 1200,
      "count": 1
    }
  ]
}

响应字段:

名称	类型	是否必需	描述
`id`	INT / STRING / `null`	YES	与原来请求的ID一样
`status`	INT	YES	响应状态。请看状态代码
`result`	OBJECT / ARRAY	YES	响应内容。请求成功则显示
`error`	OBJECT	YES	错误描述。请求失败则显示
`rateLimits`	ARRAY	NO	速率限制状态。请看速率限制

WebSocket API访问限制

速率限制与 REST API 相同，并且与 REST API 共享。
WebSocket 握手尝试消耗权重5。
ping/pong 帧的速率限制：每秒最多5次。
默认情况下，响应中包含速率限制信息，参见 rateLimits 字段。
可以通过在连接字符串或单个请求中的 returnRateLimits 布尔参数来控制 rateLimits 字段的可见性。
例如，使用 wss://ws-fapi.binance.com/ws-fapi/v1?returnRateLimits=false 默认在响应中隐藏 rateLimits。在这样的情况下，您可以在请求中传递额外的 "returnRateLimits": true 参数，当默认隐藏时，就可以在响应中显示速率限制。

WebSocket API连接后进行身份验证

你可以使用会话身份验证请求对已经建立的连接进行身份验证：

session.logon – 进行身份验证，或更改与连接相关联的API密钥。
session.status – 检查连接状态和当前API密钥。
session.logout – 忘记与连接关联的API密钥。

WebSocket API关于吊销API密钥

如果在活动会话期间，由于任何原因（例如IP地址未被加入白名单、API密钥被删除、API密钥没有正确的权限等），在下一个请求后，会话将被吊销，并显示以下错误消息:

{
  "id": null,
  "status": 401,
  "error": {
    "code": -2015,
    "msg": "Invalid API-key, IP, or permissions for action." 
  }
}

WebSocket API授权临时请求

WebSocket连接只能通过一个API密钥进行身份验证。默认情况下，经过身份验证的API密钥将用于需要apiKey参数的请求。但是，你始终可以为单个请求明确指定apiKey和signature，覆盖已认证的API密钥，以使用不同的API密钥授权特定请求。

例如，你可能希望用默认密钥来验证 USER_DATA，但在下单时使用TRADE密钥来签名。

WebSocket API身份验证请求

注意： 仅支持 Ed25519 密钥用于此功能。

用API key登录 (SIGNED)

请求

{
  "id": "c174a2b1-3f51-4580-b200-8528bd237cb7",
  "method": "session.logon",
  "params": {
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
    "signature": "1cf54395b336b0a9727ef27d5d98987962bc47aca6e13fe978612d0adee066ed",
    "timestamp": 1649729878532
  }
}

响应:

{
  "id": "c174a2b1-3f51-4580-b200-8528bd237cb7",
  "status": 200,
  "result": {
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
    "authorizedSince": 1649729878532,
    "connectedSince": 1649729873021,
    "returnRateLimits": false,
    "serverTime": 1649729878630
  }
}

使用提供的API密钥进行WebSocket连接身份验证。

在调用session.logon后，将来的需要apiKey和signature参数的请求可以省略它们。

请注意，只能认证一个API密钥。多次调用session.logon将更改当前已认证的API密钥。

权重: 2

参数:

参数名	类型	是否必需	描述
`apiKey`	STRING	YES
`recvWindow`	INT	NO	The value cannot be greater than `60000`
`signature`	STRING	YES
`timestamp`	INT	YES

数据源: 缓存

查询会话状态

请求

{
  "id": "b50c16cd-62c9-4e29-89e4-37f10111f5bf",
  "method": "session.status"
}

响应:

{
  "id": "b50c16cd-62c9-4e29-89e4-37f10111f5bf",
  "status": 200,
  "result": {
    // 如果连接未经身份验证，"apiKey" 和 "authorizedSince" 将显示为 null。
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
    "authorizedSince": 1649729878532,
    "connectedSince": 1649729873021,
    "returnRateLimits": false,
    "serverTime": 1649730611671
  }
}

查询WebSocket连接的状态，检查用于授权请求的API密钥（如果有的话）。

权重: 2

参数: NONE

数据源: 缓存

退出会话

请求

{
  "id": "c174a2b1-3f51-4580-b200-8528bd237cb7",
  "method": "session.logout"
}

响应:

{
  "id": "c174a2b1-3f51-4580-b200-8528bd237cb7",
  "status": 200,
  "result": {
    "apiKey": null,
    "authorizedSince": null,
    "connectedSince": 1649729873021,
    "returnRateLimits": false,
    "serverTime": 1649730611671
  }
}

忘记之前认证的API密钥。如果连接未经身份验证，此请求不会有任何作用。

请注意，session.logout请求后，WebSocket连接仍然保持打开状态。你可以继续使用连接，但现在必须在需要的地方明确提供apiKey和signature参数。

权重: 2

参数: NONE

数据源: 缓存

SIGNED (TRADE and USER_DATA) 请求安全

SIGNED 请求示例 (Ed25519)

参数	取值
symbol	BTCUSDT
side	SELL
type	LIMIT
timeInForce	GTC
quantity	1
price	0.2
timestamp	1668481559918

#!/usr/bin/env python3
import base64
import time
import json
from cryptography.hazmat.primitives.serialization import load_pem_private_key
from websocket import create_connection
# 设置身份验证：
API_KEY='替换成您的 API Key'
PRIVATE_KEY_PATH='test-prv-key.pem'
# 加载 private key。
# 在这个例子中，private key 没有加密，但我们建议使用强密码以提高安全性。
with open(PRIVATE_KEY_PATH, 'rb') as f:
    private_key = load_pem_private_key(data=f.read(), password=None)
# 设置请求参数：
params = {
    'apiKey':        API_KEY,	
    'symbol':       'BTCUSDT',
    'side':         'SELL',
    'type':         'LIMIT',
    'timeInForce':  'GTC',
    'quantity':     '1.0000000',
    'price':        '0.20'
}
# 参数中加时间戳：
timestamp = int(time.time() * 1000) # 以毫秒为单位的 UNIX 时间戳
params['timestamp'] = timestamp
# 参数中加签名：
payload = '&'.join([f'{param}={value}' for param, value in sorted(params.items())])
signature = base64.b64encode(private_key.sign(payload.encode('ASCII')))
params['signature'] = signature.decode('ASCII')
# 发送请求：
request = {	
    'id': 'my_new_order',	
    'method': 'order.place',	
    'params': params
}
ws = create_connection('wss://ws-fapi.binance.com/ws-fapi/v1')	
ws.send(json.dumps(request))	
result =  ws.recv()	
ws.close()	
print(result)

右边有 Python 脚本来示例如何使用 Ed25519 key 签名。

基本信息

SDK和代码示例​

Python3​

Java​

Rest 基本信息​

testnet​

HTTP 返回代码​

HTTP 503 状态码：错误类型与处理​

A. “Unknown error, please check your request or try again later.”（执行状态未知）​

B. “Service Unavailable.”（失败）​

C. “Server is currently overloaded with other requests. Please try again in a few minutes.”（1008，失败）​

接口错误代码​

接口的基本信息​

访问限制​

IP 访问限制​

接口鉴权类型​

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

时间同步安全​

POST /fapi/v1/order 的示例 - HMAC Keys​

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

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

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

POST /fapi/v1/order 的示例 - RSA Keys​

WebSocket API基本信息​

WebSocket API响应格式​

WebSocket API访问限制​

WebSocket API连接后进行身份验证​

WebSocket API关于吊销API密钥​

WebSocket API授权 临时 请求​

WebSocket API身份验证请求​

用API key登录 (SIGNED)​

查询会话状态​

退出会话​

SIGNED (TRADE and USER_DATA) 请求安全​

SIGNED 请求示例 (Ed25519)​

SDK和代码示例

Python3

Java

Rest 基本信息

testnet

HTTP 返回代码

HTTP 503 状态码：错误类型与处理

A. “Unknown error, please check your request or try again later.”（执行状态未知）

B. “Service Unavailable.”（失败）

C. “Server is currently overloaded with other requests. Please try again in a few minutes.”（1008，失败）

接口错误代码

接口的基本信息

访问限制

IP 访问限制

接口鉴权类型

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

时间同步安全

POST /fapi/v1/order 的示例 - HMAC Keys

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

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

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

POST /fapi/v1/order 的示例 - RSA Keys

WebSocket API基本信息

WebSocket API响应格式

WebSocket API访问限制

WebSocket API连接后进行身份验证

WebSocket API关于吊销API密钥

WebSocket API授权临时请求

WebSocket API身份验证请求

用API key登录 (SIGNED)

查询会话状态

退出会话

SIGNED (TRADE and USER_DATA) 请求安全

SIGNED 请求示例 (Ed25519)