Spot Trading

WebSocket API 基本信息

本篇所列出的 wss 接口的 base URL：wss://ws-api.binance.com:443/ws-api/v3
- 如果使用标准443端口时遇到问题，可以使用替代端口9443。
- 现货测试网的 base URL 是 wss://ws-api.testnet.binance.vision/ws-api/v3。
每个到 base URL 的链接有效期不超过24小时，请妥善处理断线重连。
当服务器即将关闭时，系统将发送 serverShutdown 事件，并导致连接断开。请尽快建立新连接，以防止中断。
我们支持 HMAC，RSA 以及 Ed25519 Key 类型。如需进一步了解，请参考 API Key 类型。
响应默认为 JSON 格式。如果您想接收 SBE 格式的响应，请参考简单二进制编码（SBE）常见问题。
如果您的请求包含非 ASCII 字符的交易对名称，那么响应中可能包含以 UTF-8 编码的非 ASCII 字符。
即使请求本身不包含非 ASCII 字符，某些方法也可能会返回包含以 UTF-8 编码的非 ASCII 字符的资产和/或交易对名称。
WebSocket 服务器每20秒发送 PING 消息。
- 如果websocket 服务器没有在一分钟之内收到PONG 消息应答，连接会被断开。
- 当客户收到PING消息，必须尽快回复PONG消息，同时payload需要和PING消息一致。
- 服务器允许未经请求的PONG消息，但这不会保证连接不断开。对于这些PONG 消息，建议payload为空。
除非另有说明，否则数据将按时间顺序返回。
- 如果未指定 startTime 或 endTime，则返回最近的条目，直至达到限制值。
- 如果指定 startTime，则返回从 startTime 到限制值为止最老的条目。
- 如果指定 endTime，则返回截至 endTime 和限制值为止最近的条目。
- 如果同时指定 startTime 和 endTime，则行为类似于 startTime，但不超过 endTime。
JSON 响应中的所有时间和时间戳相关字段均以UTC 毫秒为默认单位。要以微秒为单位接收信息，请在 URL 中添加参数 timeUnit=MICROSECOND 或 timeUnit=microsecond。
时间戳参数（例如 startTime、endTime、timestamp）可以以毫秒或微秒为单位传递。
除非另有说明，所有字段名称和值都大小写敏感。
如需进一步了解枚举或术语，请参考现货交易API术语表页面。
API 处理请求的超时时间为 10 秒。如果撮合引擎的响应时间超过此时间，API 将返回 “Timeout waiting for response from backend server. Send status unknown; execution status unknown.”。(-1007 超时)
- 这并不总是意味着该请求在撮合引擎中失败。
- 如果请求状态未显示在用户数据流中，请执行 API 查询以获取其状态。
请避免在请求中使用 SQL 关键字，因为这可能会触发 Web 应用防火墙（WAF）规则导致安全拦截。详情请参见 https://www.binance.com/zh-CN/support/faq/detail/360004492232

请求格式

请求必须在 text 帧 中以 JSON 格式发送，每帧一个请求。

请求示例:


Code
{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "LIMIT",
    "price": "0.1",
    "quantity": "10",
    "timeInForce": "GTC",
    "timestamp": 1655716096498,
    "apiKey": "T59MTDLWlpRW16JVeZ2Nju5A5C98WkMm8CSzWC4oqynUlTm1zXOxyauT8LmwXEv9",
    "signature": "5942ad337e6779f2f4c62cd1c26dba71c91514400a24990a3e7f5edec9323f90"
  }
}

请求字段:

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

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

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

响应格式

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

成功响应示例:


Code
{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "status": 200,
  "result": {
    "symbol": "BTCUSDT",
    "orderId": 12510053279,
    "orderListId": -1,
    "clientOrderId": "a097fe6304b20a7e4fc436",
    "transactTime": 1655716096505,
    "price": "0.10000000",
    "origQty": "10.00000000",
    "executedQty": "0.00000000",
    "origQuoteOrderQty": "0.000000",
    "cummulativeQuoteQty": "0.00000000",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "workingTime": 1655716096505,
    "selfTradePreventionMode": "NONE"
  },
  "rateLimits": [
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 10,
      "limit": 50,
      "count": 12
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "intervalNum": 1,
      "limit": 160000,
      "count": 4043
    },
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 321
    }
  ]
}

失败响应示例:


Code
{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "status": 400,
  "error": {
    "code": -2010,
    "msg": "Account has insufficient balance for requested action."
  },
  "rateLimits": [
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 10,
      "limit": 50,
      "count": 13
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "intervalNum": 1,
      "limit": 160000,
      "count": 4044
    },
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 322
    }
  ]
}

响应字段:

状态代码

status 字段的状态代码与HTTP的状态代码相同。

一些常见状态代码：

200 代码指示成功响应。
4XX 错误码用于指示错误的请求内容、行为、格式。问题在于请求者。
- 400 – 错误码表示请求失败，请参阅 error 了解原因。
- 403 – 错误码表示违反 WAF 限制(Web应用程序防火墙)。这可能表示触发了速率限制或安全拦截。详情请参见 https://www.binance.com/zh-CN/support/faq/detail/360004492232 。
- 409 – 错误码表示请求有一部分成功，一部分失败。请参阅 error 了解更多详细
- 418 – 表示收到 429 后继续访问，于是被封了。
- 429 – 错误码表示警告访问频次超限，即将被封IP。
5XX 错误码用于指示Binance服务侧的问题。
- 重要：如果响应包含 5xx 状态码，并不一定意思请求失败。执行状态为 unknown，请求可能实际成功。请使用 query 函数确认状态。建议建立一个新 WebSocket 连接用于确认状态。

有关错误代码和消息的列表，请参阅 Binance 的错误代码。

事件格式

用户数据流中的非 SBE 会话事件以 JSON 格式在 text 帧 中发送，每帧一个事件。

SBE 会话中的事件将作为 二进制帧 发送。

有关如何在 WebSocket API 中订阅用户数据流的详细信息，请参阅 订阅用户数据流。

事件示例:


Code
{
    "subscriptionId": 0,
    "event": {
        "e": "outboundAccountPosition",
        "E": 1728972148778,
        "u": 1728972148778,
        "B": [
            {
                "a": "BTC",
                "f": "11818.00000000",
                "l": "182.00000000"
            },
            {
                "a": "USDT",
                "f": "10580.00000000",
                "l": "70.00000000"
            }
        ]
    }
}

事件字段:

名称	类型	是否必须	描述
`event`	OBJECT	YES	事件 payload。请看用户数据流
`subscriptionId`	INT	NO	用以标识事件来自于哪个订阅。详见用户数据流订阅

连接事件

服务器关闭

当服务器即将关闭时，会发送 serverShutdown 事件。


Code
{
  "event": {
    "e": "serverShutdown", // 事件类型
    "E": 1770123456789     // 事件时间
   }
}

请尽快建立新连接，以防中断

速率限制

连接数量限制

每IP地址、每5分钟最多可以发送300次连接请求。

速率限制基本信息

exchangeInfo 有包含与速率限制相关的信息。
根据不同的间隔，有多种频率限制类型。
从响应中的可选 rateLimits 字段，能看到当前的频率限制状态。
当您超出未成交订单计数或者请求速率限制时，请求会失败并返回 HTTP 状态代码 429。

如何咨询频率限制

频率限制状态的响应可能如下所示：


Code
{
  "id": "7069b743-f477-4ae3-81db-db9b8df085d2",
  "status": 200,
  "result": {
    "serverTime": 1656400526260
  },
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 70
    }
  ]
}

rate Limits 数组描述了受请求影响的所有当前的速率限制。

名称	类型	是否必须	描述
`rateLimitType`	ENUM	YES	频率限制类型: `REQUEST_WEIGHT`, `ORDERS`
`interval`	ENUM	YES	频率限制间隔: `SECOND`, `MINUTE`, `HOUR`, `DAY`
`intervalNum`	INT	YES	频率限制间隔乘数
`limit`	INT	YES	每个间隔的请求限制
`count`	INT	YES	每个间隔的当前使用情况

