Skip to main content
ChainStream provides powerful real-time data streaming capabilities, allowing developers to instantly receive on-chain events, transactions, and state changes. This document covers WebSocket connection, subscription mechanisms, and best practices.

Connection

WebSocket Endpoint

Authentication

Provide the Access Token in the URL when establishing a connection:

Connection Response

Upon successful authentication, you’ll receive a response like:

Subscription Types

ChainStream WebSocket supports multiple data subscription types:
For complete subscription types, parameters, and response formats, see the WebSocket API reference. The SDKs (client.stream.subscribeTokenCandles, subscribeTokenStats, subscribeTokenTrade, …) wrap these channel strings so you don’t have to build them by hand.

Subscription Format Examples

Unsubscribe


Message Format

Request Messages

Connect Message (Authentication):
Subscribe Message:
Unsubscribe Message:

Response Messages

Subscription Confirmation:
Data Push:
Error Message:

Heartbeat

WebSocket connections require periodic heartbeat messages to stay active. Based on the ping field in the connect response (usually 25 seconds), send heartbeats within this interval:
If no messages are sent within the specified time (typically 3x the ping interval), the server will disconnect.

Complete Example


Best Practices

Performance Optimization

Use Filters

Subscribe only to needed data to reduce bandwidth. Use CEL expressions to filter data.

Batch Processing

Batch process high-frequency data instead of processing one by one. Use message queues for buffering.

Local Caching

Cache static data like token information to reduce repeated processing.

Connection Reuse

A single connection can subscribe to multiple channels. Avoid creating multiple connections.

Error Handling

  1. Listen for error events — Handle connection and data errors promptly
  2. Implement retry mechanism — Use exponential backoff for reconnection
  3. Log recording — Record key events for troubleshooting
  4. Graceful degradation — Switch to polling when WebSocket is unavailable

Resource Management


WebSocket API Reference

Complete subscription types and parameters

Price Alert Bot

Hands-on: Build a price monitoring bot