The Realtime API streams DerivaDEX market data and account-specific updates over one WebSocket connection.
wss://exchange.derivadex.com/realtime-api
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 UPDATEs. 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 UPDATEs. 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 UPDATEs. | 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://exchange.derivadex.com/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 with the flow in Realtime Connection Model and re-subscribe to the required feeds. |
Last modified on April 27, 2026