频率限制按间隔计算。

例如，1 MINUTE 间隔表示每分钟开始。在 00:01:23.456 提交的请求计入 00:01:00 分钟的限制。一旦 00:02:00 分钟开始，计数将再次重置为零。

其他间隔的行为方式类似。例如，1 DAY 频率限制是在每天 00:00 UTC 重置，并且 10 SECOND 间隔重置为每分钟的 00、10、20...秒。

API 有多种频率限制间隔。如果您用完了较短的间隔但较长的间隔仍然允许请求，您将不得不等待较短的间隔到期并重置。如果你用完了更长的间隔，你将不得不等待那个间隔重置，即使较短的频率限制计数为零。

如何显示/隐藏频率限制信息

默认情况下，每个响应都包含 rateLimits 字段。

但是，频率限制信息可能非常大。如果您对每个请求的详细频率限制状态不感兴趣，可以从响应中省略 rateLimits 字段。

请求中的可选 returnRateLimits boolean 参数。

使用 returnRateLimits 参数控制是否包含 rateLimits 字段以响应单个请求。

默认请求和响应：


Code
{ "id": 1, "method": "time" }


Code
{
  "id": 1,
  "status": 200,
  "result": { "serverTime": 1656400526260 },
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 70
    }
  ]
}

没有频率限制状态的请求和响应：


Code
{ "id": 2, "method": "time", "params": { "returnRateLimits": false } }


Code
{ "id": 2, "status": 200, "result": { "serverTime": 1656400527891 } }

连接 URL 中可选的 returnRateLimits boolean 参数。

如果您希望在默认情况下从所有响应中省略 rateLimits，可以在 query string 中使用 returnRateLimits 参数：
```
Code
wss://ws-api.binance.com:443/ws-api/v3?returnRateLimits=false
```
这将使通过此连接发出的所有请求的行为就像您已传了 "returnRateLimits"：false 一样。

如果您想查看特定请求的频率限制，您需要特定传 "returnRateLimits"：true 参数。

注意: 如果您在响应中隐藏 rateLimits 字段，您的请求仍然还是会受到频率限制的。

IP 访问限制

每个请求都有一个特定的权重，它会添加到您的访问限制中。
- 越消耗资源的接口, 比如查询多个交易对, 权重就会越大。
- 连接到 WebSocket API 会用到2个权重。
当前权重使用由 REQUEST_WEIGHT 频率限制类型指示。
请使用exchangeInfo请求来跟踪当前的重量限制。
权重是基于每个 IP 地址累积的，并由来自该地址的所有连接共享。
如果超多限制，客服端会收到 429。
- 这错误代码表示您有责任停止发送请求，不得滥用API。
- 响应会包含一个 retryAfter 字段，指示在什么时候您能重试。
屡次违反速率限制或者在收到429后未能退缩将导致自动 IP 封禁和断开连接。
- 被禁止 IP 地址的请求失败，状态为 418。
- retryAfter 字段表示解除禁令的timestamp。
频繁违反限制的封禁时间会逐渐延长，从最短2分钟到最长3天。

表示在1分钟内使用了（1200权重限制中的）70权重的成功响应：


Code
{
  "id": "7069b743-f477-4ae3-81db-db9b8df085d2",
  "status": 200,
  "result": [],
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 70
    }
  ]
}

表示已被封禁且封禁将在 epoch 1659146400000 解锁的失败响应：


Code
{
  "id": "fc93a61a-a192-4cf4-bb2a-a8f0f0c51e06",
  "status": 418,
  "error": {
    "code": -1003,
    "msg": "Way too much request weight used; IP banned until 1659146400000. Please use WebSocket Streams for live updates to avoid bans.",
    "data": {
      "serverTime": 1659142907531,
      "retryAfter": 1659146400000
    }
  },
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 2411
    }
  ]
}

未成交订单计数

成功下单将更新 订单 速率限制类型。
被拒绝或不成功的订单可能会也可能不会更新 订单 速率限制类型。
请注意，如果您的订单一直顺利完成交易，您可以通过 API 持续下订单。更多信息，请参见现货未成交订单计数规则。
使用 account.rateLimits.orders 请求来跟踪您在此时间间隔内下了多少订单。
如果超过此值，请求将失败，状态为 429。
- 此状态代码表示您应退出并停止向 API 滥发信息。
- 状态为 429 的响应会包含 retryAfter 字段，用以指示何时可以重试请求。
这是按 每一个账户 维护的，并由该账户的所有 API 密钥共享。

表示在10秒内下了12个订单和在24小时内下了4043个订单的成功响应：


Code
{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "status": 200,
  "result": {
    "symbol": "BTCUSDT",
    "orderId": 12510053279,
    "orderListId": -1,
    "clientOrderId": "a097fe6304b20a7e4fc436",
    "transactTime": 1655716096505,
    "price": "0.10000000",
    "origQty": "10.00000000",
    "executedQty": "0.00000000",
    "origQuoteOrderQty": "0.000000",
    "cummulativeQuoteQty": "0.00000000",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "workingTime": 1655716096505,
    "selfTradePreventionMode": "NONE"
  },
  "rateLimits": [
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 10,
      "limit": 50,
      "count": 12
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "intervalNum": 1,
      "limit": 160000,
      "count": 4043
    },
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 321
    }
  ]
}

请求鉴权类型

每个方法都有一个鉴权类型，指示所需的 API 密钥权限，显示在方法名称旁边（例如，下新订单 (TRADE)）。
如果未指定，则鉴权类型为 NONE。
除了为 NONE 外，所有具有鉴权类型的方法均视为 SIGNED 请求（即包含 signature），listenKey 管理除外。
具有鉴权类型的方法需要提供有效的 API 密钥并验证通过。
- API 密钥可在您的 Binance 账户的 API 管理页面创建。
- API 密钥和密钥对均为敏感信息，切勿与他人分享。 如果发现账户有异常活动，请立即撤销所有密钥并联系 Binance 支持。
API 密钥可配置为仅允许访问某些鉴权类型。
- 例如，您可以拥有具有 TRADE 权限的 API 密钥用于交易，同时使用具有 USER_DATA 权限的另一个 API 密钥来监控订单状态。
- 默认情况下，API 密钥无法进行 TRADE，您需要先在 API 管理中启用交易权限。

鉴权类型	描述
`NONE`	公开市场数据
`TRADE`	在交易所交易，下单和取消订单
`USER_DATA`	私人账户信息，例如订单状态和交易历史
`USER_STREAM`	管理用户数据流订阅

需要签名的请求

为了授权请求，SIGNED 请求必须带 signature 参数。

签名区分大小写

HMAC： 使用 HMAC 生成的签名不区分大小写。这意味着无论字母大小写如何，签名字符串都可以被验证。
RSA： 使用 RSA 生成的签名区分大小写。
Ed25519： 使用 Ed25519 生成的签名也区分大小写。

时间同步安全

SIGNED 请求还需要一个 timestamp 参数，该参数应为当前时间戳，单位为毫秒或微秒。（参见通用 API 信息）
另一个可选参数 recvWindow，用以指定请求的有效期，只能以毫秒为单位。
- recvWindow 扩展为三位小数（例如 6000.346），以便可以指定微秒。
- 如果未发送 recvWindow，则 默认为 5000 毫秒。
- recvWindow 的最大值为 60000 毫秒。
请求处理逻辑如下：


Code
serverTime = getCurrentTime()
if (timestamp < (serverTime + 1 second) && (serverTime - timestamp) <= recvWindow) {
  // 开始处理请求
  serverTime = getCurrentTime()
  if (serverTime - timestamp) <= recvWindow {
    // 将请求转发到撮合引擎
  } else {
    // 拒绝请求
  }
  // 结束处理请求
} else {
  // 拒绝请求
}

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

建议使用5000毫秒以下的 recvWindow！

SIGNED 请求示例 (HMAC)

这是有关如何用一个 HMAC secret key 签署请求的分步指南。

示例 API key 和 secret key：

