Skip to main content

WebSocket Streams

ZTDX WebSocket provides real-time market data (Public Streams) and private account updates (Private Streams). All push notifications are managed via a subscribe/unsubscribe mechanism.

Basic Connection​

  • Endpoint: wss://api.ztdx.io/ws
  • Heartbeat: It is recommended to send a ping message every 30 seconds to keep the connection alive.

Subscribing & Unsubscribing​

All subscriptions use a consistent message format:

Subscribe Channel​

{
  "type": "subscribe",
  "channel": "ticker:BTCUSDT"
}

Unsubscribe Channel​

{
  "type": "unsubscribe",
  "channel": "ticker:BTCUSDT"
}

Public Streams​

Public channels do not require authentication. Upon successful subscription, the server typically pushes an initial snapshot of the current data, followed by incremental or full updates based on the update frequency.

1. Market Tickers (Ticker)​

Pushes 24-hour price changes, mark price, index price, and open interest statistics.

  • Channel Format: ticker:{symbol}
  • Update Frequency: Every 2 seconds

Data Payload:

{
  "type": "ticker",
  "symbol": "BTCUSDT",
  "last_price": "65432.10",
  "mark_price": "65433.00",
  "index_price": "65431.50",
  "price_change_24h": "1200.50",
  "price_change_percent_24h": "1.87",
  "volume_24h": "12345.6789",
  "open_interest_long": "5000.0000",
  "open_interest_short": "4200.0000",
  "funding_rate_1h": "+0.0050%"
}

2. Order Book (Orderbook)​

Pushes the top 20 levels of the order book and the corresponding contract amounts.

  • Channel Format: orderbook:{symbol}
  • Update Frequency: Every 500 ms

Data Payload:

{
  "type": "orderbook",
  "symbol": "BTCUSDT",
  "bids": [
    { "price": "65430.00", "size": "1.2" },
    { "price": "65429.50", "size": "0.8" }
  ],
  "asks": [
    { "price": "65431.00", "size": "0.5" },
    { "price": "65431.50", "size": "1.0" }
  ],
  "timestamp": 1711000000000
}

3. Candlesticks (Kline)​

Pushes real-time updates for candlestick data for a specific interval.

  • Channel Format: kline:{symbol}:{interval}
  • Supported Intervals: 1m, 3m, 5m, 15m, 30m, 1h, 4h, 1d
  • Update Frequency: Real-time (whenever the candlestick has a delta change)

Data Payload:

{
  "type": "kline",
  "channel": "kline:BTCUSDT:5m",
  "data": {
    "time": 1711000000000,
    "open": "65400.00",
    "high": "65500.00",
    "low": "65350.00",
    "close": "65432.10",
    "volume": "123.456",
    "is_final": false // true indicates the candle has closed
  }
}

Private Streams​

Private streams require authentication first. See WebSocket General Info for details.

1. Position Updates (Positions)​

  • Channel Format: positions
  • Content: Real-time push of all position states, PnL, and liquidation prices for the user.

2. Order Updates (Orders)​

  • Channel Format: orders
  • Content: Real-time push of order status changes (filled, canceled, expired).

3. Balance Updates (Balance)​

  • Channel Format: balance
  • Content: Push of account asset changes, including available balance and frozen balance.