Public WebSocket#

General Push Rules#

Connection url#

Public channels do not require login.

Connection and Heartbeat Rules#

Each IP address is limited to 3 WebSocket connection attempts per second.

WebSocket Operation Request Rate Limits#

WebSocket operation requests use a token-bucket mechanism. Rate limiting is applied per WebSocket connection, specifically per Netty Channel.

Each complete WebSocket operation request consumes 1 token. If a subscribe or unsubscribe request contains multiple channels or products in args[], it is still counted as one request and consumes only 1 token.

Tokens are continuously replenished at a rate of 480 per hour. The bucket is capped at 480 tokens and does not reset at the beginning of each hour. A single connection can therefore send up to 480 operation requests in a burst after it is established, after which approximately one token is restored every 7.5 seconds.

All subscribe and unsubscribe operations on the same connection share the same token bucket. They are not calculated separately for business channels such as tickers or trades.

Idle Disconnect and Heartbeat#

The server automatically disconnects a connection if no subscription is created within 30 seconds after the connection is established, or if the server does not push any data for 30 consecutive seconds after a subscription is created.

After receiving each message, the client should start a timer with a duration shorter than 30 seconds. If no new message is received before the timer expires, the client should send the text string ping and expect the server to return the text string pong. If pong is not received within the expected period, the client should report an error or establish a new connection.

Data Type Conventions#

Only three data types are used for parameters:

• String: used for most parameters.
• Boolean: used for Boolean values.
• Integer: used only for exceptions such as sequence numbers.

All numeric values, including prices, quantities, and timestamps, are returned as String. Timestamps use Unix epoch milliseconds and are represented as String.

Scientific notation is not used for numeric values. For example, use 0.000001 instead of 1E-6. Decimal values do not include insignificant trailing zeros; use 5 instead of 5.0.

Subscribe#

Request Format

{
  "id": "1512",
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-tickers",
      "assetId": "1"
    }
  ]
}

A single request can subscribe to one or more channels. The total size of the channel objects in args must not exceed 64 KB.

Request Parameters

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "exchangeos-tickers",
    "assetId": "1234"
  },
  "connId": "accb8e21"
}

Response Parameters

Unsubscribe#

Request Example

{
  "op": "unsubscribe",
  "args": [
    {
      "channel": "exchangeos-tickers",
      "assetId": "1234"
    }
  ]
}

Request Parameters

Response Example

{
  "event": "unsubscribe",
  "arg": {
    "channel": "exchangeos-tickers",
    "assetId": "1234"
  },
  "connId": "d0b44253"
}

Response Parameters

Notice Message (event = notice)#

Approximately 60 seconds before a scheduled service upgrade, the server sends a notice message instructing the client to reconnect.

{
  "event": "notice",
  "code": "64008",
  "msg": "The connection will soon be closed for a service upgrade. Please reconnect.",
  "connId": "a4d3ae55"
}

Ticker Channel exchangeos-tickers#

Pushes last trade, best bid/ask, and 24-hour market statistics for one spot or perp product whenever data changes.

Subscribe with:

{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-tickers",
      "assetId": "1234"
    }
  ]
}

Trade Channel exchangeos-trades#

Pushes recent product trades at most once per 100 ms. Each aggregation contains at most 20 raw trades. Trades are aggregated only when their block, asset ID, price, side, and consecutive trade IDs match.

Trade Candle Channel exchangeos-candle{bar}#

Pushes trade OHLCV candles when data changes. Replace {bar} with an enabled interval: 1m, 5m, 15m, 1H, 4H, or 1D.

Each data[] item is:

[ts, open, high, low, close, vol, volCcy, volCcyQuote, confirm]

confirm is "0" for an unclosed candle and "1" for a closed candle.

{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-candle1H",
      "assetId": "1234"
    }
  ]
}

Mark Price Candle Channel exchangeos-mark-price-candle{bar}#

Pushes mark-price OHLC candles without volume data. Supported intervals are 1s, 1m, 5m, 15m, 1H, 4H, and 1D.

Each data[] item is:

[ts, open, high, low, close, confirm]

Use channel + assetId + ts as the candle key. Unclosed candles can be pushed repeatedly and must be overwritten with the latest version.

{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-mark-price-candle1s",
      "assetId": "2"
    }
  ]
}

Index Ticker Channel exchangeos-index-tickers#

Pushes the latest index price and 24-hour statistics. It pushes at most once per second on change, and at least once per minute when unchanged.

{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-index-tickers",
      "assetId": "1234"
    }
  ]
}

Index Candle Channel exchangeos-index-candle{bar}#

Pushes index OHLC candles without volume. Supported intervals are 1m, 5m, 15m, 1H, 4H, and 1D.

Each data[] item is:

[ts, open, high, low, close, confirm]

{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-index-candle1H",
      "assetId": "1234"
    }
  ]
}

Funding Rate Channel exchangeos-funding-rate#

Pushes the current predicted funding rate and next funding information for perpetual contracts, normally every 5 seconds. fundingTime is not returned by WebSocket; use REST GET /market/funding-rate when it is required.

{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-funding-rate",
      "assetId": "2"
    }
  ]
}

Instrument Channel exchangeos-instruments#

Subscribes by product type: spot or perp. The channel pushes the full instrument list for the subscribed instType initially and whenever instrument configuration changes.

Changes include product-state changes, precision changes, and listing or expiry-time changes. A delisting notice is pushed approximately 30 minutes before formal delisting.

Before activation, top-level precision fields retain their old values and upcChg contains the future value. After activation, the top-level field contains the new value and upcChg is an empty array.

{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-instruments",
      "instType": "perp"
    }
  ]
}

Open Interest Channel exchangeos-open-interest#

Pushes perpetual open interest when updated, at most once every 3 seconds.

{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-open-interest",
      "assetId": "1234"
    }
  ]
}

Price Limit Channel exchangeos-price-limit#

Pushes the maximum buy limit price buyLmt and minimum sell limit price sellLmt. There is no initial push. Updates are sent at most once per second when the price band changes; no update is sent while unchanged. Empty strings mean that no valid price band is available.

{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-price-limit",
      "assetId": "1234"
    }
  ]
}

Order Book Channels#

exchangeos-books#

Full order book. The initial payload is action: "snapshot"; later payloads are action: "update".

Each level is [price, size, orderCount]. In incremental updates, size: "0" removes the level.

Validate continuity strictly:

1. The first update prevSeqId must equal the snapshot seqId.
2. Every later update prevSeqId must equal the preceding seqId.
3. Re-subscribe if the sequence is discontinuous.
4. A heartbeat frame may be sent after 60 seconds of no change, with seqId == prevSeqId.

exchangeos-books5#

Top-five full book snapshots. Pushed when the book changes. It has no incremental semantics and does not require sequence validation.

exchangeos-bbo-tbt#

A full one-level best-bid-and-offer snapshot. It is not incremental. It pushes at most once per 100 ms on BBO change and may send a fallback push about every 60 seconds while unchanged.

Estimated Perpetual Settlement Price Channel exchangeos-estimated-price#

Pushes estimated settlement prices for delisting perpetual products. A current snapshot is sent after successful subscription. Price updates use an approximately 200 ms minimum aggregation window; only the latest update for the same assetId is emitted within that window.

settlePx is an empty string when no valid estimated settlement price exists. No periodic market heartbeat is sent while unchanged; keep the connection alive with the public ping / pong mechanism.

Changes to expTime, settleAt, status, settlePx, settleType, or other public fields trigger a full object push. The currently documented payload example explicitly defines the fields below.

{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-estimated-price",
      "assetId": "9102"
    }
  ]
}