Key	Value
`apiKey`	`vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A`
`secretKey`	`NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j`

警告：请勿与任何人分享您的 API 密钥和秘钥。

此处提供的示例密钥仅用于示范说明目的。

交易对名称完全由 ASCII 字符组成的请求示例：

请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "newOrderRespType": "ACK",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
    "signature": "------ 未填写 ------"
  }
}

交易对名称包含非 ASCII 字符的请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO",
    "signature": "------ FILL ME ------"
  }
}

第一步：创建签名内容

除了 signature 之外，获取所有请求 params，然后按参数名称的字母顺序对它们进行排序：

对于第一组示例参数（仅限 ASCII 字符）：

参数	取值
`apiKey`	vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
`price`	52000.00
`quantity`	0.01000000
`recvWindow`	100
`side`	SELL
`symbol`	BTCUSDT
`timeInForce`	GTC
`timestamp`	1645423376532
`type`	LIMIT

对于第二组示例参数（包含一些 Unicode 字符）：

参数	取值
`apiKey`	vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
`price`	0.10000000
`quantity`	1.00000000
`recvWindow`	5000
`side`	BUY
`symbol`	１２３４５６
`timeInForce`	GTC
`timestamp`	1645423376532
`type`	LIMIT

将参数格式化为 参数=取值 对并用 & 分隔每个参数对。数值需要采用 UTF-8 编码。

对于第一组示例参数（仅限 ASCII 字符），签名有效负载将如下所示：

Code
apiKey=vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

对于第二组示例参数（包含一些 Unicode 字符），签名有效负载将如下所示：

Code
apiKey=vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

第二步：计算签名

使用 API 密钥中的 secretKey 作为 HMAC-SHA-256 算法的签名密钥。
对步骤 1 中构建的签名 payload 进行签名。
将 HMAC-SHA-256 的输出编码为十六进制字符串。

请注意，apiKey、secretKey 和有效负载是大小写敏感的。而生成的签名值是不区分大小写的。

可以使用 OpenSSL 交叉检查您的签名算法实现：

对于第一组示例参数（仅限 ASCII 字符）：

Code
$ echo -n 'apiKey=vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT' \
  | openssl dgst -hex -sha256 -hmac 'NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j'

aa1b5712c094bc4e57c05a1a5c1fd8d88dcd628338ea863fec7b88e59fe2db24

对于第二组示例参数（包含一些 Unicode 字符）：

Code
$ echo -n 'apiKey=vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT' \
  | openssl dgst -hex -sha256 -hmac 'NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j'

b33892ae8e687c939f4468c6268ddd4c40ac1af18ad19a064864c47bae0752cd

第三步：添加 signature 到 params 中

通过在对请求中添加 signature 参数和签名字串来完成请求。

对于第一组示例参数（仅限 ASCII 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
    "signature": "aa1b5712c094bc4e57c05a1a5c1fd8d88dcd628338ea863fec7b88e59fe2db24"
  }
}

对于第二组示例参数（包含一些 Unicode 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "1.00000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
    "signature": "b33892ae8e687c939f4468c6268ddd4c40ac1af18ad19a064864c47bae0752cd"
  }
}

SIGNED 请求示例 (RSA)

这是有关如何用一个 RSA private key 签署请求的分步指南。

Key	Value
`apiKey`	`CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ`

这些示例假设私钥存储在文件 test-prv-key.pem 中。

警告：请勿与任何人分享您的 API 密钥和私钥。

此处提供的示例密钥仅用于示范说明目的。

交易对名称完全由 ASCII 字符组成的请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ",
    "signature": "------ FILL ME ------"
  }
}

交易对名称包含非 ASCII 字符的请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ",
    "signature": "------ FILL ME ------"
  }
}

第一步：创建签名内容

除了 signature，获取请求的所有其它 params，然后按参数名称的字母顺序对它们进行排序：

对于第一组示例参数（仅限 ASCII 字符）：

参数	取值
`apiKey`	CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ
`price`	52000.00
`quantity`	0.01000000
`recvWindow`	100
`side`	SELL
`symbol`	BTCUSDT
`timeInForce`	GTC
`timestamp`	1645423376532
`type`	LIMIT

对于第二组示例参数（包含一些 Unicode 字符）：

参数	取值
`apiKey`	CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ
`price`	0.10000000
`quantity`	1.00000000
`recvWindow`	5000
`side`	BUY
`symbol`	１２３４５６
`timeInForce`	GTC
`timestamp`	1645423376532
`type`	LIMIT

将参数格式化为 参数=取值 对并用 & 分隔每个参数对。数值需要采用 UTF-8 编码。

对于第一组示例参数（仅限 ASCII 字符），签名有效负载将如下所示：

Code
apiKey=CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

对于第二组示例参数（包含一些 Unicode 字符），签名有效负载将如下所示：

Code
apiKey=CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

第二步：计算签名

使用 RSASSA-PKCS1-v1_5 算法和 SHA-256 哈希函数对步骤 1 中构造的签名有效载荷的 UTF-8 字节进行签名。
将输出编码为 base64。

请注意，apiKey, payload 和生成的签名值都是大小写敏感的。

您可以使用 OpenSSL 交叉检查您的签名算法：

对于第一组示例参数（仅限 ASCII 字符）：

Code
$ echo -n 'apiKey=CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT' \
  | openssl dgst -sha256 -sign test-rsa-prv.pem \
  | openssl enc -base64 -A

OJJaf8C/3VGrU4ATTR4GiUDqL2FboSE1Qw7UnnoYNfXTXHubIl1iaePGuGyfct4NPu5oVEZCH4Q6ZStfB1w4ssgu0uiB/Bg+fBrRFfVgVaLKBdYHMvT+ljUJzqVaeoThG9oXlduiw8PbS9U8DYAbDvWN3jqZLo4Z2YJbyovyDAvDTr/oC0+vssLqP7NmlNb3fF3Bj7StmOwJvQJTbRAtzxK5PP7OQe+0mbW+D7RqVkUiSswR8qJFWTeSe4nXXNIdZdueYhF/Xf25L+KitJS5IHdIHcKfEw3MQzHFb2ZsGWkjDQwxkwr7Noi0Zaa+gFtxCuatGFm9dFIyx217pmSHtA==

对于第二组示例参数（包含一些 Unicode 字符）：

Code
$ echo -n 'apiKey=CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT' \
  | openssl dgst -sha256 -sign test-rsa-prv.pem \
  | openssl enc -base64 -A

F3o/79Ttvl2cVYGPfBOF3oEOcm5QcYmTYWpdVIrKve5u+8paMNDAdUE+teqMxFM9HcquetGcfuFpLYtsQames5bDx/tskGM76TWW8HaM+6tuSYBSFLrKqChfA9hQGLYGjAiflf1YBnDhY+7vNbJFusUborNOloOj+ufzP5q42PvI3H0uNy3W5V3pyfXpDGCBtfCYYr9NAqA4d+AQfyllL/zkO9h9JSdozN49t0/hWGoD2dWgSO0Je6MytKEvD4DQXGeqNlBTB6tUXcWnRW+FcaKZ4KYqnxCtb1u8rFXUYgFykr2CbcJLSmw6ydEJ3EZ/NaZopRr+cU0W2m0HZ3qucw==

第三步：在请求的 params 参数添加签名值

通过在对请求中添加 signature 参数和签名字串来完成请求。

对于第一组示例参数（仅限 ASCII 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "newOrderRespType": "ACK",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ",
    "signature": "OJJaf8C/3VGrU4ATTR4GiUDqL2FboSE1Qw7UnnoYNfXTXHubIl1iaePGuGyfct4NPu5oVEZCH4Q6ZStfB1w4ssgu0uiB/Bg+fBrRFfVgVaLKBdYHMvT+ljUJzqVaeoThG9oXlduiw8PbS9U8DYAbDvWN3jqZLo4Z2YJbyovyDAvDTr/oC0+vssLqP7NmlNb3fF3Bj7StmOwJvQJTbRAtzxK5PP7OQe+0mbW+D7RqVkUiSswR8qJFWTeSe4nXXNIdZdueYhF/Xf25L+KitJS5IHdIHcKfEw3MQzHFb2ZsGWkjDQwxkwr7Noi0Zaa+gFtxCuatGFm9dFIyx217pmSHtA=="
  }
}

