跳到主要内容

Binance 的公共 WebSocket API (2024-04-02)

API 基本信息

  • 本篇所列出的 wss 接口的 base URL:wss://ws-api.binance.com:443/ws-api/v3
    • 如果使用标准443端口时遇到问题,可以使用替代端口9443。
    • 现货测试网的 base URL 是 wss://testnet.binance.vision/ws-api/v3
  • 每个到 base URL 的链接有效期不超过24小时,请妥善处理断线重连。
  • Websocket 服务器每3分钟发送Ping消息。
    • 如果Websocket服务器在10分钟之内没有收到Pong消息应答,连接会被断开。
    • 当客户收到ping消息,必需尽快回复pong消息,同时payload需要和ping消息一致。
    • 未经请求的pong消息是被允许的,但是不会保证连接不断开。对于这些pong消息,建议payload为空
  • 响应中如有数组,数组元素以时间时间顺序排列,越早的数据越提前。
  • 除非另有说明,所有与时间戳相关的字段均以UTC的毫秒为单位。
  • 除非另有说明,所有字段名称和值都大小写敏感

请求格式

请求必须在 text 帧 中以 JSON 格式发送,每帧一个请求。 请求示例:

{
"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"
}
}

请求字段:

名称类型是否必需描述
idINT / STRING / nullYES任意的 ID 用于匹配对请求的响应
methodSTRINGYES请求函数名称
paramsOBJECTNO请求参数。如果没有参数可以省略
  • 请求 id 是任意的。可以使用 UUID、顺次 ID、当前时间戳等。 服务器不会以任何方式解释 id,只是在响应中回显它。 可以在一个会话中自由重复使用 ID,不过请注意不要一次发送多个具有相同 ID 的请求,因为否则可能无法区分响应。
  • 请求函数名称可以以显式版本为前缀,例如:"v3/order.place"
  • params 的顺序不重要。

响应格式

响应在 text 帧 中以 JSON 格式返回,每帧一个响应。 成功响应示例:

{
"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",
"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
}
]
}

失败响应示例:

{
"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
}
]
}

响应字段:

名称 类型 是否必需 描述
id INT / STRING / null YES 与原来请求的ID一样
status INT YES 响应状态。请看 状态代码
result OBJECT / ARRAY YES 响应内容。请求成功则显示
error OBJECT 错误描述。请求失败则显示
rateLimits ARRAY NO 速率限制状态。请看 速率限制
## 状态代码 `status` 字段的状态代码与HTTP的状态代码相同。 一些常见状态代码: * `200` 代码指示成功响应。 * `4XX` 错误码用于指示错误的请求内容、行为、格式。问题在于请求者。 * `400` – 错误码表示请求失败,请参阅 `error` 了解原因。 * `403` – 错误码表示违反 WAF 限制(Web应用程序防火墙)。 * `409` – 错误码表示请求有一部分成功,一部分失败。请参阅 `error` 了解更多详细。 * `418` – 表示收到 429 后继续访问,于是被封了。 * `429` – 错误码表示警告访问频次超限,即将被封IP。 * `5XX` 错误码用于指示Binance服务侧的问题。 * **重要**:如果响应包含 5xx 状态码,**并不**一定意思请求失败。 执行状态为 _unknown_,请求可能实际成功。 请使用 query 函数确认状态。 建议建立一个新 WebSocket 连接用于确认状态。 有关错误代码和消息的列表,请参阅 [Binance 的错误代码](/errors_CN.md)。