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.
{"arg": {"channel": "trades-all","instId": "BTC-USDT-SWAP"},"data": [{"instId": "BTC-USDT-SWAP",→ symbol"tradeId": "2975282594",→ trade_id"px": "85620.7",→ price"sz": "0.01",→ quantity"side": "sell",→ is_buyer_maker"ts": "1791227700310",→ event_time · trade_time"source": "0"}]}
Published row
ctVal (0.01 BTC for BTC-USDT-SWAP).event_time.true if side is sell (the taker sold, thus the buyer was the maker). false if side is buy.MARKET. This is a placeholder value because OKX does not send an order type.Notes
- The rows come from the
trades-allchannel on the business endpoint. This channel sends one entry for each fill. The publictradeschannel sends one entry for each taker order, fill price and order source. We stopped the use of thetradeschannel in the 2026-09 data-integrity release (refer to the venue notes). - The rows in a file are sorted by
trade_time, then bytrade_id. We publish eachtrade_idonly one time in an hour file. - We do not publish the OKX
sourcefield (0is a normal order,1is 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.
{"arg": {"channel": "books","instId": "BTC-USDT-SWAP"→ symbol},"action": "snapshot",→ event_type"data": [{"asks": [→ side["85620.8", "1969.32", "0", "91"],→ side · price · quantity · order_count["85620.9", "52.78", "0", "4"],→ side · price · quantity · order_count["85621", "0.02", "0", "2"]→ side · price · quantity · order_count],"bids": [→ side["85620.7", "741.39", "0", "21"],→ side · price · quantity · order_count["85620.6", "26.86", "0", "3"],→ side · price · quantity · order_count["85620.5", "0.64", "0", "2"]→ side · price · quantity · order_count],"ts": "1791227700007",→ event_time"checksum": 0,"seqId": 344108675409,→ final_update_id"prevSeqId": -1→ last_update_id}]}
Published rows · 6
snapshot when action is snapshot.seqId.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.bid for levels in bids, ask for levels in asks. One row per level.ctVal (0.01 BTC for BTC-USDT-SWAP).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.
{"arg": {"channel": "books","instId": "BTC-USDT-SWAP"→ symbol},"action": "update",→ event_type"data": [{"asks": [→ side["85620.9", "52.19", "0", "3"],→ side · price · quantity · order_count["85623.7", "0", "0", "0"]→ side · price · quantity · order_count],"bids": [→ side["85620.7", "771.51", "0", "23"],→ side · price · quantity · order_count["85619.7", "0.8", "0", "3"]→ side · price · quantity · order_count],"ts": "1791227700107",→ event_time"checksum": 0,"seqId": 344108675590,→ final_update_id"prevSeqId": 344108675409→ prev_final_update_id · last_update_id}]}
Published rows · 4
update when action is update.seqId.prevSeqId. It is equal to the final_update_id of the previous message. If the two values are different, there is a gap.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.bid for levels in bids, ask for levels in asks. One row per level.0 removes the level. Contracts. To find the quantity in the base coin, multiply by ctVal (0.01 BTC for BTC-USDT-SWAP).Notes
- OKX stopped the
bookschecksum in 2026. OKX still sends the field, but it is always0and we do not publish it.seqId/prevSeqIdis the only continuity check. An update continues the order book if itsprev_final_update_idis equal to thefinal_update_idof 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
seqIdcan start again at a lower value after maintenance.prevSeqIdis still equal to theseqIdof the previous message. Thus, compare eachprevSeqIdwith the previousseqId. Do not use an increase ofseqIdas 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 forBTC-USDT-SWAP). - If an order book does not change for about 60 seconds, OKX sends an update with no levels and with
seqIdequal toprevSeqId. 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_timeis the start of the hour andtransaction_timeis null.final_update_idandlast_update_idare both the lastseqIdthat we applied.
For the column types and descriptions, refer to the Order Book schema.
Ticker
One row per tickers message.
- WebSocket tickers
{"arg": {"channel": "tickers","instId": "BTC-USDT-SWAP"},"data": [{"instType": "SWAP","instId": "BTC-USDT-SWAP",→ symbol"last": "85620.7",→ price_change · price_change_percent · last_price"lastSz": "0.08",→ last_quantity"askPx": "85620.8","askSz": "1989.68","bidPx": "85620.7","bidSz": "664.09","open24h": "85350.7",→ price_change · price_change_percent · open_price"high24h": "86963.7",→ high_price"low24h": "84937.5",→ low_price"sodUtc0": "86484.8","sodUtc8": "85221.6","volCcy24h": "83846.1822",→ base_asset_volume"vol24h": "8384618.22","ts": "1791227699670"→ event_time}]}
Published row
last − open24h, as an exact decimal.last − open24h) / open24h × 100, rounded half-even to 8 decimal places. Percent.volCcy24h. For swaps, OKX gives this value in the base coin (BTC). This is the same for linear and inverse swaps.vol24h counts contracts, and we do not publish it.Notes
- For swaps,
base_asset_volumeis the 24h volume in the base coin (volCcy24h), andquote_asset_volumeis 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 pricessodUtc0andsodUtc8. - Before the October 2026 pipeline update,
quote_asset_volumefor swaps containedvolCcy24h×last. Before the 2026-09 data-integrity release,base_asset_volumecontained contracts andquote_asset_volumecontained 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.
{"arg": {"channel": "mark-price","instId": "BTC-USDT-SWAP"},"data": [{"instId": "BTC-USDT-SWAP",→ symbol"instType": "SWAP","markPx": "85623.5",→ mark_price"ts": "1791227699708"→ event_time}]}
Published row
mark-price channel has no index price.funding-rate channel.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.
{"arg": {"channel": "funding-rate","instId": "BTC-USDT-SWAP"},"data": [{"formulaType": "withRate","fundingRate": "0.0000263029004785",→ funding_rate"fundingTime": "1791244800000",→ next_funding_time"impactValue": "20000.0000000000000000","instId": "BTC-USDT-SWAP",→ symbol"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"→ event_time}]}
Published row
ts, the time when OKX published the update. Milliseconds. If ts is missing, our receive time in milliseconds.mark-price channel.0.0000263029004785 is 0.00263 %.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_priceandestimated_settle_priceare always null for OKX.- In funding rows that we published before the 2026-09 data-integrity release,
event_timeisfundingTime(refer to the venue notes). - OKX states that two
mark-pricemessages can have the sametsduring 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.
{"arg": {"channel": "open-interest","instId": "BTC-USDT-SWAP"},"data": [{"instId": "BTC-USDT-SWAP",→ symbol"instType": "SWAP","oi": "2850839.22000000697",→ sum_open_interest"oiCcy": "28508.3922000000697","oiUsd": "2440908496.03854596776279",→ sum_open_interest_value"ts": "1791227711966"→ timestamp}]}
Published row
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.oiUsd. USD.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
{"arg": {"channel": "liquidation-orders","instType": "SWAP"},"data": [{"details": [{"bkLoss": "0","bkPx": "85659.7",→ price · average_price"ccy": "","posSide": "short","side": "buy",→ side"sz": "0.06",→ quantity · last_filled_quantity · filled_quantity"ts": "1791227898140"→ event_time · trade_time}],"instFamily": "BTC-USDT","instId": "BTC-USDT-SWAP",→ symbol"instType": "SWAP","uly": "BTC-USDT"}]}
Published row
instId of the entry. The subscription covers all swaps, thus one frame can contain several instruments.BUY closes a liquidated short, and SELL closes a liquidated long.MARKET. This is a placeholder value because OKX does not send an order type.IOC. This is a placeholder value because OKX does not send a time in force.ctVal.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.bkPx, the same value as price. Not an execution price.FILLED. This is a placeholder value, not an execution status.sz, the same value as quantity.sz, the same value as quantity.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,bkLossandccy.
For the column types and descriptions, refer to the Liquidations schema.