用户数据流请求
用户数据流订阅
- 用户数据流订阅允许您通过 WebSocket 连接接收与指定帐户相关的所有事件。
- 有两种方式可以启用订阅：
- 如果您拥有已通过验证的会话，则可以使用
userDataStream.subscribe来订阅该已通过验证帐户的相关事件。 - 您还可以使用
userdataStream.subscribe.signature为拥有 API 密钥的任何帐户额外开设订阅。 - 一个帐户在指定连接上只能有一个有效订阅。
- 如果您拥有已通过验证的会话，则可以使用
- 订阅由用订阅时返回的
subscriptionId标识。该subscriptionId允许您将收到的事件映射到给定的订阅。 - 可以使用
session.subscriptions查找会话的所有有效订阅。 - 限制
- 单个会话最多可同时支持1,000 个有效订阅。
- 尝试启用超出此限制的新订阅将导致错误。
- 如果您的帐户非常活跃，我们建议您不要一次启用过多的订阅，以免连接过载。
- 单个会话在其生命周期内最多可处理65,535 个订阅。
- 如果达到此限制，您将收到错误，并且必须重新建立连接才能启用新的订阅。
- 单个会话最多可同时支持1,000 个有效订阅。
- 要验证用户数据流订阅的状态，请检查
session.status中的userDataStream字段：null- 此 WebSocket API 上不提供用户数据流订阅。true- 此会话中至少有一个有效订阅。false- 此会话中没有有效订阅。
订阅用户数据流 (USER_STREAM)
{
"id": "d3df8a21-98ea-4fe0-8f4e-0fcea5d418b7",
"method": "userDataStream.subscribe"
}
订阅当前 WebSocket 连接中的用户数据流。
注意：
- 此方法需要使用 Ed25519 密钥并经过鉴权的 WebSocket 连接。请参考
session.logon。 - 如果需要查看订阅状态,可以通过
session.status查询，当userDataStream字段值为true时,表示您有一个有效的订阅. - 用户数据流在 JSON 和 SBE 会话 中均可用。
- 有关事件格式详情，请参阅 用户数据流。
- 对于 SBE，仅支持 SBE 模式 2:1 或更高版本。
权重: 2
参数: 无
响应:
{
"id": "d3df8a21-98ea-4fe0-8f4e-0fcea5d418b7",
"status": 200,
"result": {}
}
取消订阅用户数据流
{
"id": "d3df8a21-98ea-4fe0-8f4e-0fcea5d418b7",
"method": "userDataStream.unsubscribe"
}
取消订阅当前 WebSocket 连接中的用户数据流。
请注意 session.logout 只会关闭由 userdataStream.subscribe 创建的订阅，并不会关闭通过 userDataStream.subscribe.signature 创建的订阅。
权重: 2
参数:
| 名称 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
subscriptionId | INT | No | 如果在进行调用时不用该参数，将会关闭所有订阅。 如果在进行调用时使用 subscriptionId 参数，如果该 ID 存在的话，将尝试关闭与该 ID 匹配的订阅。 |
响应:
{
"id": "d3df8a21-98ea-4fe0-8f4e-0fcea5d418b7",
"status": 200,
"result": {}
}
显示所有订阅
{
"id": "d3df5a22-88ea-4fe0-9f4e-0fcea5d418b7",
"method": "session.subscriptions",
"params": {}
}
注意：
- 用户按需要跟踪相关帐户的对应订阅情况。
权重: 2
数据源: 缓存
响应:
{
"id": "d3df5a22-88ea-4fe0-9f4e-0fcea5d418b7",
"status": 200,
"result": [
{
"subscriptionId": 0
},
{
"subscriptionId": 1
}
]
}
通过签名订阅的方式订阅用户数据流 (USER_STREAM)
{
"id": "d3df8a22-98ea-4fe0-9f4e-0fcea5d418b7",
"method": "userDataStream.subscribe.signature",
"params": {
"apiKey": "mjcKCrJzTU6TChLsnPmgnQJJMR616J4yWvdZWDUeXkk6vL6dLyS7rcVOQlADlVjA",
"timestamp": 1747385641636,
"signature": "yN1vWpXb+qoZ3/dGiFs9vmpNdV7e3FxkA+BstzbezDKwObcijvk/CVkWxIwMCtCJbP270R0OempYwEpS6rDZCQ=="
}
}
权重: 2
参数:
| 名称 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
apiKey | STRING | Yes | |
timestamp | LONG | Yes | |
signature | STRING | Yes |
数据源: 缓存
响应:
{
"id": "d3df8a22-98ea-4fe0-9f4e-0fcea5d418b7",
"status": 200,
"result": {
"subscriptionId": 0
}
}
Listen Key 管理 (已弃用)
[!IMPORTANT] 这些请求已被弃用，这意味着我们以后会删除这些请求。 请通过订阅 WebSocket API 来获得用户账户更新。
以下请求管理 用户数据流 订阅。
开始用户数据流 (USER_STREAM) （已弃用）
{
"id": "d3df8a61-98ea-4fe0-8f4e-0fcea5d418b0",
"method": "userDataStream.start",
"params": {
"apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A"
}
}
开始新的用户数据流
注意：
数据流将在 60 分钟后关闭，除非定期发送 userDataStream.ping 请求。
权重: 2
参数:
| 名称 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
apiKey | STRING | YES |
数据源: 缓存
响应:
之后在 WebSocket Stream 上订阅收到的 listen key。
{
"id": "d3df8a61-98ea-4fe0-8f4e-0fcea5d418b0",
"status": 200,
"result": {
"listenKey": "xs0mRXdAKlIPDRFrlPcw0qI41Eh3ixNntmymGyhrhgqo7L6FuLaWArTD7RLP"
},
"rateLimits": [
{
"rateLimitType": "REQUEST_WEIGHT",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 6000,
"count": 2
}
]
}
Ping 用户数据流 (USER_STREAM) （已弃用）
{
"id": "815d5fce-0880-4287-a567-80badf004c74",
"method": "userDataStream.ping",
"params": {
"listenKey": "xs0mRXdAKlIPDRFrlPcw0qI41Eh3ixNntmymGyhrhgqo7L6FuLaWArTD7RLP",
"apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A"
}
}
即使在监听, 用户数据流也会在60分钟后会自动关闭。
若要保持用户数据流的活动状态，必须使用 userDataStream.ping 请求定期发送 ping，建议的是在每30分钟发送一次 ping。
权重: 2
参数:
| 名称 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
listenKey | STRING | YES | |
apiKey | STRING | YES |
数据源: 缓存
响应:
{
"id": "815d5fce-0880-4287-a567-80badf004c74",
"status": 200,
"response": {},
"rateLimits": [
{
"rateLimitType": "REQUEST_WEIGHT",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 6000,
"count": 2
}
]
}
关闭用户数据流 (USER_STREAM) （已弃用）
{
"id": "819e1b1b-8c06-485b-a13e-131326c69599",
"method": "userDataStream.stop",
"params": {
"listenKey": "xs0mRXdAKlIPDRFrlPcw0qI41Eh3ixNntmymGyhrhgqo7L6FuLaWArTD7RLP",
"apiKey": "vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A"
}
}
强制停止和关闭用户数据流
权重: 2
参数:
| 名称 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
listenKey | STRING | YES | |
apiKey | STRING | YES |
数据源: 缓存
响应:
{
"id": "819e1b1b-8c06-485b-a13e-131326c69599",
"status": 200,
"response": {},
"rateLimits": [
{
"rateLimitType": "REQUEST_WEIGHT",
"interval": "MINUTE",
"intervalNum": 1,
"limit": 6000,
"count": 2
}
]
}