Public WebSocket#
General Push Rules#
Connection url#
| Environment | Public channel URL |
|---|---|
| Production | wss://{public-host}/ws/v5/public |
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.
| Rule | Limit |
|---|---|
| Rate-limit scope | Single WebSocket connection |
| Token-bucket capacity | 480 tokens |
| Initial tokens when the connection is established | 480 tokens |
| Token recovery rate | 480 tokens per hour, approximately 1 token every 7.5 seconds |
| Cost per request | 1 token |
| Requests included in the limit | Client operation requests such as login, subscribe, and unsubscribe |
| Separate calculation by channel | No. All channels on the same connection share one token bucket. |
| Shared by IP | No. Different connections established from the same IP have independent token buckets. |
| Reconnection | A newly established connection receives a new token bucket with the full initial capacity of 480 tokens. |
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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | String | No | A unique message identifier aligned with V5. The client provides this value, and the server returns it unchanged so the request can be matched. It must contain only letters and numbers and be 1–32 characters long. |
op | String | Yes | Operation type, fixed as subscribe. |
args | Array of Objects | Yes | List of channels to subscribe to. |
> channel | String | Yes | Channel name. |
> assetId | String | No | Product ID. |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "exchangeos-tickers",
"assetId": "1234"
},
"connId": "accb8e21"
}
Response Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
event | String | Yes | Event type. The value is subscribe or error. |
arg | Object | No | Subscription channel information. |
> channel | String | Yes | Channel name. |
> assetId | String | No | Product ID. |
code | String | No | Error code returned when the request fails. |
msg | String | No | Error message returned when the request fails. |
connId | String | Yes | WebSocket connection ID. |
Unsubscribe#
Request Example
{
"op": "unsubscribe",
"args": [
{
"channel": "exchangeos-tickers",
"assetId": "1234"
}
]
}
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
op | String | Yes | Operation type, fixed as unsubscribe. |
args | Array of Objects | Yes | List of channels to unsubscribe from. |
> channel | String | Yes | Channel name. |
> assetId | String | No | Product ID. |
Response Example
{
"event": "unsubscribe",
"arg": {
"channel": "exchangeos-tickers",
"assetId": "1234"
},
"connId": "d0b44253"
}
Response Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
event | String | Yes | Event type. The value is unsubscribe or error. |
arg | Object | No | Unsubscription channel information. |
> channel | String | Yes | Channel name. |
> assetId | String | No | Product ID. |
code | String | No | Error code. |
msg | String | No | Error message. |
connId | String | Yes | WebSocket connection ID. |
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"
}
]
}
| Field | Type | Description |
|---|---|---|
assetId | String | Product ID. |
lastPx | String | Latest trade price. |
lastSz | String | Latest trade quantity. |
askPx | String | Best ask price. |
askSz | String | Best ask quantity. |
bidPx | String | Best bid price. |
bidSz | String | Best bid quantity. |
open24h | String | 24-hour opening price. |
high24h | String | 24-hour highest price. |
low24h | String | 24-hour lowest price. |
volCcy24h | String | 24-hour trading amount denominated in the quote currency. |
vol24h | String | 24-hour trading volume denominated in the base currency. |
sodUtc0 | String | Opening price for the day in the UTC+0 time zone. |
sodUtc8 | String | Opening price for the day in the UTC+8 time zone. |
ts | String | Data update timestamp in Unix milliseconds. |
lastPxUsd | String | USD value of the latest trade price. |
Push Example
{
"arg": { "channel": "exchangeos-tickers", "assetId": "1234" },
"data": [
{
"assetId": "1234",
"lastPx": "97520.5",
"lastPxUsd": "97320.5",
"lastSz": "0.0012",
"askPx": "97521.0",
"askSz": "1.5234",
"bidPx": "97520.0",
"bidSz": "2.3041",
"open24h": "96800.0",
"high24h": "98100.3",
"low24h": "96210.5",
"volCcy24h": "582310412.56",
"vol24h": "5980.23",
"sodUtc0": "96950.0",
"sodUtc8": "97010.2",
"ts": "1710249600000"
}
]
}
Trade Channel exchangeos-trades#
Channel Description
Pushes the latest trades for a specified product.
Trade Aggregation Logic
exchangeos-trades processes trade data independently for each assetId.
Consecutive trades are merged into a single aggregated record only when all of the following conditions are met:
- The trade price is the same.
- The buy/sell direction is the same.
- The timestamp is the same to millisecond precision.
- The price precision and quantity precision are the same.
The trade quantity is accumulated after aggregation. If any condition differs, the system creates a new record.
Push Rules
- The system normally checks trade data every 100 milliseconds.
- Each push returns at most the latest 20 aggregated records.
- Records in the
dataarray are ordered from newest to oldest, with the most recently received trade first. - Each record in
datamay represent one original trade or the aggregated result of multiple adjacent trades that meet all of the conditions above. assetIdappears only in the first element of thedataarray. All trades in the same message frame belong to the sameassetId, which is identified by the outerarg.assetId.
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-trades",
"assetId": "1234"
}
]
}
| Field | Type | Description |
|---|---|---|
assetId | String | Product ID. Appears only in the first element of the data array. |
fId | String | Trade ID of the first original trade in the aggregation segment, inclusive. |
lId | String | Trade ID of the last original trade in the aggregation segment, inclusive. The first character is a lowercase l. Trade IDs within the aggregation segment are guaranteed to be consecutive from fId to lId. |
px | String | Common execution price of all trades in the aggregation segment. |
sz | String | Total trade quantity of the aggregation segment. |
side | String | Trade direction. Possible values: buy or sell. |
ts | String | Trade timestamp in Unix milliseconds. All trades in the same aggregated record have the same ts; trades with different ts values are not aggregated. |
{
"arg": {
"channel": "exchangeos-trades",
"assetId": "1802"
},
"data": [
{
"assetId": "1802",
"fId": "161999",
"lId": "161999",
"px": "94.546",
"sz": "1.05",
"side": "buy",
"ts": "1793087643641"
},
{
"fId": "161998",
"lId": "161998",
"px": "94.54",
"sz": "1.17",
"side": "buy",
"ts": "1793087643641"
}
]
}
Trade Candle Channel exchangeos-candle{bar}#
Pushes trade candlestick data whenever the data changes. Replace {bar} with the desired interval.
Supported intervals
1m, 5m, 15m, 1H, 4H, 1D
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-candle1H",
"assetId": "1234"
}
]
}
Each element in data[] is a fixed-length array containing nine string values:
| Index | Field | Description |
|---|---|---|
0 | ts | Candle start time in Unix epoch milliseconds. |
1 | open | Opening price. |
2 | high | Highest price. |
3 | low | Lowest price. |
4 | close | Closing price. |
5 | vol | Trading volume. |
6 | volCcy | Volume denominated in the volume currency. |
7 | volCcyQuote | Trading amount denominated in the quote currency. |
8 | confirm | 0: candle is not closed; 1: candle is closed. |
{
"arg": {
"channel": "exchangeos-candle1H",
"assetId": "1234"
},
"data": [
[
"1710000000000",
"50000",
"51000",
"49500",
"50500",
"1234.5",
"617250000",
"617250000",
"0"
]
]
}
Mark Price Candle Channel exchangeos-mark-price-candle{bar}#
Channel Description
Pushes mark-price candlesticks for a specified product. Candlestick prices are derived from the mark price and do not include trading volume.
Channel Name
The channel name consists of exchangeos-mark-price-candle followed by the candle interval. Examples:
exchangeos-mark-price-candle1sexchangeos-mark-price-candle1mexchangeos-mark-price-candle15mexchangeos-mark-price-candle1H
Supported Intervals (bar)
1s, 1m, 5m, 15m, 1H, 4H, 1D
Subscription Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | String | Yes | Channel name in the format exchangeos-mark-price-candle{bar}, where {bar} is the candle interval. |
assetId | String | Yes | Product ID. Only perp products are supported. |
Subscription Examples
Subscribe to 1-second mark-price candlesticks for assetId=2:
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-mark-price-candle1s",
"assetId": "2"
}
]
}
Subscribe to 15-minute mark-price candlesticks for assetId=2:
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-mark-price-candle15m",
"assetId": "2"
}
]
}
Push Structure
| Field | Type | Description |
|---|---|---|
arg | Object | Subscription channel information. |
arg.channel | String | Channel name, including the candle interval. |
arg.assetId | String | Product ID. |
data | Array<Array<String>> | Mark-price candlestick data. Each record contains exactly 6 elements. |
data[] Element Description
Each candlestick is returned in the following fixed order:
[ts, open, high, low, close, confirm]| Index | Field | Type | Description |
|---|---|---|---|
0 | ts | String | Candlestick start time in Unix milliseconds. |
1 | open | String | Opening mark price. |
2 | high | String | Highest mark price. |
3 | low | String | Lowest mark price. |
4 | close | String | Closing mark price. For an unclosed candlestick, this is the latest mark price. |
5 | confirm | String | Candlestick status: 0 means unclosed; 1 means closed. |
This channel does not return trading volume, trading amount, or trade count.
Push Example
{
"arg": {
"channel": "exchangeos-mark-price-candle1s",
"assetId": "2"
},
"data": [
[
"1785912897000",
"1.0298",
"1.0298",
"1.0298",
"1.0298",
"0"
]
]
}
Interpretation
- The candlestick start time is
1785912897000. - The opening mark price is
1.0298. - The highest mark price is
1.0298. - The lowest mark price is
1.0298. - The current closing mark price is
1.0298. confirm="0"indicates that the candlestick is not yet closed.
Client Handling Rules
An unclosed candlestick may be pushed repeatedly as the mark price changes. The client should use channel + assetId + ts as the unique key for each candlestick and overwrite the previous record with the latest data.
When confirm="1" is received, the candlestick is considered closed.
Index Ticker Channel exchangeos-index-tickers#
Channel Description
Pushes the latest index price.
- When the index price changes, updates are pushed at most once per second.
- If the index price does not change, an update is pushed once per minute.
- The push includes
idxPx,open24h,high24h,low24h,sodUtc0, andsodUtc8.
Subscription Parameters
channel: Fixed asexchangeos-index-tickers.assetId: Product ID corresponding to the index, for example1234.
Subscription Example
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-index-tickers",
"assetId": "1234"
}
]
}
Push Fields (data element)
| Field | Type | Description |
|---|---|---|
assetId | String | Product ID. |
idxPx | String | Latest index price. |
high24h | String | Highest index price over the past 24 hours. |
low24h | String | Lowest index price over the past 24 hours. |
open24h | String | Index opening price over the past 24 hours. |
sodUtc0 | String | Daily index opening price in the UTC+0 time zone. |
sodUtc8 | String | Daily index opening price in the UTC+8 time zone. |
ts | String | Data update timestamp in Unix milliseconds. |
Push Example
{
"arg": {
"channel": "exchangeos-index-tickers",
"assetId": "1234"
},
"data": [
{
"assetId": "1234",
"idxPx": "64972.1",
"high24h": "65500.0",
"low24h": "64200.0",
"open24h": "64800.0",
"sodUtc0": "64900.0",
"sodUtc8": "64950.0",
"ts": "1781701360808"
}
]
}
Index Candlestick Channel exchangeos-index-candle{bar}#
Channel Description
Pushes index candlestick data. The channel name consists of exchangeos-index-candle followed by the candle interval, for example exchangeos-index-candle1H.
The fields are aligned with the TZ REST index candlestick data. Each record contains OHLC data and the candlestick status, for a total of 6 elements. Trading volume is not included.
Supported Intervals (bar)
1m, 5m, 15m, 1H, 4H, 1D
Subscription Parameters
channel: Formatted asexchangeos-index-candle{bar}.assetId: Product ID.
Subscription Example
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-index-candle1H",
"assetId": "1234"
}
]
}
Push Fields (data is an array of 6 strings)
| Index | Description |
|---|---|
[0] | Candlestick start time in Unix milliseconds. |
[1] | Opening price. |
[2] | Highest price. |
[3] | Lowest price. |
[4] | Closing price. |
[5] | Candlestick status: 0 means unclosed; 1 means closed. |
Push Example
{
"arg": {
"channel": "exchangeos-index-candle1H",
"assetId": "1234"
},
"data": [
[
"1710000000000",
"50000.0",
"51000.0",
"49500.0",
"50500.0",
"0"
]
]
}
Funding Rate Channel exchangeos-funding-rate#
Channel Description
Pushes the current predicted funding rate and the next settlement information for perpetual contracts. Updates are pushed every 5 seconds by default.
The WebSocket response does not include fundingTime. Clients should use nextFundingTime to determine the next settlement time and settlementInterval to determine the settlement period.
To retrieve fundingTime, query the REST endpoint:
GET /market/funding-rate
Subscription Parameters
channel: Fixed asexchangeos-funding-rate.assetId: Required, for example1234.
Subscription Example
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-funding-rate",
"assetId": "2"
}
]
}
Push Fields (data element)
| Field | Type | Description |
|---|---|---|
assetId | String | Product ID. |
fundingRate | String | Current funding rate. This field was renamed from the previous TZ on-chain field rate. Returns an empty string "" when upstream data is unavailable, such as when a new trading pair has insufficient liquidity or the funding switch is disabled. |
nextFundingTime | String | Next settlement time in milliseconds. Under normal conditions, it equals fundingTime + settlementInterval × 3,600,000. |
settlementInterval | String | Settlement interval in hours. Possible values are 1, 2, 4, 8, 12, and 24. The source field is settlement_interval, with a default value of 1 hour. |
minFundingRate | String | Minimum funding rate for a single settlement. |
maxFundingRate | String | Maximum funding rate for a single settlement. |
fundingSwitch | Boolean | Funding-fee switch. false means that funding fees are not calculated, collected, or distributed during the current settlement window. When re-enabled, the sampling window is reset, rolling history is cleared, and sampling data is rebuilt according to the cold-start rules. |
Push Example
{
"arg": {
"channel": "exchangeos-funding-rate",
"assetId": "2"
},
"data": [
{
"assetId": "2",
"fundingRate": "-0.004200",
"nextFundingTime": "1785916800000",
"settlementInterval": "1",
"minFundingRate": "-0.015000",
"maxFundingRate": "0.015000",
"fundingSwitch": true
}
]
}
Instruments Channel exchangeos-instruments#
Channel Description
Pushes listing, delisting, instrument, and trading-parameter changes.
Incremental push triggers include:
- A change to the product
state, such as a new contract or trading pair going live, a manual pause or resumption, or delisting due to delivery or exercise. - A change to the trading parameters
priceDecimalsorsizeDecimals. - A change to the listing or delisting times
listTimeorexpTime.
upcChg is used to announce pending changes to priceDecimals or sizeDecimals. When a parameter is adjusted, the system pushes the parameter name, new value, and effective time:
- One push is sent when the parameter-change task is created.
- A second push is sent when the parameter becomes effective and is applied.
A delisting notice is pushed 30 minutes before the official delisting time.
Subscription Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | String | Yes | Fixed as exchangeos-instruments. |
instType | String | Yes | Product type. Supported values are SPOT and PERPS. Subscription is performed by product type. |
After subscribing, the server returns all products under the specified product type and continues pushing listing, delisting, and parameter changes. When any product changes, the server pushes the complete instrument list for that instType.
Subscription Example
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-instruments",
"instType": "SPOT"
}
]
}
Push Fields (data element)
| Field | Type | Description |
|---|---|---|
instType | String | Product type. Supported values are SPOT and PERPS. |
assetId | String | Product ID, for example 1234. |
baseTokenId | String | Trading asset ID. Applies to Spot products only. |
quoteTokenId | String | Quote asset ID. Applies to Spot products only. |
settleTokenId | String | PnL settlement and margin asset ID. Applies to Perpetual products only. |
priceDecimals | String | Price precision, representing the minimum price increment for orders. When the precision is reduced, existing order prices may be rounded: sell orders are rounded up and buy orders are rounded down. If the rounded price becomes 0, the order is canceled. |
sizeDecimals | String | Quantity precision. |
state | String | Product state: live means available for trading; preopen means pre-listed. After a product is listed in the backend and its data is recorded on-chain, the system pushes the preopen state. |
listTime | String | Product listing time in Unix epoch milliseconds. |
expTime | String | Product delisting time in Unix epoch milliseconds. Pushed when changed. |
upcChg | Array | List of pending parameter changes. Returns an empty array [] when there are no pending changes. |
upcChg[].param | String | Parameter scheduled to change. Supported values are priceDecimals and sizeDecimals. |
upcChg[].newValue | String | New parameter value to be applied. |
upcChg[].effTime | String | Parameter effective time in Unix epoch milliseconds. |
ts | String | Event push timestamp in Unix epoch milliseconds. |
Parameter-Change Lifecycle Example
The following example shows priceDecimals changing from 1 to 2 at 1710086400000.
1. Pending-Change Push
The top-level field still contains the old value, while upcChg carries the new value and effective time.
{
"arg": {
"channel": "exchangeos-instruments",
"instType": "PERPS"
},
"data": [
{
"instType": "PERPS",
"assetId": "5678",
"settleTokenId": "0",
"priceDecimals": "1",
"sizeDecimals": "3",
"state": "live",
"listTime": "1710000000000",
"expTime": "",
"upcChg": [
{
"param": "priceDecimals",
"newValue": "2",
"effTime": "1710086400000"
}
],
"ts": "1710000000000"
}
]
}
The client should retain the current value from the top-level field and compare it with upcChg[].newValue. The API does not provide a separate oldValue field.
2. Effective-Change Confirmation Push
When effTime is reached, the top-level field is updated to the new value and upcChg is cleared.
{
"arg": {
"channel": "exchangeos-instruments",
"instType": "PERPS"
},
"data": [
{
"instType": "PERPS",
"assetId": "5678",
"settleTokenId": "0",
"priceDecimals": "2",
"sizeDecimals": "3",
"state": "live",
"listTime": "1710000000000",
"expTime": "",
"upcChg": [],
"ts": "1710086400000"
}
]
}
Open Interest Channel exchangeos-open-interest#
Channel Description
Pushes the total open interest for perpetual contracts. An update is pushed every 3 seconds when the data changes.
Subscription Parameters
channel: Fixed asexchangeos-open-interest.assetId: Required, for example1234.
Subscription Example
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-open-interest",
"assetId": "1234"
}
]
}
| Field | Type | Description |
|---|---|---|
assetId | String | Product ID. Only Perps assetId values are supported. If a Spot assetId is provided, the server returns a successful subscription acknowledgment but does not push any data. |
oiCcy | String | Open interest denominated in the underlying currency. |
oiUsd | String | Open interest converted to USD. |
ts | String | Data update timestamp in Unix milliseconds. |
Push Example
{
"arg": {
"channel": "exchangeos-open-interest",
"assetId": "1234"
},
"data": [
{
"assetId": "1234",
"oiCcy": "22161.13",
"oiUsd": "1939251795.54",
"ts": "1710249600000"
}
]
}
Price Limit Channel exchangeos-price-limit#
The channel pushes the highest allowed buy price, buyLmt, and the lowest allowed sell price, sellLmt.
There is no initial push. When the price-limit band changes, an update is pushed at most once per second. No update is pushed when the band remains unchanged. The initial configuration of a price band triggers a push. If no valid price-limit band exists, the related fields return an empty string instead of "0".
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-price-limit",
"assetId": "1234"
}
]
}
| Field | Type | Description |
|---|---|---|
assetId | String | Product asset ID. |
buyLmt | String | Highest allowed buy price. Returns an empty string when no value is available. |
sellLmt | String | Lowest allowed sell price. Returns an empty string when no value is available. |
ts | String | Push timestamp in Unix epoch milliseconds. |
{
"arg": {
"channel": "exchangeos-price-limit",
"assetId": "1234"
},
"data": [
{
"assetId": "1234",
"buyLmt": "52000",
"sellLmt": "48000",
"ts": "1710249600000"
}
]
}
Order Book Channels#
exchangeos-books#
The full order book channel. The first push is a complete snapshot with action: "snapshot". Subsequent pushes are incremental updates with action: "update".
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-books",
"assetId": "1234"
}
]
}
Each price level is represented as [price, size, orderCount]. In an incremental update, size: "0" indicates that the price level should be removed.
| Field | Type | Description |
|---|---|---|
asks / bids | Array | Ask-side or bid-side price-level lists. |
ts | String | Push timestamp in Unix epoch milliseconds. |
prevSeqId | Integer | Previous sequence number. |
seqId | Integer | Current sequence number. |
The client must validate sequence continuity:
- The
prevSeqIdof the firstupdatemust equal the snapshotseqId. - For each subsequent update,
update.prevSeqIdmust equal the previousseqId. - If the sequence is discontinuous, the client must resubscribe.
- If there is no change for 60 seconds, the server may send a heartbeat frame where
seqId == prevSeqId.
{
"arg": {
"channel": "exchangeos-books",
"assetId": "1234"
},
"action": "update",
"data": [
{
"asks": [
["8477", "415", "3"]
],
"bids": [
["8476", "0", "0"]
],
"ts": "1710249600000",
"prevSeqId": 123455,
"seqId": 123456
}
]
}
exchangeos-books5#
Pushes a complete snapshot of the top five order-book levels. Updates are pushed when the order book changes. This channel does not have incremental semantics, so sequence validation is not required.
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-books5",
"assetId": "1234"
}
]
}
{
"arg": {
"channel": "exchangeos-books5",
"assetId": "1234"
},
"data": [
{
"asks": [
["8477", "415", "3"],
["8478", "7", "1"]
],
"bids": [
["8476", "256", "4"],
["8475", "101", "2"]
],
"assetId": "1234",
"ts": "1710249600000",
"seqId": 123456
}
]
}
exchangeos-bbo-tbt#
Pushes a complete BBO snapshot containing one best ask level and one best bid level. This is not an incremental update.
When the BBO changes, updates are pushed at most once every 100 ms. Multiple changes within the same 100 ms window are merged. If the BBO remains unchanged, the server sends a fallback update approximately every 60 seconds.
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-bbo-tbt",
"assetId": "1234"
}
]
}
{
"arg": {
"channel": "exchangeos-bbo-tbt",
"assetId": "1234"
},
"data": [
{
"asks": [
["8477", "415", "3"]
],
"bids": [
["8476", "256", "4"]
],
"assetId": "1234",
"ts": "1710249600000",
"seqId": 123457
}
]
}
Estimated Perpetual Settlement Price Channel exchangeos-estimated-price#
This channel pushes the estimated settlement price when a product is scheduled for delisting.
After a successful subscription, the server pushes the current snapshot. Price updates use an aggregation window of approximately 200 ms; within the same window, only the latest value for the same assetId is pushed.
If no valid estimated price is available, settlePx returns an empty string.
No periodic market-data heartbeat is sent when the price does not change. Connection keepalive uses the public WebSocket ping / pong mechanism.
When expTime, settleAt, status, settlePx, settleType, or another public field changes, the server pushes the complete object. The current raw interface example explicitly defines the following fields.
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-estimated-price",
"assetId": "9102"
}
]
}
| Field | Type | Description |
|---|---|---|
assetId | String | Perpetual contract asset ID. |
name | String | Product name. |
marketType | String | Market type, for example perp. |
expTime | String | Estimated delisting or expiration time in Unix epoch milliseconds. |
settlePx | String | Estimated settlement price. Returns an empty string when no valid price is available. |
ts | String | Push timestamp in Unix epoch milliseconds. |
{
"arg": {
"channel": "exchangeos-estimated-price",
"assetId": "9102"
},
"data": [
{
"assetId": "9102",
"name": "UNI-USD-PERP",
"marketType": "perp",
"expTime": "1751990400000",
"settlePx": "6.4182",
"ts": "1751988600123"
}
]
}
Block Channel exchangeos-new-heads#
This channel pushes the height and block time of each latest on-chain block once it becomes available to the market-data service. Clients can calculate the block interval from adjacent blockTime values and combine it with the local message-receipt time to estimate the time window for the next block.
Push Semantics
- Trigger: A push is generated when the source chain produces a new block and the public market-data push service accepts it as the current canonical head.
- Frequency: Each block that meets the trigger condition is pushed once.
- Initial push: The subscription ACK only confirms that the subscription was created. The server does not send a snapshot of the latest block from before the subscription. The first data message is the first new block observed after the subscription is established.
- Ordering: Within the same healthy WebSocket subscription, the server sends messages in ascending
blockHeightorder. Missing messages are not replayed. - Time semantics:
blockTimeis the on-chain block-production time for the corresponding TradeZone block height, expressed as Unix epoch milliseconds. It must not be replaced with the Indexer ingestion time, WebSocket send time, Gateway time, or client receipt time. - Chain reorganization and finality: In v1, the channel only pushes block heads identified by the upstream system as canonical and does not intentionally delay delivery to wait for additional finality. If the upstream system may replace an already pushed block at the same height, confirm before development whether reorg notifications are required. Height and time alone are insufficient for a client to identify a same-height block replacement.
The top-level object contains only arg and data; action is not returned. All block heights and timestamps are returned as JSON String values.
{
"arg": {
"channel": "exchangeos-new-heads"
},
"data": [
{
"blockHeight": "78231934",
"blockTime": "1784106859965"
}
]
}
Subscription Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | String | No | Client request identifier. Must contain 1–32 alphanumeric characters. When provided, it is returned unchanged in the subscription ACK or error response. |
op | String | Yes | Fixed as subscribe. |
args | Array<Object> | Yes | Array of subscription objects. The public WebSocket total-length limit applies. |
args[].channel | String | Yes | Fixed as exchangeos-new-heads. |
exchangeos-new-heads is a chain-level channel. Therefore, args[] must not include assetId, instType, marketType, instId, or any other filter parameter. Requests containing undefined fields are invalid.
Subscription Example
{
"id": "1512",
"op": "subscribe",
"args": [
{
"channel": "exchangeos-new-heads"
}
]
}
Successful Subscription ACK
{
"id": "1512",
"event": "subscribe",
"arg": {
"channel": "exchangeos-new-heads"
},
"connId": "a4d3ae55"
}
Push Specification
Top-Level Push Fields
| Field | Type | Required | Description |
|---|---|---|---|
arg | Object | Yes | Subscription scope for the push. |
arg.channel | String | Yes | Fixed as exchangeos-new-heads. |
data | Array<Object> | Yes | Data for the new block head. In v1, each push contains exactly one element. |
data[] Fields
| Field | Type | Required | Description |
|---|---|---|---|
blockHeight | String | Yes | TradeZone block height of the new head, returned as a JSON String. |
blockTime | String | Yes | On-chain block-production time, expressed as Unix epoch milliseconds. This is not the WebSocket push time. |
Push Example
{
"arg": {
"channel": "exchangeos-new-heads"
},
"data": [
{
"blockHeight": "78231934",
"blockTime": "1784106859965"
}
]
}
Unsubscribe
Unsubscription follows the public WebSocket protocol. The parameters must use the same subscription scope.
{
"id": "1513",
"op": "unsubscribe",
"args": [
{
"channel": "exchangeos-new-heads"
}
]
}
Unsubscription ACK Example
{
"id": "1513",
"event": "unsubscribe",
"arg": {
"channel": "exchangeos-new-heads"
},
"connId": "a4d3ae55"
}
Corporate Actions WebSocket Channel exchangeos-corporate-actions#
The public exchangeos-corporate-actions channel pushes status changes for corporate action (CA) events. Clients should first retrieve current events through REST GET /api/v5/exchangeos/market/corporate-actions, then subscribe to this channel for subsequent updates. The public channel does not require login.
Subscribe
Subscription Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
op | String | Yes | Fixed as subscribe. |
args | Array | Yes | Array of subscription objects. |
args[].channel | String | Yes | Fixed as exchangeos-corporate-actions. |
Subscription Example
{
"op": "subscribe",
"args": [
{
"channel": "exchangeos-corporate-actions"
}
]
}
Successful Subscription ACK
{
"event": "subscribe",
"arg": {
"channel": "exchangeos-corporate-actions"
},
"connId": "a4d3ae55"
}
The server does not send an initial snapshot after subscription. The ACK only confirms that the subscription was established. Query current CA information through REST; WebSocket pushes subsequent changes.
Push Triggers and Statuses
| Status | Push Trigger and Meaning |
|---|---|
SCHEDULED | The event has been created and its schedule has been confirmed. |
PREPARING | The event enters the preparation stage, and price limits for affected products begin to tighten. |
COMPLETED | CA execution is complete. The event includes executionBlockHeight, and the price limits subsequently return to their normal range. |
When a confirmed event is rescheduled, its status may remain SCHEDULED. After plannedCutoverAt and eventVersion are updated, the server pushes another complete snapshot of the event.
The channel does not expose a CANCELLED status. If an event is canceled, no cancellation message is pushed, and the event is no longer returned by REST.
Push Format
Each message contains one complete CA event snapshot in the data array. Status updates for the same event are pushed in stage order. Clients can use caEventId to associate updates with the same event and eventVersion to identify its version.
Top-Level Push Fields
| Field | Type | Description |
|---|---|---|
arg | Object | Subscription channel information. |
arg.channel | String | Fixed as exchangeos-corporate-actions. |
data | Array | CA event array; each push contains one event. |
Event Fields in data[]
| Field | Type | Description |
|---|---|---|
caEventId | String | CA event ID used to associate different states of the same event. |
eventVersion | Number | Event version. |
bbGlobalId | String | Bloomberg Global ID of the underlying stock. |
underlying | String | Underlying stock symbol, for example SNDK. |
exchange | String | Exchange code of the underlying stock. |
caClass | String | Event class: DIVIDEND or SPLIT. |
actionType | String | Action type: CASH_DIVIDEND, STOCK_DIVIDEND, STOCK_SPLIT, or REVERSE_SPLIT. |
status | String | Event status: SCHEDULED, PREPARING, or COMPLETED. |
plannedCutoverAt | Number | Planned cutover time in Unix epoch milliseconds. |
instruments | Array | List of affected products. |
instruments[].assetId | String | ID of an affected product. |
instruments[].state | String | Actual trading state of the product, such as live; this is not the CA status. |
executionBlockHeight | String | Block height at which the CA was executed. Returned only when the event is COMPLETED. |
cashDividend | String | Cash dividend per share and its currency. Applies only to CASH_DIVIDEND. |
dividendSize | String | Dividend classification: SMALL or LARGE. Applies only to dividend events. |
sharesReceivedPerHeldShare | String | Number of new shares received for each existing share. Applies only to STOCK_DIVIDEND. |
stockDividendRatioPct | String | Stock dividend ratio expressed as a percentage value. Applies only to STOCK_DIVIDEND. |
ratioFrom | String | Number of shares before a split or reverse split. Applies only to the relevant action. |
ratioTo | String | Number of shares after a split or reverse split. Applies only to the relevant action. |
Fields that do not apply to an event are omitted. For example, a stock split does not include dividendSize, and a dividend does not include ratioFrom. Price limits are not included in instruments. Query current limits through REST GET /api/v5/exchangeos/market/price-limit.
Push Examples by Scenario and Stage
The following examples follow the updated specification and are not copied directly from runtime logs. Across these three stages of the same event, typically only status changes; executionBlockHeight is added at COMPLETED. In these examples, eventVersion remains 1. The applicable fields depend on actionType.
Scenario 1: Stock dividend (SNDK, 2 new shares for every 5 shares held, LARGE)
SCHEDULED: Schedule confirmed; no executionBlockHeight
{
"arg": {
"channel": "exchangeos-corporate-actions"
},
"data": [
{
"actionType": "STOCK_DIVIDEND",
"bbGlobalId": "BBG01R388JG1",
"caClass": "DIVIDEND",
"caEventId": "0fcffde70c9e4a1b8d3e5f6a7b8c9d01",
"dividendSize": "LARGE",
"eventVersion": 1,
"exchange": "XNGS",
"instruments": [
{
"assetId": "5202",
"state": "live"
},
{
"assetId": "7476101",
"state": "live"
}
],
"plannedCutoverAt": 1794571200000,
"sharesReceivedPerHeldShare": "0.4",
"status": "SCHEDULED",
"stockDividendRatioPct": "40",
"underlying": "SNDK"
}
]
}
PREPARING: Preparation begins; no executionBlockHeight
{
"arg": {
"channel": "exchangeos-corporate-actions"
},
"data": [
{
"actionType": "STOCK_DIVIDEND",
"bbGlobalId": "BBG01R388JG1",
"caClass": "DIVIDEND",
"caEventId": "0fcffde70c9e4a1b8d3e5f6a7b8c9d01",
"dividendSize": "LARGE",
"eventVersion": 1,
"exchange": "XNGS",
"instruments": [
{
"assetId": "5202",
"state": "live"
},
{
"assetId": "7476101",
"state": "live"
}
],
"plannedCutoverAt": 1794571200000,
"sharesReceivedPerHeldShare": "0.4",
"status": "PREPARING",
"stockDividendRatioPct": "40",
"underlying": "SNDK"
}
]
}
COMPLETED: CA execution complete; includes executionBlockHeight
{
"arg": {
"channel": "exchangeos-corporate-actions"
},
"data": [
{
"actionType": "STOCK_DIVIDEND",
"bbGlobalId": "BBG01R388JG1",
"caClass": "DIVIDEND",
"caEventId": "0fcffde70c9e4a1b8d3e5f6a7b8c9d01",
"dividendSize": "LARGE",
"eventVersion": 1,
"exchange": "XNGS",
"executionBlockHeight": "181140128",
"instruments": [
{
"assetId": "5202",
"state": "live"
},
{
"assetId": "7476101",
"state": "live"
}
],
"plannedCutoverAt": 1794571200000,
"sharesReceivedPerHeldShare": "0.4",
"status": "COMPLETED",
"stockDividendRatioPct": "40",
"underlying": "SNDK"
}
]
}
Scenario 2: Cash dividend (SNDK, USD 35.5 per share, LARGE)
SCHEDULED: Schedule confirmed; no executionBlockHeight
{
"arg": {
"channel": "exchangeos-corporate-actions"
},
"data": [
{
"actionType": "CASH_DIVIDEND",
"bbGlobalId": "BBG01R388JG1",
"caClass": "DIVIDEND",
"caEventId": "63192e7a0482463989a7437cf7c172de",
"cashDividend": "USD 35.5 / share",
"dividendSize": "LARGE",
"eventVersion": 1,
"exchange": "XNGS",
"instruments": [
{
"assetId": "5202",
"state": "live"
},
{
"assetId": "7476101",
"state": "live"
}
],
"plannedCutoverAt": 1794571200000,
"status": "SCHEDULED",
"underlying": "SNDK"
}
]
}
PREPARING: Preparation begins; no executionBlockHeight
{
"arg": {
"channel": "exchangeos-corporate-actions"
},
"data": [
{
"actionType": "CASH_DIVIDEND",
"bbGlobalId": "BBG01R388JG1",
"caClass": "DIVIDEND",
"caEventId": "63192e7a0482463989a7437cf7c172de",
"cashDividend": "USD 35.5 / share",
"dividendSize": "LARGE",
"eventVersion": 1,
"exchange": "XNGS",
"instruments": [
{
"assetId": "5202",
"state": "live"
},
{
"assetId": "7476101",
"state": "live"
}
],
"plannedCutoverAt": 1794571200000,
"status": "PREPARING",
"underlying": "SNDK"
}
]
}
COMPLETED: CA execution complete; includes executionBlockHeight
{
"arg": {
"channel": "exchangeos-corporate-actions"
},
"data": [
{
"actionType": "CASH_DIVIDEND",
"bbGlobalId": "BBG01R388JG1",
"caClass": "DIVIDEND",
"caEventId": "63192e7a0482463989a7437cf7c172de",
"cashDividend": "USD 35.5 / share",
"dividendSize": "LARGE",
"eventVersion": 1,
"exchange": "XNGS",
"executionBlockHeight": "180052436",
"instruments": [
{
"assetId": "5202",
"state": "live"
},
{
"assetId": "7476101",
"state": "live"
}
],
"plannedCutoverAt": 1794571200000,
"status": "COMPLETED",
"underlying": "SNDK"
}
]
}
Scenario 3: Stock split (SNDK, 1 share becomes 8 shares)
SCHEDULED: Schedule confirmed; no executionBlockHeight
{
"arg": {
"channel": "exchangeos-corporate-actions"
},
"data": [
{
"actionType": "STOCK_SPLIT",
"bbGlobalId": "BBG01R388JG1",
"caClass": "SPLIT",
"caEventId": "d235d298f3144e8d821458380d15f9e8",
"eventVersion": 1,
"exchange": "XNGS",
"instruments": [
{
"assetId": "5202",
"state": "live"
},
{
"assetId": "7476101",
"state": "live"
}
],
"plannedCutoverAt": 1794571200000,
"ratioFrom": "1",
"ratioTo": "8",
"status": "SCHEDULED",
"underlying": "SNDK"
}
]
}
PREPARING: Preparation begins; no executionBlockHeight
{
"arg": {
"channel": "exchangeos-corporate-actions"
},
"data": [
{
"actionType": "STOCK_SPLIT",
"bbGlobalId": "BBG01R388JG1",
"caClass": "SPLIT",
"caEventId": "d235d298f3144e8d821458380d15f9e8",
"eventVersion": 1,
"exchange": "XNGS",
"instruments": [
{
"assetId": "5202",
"state": "live"
},
{
"assetId": "7476101",
"state": "live"
}
],
"plannedCutoverAt": 1794571200000,
"ratioFrom": "1",
"ratioTo": "8",
"status": "PREPARING",
"underlying": "SNDK"
}
]
}
COMPLETED: CA execution complete; includes executionBlockHeight
{
"arg": {
"channel": "exchangeos-corporate-actions"
},
"data": [
{
"actionType": "STOCK_SPLIT",
"bbGlobalId": "BBG01R388JG1",
"caClass": "SPLIT",
"caEventId": "d235d298f3144e8d821458380d15f9e8",
"eventVersion": 1,
"exchange": "XNGS",
"executionBlockHeight": "179195685",
"instruments": [
{
"assetId": "5202",
"state": "live"
},
{
"assetId": "7476101",
"state": "live"
}
],
"plannedCutoverAt": 1794571200000,
"ratioFrom": "1",
"ratioTo": "8",
"status": "COMPLETED",
"underlying": "SNDK"
}
]
}
- General Push RulesConnection urlConnection and Heartbeat RulesWebSocket Operation Request Rate LimitsIdle Disconnect and HeartbeatData Type ConventionsSubscribeUnsubscribeNotice Message (event = notice)Ticker Channel exchangeos-tickersTrade Channel exchangeos-tradesTrade Candle Channel exchangeos-candle{bar}Mark Price Candle Channel exchangeos-mark-price-candle{bar}Index Ticker Channel exchangeos-index-tickersIndex Candlestick Channel exchangeos-index-candle{bar}Funding Rate Channel exchangeos-funding-rateInstruments Channel exchangeos-instrumentsOpen Interest Channel exchangeos-open-interestPrice Limit Channel exchangeos-price-limitOrder Book Channelsexchangeos-booksexchangeos-books5exchangeos-bbo-tbtEstimated Perpetual Settlement Price Channel exchangeos-estimated-priceBlock Channel exchangeos-new-headsCorporate Actions WebSocket Channel exchangeos-corporate-actions
