Skip to main content

总览

SDK 提供 WebSocket 支持,用于实时报价推送。WebSocket 客户端会负责连接管理、带指数退避的自动重连,以及 ping/pong 保活。 使用 WebSocket 有两种方式:
  1. 高层接口:使用 MakerClient 上的 streamQuotes / streamQuotesByTicker 便捷方法
  2. 底层接口:直接使用 WSClient,基于事件处理消息

启用 WebSocket

在订阅报价之前,先启用 WebSocket 连接:
URL 中包含一个客户端 ID,用于会话跟踪。enableWebSocket 方法返回一个 WSClient 实例。
本页示例使用 signet,它同时也是 SDK 的默认环境。请让 WebSocket URL 与 baseUrl 指向的环境保持一致。参阅 可用环境

高层接口

streamQuotesByTicker / stream_quotes_by_ticker

订阅报价最简单的方式,会自动发现路由并开始推送。
选项:

streamQuotes / stream_quotes

针对指定路由(代码与分层协议)订阅报价。

streamQuotesForAllRoutes / stream_quotes_for_all_routes

同时订阅两个代码之间所有可用路由的报价。

getAvailableRoutes / get_available_routes

在订阅之前,先查询某个交易对可用的路由。

底层 WSClient 接口

如需完全控制,可直接使用 WSClient

连接

事件

使用 on / off 订阅事件:

请求报价

Ping 与保活

WSClient 会按配置的间隔自动向服务端发送 ping。你也可以手动发送:

配置

WSClient 支持以下配置选项: 重连采用指数退避:delay * 2^attempt

WebSocket 协议

WebSocket 使用 JSON 消息协议:

消息类型

QuoteResponse 字段

每个 SwapLegData 对象描述交换中的一侧:

最佳实践

订阅 disconnectedreconnecting 事件。WSClient 会以指数退避自动重连,但你仍应处理超出最大尝试次数的情况。
streamQuotesByTicker 会替你完成路由发现、连接管理和报价分发。只有在需要自定义控制时才使用底层的 WSClient
不再需要报价时,务必调用 streamQuotes / streamQuotesByTicker 返回的取消订阅函数,以避免内存泄漏和不必要的网络流量。
每条报价响应中的 rfq_id 就是传给 initSwapPOST /api/v1/swaps/init)的值。请使用最新的报价,以确保汇率仍然有效。

后续步骤

示例

在完整的端到端示例中查看 WebSocket 推送用法

客户端参考

MakerClient 上所有推送方法的完整参考

类型定义

QuoteResponse、QuoteRequest 及其他 WebSocket 类型定义

最佳实践

重连策略与生产环境实践模式