​
Overview

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

  • Candle Data
  • Token Series
  • Trade Series
  • Wallet Series
  • Pnl Series

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
}

​
Hot Tokens Stats

Get real-time market statistics for trending tokens.

Subscription Format

dex-ranking-trending-tokens-stats:{chain}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

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
}

​
New Tokens Stats

Get real-time market statistics for newly listed tokens.

Subscription Format

dex-ranking-new-tokens-stats:{chain}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

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
}

​
New Tokens Metadata

Get real-time metadata for newly listed tokens.

Subscription Format

dex-new-tokens-metadata:{chain}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

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
  "n": string,      // Name
  "s": string,      // Symbol
  "iu": string,     // Image URL
  "de": string,     // Description
  "sm": {           // Social media
    "tw": string,   // Twitter
    "tg": string,   // Telegram
    "w": string,    // Website
    "tt": string,   // TikTok
    "dc": string,   // Discord
    "fb": string,   // Facebook
    "gh": string,   // GitHub
    "ig": string,   // Instagram
    "li": string,   // LinkedIn
    "md": string,   // Medium
    "rd": string,   // Reddit
    "yt": string,   // YouTube
    "bb": string    // BitBucket
  },
  "cts": number     // Created timestamp (ms)
}

​
New Tokens

Get real-time information about newly created tokens.

Subscription Format

dex-new-tokens:{chain}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

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
  "n": string,      // Name
  "s": string,      // Symbol
  "de": string,     // Description
  "cts": number     // Created timestamp (ms)
}

​
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
}

​
Token Supply

Get real-time token supply and market cap information.

Subscription Format

dex-token-supply:{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 for better code readability.

{
  "a": string,    // Token address
  "s": number,    // Supply
  "mc": number,   // Market cap in USD
  "ts": number    // Timestamp
}

​
Token Liquidity

Get real-time token liquidity 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

Response Data Format

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

{
  "a": string,    // Token address
  "t": string,    // Metric type
  "v": number,    // Value
  "ts": number    // Timestamp
}

​
Token Trade

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

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
}

​
Wallet PnL Data

Get real-time wallet profit and loss (PnL) statistics.

Subscription Format

dex-wallet-pnl-list:{chain}_{walletAddress}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

​
walletAddress
string
required

Wallet address

Response Data Format

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

{
  "a": string,     // Wallet address
  "bs": number,    // Number of buys
  "ba": number,    // Buy amount
  "baiu": number,  // Buy amount in USD
  "abpiu": number, // Average buy price in USD
  "sa": number,    // Sell amount
  "saiu": number,  // Sell amount in USD
  "ss": number,    // Number of sells
  "ws": number,    // Number of wins
  "wr": number,    // Win ratio
  "piu": number,   // PnL in USD
  "apiu": number,  // Average PnL in USD
  "pr": number,    // PnL ratio
  "pd": number,    // Profitable days
  "ld": number,    // Losing days
  "ts": number,    // Number of tokens traded
  "r": string      // Resolution
}

​
DEX Pool Balance

Get real-time DEX pool balance information.

Subscription Format

dex-pool-balance:{chain}_{poolAddress}

Parameters

​
chain
string
required

Blockchain name, e.g., sol

​
poolAddress
string
required

Pool address

Response Data Format

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

{
  "a": string,     // Pool address
  "taa": string,   // Token A address
  "taliu": number, // Token A liquidity in USD
  "tba": string,   // Token B address
  "tbliu": number  // Token B liquidity in USD
}

​
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
  }
}