Channels & Subscriptions

The core of the WebSocket API is to receive specific data streams by subscribing to different channels.

1. Subscribe and Unsubscribe Messages

To receive data, you need to send a subscribe message to the server. If you no longer need a data stream, you can send an unsubscribe message.

• Example Subscribe Request:

  {
    "op": "subscribe",
    "args": [
      {"channel": "tickers", "instId": "BTC-USDT-SWAP"},
      {"channel": "books", "instId": "ETH-USDT-SWAP"}
    ]
  }

• Server Success Response:

  • The server will reply with a separate confirmation message for each subscription request in the args array.

  {
    "event": "subscribe",
    "arg": {
      "channel": "tickers",
      "instId": "BTC-USDT-SWAP"
    },
    "ts": ...
  }

• Example Unsubscribe Request:

  {
    "op": "unsubscribe",
    "args": [
      {"channel": "tickers", "instId": "BTC-USDT-SWAP"}
    ]
  }

• Server Success Response:

  {
    "event": "unsubscribe",
    "arg": {
      "channel": "tickers",
      "instId": "BTC-USDT-SWAP"
    },
    "ts": ...
  }

2. Public Channels

Subscriptions to these channels do not require authentication.

• tickers: Tickers channel for instrument price information.

  • Argument: instId

  • Example: {"channel": "tickers", "instId": "BTC-USDT-SWAP"}

• books: Order book channel.

  • Note: Upon first subscription, a full snapshot is pushed, followed by incremental updates.

  • Argument: instId

  • Example: {"channel": "books", "instId": "BTC-USDT-SWAP"}

• trades: Trades channel for individual trade data.

  • Argument: instId

  • Example: {"channel": "trades", "instId": "BTC-USDT-SWAP"}

3. Private Channels

You must successfully authenticate (login) before subscribing to these channels.

• account: Account balance channel.

  • Note: Pushes updates when your account balance changes.

  • Argument: ccy (optional, to specify a currency)

  • Example: {"channel": "account", "ccy": "USDT"} or {"channel": "account"}

• positions: Positions channel.

  • Note: Pushes updates when your position changes.

  • Arguments: instType (instrument type), instId (optional)

  • Example: {"channel": "positions", "instType": "SWAP"}

• orders: Orders channel.

  • Note: Pushes updates when the status of your orders changes.

  • Arguments: instType (instrument type), instId (optional)

  • Example: {"channel": "orders", "instType": "SWAP"}

---