Realtime Examples - DerivaDEX Docs

The Realtime API uses JSON messages over one WebSocket connection. Market-data feeds send populated PARTIAL snapshots first; user-data feeds send an empty PARTIAL first and then UPDATE messages.

Subscription messages

{
  "action": "SUBSCRIBE",
  "nonce": "foo",
  "feeds": [
    {
      "feed": "ORDER_BOOK_L2",
      "params": {
        "orderBookL2Filters": [
          {
            "symbol": "ETHP",
            "aggregation": 1
          }
        ]
      }
    }
  ]
}

Unsubscribe from feeds

{
  "action": "UNSUBSCRIBE",
  "nonce": "foo",
  "feeds": ["ORDER_UPDATE", "ORDER_BOOK_L2"]
}

Acknowledgements

{
  "action": "SUBSCRIBE",
  "nonce": "foo",
  "result": {}
}

{
  "action": "UNSUBSCRIBE",
  "nonce": "bar",
  "result": {
    "error": "Unexpected error."
  }
}

Market-data messages

L2 order book snapshot

{
  "sequence": 0,
  "ordinal": 0,
  "feed": "ORDER_BOOK_L2",
  "subscriptionKey": "ORDER_BOOK_L2|symbol=ETHP|aggr=0.1",
  "contents": {
    "messageType": "PARTIAL",
    "data": [
      {
        "symbol": "ETHP",
        "side": 0,
        "amount": "50.25",
        "price": "2000.0"
      },
      {
        "symbol": "ETHP",
        "side": 1,
        "amount": "100.5",
        "price": "2000.5"
      }
    ]
  }
}

L2 order book update with a removed row

{
  "sequence": 1,
  "ordinal": 1,
  "feed": "ORDER_BOOK_L2",
  "subscriptionKey": "ORDER_BOOK_L2|symbol=ETHP|aggr=1",
  "contents": {
    "messageType": "UPDATE",
    "data": [
      {
        "symbol": "ETHP",
        "side": 0,
        "amount": "0",
        "price": "2100"
      },
      {
        "symbol": "ETHP",
        "side": 1,
        "amount": "15.5",
        "price": "2101"
      }
    ]
  }
}

L3 order book snapshot

{
  "sequence": 0,
  "ordinal": 0,
  "feed": "ORDER_BOOK_L3",
  "subscriptionKey": "ORDER_BOOK_L3|symbol=ETHP",
  "contents": {
    "messageType": "PARTIAL",
    "data": [
      {
        "orderHash": "0x92aaeac66831b00d0db66517debb3eac7370105d854420ed82",
        "symbol": "ETHP",
        "side": 0,
        "originalAmount": "50",
        "amount": "50",
        "price": "2000",
        "traderAddress": "0x00112233445566778899aabbccddeeff0011223344",
        "strategyIdHash": "0x2576ebd1",
        "bookOrdinal": 0
      }
    ]
  }
}

Mark price update

{
  "sequence": 1,
  "ordinal": 1,
  "feed": "MARK_PRICE",
  "subscriptionKey": "MARK_PRICE|symbols=BTCP",
  "contents": {
    "messageType": "UPDATE",
    "data": [
      {
        "globalOrdinal": 1,
        "epochId": 44,
        "price": "30500.57",
        "fundingRate": "0.003532",
        "symbol": "BTCP",
        "createdAt": "2023-10-01T12:01:00Z"
      }
    ]
  }
}

Order updates

Empty user-data snapshot

{
  "sequence": 0,
  "ordinal": 0,
  "feed": "ORDER_UPDATE",
  "subscriptionKey": "ORDER_UPDATE|trader=0x00aabbccddeeff00112233445566778899aabbccdd|strategy=0x2576ebd1|symbol=ETHP|reason=",
  "contents": {
    "messageType": "PARTIAL",
    "data": []
  }
}

Posted order

{
  "sequence": 1,
  "ordinal": 1,
  "feed": "ORDER_UPDATE",
  "subscriptionKey": "ORDER_UPDATE|trader=0x00aabbccddeeff00112233445566778899aabbccdd|strategy=0x2576ebd1|symbol=ETHP|reason=",
  "contents": {
    "messageType": "UPDATE",
    "data": [
      {
        "globalOrdinal": 0,
        "epochId": 200,
        "reason": 0,
        "amount": "0",
        "quoteAssetAmount": "0",
        "symbol": "ETHP",
        "orderMatchOrdinal": 8,
        "ordinal": 0,
        "makerOrderIntent": {
          "epochId": 200,
          "orderHash": "0xa1b2c3d4e5f67890abcdef01234567891234567890123456789",
          "symbol": "ETHP",
          "side": 0,
          "amount": "20",
          "price": "100",
          "traderAddress": "0x00f1e2d3c4b5a6978899aabbccddeeff1122334455",
          "strategyIdHash": "0x2576ebd1",
          "orderType": 0,
          "stopPrice": "0",
          "nonce": "nonce-maker-1",
          "signature": "0xfedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
          "createdAt": "2023-10-01T11:59:50Z"
        },
        "createdAt": "2023-10-01T12:00:05Z"
      }
    ]
  }
}

