Exchange Wire Formats

OKX Futures wire format

This page shows how OKX perpetual swaps (SWAP) messages become rows in our Parquet files. For each data type below, you see a real message next to the rows that we publish for it. The page also gives the source and the rule for each column. Put the pointer on a line or a column to see how they connect.

Checked against our pipeline

We recorded these messages from OKX perpetual swaps (SWAP) on 2026-10-05. Our test suite replays each message through the production collector parser and the postprocessor. The test fails if the published rows are different from the rows on this page. Files that we wrote before a change to the pipeline can be different. Refer to Known Gaps & Corrections.

The collector subscribes to each channel for each instrument with {"channel": …, "instId": "BTC-USDT-SWAP"}. Liquidations are different: one {"channel": "liquidation-orders", "instType": "SWAP"} subscription covers all swaps. Sizes in trades, order book levels, the ticker last_quantity, open interest and liquidations are in contracts. Multiply these sizes by the ctVal of the instrument (OKX GET /api/v5/public/instruments). The unit of ctVal is ctValCcy: the base coin for linear swaps (0.01 BTC for BTC-USDT-SWAP) and USD for inverse swaps (100 USD for BTC-USD-SWAP).

  • Public WebSocket (books, tickers, mark price, funding rate, open interest, liquidations): wss://ws.okx.com:8443/ws/v5/public
  • Business WebSocket (trades-all): wss://ws.okx.com:8443/ws/v5/business

Exchange API reference: www.okx.com. For the conventions that apply to all exchanges, refer to the wire formats overview.

Trades

One row per fill from the trades-all channel.

  • WebSocket trades-all

Each trades-all message contains exactly one fill.

WebSocket message · trades-allreceived 2026-10-05 19:15:00.442818 UTC
{
"arg": {
"channel": "trades-all",
"instId": "BTC-USDT-SWAP"
},
"data": [
{
"instId": "BTC-USDT-SWAP",
"tradeId": "2975282594",
"px": "85620.7",
"sz": "0.01",
"side": "sell",
"ts": "1791227700310",
"source": "0"
}
]
}

Published row

received_time1791227700442818000—Our collector's clock when it received the message, in nanoseconds since the Unix epoch. OKX does not send this value.
event_time1791227700310data[].tsCopied from the fill time. Milliseconds.
symbolBTC-USDT-SWAPdata[].instIdCopied.
trade_id2975282594data[].tradeIdParsed from the OKX string to an integer.
price85620.7data[].pxCopied as the exact decimal string that OKX sent.
quantity0.01data[].szCopied as the exact decimal string. Contracts. To find the quantity in the base coin, multiply by ctVal (0.01 BTC for BTC-USDT-SWAP).
trade_time1791227700310data[].tsCopied. Milliseconds. The same value as event_time.
is_buyer_makertruedata[].sidetrue if side is sell (the taker sold, thus the buyer was the maker). false if side is buy.
order_typeMARKET—Always MARKET. This is a placeholder value because OKX does not send an order type.

Notes

  • The rows come from the trades-all channel on the business endpoint. This channel sends one entry for each fill. The public trades channel sends one entry for each taker order, fill price and order source. We stopped the use of the trades channel in the 2026-09 data-integrity release (refer to the venue notes).
  • The rows in a file are sorted by trade_time, then by trade_id. We publish each trade_id only one time in an hour file.
  • We do not publish the OKX source field (0 is a normal order, 1 is an Enhanced Liquidity Program order).

For the column types and descriptions, refer to the Trades schema.

Order Book

One row per price level from the 400-level books channel. OKX sends a snapshot after the subscription, then updates at 100 ms intervals.

  • WebSocket books

Order book snapshot (action: snapshot)

OKX sends a 400-level snapshot immediately after the subscription. This snapshot is the start of the update chain. Its prevSeqId is always -1.

Shortened: OKX sent 400 bid levels and 400 ask levels in this message. This example shows the best three of each.