对于第二组示例参数（包含一些 Unicode 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "1.00000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ",
    "signature": "F3o/79Ttvl2cVYGPfBOF3oEOcm5QcYmTYWpdVIrKve5u+8paMNDAdUE+teqMxFM9HcquetGcfuFpLYtsQames5bDx/tskGM76TWW8HaM+6tuSYBSFLrKqChfA9hQGLYGjAiflf1YBnDhY+7vNbJFusUborNOloOj+ufzP5q42PvI3H0uNy3W5V3pyfXpDGCBtfCYYr9NAqA4d+AQfyllL/zkO9h9JSdozN49t0/hWGoD2dWgSO0Je6MytKEvD4DQXGeqNlBTB6tUXcWnRW+FcaKZ4KYqnxCtb1u8rFXUYgFykr2CbcJLSmw6ydEJ3EZ/NaZopRr+cU0W2m0HZ3qucw=="
  }
}

SIGNED 请求示例 (Ed25519)

我们强烈建议使用 Ed25519 API keys，因为它在所有受支持的 API key 类型中提供最佳性能和安全性。

这是有关如何用一个 Ed25519 private key 签署请求的分步指南。

Key	Value
`apiKey`	`4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO`

这些示例假设私钥存储在文件 test-ed25519-prv.pem 中。

警告：请勿与任何人分享您的 API 密钥和私钥。

此处提供的示例密钥仅用于示范说明目的。

交易对名称完全由 ASCII 字符组成的请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO",
    "signature": "------ FILL ME ------"
  }
}

交易对名称包含非 ASCII 字符的请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO",
    "signature": "------ FILL ME ------"
  }
}

第一步：创建签名内容

除了 signature，获取请求的所有其它 params，然后按参数名称的字母顺序对它们进行排序：

对于第一组示例参数（仅限 ASCII 字符）：

参数	取值
`apiKey`	4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO
`price`	52000.00
`quantity`	0.01000000
`recvWindow`	100
`side`	SELL
`symbol`	BTCUSDT
`timeInForce`	GTC
`timestamp`	1645423376532
`type`	LIMIT

对于第二组示例参数（包含一些 Unicode 字符）：

参数	取值
`apiKey`	4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO
`price`	0.20000000
`quantity`	1.00000000
`recvWindow`	5000
`side`	SELL
`symbol`	１２３４５６
`timeInForce`	GTC
`timestamp`	1668481559918
`type`	LIMIT

将参数格式化为 参数=取值 对并用 & 分隔每个参数对。数值需要采用 UTF-8 编码。

对于第一组示例参数（仅限 ASCII 字符），签名有效负载将如下所示：

Code
apiKey=4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

对于第二组示例参数（包含一些 Unicode 字符），签名有效负载将如下所示：

Code
apiKey=4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

第二步：计算签名

使用 Ed25519 密钥对步骤 1 中构造的签名有效载荷的 UTF-8 字节进行签名。
将输出编码为 base64。

请注意，apiKey, payload 和生成的签名值都是大小写敏感的。

您可以使用 OpenSSL 交叉检查您的签名算法：

对于第一组示例参数（仅限 ASCII 字符）：

Code
echo -n "apiKey=4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT" \
  | openssl dgst -sign ./test-ed25519-prv.pem \
  | openssl enc -base64 -A

EocljwPl29jDxWYaaRaOo4pJ9wEblFbklJvPugNscLLuKd5vHM2grWjn1z+rY0aJ7r/44enxHL6mOAJuJ1kqCg==

对于第二组示例参数（包含一些 Unicode 字符）：

Code
echo -n "apiKey=4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT" \
  | openssl dgst -sign ./test-ed25519-prv.pem \
  | openssl enc -base64 -A

dtNHJeyKry+cNjiGv+sv5kynO9S40tf8k7D5CfAEQAp0s2scunZj+ovJdz2OgW8XhkB9G3/HmASkA9uY9eyFCA==

第三步：在请求的 params 参数添加签名值

对于第一组示例参数（仅限 ASCII 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "newOrderRespType": "ACK",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO",
    "signature": "EocljwPl29jDxWYaaRaOo4pJ9wEblFbklJvPugNscLLuKd5vHM2grWjn1z+rY0aJ7r/44enxHL6mOAJuJ1kqCg=="
  }
}

对于第二组示例参数（包含一些 Unicode 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "1.00000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO",
    "signature": "dtNHJeyKry+cNjiGv+sv5kynO9S40tf8k7D5CfAEQAp0s2scunZj+ovJdz2OgW8XhkB9G3/HmASkA9uY9eyFCA=="
  }
}

下面的 Python 示例代码能执行上述所有步骤。


Code
#!/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':       '１２３４５６',
    'side':         'SELL',
    'type':         'LIMIT',
    'timeInForce':  'GTC',
    'quantity':     '1.0000000',
    'price':        '0.10000000',
    'recvWindow':   5000
}

# 参数中加时间戳：
timestamp = int(time.time() * 1000) # UNIX timestamp in milliseconds
params['timestamp'] = timestamp

# 按参数名称的字母顺序进行排序
params = dict(sorted(params.items()))

# 计算签名有效负载
payload = '&'.join([f"{k}={v}" for k,v in params.items()]) # no percent encoding here!

# 对请求进行签名
signature = base64.b64encode(private_key.sign(payload.encode('UTF-8')))
params['signature'] = signature.decode('ASCII')

# 发送请求：
request = {
    'id': 'my_new_order',
    'method': 'order.place',
    'params': params
}

ws = create_connection("wss://ws-api.binance.com:443/ws-api/v3")
ws.send(json.dumps(request))
result =  ws.recv()
ws.close()

print(result)

会话身份验证

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

如果你不想在每个单独的请求中指定apiKey和signature，你可以为有效的WebSocket会话进行API密钥身份验证。

一旦完成身份验证，你将不需在需要它们的请求中指定apiKey和signature。这些请求将代表拥有已验证API密钥的帐户执行。

注意： 对于SIGNED请求，你仍需要指定timestamp参数。

连接后进行身份验证

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

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

关于吊销API密钥:

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


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

授权临时请求

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

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

数据源

API 系统是异步的。响应中一些延迟是正常和预期的。
每种函数都会有一个数据源, 用来指示数据的来源，以及它的最新程度。

数据源	延迟	描述
撮合引擎	最低	表示撮合引擎直接产生响应
缓存	低	表示数据来源于内部或者外部的缓存
数据库	中度	表示数据直接来源于数据库

某些函数有多个数据源（例如，缓存 => 数据库）。

这代表 API 将按该顺序查找最新数据：首先是缓存，然后是数据库。

此页面是否有帮助？

Last modified on June 26, 2026

REST API 基本信息通用 WebSocket 流信息

Spot Trading

WebSocket API 基本信息