Trade outcome

{
  "sequence": 2,
  "ordinal": 2,
  "feed": "ORDER_UPDATE",
  "subscriptionKey": "ORDER_UPDATE|trader=0x00aabbccddeeff00112233445566778899aabbccdd|strategy=0x2576ebd1|symbol=ETHP|reason=",
  "contents": {
    "messageType": "UPDATE",
    "data": [
      {
        "globalOrdinal": 0,
        "epochId": 200,
        "reason": 1,
        "amount": "10",
        "quoteAssetAmount": "2000",
        "symbol": "ETHP",
        "price": "100",
        "orderMatchOrdinal": 10,
        "ordinal": 0,
        "cumulativeFilledAmount": "10",
        "cumulativeQuoteAssetTransactedAmount": "2000",
        "makerRealizedPnl": "30",
        "takerFeeDDX": "0.05",
        "takerRealizedPnl": "50",
        "makerOrderIntent": {
          "epochId": 200,
          "orderHash": "0xa1b2c3d4e5f67890abcdef01234567891234567890123456789",
          "symbol": "ETHP",
          "side": 0,
          "amount": "20",
          "price": "100",
          "traderAddress": "0x00f1e2d3c4b5a6978899aabbccddeeff1122334455",
          "strategyIdHash": "0x2576ebd1",
          "orderType": 0,
          "stopPrice": "0",
          "nonce": "nonce-maker-1",
          "signature": "0xfedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
          "createdAt": "2023-10-01T11:59:50Z"
        },
        "takerOrderIntent": {
          "epochId": 200,
          "orderHash": "0xb1c2d3e4f5a67890abcdef0123456789234567890abcdef12",
          "symbol": "ETHP",
          "side": 1,
          "amount": "20",
          "price": "100",
          "traderAddress": "0x00aabbccddeeff00112233445566778899aabbccdd",
          "strategyIdHash": "0x2576ebd1",
          "orderType": 0,
          "stopPrice": "0",
          "nonce": "nonce-taker-1",
          "signature": "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
          "createdAt": "2023-10-01T11:59:55Z"
        },
        "createdAt": "2023-10-01T12:00:05Z"
      }
    ]
  }
}

Order rejection

{
  "sequence": 4,
  "ordinal": 4,
  "feed": "ORDER_UPDATE",
  "subscriptionKey": "ORDER_UPDATE|trader=0x00aabbccddeeff00112233445566778899aabbccdd|strategy=0x2576ebd1|symbol=ETHP|reason=",
  "contents": {
    "messageType": "UPDATE",
    "data": [
      {
        "globalOrdinal": 4,
        "epochId": 201,
        "orderRejection": 4,
        "reason": 4,
        "amount": "0",
        "symbol": "ETHP",
        "price": "100",
        "makerOrderIntent": {
          "epochId": 201,
          "orderHash": "0xa1b2c3d4e5f67890abcdef01234567891234567890123456789",
          "symbol": "ETHP",
          "side": 0,
          "amount": "5",
          "price": "",
          "traderAddress": "0x00c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3",
          "strategyIdHash": "0x2576ebd1",
          "orderType": 0,
          "stopPrice": "",
          "nonce": "",
          "signature": "",
          "createdAt": "2023-10-01T11:59:50Z"
        },
        "createdAt": "2023-10-01T12:00:10Z"
      }
    ]
  }
}

Order-update example variants

Example	Key fields
Empty partial	`messageType: PARTIAL`, empty `data` array
Posted order	`reason: 0`, `makerOrderIntent`
Trade outcome	`reason: 1`, maker and taker order intents, fill amounts, realized PnL, fees
Self-match rejection after previous trade outcomes	`reason: 4`, `orderRejection: 0`, previous fill fields
Full order rejection	`reason: 4`, `orderRejection: 4`, empty unavailable order-intent fields
User cancellation	`reason: 3`, canceled order intent
Cancel rejection	`reason: 5`, `cancelRejection: 0`
Liquidation	`reason: 2`, liquidated trader and strategy identifiers

Strategy updates

Collateral deposit

{
  "sequence": 1,
  "ordinal": 1,
  "feed": "STRATEGY_UPDATE",
  "subscriptionKey": "STRATEGY_UPDATE|trader=0x00aabbccddeeff00112233445566778899aabbccdd|strategy=0x2576ebd1|reason=",
  "contents": {
    "messageType": "UPDATE",
    "data": [
      {
        "globalOrdinal": 0,
        "epochId": 300,
        "reason": 0,
        "traderAddress": "0x00a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
        "strategyIdHash": "0x2576ebd1",
        "collateralAddress": "0x00aabbccddeeff00112233445566778899aabbccdd",
        "collateralSymbol": "USDC",
        "amount": "1000",
        "newAvailCollateral": "5000",
        "blockNumber": 150000,
        "createdAt": "2023-10-01T12:05:00Z"
      }
    ]
  }
}