WebSocket message · booksreceived 2026-10-05 19:15:00.148808 UTC
{
"arg": {
"channel": "books",
"instId": "BTC-USDT-SWAP"
},
"action": "snapshot",
"data": [
{
"asks": [
["85620.8", "1969.32", "0", "91"],
["85620.9", "52.78", "0", "4"],
["85621", "0.02", "0", "2"]
],
"bids": [
["85620.7", "741.39", "0", "21"],
["85620.6", "26.86", "0", "3"],
["85620.5", "0.64", "0", "2"]
],
"ts": "1791227700007",
"checksum": 0,
"seqId": 344108675409,
"prevSeqId": -1
}
]
}

Published rows · 6

received_time1791227700148808000—Our collector's clock when it received the message, in nanoseconds since the Unix epoch. OKX does not send this value.
event_time1791227700007data[].tsCopied from the time when OKX generated the order book. Milliseconds.
transaction_timenull—Null. OKX sends only one order book timestamp.
symbolBTC-USDT-SWAParg.instIdCopied.
event_typesnapshotactionsnapshot when action is snapshot.
first_update_idnull—Null. OKX sends no first update ID.
final_update_id344108675409data[].seqIdCopied from seqId.
prev_final_update_idnull—Null for snapshots. A snapshot starts a new chain.
last_update_id-1data[].prevSeqIdCopied from prevSeqId, which is always -1 for a snapshot. We keep this column for the files that we wrote before we added prev_final_update_id.
sidebiddata[].bidsdata[].asksbid for levels in bids, ask for levels in asks. One row per level.
price85620.7data[].bids[][0]data[].asks[][0]Copied as the exact decimal string.
quantity741.39data[].bids[][1]data[].asks[][1]Copied as the exact decimal string. Contracts. To find the quantity in the base coin, multiply by ctVal (0.01 BTC for BTC-USDT-SWAP).
order_count21data[].bids[][3]data[].asks[][3]Copied as an integer from the fourth element of the level (number of orders). OKX does not use the third element now (always 0), and we do not publish it.

Order book update (action: update)

Incremental changes. OKX sends them every 100 ms when the order book changes. The prevSeqId of each update is equal to the seqId of the previous message.

Shortened: OKX sent 51 bid levels and 17 ask levels in this message. This example shows two bids and two asks. One of these levels has quantity 0, which removes the level.

WebSocket message · booksreceived 2026-10-05 19:15:00.246680 UTC
{
"arg": {
"channel": "books",
"instId": "BTC-USDT-SWAP"
},
"action": "update",
"data": [
{
"asks": [
["85620.9", "52.19", "0", "3"],
["85623.7", "0", "0", "0"]
],
"bids": [
["85620.7", "771.51", "0", "23"],
["85619.7", "0.8", "0", "3"]
],
"ts": "1791227700107",
"checksum": 0,
"seqId": 344108675590,
"prevSeqId": 344108675409
}
]
}

Published rows · 4

received_time1791227700246680000—Our collector's clock when it received the message, in nanoseconds since the Unix epoch. OKX does not send this value.
event_time1791227700107data[].tsCopied from the time when OKX generated the order book. Milliseconds.
transaction_timenull—Null. OKX sends only one order book timestamp.
symbolBTC-USDT-SWAParg.instIdCopied.
event_typeupdateactionupdate when action is update.
first_update_idnull—Null. OKX sends no first update ID.
final_update_id344108675590data[].seqIdCopied from seqId.
prev_final_update_id344108675409data[].prevSeqIdCopied from prevSeqId. It is equal to the final_update_id of the previous message. If the two values are different, there is a gap.
last_update_id344108675409data[].prevSeqIdCopied from prevSeqId, the same value as prev_final_update_id. We keep this column for the files that we wrote before we added prev_final_update_id.
sidebiddata[].bidsdata[].asksbid for levels in bids, ask for levels in asks. One row per level.
price85620.7data[].bids[][0]data[].asks[][0]Copied as the exact decimal string.
quantity771.51data[].bids[][1]data[].asks[][1]Copied as the exact decimal string. It is the new total at that price. 0 removes the level. Contracts. To find the quantity in the base coin, multiply by ctVal (0.01 BTC for BTC-USDT-SWAP).
order_count23data[].bids[][3]data[].asks[][3]Copied as an integer from the fourth element of the level (number of orders).

