Realtime Channels - DerivaDEX Docs

The Realtime API streams DerivaDEX market data and account-specific updates over one WebSocket connection.

wss://testnet.derivadex.io/realtime-api

Clients send subscribe and unsubscribe messages on the connection and receive an acknowledgement with the same nonce. Market-data feeds send an initial PARTIAL snapshot before UPDATE messages. User-data feeds start with an empty PARTIAL, so clients fetch current order, strategy, and trader state with REST before applying realtime updates.

Subscription control

Channel	Message	Payload	Use it for
`subscribe`	`subscribe`	`subscribePayload`	Subscribe to one or more feeds with the parameters required by each feed.
`unsubscribe`	`unsubscribe`	`unsubscribePayload`	Stop one or more feed subscriptions.
`subscribe` / `unsubscribe`	`acknowledge`	`acknowledgePayload`	Match success or failure responses to client requests by `nonce`; an empty `result` means success.

Public market-data feeds

Channel	Feed	Payload	Snapshot behavior	Use it for
`orderBookL2`	`ORDER_BOOK_L2`	`orderBookL2Payload`	First message is the current L2 book as `PARTIAL`; later messages are `UPDATE`s. An `amount` of `0` removes the price level.	Aggregated order book levels by symbol and price aggregation.
`orderBookL3`	`ORDER_BOOK_L3`	`orderBookL3Payload`	First message is the current L3 book as `PARTIAL`; later messages are `UPDATE`s. An `amount` of `0` removes the order row.	Full-depth order book rows by symbol.
`markPrice`	`MARK_PRICE`	`markPricePayload`	First message is the latest mark prices and funding rates as `PARTIAL`; later messages are `UPDATE`s.	Mark price and funding-rate updates by symbol.

Market-data filters

Feed	Filter fields
`ORDER_BOOK_L2`	`orderBookL2Filters[]` with `symbol` and `aggregation`. Current aggregation values are `0.1`, `1`, and `10` for `ETHP`; `1`, `10`, and `100` for `BTCP`.
`ORDER_BOOK_L3`	`symbols[]`; omitting parameters subscribes to all L3 book orders for all symbols.
`MARK_PRICE`	`symbols[]`; omitting parameters subscribes to all mark prices for all symbols.

User-data feeds

Channel	Feed	Payload	Snapshot behavior	Use it for
`orderUpdate`	`ORDER_UPDATE`	`orderUpdatePayload`	First message is an empty `PARTIAL`; use REST for the initial order state.	Order posts, fills, cancellations, liquidations, ADL, order rejections, and cancel rejections. Messages include maker and taker or liquidated-trader details when applicable.
`strategyUpdate`	`STRATEGY_UPDATE`	`strategyUpdatePayload`	First message is an empty `PARTIAL`; use REST for the initial strategy state.	Strategy collateral changes, deposits, withdrawals, withdrawal intents, funding payments, PnL settlement, trades, fees, liquidations, ADL, and withdrawal rejections.
`traderUpdate`	`TRADER_UPDATE`	`traderUpdatePayload`	First message is an empty `PARTIAL`; use REST for the initial trader DDX balance.	DDX deposits, DDX withdrawals, DDX withdrawal intents, trade mining rewards, fee distribution rewards, profile updates, admission, denial, DDX fees, and DDX withdrawal rejections.

User-data filters

Trader addresses are prefixed with the blockchain discriminant. For Ethereum, the address is prefixed with 0x00.

Feed	Filter fields
`ORDER_UPDATE`	`orderFilters[]` with `traderAddress`, optional `strategyIdHash`, optional `symbol`, and optional `reason`.
`STRATEGY_UPDATE`	`strategyFilters[]` with `traderAddress`, optional `strategyIdHash`, and optional `reason`.
`TRADER_UPDATE`	`traderFilters[]` with `traderAddress` and optional `reason`.

strategyIdHash is the first 4 bytes of the keccak256 hash of the strategy ID encoded as a 32-byte value. The default main strategy hashes to 0x2576ebd1.

Common payload fields

Field	Meaning
`sequence`	Global monotonically increasing sequence assigned by the server to every notification across all feeds and connections. A single connection may see gaps when other notifications do not match its subscriptions.
`ordinal`	Per-connection sequence number across all feed messages delivered to that connection.
`feed`	Feed name, such as `ORDER_BOOK_L2` or `STRATEGY_UPDATE`.
`subscriptionKey`	Normalized key for the subscription and ordering scope.
`contents.messageType`	`PARTIAL` for the initial snapshot, `UPDATE` for later changes.
`contents.data`	Feed-specific records. Decimal quantities are strings to preserve precision.