本篇所列出的 wss 接口的 base URL：wss://ws-api.binance.com:443/ws-api/v3
- 如果使用标准443端口时遇到问题，可以使用替代端口9443。
- 现货测试网的 base URL 是 wss://ws-api.testnet.binance.vision/ws-api/v3。
每个到 base URL 的链接有效期不超过24小时，请妥善处理断线重连。
当服务器即将关闭时，系统将发送 serverShutdown 事件，并导致连接断开。请尽快建立新连接，以防止中断。
我们支持 HMAC，RSA 以及 Ed25519 Key 类型。如需进一步了解，请参考 API Key 类型。
响应默认为 JSON 格式。如果您想接收 SBE 格式的响应，请参考简单二进制编码（SBE）常见问题。
如果您的请求包含非 ASCII 字符的交易对名称，那么响应中可能包含以 UTF-8 编码的非 ASCII 字符。
即使请求本身不包含非 ASCII 字符，某些方法也可能会返回包含以 UTF-8 编码的非 ASCII 字符的资产和/或交易对名称。
WebSocket 服务器每20秒发送 PING 消息。
- 如果websocket 服务器没有在一分钟之内收到PONG 消息应答，连接会被断开。
- 当客户收到PING消息，必须尽快回复PONG消息，同时payload需要和PING消息一致。
- 服务器允许未经请求的PONG消息，但这不会保证连接不断开。对于这些PONG 消息，建议payload为空。
除非另有说明，否则数据将按时间顺序返回。
- 如果未指定 startTime 或 endTime，则返回最近的条目，直至达到限制值。
- 如果指定 startTime，则返回从 startTime 到限制值为止最老的条目。
- 如果指定 endTime，则返回截至 endTime 和限制值为止最近的条目。
- 如果同时指定 startTime 和 endTime，则行为类似于 startTime，但不超过 endTime。
JSON 响应中的所有时间和时间戳相关字段均以UTC 毫秒为默认单位。要以微秒为单位接收信息，请在 URL 中添加参数 timeUnit=MICROSECOND 或 timeUnit=microsecond。
时间戳参数（例如 startTime、endTime、timestamp）可以以毫秒或微秒为单位传递。
除非另有说明，所有字段名称和值都大小写敏感。
如需进一步了解枚举或术语，请参考现货交易API术语表页面。
API 处理请求的超时时间为 10 秒。如果撮合引擎的响应时间超过此时间，API 将返回 “Timeout waiting for response from backend server. Send status unknown; execution status unknown.”。(-1007 超时)
- 这并不总是意味着该请求在撮合引擎中失败。
- 如果请求状态未显示在用户数据流中，请执行 API 查询以获取其状态。
请避免在请求中使用 SQL 关键字，因为这可能会触发 Web 应用防火墙（WAF）规则导致安全拦截。详情请参见 https://www.binance.com/zh-CN/support/faq/detail/360004492232

请求格式

请求必须在 text 帧 中以 JSON 格式发送，每帧一个请求。

请求示例:


Code
{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "LIMIT",
    "price": "0.1",
    "quantity": "10",
    "timeInForce": "GTC",
    "timestamp": 1655716096498,
    "apiKey": "T59MTDLWlpRW16JVeZ2Nju5A5C98WkMm8CSzWC4oqynUlTm1zXOxyauT8LmwXEv9",
    "signature": "5942ad337e6779f2f4c62cd1c26dba71c91514400a24990a3e7f5edec9323f90"
  }
}

请求字段:

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

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

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

响应格式

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

成功响应示例:


Code
{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "status": 200,
  "result": {
    "symbol": "BTCUSDT",
    "orderId": 12510053279,
    "orderListId": -1,
    "clientOrderId": "a097fe6304b20a7e4fc436",
    "transactTime": 1655716096505,
    "price": "0.10000000",
    "origQty": "10.00000000",
    "executedQty": "0.00000000",
    "origQuoteOrderQty": "0.000000",
    "cummulativeQuoteQty": "0.00000000",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "workingTime": 1655716096505,
    "selfTradePreventionMode": "NONE"
  },
  "rateLimits": [
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 10,
      "limit": 50,
      "count": 12
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "intervalNum": 1,
      "limit": 160000,
      "count": 4043
    },
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 321
    }
  ]
}

失败响应示例:


Code
{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "status": 400,
  "error": {
    "code": -2010,
    "msg": "Account has insufficient balance for requested action."
  },
  "rateLimits": [
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 10,
      "limit": 50,
      "count": 13
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "intervalNum": 1,
      "limit": 160000,
      "count": 4044
    },
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 322
    }
  ]
}

响应字段:

状态代码

status 字段的状态代码与HTTP的状态代码相同。

一些常见状态代码：

200 代码指示成功响应。
4XX 错误码用于指示错误的请求内容、行为、格式。问题在于请求者。
- 400 – 错误码表示请求失败，请参阅 error 了解原因。
- 403 – 错误码表示违反 WAF 限制(Web应用程序防火墙)。这可能表示触发了速率限制或安全拦截。详情请参见 https://www.binance.com/zh-CN/support/faq/detail/360004492232 。
- 409 – 错误码表示请求有一部分成功，一部分失败。请参阅 error 了解更多详细
- 418 – 表示收到 429 后继续访问，于是被封了。
- 429 – 错误码表示警告访问频次超限，即将被封IP。
5XX 错误码用于指示Binance服务侧的问题。
- 重要：如果响应包含 5xx 状态码，并不一定意思请求失败。执行状态为 unknown，请求可能实际成功。请使用 query 函数确认状态。建议建立一个新 WebSocket 连接用于确认状态。

有关错误代码和消息的列表，请参阅 Binance 的错误代码。

事件格式

用户数据流中的非 SBE 会话事件以 JSON 格式在 text 帧 中发送，每帧一个事件。

SBE 会话中的事件将作为 二进制帧 发送。

有关如何在 WebSocket API 中订阅用户数据流的详细信息，请参阅 订阅用户数据流。

事件示例:


Code
{
    "subscriptionId": 0,
    "event": {
        "e": "outboundAccountPosition",
        "E": 1728972148778,
        "u": 1728972148778,
        "B": [
            {
                "a": "BTC",
                "f": "11818.00000000",
                "l": "182.00000000"
            },
            {
                "a": "USDT",
                "f": "10580.00000000",
                "l": "70.00000000"
            }
        ]
    }
}

事件字段:

名称	类型	是否必须	描述
`event`	OBJECT	YES	事件 payload。请看用户数据流
`subscriptionId`	INT	NO	用以标识事件来自于哪个订阅。详见用户数据流订阅

连接事件

服务器关闭

当服务器即将关闭时，会发送 serverShutdown 事件。


Code
{
  "event": {
    "e": "serverShutdown", // 事件类型
    "E": 1770123456789     // 事件时间
   }
}

请尽快建立新连接，以防中断

速率限制

连接数量限制

每IP地址、每5分钟最多可以发送300次连接请求。

速率限制基本信息

exchangeInfo 有包含与速率限制相关的信息。
根据不同的间隔，有多种频率限制类型。
从响应中的可选 rateLimits 字段，能看到当前的频率限制状态。
当您超出未成交订单计数或者请求速率限制时，请求会失败并返回 HTTP 状态代码 429。

如何咨询频率限制

频率限制状态的响应可能如下所示：


Code
{
  "id": "7069b743-f477-4ae3-81db-db9b8df085d2",
  "status": 200,
  "result": {
    "serverTime": 1656400526260
  },
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 70
    }
  ]
}

rate Limits 数组描述了受请求影响的所有当前的速率限制。

名称	类型	是否必须	描述
`rateLimitType`	ENUM	YES	频率限制类型: `REQUEST_WEIGHT`, `ORDERS`
`interval`	ENUM	YES	频率限制间隔: `SECOND`, `MINUTE`, `HOUR`, `DAY`
`intervalNum`	INT	YES	频率限制间隔乘数
`limit`	INT	YES	每个间隔的请求限制
`count`	INT	YES	每个间隔的当前使用情况

频率限制按间隔计算。

例如，1 MINUTE 间隔表示每分钟开始。在 00:01:23.456 提交的请求计入 00:01:00 分钟的限制。一旦 00:02:00 分钟开始，计数将再次重置为零。

其他间隔的行为方式类似。例如，1 DAY 频率限制是在每天 00:00 UTC 重置，并且 10 SECOND 间隔重置为每分钟的 00、10、20...秒。

如何显示/隐藏频率限制信息

默认情况下，每个响应都包含 rateLimits 字段。

但是，频率限制信息可能非常大。如果您对每个请求的详细频率限制状态不感兴趣，可以从响应中省略 rateLimits 字段。

请求中的可选 returnRateLimits boolean 参数。

使用 returnRateLimits 参数控制是否包含 rateLimits 字段以响应单个请求。

默认请求和响应：


Code
{ "id": 1, "method": "time" }


Code
{
  "id": 1,
  "status": 200,
  "result": { "serverTime": 1656400526260 },
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 70
    }
  ]
}

没有频率限制状态的请求和响应：