Notes

  • OKX stopped the books checksum in 2026. OKX still sends the field, but it is always 0 and we do not publish it. seqId/prevSeqId is the only continuity check. An update continues the order book if its prev_final_update_id is equal to the final_update_id of the previous message. All rows of one message have the same two IDs. Thus, do the check one time for each message, not for each row.
  • OKX documentation states that seqId can start again at a lower value after maintenance. prevSeqId is still equal to the seqId of the previous message. Thus, compare each prevSeqId with the previous seqId. Do not use an increase of seqId as the check.
  • The collector makes sure that the chain is correct before it writes the data. After a gap, it connects again and starts from a new WebSocket snapshot.
  • Quantities are in contracts. To find the quantity in the base coin, multiply by ctVal (0.01 BTC for BTC-USDT-SWAP).
  • If an order book does not change for about 60 seconds, OKX sends an update with no levels and with seqId equal to prevSeqId. We do not publish this update. The OKX Spot page shows an example.
  • A file can start with a checkpoint snapshot of the order book that continues from the previous hour. In this snapshot, received_time is the start of the hour and transaction_time is null. final_update_id and last_update_id are both the last seqId that we applied.

For the column types and descriptions, refer to the Order Book schema.

Ticker

One row per tickers message.

  • WebSocket tickers
WebSocket message · tickersreceived 2026-10-05 19:15:00.038857 UTC
{
"arg": {
"channel": "tickers",
"instId": "BTC-USDT-SWAP"
},
"data": [
{
"instType": "SWAP",
"instId": "BTC-USDT-SWAP",
"last": "85620.7",
"lastSz": "0.08",
"askPx": "85620.8",
"askSz": "1989.68",
"bidPx": "85620.7",
"bidSz": "664.09",
"open24h": "85350.7",
"high24h": "86963.7",
"low24h": "84937.5",
"sodUtc0": "86484.8",
"sodUtc8": "85221.6",
"volCcy24h": "83846.1822",
"vol24h": "8384618.22",
"ts": "1791227699670"
}
]
}

Published row

received_time1791227700038857000—Our collector's clock when it received the message, in nanoseconds since the Unix epoch. OKX does not send this value.
event_time1791227699670data[].tsCopied from the time when OKX generated the ticker. Milliseconds.
symbolBTC-USDT-SWAPdata[].instIdCopied.
price_change270.0data[].lastdata[].open24hCalculated: last − open24h, as an exact decimal.
price_change_percent0.31634187data[].lastdata[].open24hCalculated: (last − open24h) / open24h × 100, rounded half-even to 8 decimal places. Percent.
weighted_average_pricenull—Null. OKX does not send a weighted average price.
last_price85620.7data[].lastCopied.
last_quantity0.08data[].lastSzCopied. Contracts.
open_price85350.7data[].open24hCopied. The open price of the last 24 hours.
high_price86963.7data[].high24hCopied.
low_price84937.5data[].low24hCopied.
base_asset_volume83846.1822data[].volCcy24hCopied from volCcy24h. For swaps, OKX gives this value in the base coin (BTC). This is the same for linear and inverse swaps.
quote_asset_volumenull—Null for swaps. OKX sends no 24h quote turnover for swaps. vol24h counts contracts, and we do not publish it.
statistics_open_timenull—Null. OKX does not send the limits of the statistics window.
statistics_close_timenull—Null. OKX does not send the limits of the statistics window.
first_trade_idnull—Null. OKX does not send trade IDs in tickers.
last_trade_idnull—Null. OKX does not send trade IDs in tickers.
total_tradesnull—Null. OKX does not send a trade count.

Notes

  • For swaps, base_asset_volume is the 24h volume in the base coin (volCcy24h), and quote_asset_volume is null. OKX sends no quote turnover for swaps.
  • We do not publish the best bid and ask (bidPx, bidSz, askPx, askSz) or the day open prices sodUtc0 and sodUtc8.
  • Before the October 2026 pipeline update, quote_asset_volume for swaps contained volCcy24h × last. Before the 2026-09 data-integrity release, base_asset_volume contained contracts and quote_asset_volume contained the base-coin volume (refer to the venue notes).

