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"
}
}
请求字段:
名称 | 类型 | 是否必需 | 描述 |
---|---|---|---|
id | INT / STRING / null | YES | 任意的 ID 用于匹配对请求的响应 |
method | STRING | YES | 请求函数名称 |
params | OBJECT | NO | 请求参数。如果没有参数可以省略 |
- 请求
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 | 速率限制状态。请看 速率限制 |