Code
{ "id": 2, "method": "time", "params": { "returnRateLimits": false } }


Code
{ "id": 2, "status": 200, "result": { "serverTime": 1656400527891 } }

连接 URL 中可选的 returnRateLimits boolean 参数。

如果您希望在默认情况下从所有响应中省略 rateLimits，可以在 query string 中使用 returnRateLimits 参数：
```
Code
wss://ws-api.binance.com:443/ws-api/v3?returnRateLimits=false
```
这将使通过此连接发出的所有请求的行为就像您已传了 "returnRateLimits"：false 一样。

如果您想查看特定请求的频率限制，您需要特定传 "returnRateLimits"：true 参数。

注意: 如果您在响应中隐藏 rateLimits 字段，您的请求仍然还是会受到频率限制的。

IP 访问限制

每个请求都有一个特定的权重，它会添加到您的访问限制中。
- 越消耗资源的接口, 比如查询多个交易对, 权重就会越大。
- 连接到 WebSocket API 会用到2个权重。
当前权重使用由 REQUEST_WEIGHT 频率限制类型指示。
请使用exchangeInfo请求来跟踪当前的重量限制。
权重是基于每个 IP 地址累积的，并由来自该地址的所有连接共享。
如果超多限制，客服端会收到 429。
- 这错误代码表示您有责任停止发送请求，不得滥用API。
- 响应会包含一个 retryAfter 字段，指示在什么时候您能重试。
屡次违反速率限制或者在收到429后未能退缩将导致自动 IP 封禁和断开连接。
- 被禁止 IP 地址的请求失败，状态为 418。
- retryAfter 字段表示解除禁令的timestamp。
频繁违反限制的封禁时间会逐渐延长，从最短2分钟到最长3天。

表示在1分钟内使用了（1200权重限制中的）70权重的成功响应：


Code
{
  "id": "7069b743-f477-4ae3-81db-db9b8df085d2",
  "status": 200,
  "result": [],
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 70
    }
  ]
}

表示已被封禁且封禁将在 epoch 1659146400000 解锁的失败响应：


Code
{
  "id": "fc93a61a-a192-4cf4-bb2a-a8f0f0c51e06",
  "status": 418,
  "error": {
    "code": -1003,
    "msg": "Way too much request weight used; IP banned until 1659146400000. Please use WebSocket Streams for live updates to avoid bans.",
    "data": {
      "serverTime": 1659142907531,
      "retryAfter": 1659146400000
    }
  },
  "rateLimits": [
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 2411
    }
  ]
}

未成交订单计数

成功下单将更新 订单 速率限制类型。
被拒绝或不成功的订单可能会也可能不会更新 订单 速率限制类型。
请注意，如果您的订单一直顺利完成交易，您可以通过 API 持续下订单。更多信息，请参见现货未成交订单计数规则。
使用 account.rateLimits.orders 请求来跟踪您在此时间间隔内下了多少订单。
如果超过此值，请求将失败，状态为 429。
- 此状态代码表示您应退出并停止向 API 滥发信息。
- 状态为 429 的响应会包含 retryAfter 字段，用以指示何时可以重试请求。
这是按 每一个账户 维护的，并由该账户的所有 API 密钥共享。

表示在10秒内下了12个订单和在24小时内下了4043个订单的成功响应：


Code
{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "status": 200,
  "result": {
    "symbol": "BTCUSDT",
    "orderId": 12510053279,
    "orderListId": -1,
    "clientOrderId": "a097fe6304b20a7e4fc436",
    "transactTime": 1655716096505,
    "price": "0.10000000",
    "origQty": "10.00000000",
    "executedQty": "0.00000000",
    "origQuoteOrderQty": "0.000000",
    "cummulativeQuoteQty": "0.00000000",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "workingTime": 1655716096505,
    "selfTradePreventionMode": "NONE"
  },
  "rateLimits": [
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 10,
      "limit": 50,
      "count": 12
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "intervalNum": 1,
      "limit": 160000,
      "count": 4043
    },
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 321
    }
  ]
}

请求鉴权类型

每个方法都有一个鉴权类型，指示所需的 API 密钥权限，显示在方法名称旁边（例如，下新订单 (TRADE)）。
如果未指定，则鉴权类型为 NONE。
除了为 NONE 外，所有具有鉴权类型的方法均视为 SIGNED 请求（即包含 signature），listenKey 管理除外。
具有鉴权类型的方法需要提供有效的 API 密钥并验证通过。
- API 密钥可在您的 Binance 账户的 API 管理页面创建。
- API 密钥和密钥对均为敏感信息，切勿与他人分享。 如果发现账户有异常活动，请立即撤销所有密钥并联系 Binance 支持。
API 密钥可配置为仅允许访问某些鉴权类型。
- 例如，您可以拥有具有 TRADE 权限的 API 密钥用于交易，同时使用具有 USER_DATA 权限的另一个 API 密钥来监控订单状态。
- 默认情况下，API 密钥无法进行 TRADE，您需要先在 API 管理中启用交易权限。

鉴权类型	描述
`NONE`	公开市场数据
`TRADE`	在交易所交易，下单和取消订单
`USER_DATA`	私人账户信息，例如订单状态和交易历史
`USER_STREAM`	管理用户数据流订阅

需要签名的请求

为了授权请求，SIGNED 请求必须带 signature 参数。

签名区分大小写

HMAC： 使用 HMAC 生成的签名不区分大小写。这意味着无论字母大小写如何，签名字符串都可以被验证。
RSA： 使用 RSA 生成的签名区分大小写。
Ed25519： 使用 Ed25519 生成的签名也区分大小写。

时间同步安全

SIGNED 请求还需要一个 timestamp 参数，该参数应为当前时间戳，单位为毫秒或微秒。（参见通用 API 信息）
另一个可选参数 recvWindow，用以指定请求的有效期，只能以毫秒为单位。
- recvWindow 扩展为三位小数（例如 6000.346），以便可以指定微秒。
- 如果未发送 recvWindow，则 默认为 5000 毫秒。
- recvWindow 的最大值为 60000 毫秒。
请求处理逻辑如下：


Code
serverTime = getCurrentTime()
if (timestamp < (serverTime + 1 second) && (serverTime - timestamp) <= recvWindow) {
  // 开始处理请求
  serverTime = getCurrentTime()
  if (serverTime - timestamp) <= recvWindow {
    // 将请求转发到撮合引擎
  } else {
    // 拒绝请求
  }
  // 结束处理请求
} else {
  // 拒绝请求
}

建议使用5000毫秒以下的 recvWindow！

SIGNED 请求示例 (HMAC)

这是有关如何用一个 HMAC secret key 签署请求的分步指南。

示例 API key 和 secret key：

Key	Value
`apiKey`	`vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A`
`secretKey`	`NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j`

警告：请勿与任何人分享您的 API 密钥和秘钥。

此处提供的示例密钥仅用于示范说明目的。

交易对名称完全由 ASCII 字符组成的请求示例：

请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "newOrderRespType": "ACK",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
    "signature": "------ 未填写 ------"
  }
}

交易对名称包含非 ASCII 字符的请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO",
    "signature": "------ FILL ME ------"
  }
}

第一步：创建签名内容

除了 signature 之外，获取所有请求 params，然后按参数名称的字母顺序对它们进行排序：

对于第一组示例参数（仅限 ASCII 字符）：

参数	取值
`apiKey`	vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
`price`	52000.00
`quantity`	0.01000000
`recvWindow`	100
`side`	SELL
`symbol`	BTCUSDT
`timeInForce`	GTC
`timestamp`	1645423376532
`type`	LIMIT

对于第二组示例参数（包含一些 Unicode 字符）：

参数	取值
`apiKey`	vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
`price`	0.10000000
`quantity`	1.00000000
`recvWindow`	5000
`side`	BUY
`symbol`	１２３４５６
`timeInForce`	GTC
`timestamp`	1645423376532
`type`	LIMIT

将参数格式化为 参数=取值 对并用 & 分隔每个参数对。数值需要采用 UTF-8 编码。