For the column types and descriptions, refer to the Ticker schema.

Mark Price

Two channels write to one file. Rows from mark-price contain mark_price. Rows from funding-rate contain funding_rate and next_funding_time. The rows are sorted by event_time.

  • WebSocket mark-price
  • WebSocket funding-rate

Mark price (mark-price channel)

OKX sends this message every 200 ms when the mark price changes. If the mark price does not change, OKX sends it every 10 seconds. These rows contain only the mark price.

WebSocket messagereceived 2026-10-05 19:14:59.991433 UTC
{
"arg": {
"channel": "mark-price",
"instId": "BTC-USDT-SWAP"
},
"data": [
{
"instId": "BTC-USDT-SWAP",
"instType": "SWAP",
"markPx": "85623.5",
"ts": "1791227699708"
}
]
}

Published row

received_time1791227699991433000—Our collector's clock when it received the message, in nanoseconds since the Unix epoch. OKX does not send this value.
event_time1791227699708data[].tsCopied from the time of the price update. Milliseconds.
symbolBTC-USDT-SWAPdata[].instIdCopied.
mark_price85623.5data[].markPxCopied.
index_pricenull—Null. The mark-price channel has no index price.
estimated_settle_pricenull—Null. This channel does not send it.
funding_ratenull—Null on mark price rows. Funding data comes in separate rows from the funding-rate channel.
next_funding_timenull—Null on mark price rows.

Funding rate (funding-rate channel)

OKX sends this message every 30 to 90 seconds. These rows contain only the funding fields. They go into the same file as the mark price rows.

WebSocket messagereceived 2026-10-05 19:16:10.086326 UTC
{
"arg": {
"channel": "funding-rate",
"instId": "BTC-USDT-SWAP"
},
"data": [
{
"formulaType": "withRate",
"fundingRate": "0.0000263029004785",
"fundingTime": "1791244800000",
"impactValue": "20000.0000000000000000",
"instId": "BTC-USDT-SWAP",
"instType": "SWAP",
"interestRate": "0.0001000000000000",
"maxFundingRate": "0.00375",
"method": "current_period",
"minFundingRate": "-0.00375",
"nextFundingRate": "",
"nextFundingTime": "1791273600000",
"premium": "-0.0005569827183559",
"prevFundingTime": "1791216000000",
"settFundingRate": "0.0000265340358766",
"settState": "settled",
"ts": "1791227769932"
}
]
}

Published row

received_time1791227770086326000—Our collector's clock when it received the message, in nanoseconds since the Unix epoch. OKX does not send this value.
event_time1791227769932data[].tsCopied from ts, the time when OKX published the update. Milliseconds. If ts is missing, our receive time in milliseconds.
symbolBTC-USDT-SWAPdata[].instIdCopied.
mark_pricenull—Null on funding rows. Mark prices come in separate rows from the mark-price channel.
index_pricenull—Null. This channel does not send it.
estimated_settle_pricenull—Null. This channel does not send it.
funding_rate0.0000263029004785data[].fundingRateCopied. The current funding rate, as a fraction per funding period. 0.0000263029004785 is 0.00263 %.
next_funding_time1791244800000data[].fundingTimeCopied from fundingTime, the time of the next settlement for fundingRate. Milliseconds. This is not nextFundingTime, which is the settlement after that one.

Notes

  • Each row has either the mark price or the funding fields. The other fields are null. To have both on one row, forward-fill each column.
  • index_price and estimated_settle_price are always null for OKX.
  • In funding rows that we published before the 2026-09 data-integrity release, event_time is fundingTime (refer to the venue notes).
  • OKX states that two mark-price messages can have the same ts during maintenance. OKX also states that the message received last is the correct one. We publish both messages.

For the column types and descriptions, refer to the Mark Price schema.

Open Interest

