跳转到主要内容
ChainStream 提供强大的实时数据流处理能力,让开发者能够即时接收链上事件、交易和状态变化。本文档介绍 WebSocket 连接、订阅机制和最佳实践。

连接方式

WebSocket 端点

连接认证

建立连接时需要在 URL 中提供 Access Token:
SDK 已内置连接和认证处理,直接调用订阅方法即可:
SDK 会自动检测连接状态,未连接时自动建立连接,无需手动调用 connect()

连接响应

认证成功后会收到如下响应:

订阅类型

ChainStream WebSocket 支持多种数据订阅类型:
完整的订阅类型、参数说明和响应格式请参考 WebSocket API 文档。SDK(client.stream.subscribeTokenCandlessubscribeTokenStatssubscribeTokenTrade 等)已经封装了这些频道字符串,无需手动拼接。

订阅格式示例

取消订阅


消息格式

请求消息

Connect 消息(认证):
Subscribe 消息(订阅):
Unsubscribe 消息(取消订阅):

响应消息

订阅确认:
数据推送:
错误消息:

心跳保活

WebSocket 连接需要定期发送心跳消息以保持活跃。根据 connect 响应中的 ping 字段(通常为 25 秒),在此间隔内发送心跳:
如果在指定时间内(通常为 ping 间隔的 3 倍)未发送任何消息,服务器将主动断开连接。

完整示例


最佳实践

性能优化

使用过滤条件

只订阅需要的数据,减少带宽消耗。使用 CEL 表达式过滤数据。

批量处理

对高频数据进行批量处理而非逐条处理,使用消息队列缓冲。

本地缓存

缓存 Token 信息等静态数据,减少重复处理。

连接复用

单个连接可订阅多个频道,避免创建多个连接。

错误处理

  1. 监听错误事件 — 及时处理连接错误和数据错误
  2. 实现重试机制 — 使用指数退避策略进行重连
  3. 日志记录 — 记录关键事件便于问题排查
  4. 优雅降级 — WebSocket 不可用时切换到轮询

资源管理


相关文档

WebSocket API 参考

完整的订阅类型和参数说明

价格预警机器人

实战:构建价格监控 Bot