跳到主要内容

WebSocket 账户接口

最近更新: 2024-12-09

基本信息

  • 本篇所列出API接口的base url : https://api.binance.com
  • 用于订阅账户数据的 listenKey 从创建时刻起有效期为60分钟
  • 可以通过 PUT 一个 listenKey 延长60分钟有效期
  • 可以通过DELETE一个 listenKey 立即关闭当前数据流,并使该listenKey 无效
  • 在具有有效listenKey的帐户上执行POST将返回当前有效的listenKey并将其有效期延长60分钟
  • websocket接口的baseurl: wss://stream.binance.com:9443
  • U订阅账户数据流的stream名称为 /ws/<listenKey>/stream?streams=<listenKey>
  • 每个链接有效期不超过24小时,请妥善处理断线重连。
  • 账户数据流的消息不保证严格时间序; 请使用 E 字段进行排序

与Websocket账户接口相关的REST接口

生成 Listen Key (USER_STREAM)

POST /api/v3/userDataStream

开始一个新的数据流。除非发送 keepalive,否则数据流于60分钟后关闭。如果该帐户具有有效的listenKey,则将返回该listenKey并将其有效期延长60分钟。

权重: 1

参数: NONE

响应:

{
"listenKey": "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"
}

延长 Listen Key 有效期 (USER_STREAM)

PUT /api/v3/userDataStream

有效期延长至本次调用后60分钟, 建议每30分钟发送一个 ping。

权重: 1

参数:

名称类型是否必须描述
listenKeySTRINGYES

响应:

{}

关闭 Listen Key (USER_STREAM)

DELETE /api/v3/userDataStream

关闭某账户数据流

权重: 1

参数:

名称类型是否必须描述
listenKeySTRINGYES

响应:

{}

Websocket推送事件

账户更新

每当帐户余额发生更改时,都会发送一个事件outboundAccountPosition,其中包含可能由生成余额变动的事件而变动的资产。

Payload

{
"e": "outboundAccountPosition", // 事件类型
"E": 1564034571105, // 事件时间
"u": 1564034571073, // 账户末次更新时间戳
"B": [ // 余额
{
"a": "ETH", // 资产名称
"f": "10000.000000", // 可用余额
"l": "0.000000" // 冻结余额
}
]
}

余额更新

当下列情形发生时更新:

  • 账户发生充值或提取
  • 交易账户之间发生划转(例如 现货向杠杆账户划转)

Payload

{
"e": "balanceUpdate", // Event Type
"E": 1573200697110, // Event Time
"a": "ABC", // Asset
"d": "100.00000000", // Balance Delta
"T": 1573200697068 // Clear Time
}

订单更新

订单通过executionReport事件进行更新。

与使用用户数据流相比,我们建议使用 FIX API 以获得更好的性能。

Payload:

{
"e": "executionReport", // 事件类型
"E": 1499405658658, // 事件时间
"s": "ETHBTC", // 交易对
"c": "mUvoqJxFIILMdfAW5iGSOW", // clientOrderId
"S": "BUY", // 订单方向
"o": "LIMIT", // 订单类型
"f": "GTC", // 有效方式
"q": "1.00000000", // 订单原始数量
"p": "0.10264410", // 订单原始价格
"P": "0.00000000", // 止盈止损单触发价格
"F": "0.00000000", // 冰山订单数量
"g": -1, // OCO订单 OrderListId
"C": "", // 原始订单自定义ID(原始订单,指撤单操作的对象。撤单本身被视为另一个订单)
"x": "NEW", // 本次事件的具体执行类型
"X": "NEW", // 订单的当前状态
"r": "NONE", // 订单被拒绝的原因
"i": 4293153, // orderId
"l": "0.00000000", // 订单末次成交量
"z": "0.00000000", // 订单累计已成交量
"L": "0.00000000", // 订单末次成交价格
"n": "0", // 手续费数量
"N": null, // 手续费资产类别
"T": 1499405658657, // 成交时间
"I": 8641984, // 请忽略
"w": true, // 订单是否在订单簿上?
"m": false, // 该成交是作为挂单成交吗?
"M": false, // 请忽略
"O": 1499405658657, // 订单创建时间
"Z": "0.00000000", // 订单累计已成交金额
"Y": "0.00000000", // 订单末次成交金额
"Q": "0.00000000", // Quote Order Quantity
"D": 1668680518494, // 追踪时间; 这仅在追踪止损订单已被激活时可见
"W": 1499405658657, // Working Time; 订单被添加到 order book 的时间
"V": "NONE" // SelfTradePreventionMode
}