对于第一组示例参数（仅限 ASCII 字符），签名有效负载将如下所示：

Code
apiKey=vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

对于第二组示例参数（包含一些 Unicode 字符），签名有效负载将如下所示：

Code
apiKey=vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

第二步：计算签名

使用 API 密钥中的 secretKey 作为 HMAC-SHA-256 算法的签名密钥。
对步骤 1 中构建的签名 payload 进行签名。
将 HMAC-SHA-256 的输出编码为十六进制字符串。

请注意，apiKey、secretKey 和有效负载是大小写敏感的。而生成的签名值是不区分大小写的。

可以使用 OpenSSL 交叉检查您的签名算法实现：

对于第一组示例参数（仅限 ASCII 字符）：

Code
$ echo -n 'apiKey=vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT' \
  | openssl dgst -hex -sha256 -hmac 'NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j'

aa1b5712c094bc4e57c05a1a5c1fd8d88dcd628338ea863fec7b88e59fe2db24

对于第二组示例参数（包含一些 Unicode 字符）：

Code
$ echo -n 'apiKey=vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT' \
  | openssl dgst -hex -sha256 -hmac 'NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j'

b33892ae8e687c939f4468c6268ddd4c40ac1af18ad19a064864c47bae0752cd

第三步：添加 signature 到 params 中

通过在对请求中添加 signature 参数和签名字串来完成请求。

对于第一组示例参数（仅限 ASCII 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
    "signature": "aa1b5712c094bc4e57c05a1a5c1fd8d88dcd628338ea863fec7b88e59fe2db24"
  }
}

对于第二组示例参数（包含一些 Unicode 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "1.00000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A",
    "signature": "b33892ae8e687c939f4468c6268ddd4c40ac1af18ad19a064864c47bae0752cd"
  }
}

SIGNED 请求示例 (RSA)

这是有关如何用一个 RSA private key 签署请求的分步指南。

Key	Value
`apiKey`	`CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ`

这些示例假设私钥存储在文件 test-prv-key.pem 中。

警告：请勿与任何人分享您的 API 密钥和私钥。

此处提供的示例密钥仅用于示范说明目的。

交易对名称完全由 ASCII 字符组成的请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ",
    "signature": "------ FILL ME ------"
  }
}

交易对名称包含非 ASCII 字符的请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ",
    "signature": "------ FILL ME ------"
  }
}

第一步：创建签名内容

除了 signature，获取请求的所有其它 params，然后按参数名称的字母顺序对它们进行排序：

对于第一组示例参数（仅限 ASCII 字符）：

参数	取值
`apiKey`	CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ
`price`	52000.00
`quantity`	0.01000000
`recvWindow`	100
`side`	SELL
`symbol`	BTCUSDT
`timeInForce`	GTC
`timestamp`	1645423376532
`type`	LIMIT

对于第二组示例参数（包含一些 Unicode 字符）：

参数	取值
`apiKey`	CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ
`price`	0.10000000
`quantity`	1.00000000
`recvWindow`	5000
`side`	BUY
`symbol`	１２３４５６
`timeInForce`	GTC
`timestamp`	1645423376532
`type`	LIMIT

将参数格式化为 参数=取值 对并用 & 分隔每个参数对。数值需要采用 UTF-8 编码。

对于第一组示例参数（仅限 ASCII 字符），签名有效负载将如下所示：

Code
apiKey=CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

对于第二组示例参数（包含一些 Unicode 字符），签名有效负载将如下所示：

Code
apiKey=CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

第二步：计算签名

使用 RSASSA-PKCS1-v1_5 算法和 SHA-256 哈希函数对步骤 1 中构造的签名有效载荷的 UTF-8 字节进行签名。
将输出编码为 base64。

请注意，apiKey, payload 和生成的签名值都是大小写敏感的。

您可以使用 OpenSSL 交叉检查您的签名算法：

对于第一组示例参数（仅限 ASCII 字符）：

Code
$ echo -n 'apiKey=CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT' \
  | openssl dgst -sha256 -sign test-rsa-prv.pem \
  | openssl enc -base64 -A

OJJaf8C/3VGrU4ATTR4GiUDqL2FboSE1Qw7UnnoYNfXTXHubIl1iaePGuGyfct4NPu5oVEZCH4Q6ZStfB1w4ssgu0uiB/Bg+fBrRFfVgVaLKBdYHMvT+ljUJzqVaeoThG9oXlduiw8PbS9U8DYAbDvWN3jqZLo4Z2YJbyovyDAvDTr/oC0+vssLqP7NmlNb3fF3Bj7StmOwJvQJTbRAtzxK5PP7OQe+0mbW+D7RqVkUiSswR8qJFWTeSe4nXXNIdZdueYhF/Xf25L+KitJS5IHdIHcKfEw3MQzHFb2ZsGWkjDQwxkwr7Noi0Zaa+gFtxCuatGFm9dFIyx217pmSHtA==

对于第二组示例参数（包含一些 Unicode 字符）：

Code
$ echo -n 'apiKey=CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT' \
  | openssl dgst -sha256 -sign test-rsa-prv.pem \
  | openssl enc -base64 -A

F3o/79Ttvl2cVYGPfBOF3oEOcm5QcYmTYWpdVIrKve5u+8paMNDAdUE+teqMxFM9HcquetGcfuFpLYtsQames5bDx/tskGM76TWW8HaM+6tuSYBSFLrKqChfA9hQGLYGjAiflf1YBnDhY+7vNbJFusUborNOloOj+ufzP5q42PvI3H0uNy3W5V3pyfXpDGCBtfCYYr9NAqA4d+AQfyllL/zkO9h9JSdozN49t0/hWGoD2dWgSO0Je6MytKEvD4DQXGeqNlBTB6tUXcWnRW+FcaKZ4KYqnxCtb1u8rFXUYgFykr2CbcJLSmw6ydEJ3EZ/NaZopRr+cU0W2m0HZ3qucw==

第三步：在请求的 params 参数添加签名值

通过在对请求中添加 signature 参数和签名字串来完成请求。

对于第一组示例参数（仅限 ASCII 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "newOrderRespType": "ACK",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ",
    "signature": "OJJaf8C/3VGrU4ATTR4GiUDqL2FboSE1Qw7UnnoYNfXTXHubIl1iaePGuGyfct4NPu5oVEZCH4Q6ZStfB1w4ssgu0uiB/Bg+fBrRFfVgVaLKBdYHMvT+ljUJzqVaeoThG9oXlduiw8PbS9U8DYAbDvWN3jqZLo4Z2YJbyovyDAvDTr/oC0+vssLqP7NmlNb3fF3Bj7StmOwJvQJTbRAtzxK5PP7OQe+0mbW+D7RqVkUiSswR8qJFWTeSe4nXXNIdZdueYhF/Xf25L+KitJS5IHdIHcKfEw3MQzHFb2ZsGWkjDQwxkwr7Noi0Zaa+gFtxCuatGFm9dFIyx217pmSHtA=="
  }
}

对于第二组示例参数（包含一些 Unicode 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "1.00000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "CAvIjXy3F44yW6Pou5k8Dy1swsYDWJZLeoK2r8G4cFDnE9nosRppc2eKc1T8TRTQ",
    "signature": "F3o/79Ttvl2cVYGPfBOF3oEOcm5QcYmTYWpdVIrKve5u+8paMNDAdUE+teqMxFM9HcquetGcfuFpLYtsQames5bDx/tskGM76TWW8HaM+6tuSYBSFLrKqChfA9hQGLYGjAiflf1YBnDhY+7vNbJFusUborNOloOj+ufzP5q42PvI3H0uNy3W5V3pyfXpDGCBtfCYYr9NAqA4d+AQfyllL/zkO9h9JSdozN49t0/hWGoD2dWgSO0Je6MytKEvD4DQXGeqNlBTB6tUXcWnRW+FcaKZ4KYqnxCtb1u8rFXUYgFykr2CbcJLSmw6ydEJ3EZ/NaZopRr+cU0W2m0HZ3qucw=="
  }
}

