跳到主要内容

WebSocket 行情推送

ZTDX WebSocket 提供实时行情数据推送（Public Streams）和私有数据更新（Private Streams）。所有推送均通过订阅/取消订阅机制进行管理。

基础连接​

  • 地址: wss://api.ztdx.io/ws
  • 心跳: 建议每 30 秒发送一次 ping 消息以保持连接。

订阅与退订​

订阅任何频道均采用统一的消息格式：

订阅频道​

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

取消订阅​

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

公共频道 (Public Streams)​

公共频道无需认证即可订阅。订阅成功后，服务端通常会立推送一份当前数据的 快照，随后根据更新频率推送增量或完整更新。

1. 实时行情 (Ticker)​

推送 24 小时价格变动、标记价格、指数价格及持仓统计。

  • 频道格式: ticker:{symbol}
  • 推送频率: 每 2 秒

数据负载:

{
  "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. 订单簿深度 (Orderbook)​

推送买卖盘前 20 档深度及其对应的合约数量。

  • 频道格式: orderbook:{symbol}
  • 推送频率: 每 500 毫秒

数据负载:

{
  "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. K线数据 (Kline)​

推送特定周期内的 K 线数据更新。

  • 频道格式: kline:{symbol}:{interval}
  • 支持周期: 1m, 3m, 5m, 15m, 30m, 1h, 4h, 1d
  • 推送频率: 实时 (每当 K 线有变动时)

数据负载:

{
  "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 时表示该根 K 线已结束
  }
}

私有频道 (Private Streams)​

私有频道需要先通过 auth 消息完成认证。详情请参阅 WebSocket 基本信息。

1. 持仓更新 (Positions)​

  • 频道格式: positions
  • 内容: 推送用户的所有持仓状态、盈亏及强平价。

2. 订单更新 (Orders)​

  • 频道格式: orders
  • 内容: 实时推送用户订单的状态变更（成交、撤销、已过期）。

3. 余额更新 (Balance)​

  • 频道格式: balance
  • 内容: 推送账户各资产的可用余额与冻结余额变动。