​
Overview

ChainStream DEX WebSocket API provides real-time data subscription services, supporting the following data types:

  • Candle Data
  • Token Stats
  • Trade Events
  • Wallet Trade Event
  • Wallet Balance
  • Token Holders

Base URL

wss://realtime-dex.chainstream.io/connection/websocket

​
Quick Start

​
1. Establish Connection

First, create a WebSocket connection and authenticate:

const ws = new WebSocket("wss://realtime-dex.chainstream.io/connection/websocket");

ws.onopen = () => {
  // Send authentication message
  ws.send(JSON.stringify({
    type: "auth",
    token: "YOUR_ACCESS_TOKEN"
  }));
};

​
2. Subscribe to Data

Choose the data type you want to subscribe to:

// Example of subscribing to candle data
ws.send(JSON.stringify({
  type: "subscribe",
  channel: "dex-candle:sol_6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN_1m"
}));

​
3. Handle Data

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received data:', data);
};

​
Data Subscriptions

​
Candles Data

Get real-time price movement data for tokens.

Subscription Format

dex-candle:{chain}_{tokenAddress}_{resolution}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

​
tokenAddress
string
required

Token contract address, e.g., 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN

​
resolution
string
required

Candle period, supports: 1m, 5m, 15m, 1h, 4h, 1d

Response Data Format

WebSocket API returns shortened field names to optimize transmission efficiency, while SDK returns full field names to improve code readability.

{
  "o": number,    // Open price
  "c": number,    // Close price
  "h": number,    // High price
  "l": number,    // Low price
  "v": number,    // Volume
  "r": string,    // Resolution
  "t": number     // Timestamp
}

​
Token Stats

Get real-time market statistics for tokens.

Subscription Format

dex-token-stats:{chain}_{tokenAddress}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

​
tokenAddress
string
required

Token contract address, e.g., 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN

Response Data Format

WebSocket API returns shortened field names to optimize transmission efficiency, while SDK returns full field names to improve code readability.

{
  "a": string,      // Token address
  "t": number,      // Timestamp
  "b1m": number,    // Buys in 1m
  "s1m": number,    // Sells in 1m
  "be1m": number,   // Buyers in 1m
  "se1m": number,   // Sellers in 1m
  "bviu1m": number, // Buy volume in USD 1m
  "sviu1m": number, // Sell volume in USD 1m
  "p1m": number,    // Price 1m
  "b5m": number,    // Buys in 5m
  "s5m": number,    // Sells in 5m
  "be5m": number,   // Buyers in 5m
  "se5m": number,   // Sellers in 5m
  "bviu5m": number, // Buy volume in USD 5m
  "sviu5m": number, // Sell volume in USD 5m
  "p5m": number,    // Price 5m
  "b15m": number,   // Buys in 15m
  "s15m": number,   // Sells in 15m
  "be15m": number,  // Buyers in 15m
  "se15m": number,  // Sellers in 15m
  "bviu15m": number,// Buy volume in USD 15m
  "sviu15m": number,// Sell volume in USD 15m
  "p15m": number,   // Price 15m
  "b30m": number,   // Buys in 30m
  "s30m": number,   // Sells in 30m
  "be30m": number,  // Buyers in 30m
  "se30m": number,  // Sellers in 30m
  "bviu30m": number,// Buy volume in USD 30m
  "sviu30m": number,// Sell volume in USD 30m
  "p30m": number,   // Price 30m
  "b1h": number,    // Buys in 1h
  "s1h": number,    // Sells in 1h
  "be1h": number,   // Buyers in 1h
  "se1h": number,   // Sellers in 1h
  "bviu1h": number, // Buy volume in USD 1h
  "sviu1h": number, // Sell volume in USD 1h
  "p1h": number,    // Price 1h
  "b4h": number,    // Buys in 4h
  "s4h": number,    // Sells in 4h
  "be4h": number,   // Buyers in 4h
  "se4h": number,   // Sellers in 4h
  "bviu4h": number, // Buy volume in USD 4h
  "sviu4h": number, // Sell volume in USD 4h
  "p4h": number,    // Price 4h
  "b24h": number,   // Buys in 24h
  "s24h": number,   // Sells in 24h
  "be24h": number,  // Buyers in 24h
  "se24h": number,  // Sellers in 24h
  "bviu24h": number,// Buy volume in USD 24h
  "sviu24h": number,// Sell volume in USD 24h
  "p24h": number,   // Price 24h
  "p": number       // Current price
}

​
Trade Events

Get real-time token trading events.

Subscription Format

dex-trades:{chain}_{tokenAddress}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

​
tokenAddress
string
required

Token contract address, e.g., 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN

Response Data Format

WebSocket API returns shortened field names to optimize transmission efficiency, while SDK returns full field names to improve code readability.