One row per open-interest message. A message comes about every 3 seconds when open interest changes.

  • WebSocket open-interest

OKX sends this message every 3 seconds when open interest changes.

WebSocket message · open-interestreceived 2026-10-05 19:15:12.109227 UTC
{
"arg": {
"channel": "open-interest",
"instId": "BTC-USDT-SWAP"
},
"data": [
{
"instId": "BTC-USDT-SWAP",
"instType": "SWAP",
"oi": "2850839.22000000697",
"oiCcy": "28508.3922000000697",
"oiUsd": "2440908496.03854596776279",
"ts": "1791227711966"
}
]
}

Published row

received_time1791227712109227000—Our collector's clock when it received the message, in nanoseconds since the Unix epoch. OKX does not send this value.
symbolBTC-USDT-SWAPdata[].instIdCopied.
sum_open_interest2850839.22000000697data[].oiCopied from oi. Contracts. To find the quantity in the base coin, multiply by ctVal (0.01 BTC for BTC-USDT-SWAP). We do not publish oiCcy, the OKX value in the base coin.
sum_open_interest_value2440908496.03854596776279data[].oiUsdCopied from oiUsd. USD.
timestamp1791227711966data[].tsCopied from the time of the update. Milliseconds.

Notes

  • If messages have the same ts, we publish only the first message that we received.
  • The collector also polls open interest through REST (GET /api/v5/public/open-interest). We do not publish the data from this poll.

For the column types and descriptions, refer to the Open Interest schema.

Liquidations

One row per entry in details of the liquidation-orders channel. One subscription covers all swaps.

  • WebSocket liquidation-orders
WebSocket message · liquidation-ordersreceived 2026-10-05 19:18:19.224997 UTC
{
"arg": {
"channel": "liquidation-orders",
"instType": "SWAP"
},
"data": [
{
"details": [
{
"bkLoss": "0",
"bkPx": "85659.7",
"ccy": "",
"posSide": "short",
"side": "buy",
"sz": "0.06",
"ts": "1791227898140"
}
],
"instFamily": "BTC-USDT",
"instId": "BTC-USDT-SWAP",
"instType": "SWAP",
"uly": "BTC-USDT"
}
]
}

Published row

received_time1791227899224997000—Our collector's clock when it received the message, in nanoseconds since the Unix epoch. OKX does not send this value.
event_time1791227898140data[].details[].tsCopied from the liquidation time. Milliseconds.
symbolBTC-USDT-SWAPdata[].instIdCopied from the instId of the entry. The subscription covers all swaps, thus one frame can contain several instruments.
sideBUYdata[].details[].sideThe side of the liquidation order, in upper case. BUY closes a liquidated short, and SELL closes a liquidated long.
order_typeMARKET—Always MARKET. This is a placeholder value because OKX does not send an order type.
time_in_forceIOC—Always IOC. This is a placeholder value because OKX does not send a time in force.
quantity0.06data[].details[].szCopied. Contracts. To find the quantity in the base coin, multiply by ctVal.
price85659.7data[].details[].bkPxCopied from bkPx. OKX documentation calls it the liquidation mark price. This is the price of the transaction with the liquidation account of the system. It is not a fill price on the order book.
average_price85659.7data[].details[].bkPxCopied from bkPx, the same value as price. Not an execution price.
order_statusFILLED—Always FILLED. This is a placeholder value, not an execution status.
last_filled_quantity0.06data[].details[].szCopied from sz, the same value as quantity.
filled_quantity0.06data[].details[].szCopied from sz, the same value as quantity.
trade_time1791227898140data[].details[].tsCopied. Milliseconds. The same value as event_time.

Notes

  • OKX states that this channel does not send all liquidations on OKX.
  • OKX states that liquidations come from different sources and can be out of time order. A liquidation can come hours after its event_time. Thus, a row can be in the file of a later hour (refer to the venue notes).
  • We do not publish posSide, bkLoss and ccy.

For the column types and descriptions, refer to the Liquidations schema.

If you cannot find the information that you need, tell us. We also help with integrations.

Contact support