备注: 通过将Z除以z可以找到平均价格。

executionReport 中的特定条件时才会出现的字段

这些字段仅在满足特定条件时才会出现。有关这些参数的更多信息,请参阅 现货交易API术语表

字段 名称 描述 示例
d Trailing Delta 出现在追踪止损订单中。 "d": 4
D Trailing Time "D": 1668680518494
j Strategy Id 如果在请求中添加了strategyId参数,则会出现。 "j": 1
J Strategy Type 如果在请求中添加了strategyType参数,则会出现。 "J": 1000000
v Prevented Match Id 只有在因为 STP 导致订单失效时可见。 "v": 3
A Prevented Quantity "A":"3.000000"
B Last Prevented Quantity "B":"3.000000"
u Trade Group Id "u":1
U Counter Order Id "U":37
Cs Counter Symbol "Cs": "BTCUSDT"
pl Prevented Execution Quantity "pl":"2.123456"
pL Prevented Execution Price "pL":"0.10000001"
pY Prevented Execution Quote Qty "pY":"0.21234562"
W Working Time 只有在订单在订单簿上时可见 "W": 1668683798379
b Match Type 只有在订单有分配时可见 "b":"ONE_PARTY_TRADE_REPORT"
a Allocation ID "a":1234
k Working Floor 只有在订单可能有分配时可见 "k":"SOR"
uS UsedSor 只有在订单使用 SOR 时可见 "uS":true

如果是一个订单组,则除了显示executionReport事件外,还将显示一个名为ListStatus的事件。

Payload

{
"e": "listStatus", // 事件类型
"E": 1564035303637, // 事件时间
"s": "ETHBTC", // 交易对
"g": 2, // OrderListId
"c": "OCO", // Contingency Type
"l": "EXEC_STARTED", // List Status Type
"L": "EXECUTING", // List Order Status
"r": "NONE", // List 被拒绝的原因
"C": "F4QN4G8DlFATFlIUQ0cjdD", // List Client Order ID
"T": 1564035303625, // 成交时间
"O": [
{
"s": "ETHBTC", // 交易对
"i": 17, // orderId
"c": "AJYsMjErWJesZvqlJCTUgL" // clientOrderId
},
{
"s": "ETHBTC",
"i": 18,
"c": "bfYPSQdLoqAJeNrOr9adzq"
}
]
}

可能的执行类型:

  • NEW - 新订单已被引擎接受。
  • CANCELED - 订单被用户取消。
  • REPLACED - (保留字段,当前未使用)
  • REJECTED - 新订单被拒绝 (这信息只会在撤消挂单再下单中发生,下新订单被拒绝但撤消挂单请求成功)。
  • TRADE - 订单有新成交。
  • EXPIRED - 订单已根据 Time In Force 参数的规则取消(e.g. 没有成交的 LIMIT FOK 订单或部分成交的 LIMIT IOC 订单)或者被交易所取消(e.g. 强平或维护期间取消的订单)。
  • TRADE_PREVENTION - 订单因 STP 触发而过期。

请查阅 枚举定义 文档获取更多枚举定义。

Listen Key 已过期

当监听 listen key 过期时会发送此事件。此后不会再发送任何事件,直到创建新的 listenKey

正常关闭流时不会推送该事件。

Payload:

{
"e": "listenKeyExpired", // 事件类型
"E": 1699596037418, // 事件时间
"listenKey": "OfYGbUzi3PraNagEkdKuFwUHn48brFsItTdsuiIXrucEvD0rhRXZ7I6URWfE8YE8"
}

事件流已终止

此事件仅在使用 WebSocket API 时才会发生。

当账户数据流被终止时,eventStreamTerminated 会被发送。例如,在您发送 userDataStream.stop 请求或 session.logout 请求之后。

Payload:

{
"event": {
"e": "eventStreamTerminated", // Event Type
"E": 1728973001334 // Event Time
}
}

外部锁定更新

当您的现货钱包余额被外部系统锁定/解锁时 (例如,当用作保证金抵押品时),新事件 externalLockUpdate 将会被发送。

Payload:

{
"e": "externalLockUpdate", // Event Type
"E": 1581557507324, // Event Time
"a": "NEO", // Asset
"d": "10.00000000", // Delta
"T": 1581557507268 // Transaction Time
}