{
  "bwa": string,     // Maker address
  "ba": number,      // Base token amount
  "sa": number,      // Quote token amount
  "swa": string,     // Quote token address
  "bais": number,    // USD amount
  "t": number,       // Timestamp
  "k": string,       // Event type
  "h": string,       // Transaction hash
  "a": string        // Token address
}

​
Wallet Trade Event

Get real-time wallet trading event.

Subscription Format

dex-wallet-trade:{chain}_{walletAddress}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

​
walletAddress
string
required

Token contract address, e.g., GDekof7TtgeBKJtoVpkvzPin5mvhxSDyoUY2c1FK1T3i

Response Data Format

WebSocket API returns shortened field names to optimize transmission efficiency, while SDK returns full field names to improve code readability.

{
  "bwa": string,     // Maker address
  "ba": number,      // Base token amount
  "sa": number,      // Quote token amount
  "swa": string,     // Quote token address
  "bais": number,    // USD amount
  "t": number,       // Timestamp
  "k": string,       // Event type
  "h": string,       // Transaction hash
  "a": string        // Token address
}

​
Wallet Balance

Get real-time wallet balance information.

Subscription Format

dex-wallet-balance:{chain}_{walletAddress}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

​
walletAddress
string
required

Wallet address, e.g., HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH

Response Data Format

WebSocket API returns shortened field names to optimize transmission efficiency, while SDK returns full field names to improve code readability.

{
  "a": string,      // Wallet address
  "ta": string,     // Token address
  "tpiu": number,   // Token price in USD
  "t": number,      // Timestamp
  "ba": number,     // Buy amount
  "baiu": number,   // Buy amount in USD
  "bs": number,     // Number of buys
  "sa": number,     // Sell amount
  "saiu": number,   // Sell amount in USD
  "ss": number,     // Number of sells
  "abp": number,    // Average buy price
  "asp": number,    // Average sell price
  "upiu": number,   // Unrealized profit in USD
  "upr": number,    // Unrealized profit ratio
  "rpiu": number,   // Realized profit in USD
  "rpr": number,    // Realized profit ratio
  "trpiu": number,  // Total realized profit in USD
  "trr": number     // Total realized profit ratio
}

​
Token Holders Statistics

Get real-time token holder statistics.

Subscription Format

dex-token-general-stat-num:{chain}_{tokenAddress}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

​
tokenAddress
string
required

Token contract address, e.g., 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN

Response Data Format

WebSocket API returns shortened field names to optimize transmission efficiency, while SDK returns full field names to improve code readability.

{
  "a": string,    // Token address
  "v": number,    // Number of holders
  "ts": number    // Timestamp
}

​
Usage Examples

const streamApi = new StreamApi(context);

// Subscribe to candle data
streamApi.subscribeTokenCandles({
  chain: "sol",
  tokenAddress: "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
  resolution: "1m",
  callback: (data) => {
    console.log("Candle data:", data);
  }
});

// Subscribe to wallet balance
streamApi.subscribeWalletBalance({
  chain: "sol",
  walletAddress: "YOUR_WALLET_ADDRESS",
  callback: (data) => {
    console.log("Wallet balance:", data);
  }
});

​
Reconnection Strategy

Recommended to use exponential backoff for reconnection:

function reconnect(attempt) {
  const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
  setTimeout(() => {
    connect();
  }, delay);
}

​
Usage Limits

LimitValueDescription
Maximum Subscriptions100/connectionExcess will be rejected
Message Size100KBExcess will be truncated
Heartbeat Interval30 secondsRegular heartbeat required

​
Best Practices

  1. Connection Management

    • Maintain a single WebSocket connection
    • Implement automatic reconnection
    • Send regular heartbeats

  2. Error Handling

    • Implement complete error handling
    • Log detailed error information
    • Use exponential backoff for reconnection

  3. Performance Optimization

    • Control subscription quantity
    • Implement message queue mechanism
    • Clean up unused subscriptions

​
Complete Example

class DexWebSocket {
  private ws: WebSocket;
  private reconnectAttempts = 0;
  private maxReconnectAttempts = 5;
  private messageHandlers = new Map<string, Set<(data: any) => void>>();

  constructor(
    private url: string,
    private accessToken: string
  ) {
    this.connect();
  }

  private connect() {
    this.ws = new WebSocket(this.url);
    
    this.ws.onopen = () => {
      // Send authentication
      this.authenticate();
      // Resubscribe
      this.resubscribe();
    };

    this.ws.onmessage = (event) => {
      this.handleMessage(JSON.parse(event.data));
    };

    this.ws.onclose = () => {
      this.reconnect();
    };
  }

  private authenticate() {
    this.send({
      type: "auth",
      token: this.accessToken
    });
  }

  public subscribe(channel: string, handler: (data: any) => void) {
    // Subscription implementation
  }

  public unsubscribe(channel: string) {
    // Unsubscribe implementation
  }
}

Was this page helpful?