总览
SDK 提供 WebSocket 支持,用于实时报价推送。WebSocket 客户端会负责连接管理、带指数退避的自动重连,以及 ping/pong 保活。 使用 WebSocket 有两种方式:- 高层接口:使用
MakerClient上的streamQuotes/streamQuotesByTicker便捷方法 - 底层接口:直接使用
WSClient,基于事件处理消息
启用 WebSocket
在订阅报价之前,先启用 WebSocket 连接: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 对象描述交换中的一侧:
最佳实践
妥善处理断开连接
妥善处理断开连接
订阅
disconnected 和 reconnecting 事件。WSClient 会以指数退避自动重连,但你仍应处理超出最大尝试次数的情况。尽量使用高层接口
尽量使用高层接口
streamQuotesByTicker 会替你完成路由发现、连接管理和报价分发。只有在需要自定义控制时才使用底层的 WSClient。用完后及时取消订阅
用完后及时取消订阅
不再需要报价时,务必调用
streamQuotes / streamQuotesByTicker 返回的取消订阅函数,以避免内存泄漏和不必要的网络流量。使用报价中的 rfq_id 发起交换
使用报价中的 rfq_id 发起交换
每条报价响应中的
rfq_id 就是传给 initSwap(POST /api/v1/swaps/init)的值。请使用最新的报价,以确保汇率仍然有效。后续步骤
示例
在完整的端到端示例中查看 WebSocket 推送用法
客户端参考
MakerClient 上所有推送方法的完整参考
类型定义
QuoteResponse、QuoteRequest 及其他 WebSocket 类型定义
最佳实践
重连策略与生产环境实践模式