Trade and fee updates

{
  "sequence": 8,
  "ordinal": 8,
  "feed": "STRATEGY_UPDATE",
  "subscriptionKey": "STRATEGY_UPDATE|trader=0x00aabbccddeeff00112233445566778899aabbccdd|strategy=0x2576ebd1|reason=",
  "contents": {
    "messageType": "UPDATE",
    "data": [
      {
        "globalOrdinal": 7,
        "epochId": 308,
        "reason": 5,
        "traderAddress": "0x00aabbccddeeff00112233445566778899aabbccdd",
        "strategyIdHash": "0x2576ebd1",
        "collateralAddress": "0x00abc123def4567890abcdef1234567890abcdef",
        "collateralSymbol": "USDC",
        "amount": "25",
        "positions": [
          {
            "symbol": "ETHP",
            "balance": "40",
            "side": 0,
            "avgEntryPrice": "100",
            "realizedPnl": "25"
          }
        ],
        "newAvailCollateral": "2000",
        "createdAt": "2023-10-01T12:14:00Z"
      },
      {
        "globalOrdinal": 8,
        "epochId": 308,
        "reason": 6,
        "traderAddress": "0x00aabbccddeeff00112233445566778899aabbccdd",
        "strategyIdHash": "0x2576ebd1",
        "collateralAddress": "0x00abc123def4567890abcdef1234567890abcdef",
        "collateralSymbol": "USDC",
        "amount": "-0.75",
        "newAvailCollateral": "1999.25",
        "createdAt": "2023-10-01T12:14:00Z"
      }
    ]
  }
}

Strategy-update example variants

Example	Key fields
Empty partial	`messageType: PARTIAL`, empty `data` array
Collateral deposit	`reason: 0`, positive `amount`, `newAvailCollateral`
Collateral withdrawal	`reason: 1`, negative `amount`, `newLockedCollateral`
Withdrawal intent	`reason: 2`, `newAvailCollateral`, `newLockedCollateral`
Withdrawal rejection	`reason: 9`, `withdrawRejection`
PnL realization	`reason: 4`, `positions[].realizedPnl`
Liquidation	`reason: 7`, negative `amount`, collateral zeroing fields
Funding payment	`reason: 3`, funding `amount`
Trade and fee	`reason: 5` for trade and `reason: 6` for fee
ADL	`reason: 8`, ADL collateral effect

Trader updates

DDX deposit

{
  "sequence": 1,
  "ordinal": 1,
  "feed": "TRADER_UPDATE",
  "subscriptionKey": "TRADER_UPDATE|trader=0x00112233445566778899aabbccddeeff00112233|reason=",
  "contents": {
    "messageType": "UPDATE",
    "data": [
      {
        "globalOrdinal": 0,
        "epochId": 500,
        "reason": 0,
        "traderAddress": "0x00112233445566778899aabbccddeeff00112233",
        "amount": "150",
        "newAvailDDXBalance": "1150",
        "blockNumber": 123456,
        "createdAt": "2023-10-01T12:15:00Z"
      }
    ]
  }
}

Trade mining reward

{
  "sequence": 6,
  "ordinal": 6,
  "feed": "TRADER_UPDATE",
  "subscriptionKey": "TRADER_UPDATE|trader=0x00abcdefabcdefabcdefabcdefabcdefabcdefabcd|reason=",
  "contents": {
    "messageType": "UPDATE",
    "data": [
      {
        "globalOrdinal": 5,
        "epochId": 505,
        "reason": 3,
        "traderAddress": "0x00abcdefabcdefabcdefabcdefabcdefabcdefabcd",
        "amount": "12",
        "newAvailDDXBalance": "1232",
        "createdAt": "2023-10-01T12:19:00Z"
      }
    ]
  }
}

Trader-update example variants

Example	Key fields
Empty partial	`messageType: PARTIAL`, empty `data` array
DDX deposit	`reason: 0`, positive `amount`, `newAvailDDXBalance`
DDX withdrawal	`reason: 1`, negative `amount`, `newLockedDDXBalance`
DDX withdrawal intent	`reason: 2`, `newAvailDDXBalance`, `newLockedDDXBalance`
DDX withdrawal rejection	`reason: 9`, `withdrawDDXRejection`
Profile update	`reason: 4`, `payFeesInDDX`
Trade mining reward	`reason: 3`, reward `amount`
DDX fee charged	`reason: 8`, negative `amount`
Fee distribution reward	`reason: 5`, reward `amount`

​Subscription messages

​Subscribe to L2 order book updates

​Unsubscribe from feeds

​Acknowledgements

​Market-data messages

​L2 order book snapshot

​L2 order book update with a removed row

​L3 order book snapshot

​Mark price update

​Order updates

​Empty user-data snapshot

​Posted order

​Trade outcome

​Order rejection

​Order-update example variants

​Strategy updates

​Collateral deposit

​Trade and fee updates

​Strategy-update example variants

​Trader updates

​DDX deposit

​Trade mining reward

​Trader-update example variants

​Related references