SIGNED 请求示例 (Ed25519)

我们强烈建议使用 Ed25519 API keys，因为它在所有受支持的 API key 类型中提供最佳性能和安全性。

这是有关如何用一个 Ed25519 private key 签署请求的分步指南。

Key	Value
`apiKey`	`4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO`

这些示例假设私钥存储在文件 test-ed25519-prv.pem 中。

警告：请勿与任何人分享您的 API 密钥和私钥。

此处提供的示例密钥仅用于示范说明目的。

交易对名称完全由 ASCII 字符组成的请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO",
    "signature": "------ FILL ME ------"
  }
}

交易对名称包含非 ASCII 字符的请求示例：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "BUY",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO",
    "signature": "------ FILL ME ------"
  }
}

第一步：创建签名内容

除了 signature，获取请求的所有其它 params，然后按参数名称的字母顺序对它们进行排序：

对于第一组示例参数（仅限 ASCII 字符）：

参数	取值
`apiKey`	4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO
`price`	52000.00
`quantity`	0.01000000
`recvWindow`	100
`side`	SELL
`symbol`	BTCUSDT
`timeInForce`	GTC
`timestamp`	1645423376532
`type`	LIMIT

对于第二组示例参数（包含一些 Unicode 字符）：

参数	取值
`apiKey`	4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO
`price`	0.20000000
`quantity`	1.00000000
`recvWindow`	5000
`side`	SELL
`symbol`	１２３４５６
`timeInForce`	GTC
`timestamp`	1668481559918
`type`	LIMIT

将参数格式化为 参数=取值 对并用 & 分隔每个参数对。数值需要采用 UTF-8 编码。

对于第一组示例参数（仅限 ASCII 字符），签名有效负载将如下所示：

Code
apiKey=4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

对于第二组示例参数（包含一些 Unicode 字符），签名有效负载将如下所示：

Code
apiKey=4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT

第二步：计算签名

使用 Ed25519 密钥对步骤 1 中构造的签名有效载荷的 UTF-8 字节进行签名。
将输出编码为 base64。

请注意，apiKey, payload 和生成的签名值都是大小写敏感的。

您可以使用 OpenSSL 交叉检查您的签名算法：

对于第一组示例参数（仅限 ASCII 字符）：

Code
echo -n "apiKey=4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO&price=52000.00&quantity=0.01000000&recvWindow=100&side=SELL&symbol=BTCUSDT&timeInForce=GTC&timestamp=1645423376532&type=LIMIT" \
  | openssl dgst -sign ./test-ed25519-prv.pem \
  | openssl enc -base64 -A

EocljwPl29jDxWYaaRaOo4pJ9wEblFbklJvPugNscLLuKd5vHM2grWjn1z+rY0aJ7r/44enxHL6mOAJuJ1kqCg==

对于第二组示例参数（包含一些 Unicode 字符）：

Code
echo -n "apiKey=4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO&price=0.10000000&quantity=1.00000000&recvWindow=5000&side=BUY&symbol=１２３４５６&timeInForce=GTC&timestamp=1645423376532&type=LIMIT" \
  | openssl dgst -sign ./test-ed25519-prv.pem \
  | openssl enc -base64 -A

dtNHJeyKry+cNjiGv+sv5kynO9S40tf8k7D5CfAEQAp0s2scunZj+ovJdz2OgW8XhkB9G3/HmASkA9uY9eyFCA==

第三步：在请求的 params 参数添加签名值

对于第一组示例参数（仅限 ASCII 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "0.01000000",
    "price": "52000.00",
    "newOrderRespType": "ACK",
    "recvWindow": 100,
    "timestamp": 1645423376532,
    "apiKey": "4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO",
    "signature": "EocljwPl29jDxWYaaRaOo4pJ9wEblFbklJvPugNscLLuKd5vHM2grWjn1z+rY0aJ7r/44enxHL6mOAJuJ1kqCg=="
  }
}

对于第二组示例参数（包含一些 Unicode 字符）：


Code
{
  "id": "4885f793-e5ad-4c3b-8f6c-55d891472b71",
  "method": "order.place",
  "params": {
    "symbol": "１２３４５６",
    "side": "SELL",
    "type": "LIMIT",
    "timeInForce": "GTC",
    "quantity": "1.00000000",
    "price": "0.10000000",
    "recvWindow": 5000,
    "timestamp": 1645423376532,
    "apiKey": "4yNzx3yWC5bS6YTwEkSRaC0nRmSQIIStAUOh1b6kqaBrTLIhjCpI5lJH8q8R8WNO",
    "signature": "dtNHJeyKry+cNjiGv+sv5kynO9S40tf8k7D5CfAEQAp0s2scunZj+ovJdz2OgW8XhkB9G3/HmASkA9uY9eyFCA=="
  }
}

下面的 Python 示例代码能执行上述所有步骤。


Code
#!/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':       '１２３４５６',
    'side':         'SELL',
    'type':         'LIMIT',
    'timeInForce':  'GTC',
    'quantity':     '1.0000000',
    'price':        '0.10000000',
    'recvWindow':   5000
}

# 参数中加时间戳：
timestamp = int(time.time() * 1000) # UNIX timestamp in milliseconds
params['timestamp'] = timestamp

# 按参数名称的字母顺序进行排序
params = dict(sorted(params.items()))

# 计算签名有效负载
payload = '&'.join([f"{k}={v}" for k,v in params.items()]) # no percent encoding here!

# 对请求进行签名
signature = base64.b64encode(private_key.sign(payload.encode('UTF-8')))
params['signature'] = signature.decode('ASCII')

# 发送请求：
request = {
    'id': 'my_new_order',
    'method': 'order.place',
    'params': params
}

ws = create_connection("wss://ws-api.binance.com:443/ws-api/v3")
ws.send(json.dumps(request))
result =  ws.recv()
ws.close()

print(result)

会话身份验证

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

如果你不想在每个单独的请求中指定apiKey和signature，你可以为有效的WebSocket会话进行API密钥身份验证。

一旦完成身份验证，你将不需在需要它们的请求中指定apiKey和signature。这些请求将代表拥有已验证API密钥的帐户执行。

注意： 对于SIGNED请求，你仍需要指定timestamp参数。

连接后进行身份验证

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

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

关于吊销API密钥:


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

授权临时请求

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

数据源

API 系统是异步的。响应中一些延迟是正常和预期的。
每种函数都会有一个数据源, 用来指示数据的来源，以及它的最新程度。

数据源	延迟	描述
撮合引擎	最低	表示撮合引擎直接产生响应
缓存	低	表示数据来源于内部或者外部的缓存
数据库	中度	表示数据直接来源于数据库

某些函数有多个数据源（例如，缓存 => 数据库）。

这代表 API 将按该顺序查找最新数据：首先是缓存，然后是数据库。

此页面是否有帮助？

Last modified on June 26, 2026

REST API 基本信息通用 WebSocket 流信息

WebSocket API 基本信息

请求格式

响应格式

状态代码

事件格式

连接事件

服务器关闭

速率限制

连接数量限制

速率限制基本信息

如何咨询频率限制

如何显示/隐藏频率限制信息

IP 访问限制

未成交订单计数

请求鉴权类型

需要签名的请求

签名区分大小写

时间同步安全

SIGNED 请求示例 (HMAC)

SIGNED 请求示例 (RSA)

SIGNED 请求示例 (Ed25519)

会话身份验证

连接后进行身份验证

授权 临时 请求

数据源

WebSocket API 基本信息

请求格式

响应格式

状态代码

事件格式

连接事件

服务器关闭

速率限制

连接数量限制

速率限制基本信息

如何咨询频率限制

如何显示/隐藏频率限制信息

IP 访问限制

未成交订单计数

请求鉴权类型

需要签名的请求

签名区分大小写

时间同步安全

SIGNED 请求示例 (HMAC)

SIGNED 请求示例 (RSA)

SIGNED 请求示例 (Ed25519)

会话身份验证

连接后进行身份验证

授权 临时 请求

数据源

授权临时请求

授权临时请求