Update reason codes

Feed	Code	Reason
`ORDER_UPDATE`	`0`	`Post`
`ORDER_UPDATE`	`1`	`Trade`
`ORDER_UPDATE`	`2`	`Liquidation`
`ORDER_UPDATE`	`3`	`Cancellation`
`ORDER_UPDATE`	`4`	`OrderRejection`
`ORDER_UPDATE`	`5`	`CancelRejection`
`STRATEGY_UPDATE`	`0`	`Deposit`
`STRATEGY_UPDATE`	`1`	`Withdraw`
`STRATEGY_UPDATE`	`2`	`WithdrawIntent`
`STRATEGY_UPDATE`	`3`	`FundingPayment`
`STRATEGY_UPDATE`	`4`	`PnlSettlement`
`STRATEGY_UPDATE`	`5`	`Trade`
`STRATEGY_UPDATE`	`6`	`Fee`
`STRATEGY_UPDATE`	`7`	`Liquidation`
`STRATEGY_UPDATE`	`8`	`ADL`
`STRATEGY_UPDATE`	`9`	`WithdrawRejection`
`TRADER_UPDATE`	`0`	`DepositDDX`
`TRADER_UPDATE`	`1`	`WithdrawDDX`
`TRADER_UPDATE`	`2`	`WithdrawDDXIntent`
`TRADER_UPDATE`	`3`	`TradeMiningReward`
`TRADER_UPDATE`	`4`	`ProfileUpdate`
`TRADER_UPDATE`	`5`	`FeeDistribution`
`TRADER_UPDATE`	`6`	`Admission`
`TRADER_UPDATE`	`7`	`Denial`
`TRADER_UPDATE`	`8`	`Fee`
`TRADER_UPDATE`	`9`	`WithdrawDDXRejection`

Rejection codes

Field	Code	Reason	Meaning
`orderRejection`	`0`	`SelfMatch`	Part or all of the order was canceled because the same maker owns the best match.
`orderRejection`	`1`	`SolvencyGuard`	Part or all of the order was canceled for failing solvency guards.
`orderRejection`	`2`	`MaxTakerPriceDeviation`	Part or all of the order was canceled because the maker price deviated too far from the mark price.
`orderRejection`	`3`	`NoLiquidity`	All of the order was canceled because no liquidity remained in the book.
`orderRejection`	`4`	`InvalidStrategy`	All of the order was canceled because the strategy is invalid or nonexistent.
`orderRejection`	`5`	`PostOnlyViolation`	All of the order was canceled because it would have matched immediately.
`cancelRejection`	`0`	`InvalidOrder`	The cancel or modify request failed because the order does not exist.
`withdrawRejection`	`0`	`InvalidStrategy`	The collateral withdrawal failed because the strategy is invalid or nonexistent.
`withdrawRejection`	`1`	`InvalidInsuranceFundContribution`	The insurance fund withdrawal failed because the insurance fund contribution is invalid or nonexistent.
`withdrawRejection`	`2`	`MaxWithdrawalAmount`	The collateral withdrawal failed because the amount exceeds the maximum withdrawal amount.
`withdrawRejection`	`3`	`InsufficientInsuranceFundContribution`	The insurance fund withdrawal failed because the amount exceeds the contribution amount.
`withdrawRejection`	`4`	`InsufficientRemainingInsuranceFund`	The insurance fund withdrawal failed because the remaining insurance fund would be dangerously low.
`withdrawDDXRejection`	`0`	`InvalidTrader`	The DDX withdrawal failed because the trader is invalid or nonexistent.
`withdrawDDXRejection`	`1`	`InsufficientDDXBalance`	The DDX withdrawal failed because the trader has insufficient DDX balance.

Integration notes

Topic	Detail
Connection URL	Connect to `wss://testnet.derivadex.io/realtime-api`.
Bootstrap	Use REST for the initial state of orders, strategies, and trader balances before applying user-data updates.
Ordering	Use sequence and ordinal fields from message payloads to process updates deterministically.
Subscription identity	User-data subscriptions are filtered by trader address, strategy, symbol, or reason.
Recovery	Reconnect, then re-subscribe to the required feeds.

​Subscription control

​Public market-data feeds

​Market-data filters

​User-data feeds

​User-data filters

​Common payload fields

​Update reason codes

​Rejection codes

​Integration notes