Websocket Gateway

Overview

The gateway ws subscription allow users to listen to data streams in real-time data, delivering instant trading updates directly from the Ethereal exchange platform. To interact with the subscription gateway API, send websocket messages after connecting to wss://ws.ethereal.trade/v1/stream.

Socket.io

Ethereal uses Socket.io, a library that extends the standard WebSocket protocol. Socket.io provides ready-made client libraries in multiple languages with automatic reconnection handling and built-in ping/pong frames to maintain stable connections, saving developers from implementing these basic features themselves.

Refer to Socket.io for language specific client implementations.

Team is now internally testing native WebSockets; Socket.io will be replaced and removed. If you are using the Python SDK, the transition should be seamless aside from a future upgrade requirement.

Migration Native WebSockets will be available on testnet first for integrators to test and provide feedback. After mainnet release, both Socket.io and native WebSockets will remain available for a transition period to allow a smooth migration without disruption.

WebSockets

Ethereal also offers WebSocket support, which communicates with plain JSON payloads, resulting in lower latency, reduced overhead, and smaller message sizes. This makes it well-suited for latency-sensitive integrations and lightweight clients that don't need the built-in reconnections provided by Socket.io.

Websockets support a subset of the Socket.io feeds. If you require additional data streams, use the Socket.io gateway above which supports the full set of subscription types.

Socket.io Subscription Streams

Subscribe

The WebSocket gateway offers the following subscription streams:

BOOK_DEPTH - Provides order book depth updates for a specific product.

// Subscription message payload
{
  "type": "BookDepth",
  "productId": "<uuid>"
}

// Response message
{
  "timestamp": "<epoch>",
  "previousTimestamp": "<epoch>",
  "productId": "<uuid>",
  "asks": [[price: string, quantity: string]],
  "bids": [[price: string, quantity: string]]
}

• BookDepth events are emitted on a configurable fixed interval (as of writing, this is configured to be once every 200ms)

• previousTimestamp is in milliseconds and represents the last time the BookDepth emitted

• timestamp also in milliseconds and the system timestamp of when this BookDepthwas emitted

• Using both the previousTimestamp and timestamp you can infer whether or not any events were missed during connection or during consumption

• asks an array of price/quantity tuples representing asks

• bids an array of price/quantity tuples representing bids

A BookDepth message of the current book (up to 100 price levels per side) is emitted back on initial connection. Every subsequent message is a price level diff with absolute quantities. A zero quantity price diff indicates that this level has been removed.

MARKET_PRICE - Delivers real-time market price updates for a specified product.

// Subscription message payload
{
  "type": "MarketPrice",
  "productId": "<uuid>"
}

// Response message (same as `/v1/product/market-price`)
// @see: https://api.ethereal.trade/docs#/Product/ProductController_getMarketPrice
{
  "productId": "<uuid>",
  "bestBidPrice": numberString,
  "bestAskPrice": numberString,
  "oraclePrice": numberString,
  "price24hAgo": numberString
}

• MarketPrice events are emitted on a configurable fixed interval (currently configured to be once every second)

ORDER_FILL - Notifies when orders are filled for a specific subaccount.

// Subscription message payload
{
  "type": "OrderFill",
  "subaccountId": "<uuid>"
}

// Response message (same as `/v1/order/fill`)
// @see: https://api.ethereal.trade/docs#/Order/OrderController_listFillsBySubaccountId
{
  "data": [
      {
        "id": "<uuid>",
        "orderId": "<uuid>",
        "clientOrderId": "string",
        "price": numberString,
        "filled": numberString,
        "type": "LIMIT|MARKET",
        "side": 0|1,
        "reduceOnly": boolean,
        "feeUsd": numberString,
        "isMaker": boolean,
        "productId": "<uuid>",
        "subaccountId": "<uuid>",
        "createdAt": "<epoch>"
      }
    ]
}

• OrderFill events are emitted in real-time as they occur

TRADE_FILL - Provides a stream of trades that have occurred filtered by product.

// Subscription message payload
{
  "type": "TradeFill",
  "productId": "<uuid>"
}

// Response message
{
  "data": [
    {
      "id": "<uuid>",
      "price": numberString,
      "filled": numberString,
      "takerSide": 0|1,
      "createdAt": "<epoch>"
    }
  ],
  "productId": "<uuid>"
}

• TradeFill events are emitted in real-time as they occur

• Similar to OrderFill, an array of trade fills will be emitted in a single message, grouped by the product they were traded on

ORDER_UPDATE - Provides updates about order status changes for a specific subaccount.

// Subscription message payload
{
  "type": "OrderUpdate",
  "subaccountId": "<uuid>"
}

// Response message (same as `/v1/order`)
// @see https://api.ethereal.trade/docs#/Order/OrderController_listBySubaccountId
{
  "data": [
    {
      "id": "<uuid>",
      "clientOrderId": "string",
      "type": "LIMIT"|"MARKET",
      "availableQuantity": numberString,
      "quantity": numberString,
      "side": 0|1,
      "productId": "<uuid>",
      "subaccountId": "<uuid>",
      "status": "<status>",
      "reduceOnly": boolean,
      "close": booleanue,
      "updatedAt": "<epoch>",
      "createdAt": "<epoch>",
      "sender": "<address>",
      "price": numberString,
      "filled": numberString,
      "stopPrice": numberString,
      "stopType": "<stopType>",
      "stopPriceType": "<stopPriceType>",
      "timeInForce": "<tif>",
      "expiresAt": "<epochInSeconds>",
      "postOnly": boolean,
      "groupContingencyType": "<groupContingencyType>",
      "groupId": "<uuid>"
    }
  ]
}

• OrderUpdate events are emitted in real-time

Only the latest update processed is emitted and intermediary states are omitted.

SUBACCOUNT_LIQUIDATION - Provides an update when a subaccount is liquidated.

// Subscription message payload
{
  "type": "SubaccountLiquidation",
  "subaccountId": "<uuid>"
}

// Response message
{
  "subaccountId": "<uuid>",
  "liquidatedAt": "<epoch>"
}

• SubaccountLiquidation events are emitted in real-time

• subaccountId the subaccount that has been liquidated, liquidatedAt the time (in ms, since the Unix epoch) when the liquidation occurred

TOKEN_TRANSFER - Updates on token transfers (deposits/withdrawals) for a specific subaccount.

// Subscription message payload
{
  "type": "TokenTransfer",
  "subaccountId": "<uuid>"
}

// Response message (same as `/v1/token/transfer` with pagination)
// @see https://api.ethereal.trade/docs#/Token/TokenController_listTransfers
{
  "id": "<uuid>",
  "initiatedBlockNumber": numberString,
  "finalizedBlockNumber": numberString,
  "status": "<status>",
  "subaccountId": "<uuid>",
  "tokenName": "string",
  "tokenAddress": "<address>",
  "type": "WITHDRAW"|"DEPOSIT",
  "amount": numberString,
  "lzDestinationAddress": "<address>",
  "lzDestinationEid": number,
  "fee": numberString,
  "createdAt": "<epoch>",
  "initiatedTransactionHash": "<hex>",
  "finalizedTransactionHash": "<hex>"
}

Each subscription requires specific parameters as shown in the formats above. To subscribe to these streams, emit a 'subscribe' event to the socket with the appropriate subscription message.

During connection establishment ensure websocket is the only configured transport (i.e. transports: ['websocket']).

Unsubscribe

To stop receiving data from a previously established subscription, you can unsubscribe using the same payload format as your original subscription. Simply emit an unsubscribe event to the socket with the identical payload structure you used when subscribing.

Handling Socket.io Exceptions

Exceptions are exposed in its own event aptly named "exception". Exceptions follow the following shape:

{
  pattern: 'order:dryRun',
  status: 'BadRequest',
  error: {
    message: [
      'subaccount is not a valid subaccount',
    ]
  }
}

• pattern indicates the source event pattern if available e.g. "subscribe"

• status the error status

• error general body of the error its shape changes depending on the status

Websocket Subscription Streams

The Native WebSocket interface provides a streamlined alternative to Socket.IO for subscribing to real-time data streams. Subscriptions follow the same channel-based model but use a simplified payload format with short-form keys for reduced bandwidth and faster parsing.

Below is the initial specification for the upcoming native WebSocket stream. As of writing, native WebSockets are not yet live and this specification is subject to change. Feedback is welcome.

Subscribe

There are few minor differences subscription payloads compared to socket.io .

• symbol is used as an identifier instead of productId

• Short form keys are returned instead

• e event type is returned for customized message handling

L2Book (replaces BOOK_DEPTH ) - Provides order book depth updates for a specific product.

// Subscription message payload
{
  "event": "subscribe",
  "data": {
    "type": "L2Book",
    "symbol": "<string>" // e.g. "BTCUSD", "ETHUSD"
  }
}

// Response message
{
  "e": "L2Book",
  "s": "<string>",
  "t": <epoch>,
  "pt": <epoch>,
  "a": [[price: string, quantity: string]],
  "b": [[price: string, quantity: string]]
}

• e is the event name

• s is the symbol e.g. BTCUSD

• t is the timestamp (epoch in milliseconds)

• pt is the previous timestamp (epoch in milliseconds) - optional

• a are asks, array of [price, qty] pairs

• b are bids, array of [price, qty] pairs

L2Book is a renaming of the Socket.IO BookDepth stream.

MARKET_PRICE - Delivers real-time market price updates for a specified product.

// Subscription message payload
{
  "event": "subscribe",
  "data": {
    "type": "MarketPrice",
    "symbol": "<string>" // e.g. "BTCUSD", "ETHUSD"
  }
}

// Response message
{
  "e": "MarketPrice",
  "s": "<string>",
  "t": <epoch>,
  "bidPx": "Optional<string>",
  "askPx": "Optional<string>",
  "bidAmt": "Optional<string>",
  "askAmt": "Optional<string>",
  "markPx": "Optional<string>",
  "mark24hPx": "Optional<string>"
}

• e is the event name

• s is the symbol e.g. BTCUSD

• t is the server timestamp this message was emitted at (epoch in milliseconds)

• bidPx is the best bid price

• askPx is the best ask price

• bidAmt is the total quantity at the best bid

• askAmt is the total quantity at the best ask

• markPx is the current mark price

• mark24hPx is the 24h mark price

MarketPrice fields can be explored with some minor renaming. In extreme cases, MarketPrice will skip publishing if both bidPx & askPx are not available. All numbers are returned as decimals (9 precision).

SUBACCOUNT_LIQUIDATION - Provides an update when a subaccount is liquidated.

// Subscription message payload
{
  "event": "subscribe",
  "data": {
    "type": "SubaccountLiquidation",
    "subaccountId": "<uuid>"
  }
}

// Response message
{
  "e": "SubaccountLiquidation",
  "sid": "<uuid>",
  "t": <epoch>,
  "p": [
    {
      "s": "<string>",
      "px": "<string>",
      "sz": "<string>"
    }
  ]
}

• When a subaccount is liquidated, all positions are transferred to the insurance fund and derisked at a later time.

• p - An array of positions liquidated (subaccount may have one or many positions):

  • price is the mark price at the time of liquidation

  • sz is the position size at liquidation

• t is the server timestamp (epoch in milliseconds)

• sid is the id of liquidated subaccount

ORDER_UPDATE - Provides updates about order status changes for a specific subaccount.

// Subscription message payload
{
  "event": "subscribe",
  "data": {
    "type": "OrderUpdate",
    "subaccountId": "<uuid>"
  }
}

// Response message
{
  "e": "OrderUpdate",
  "data": OrderDto[],
  "t": <epoch>,
}

• data is the same response type as OrderDto

• t is the server timestamp (epoch in milliseconds)

Unsubscribe

Similar to subscribe request format we have, instead use unsubscribe as the event type:

{
  "event": "unsubscribe",
  "data": {
    "type": "MarketPrice",
    "symbol": "<string>" // e.g. "BTCUSD", "ETHUSD"
  }
}

Handling Websocket Exceptions

Error responses are returned directly as a reply to the originating event (e.g. subscribe, unsubscribe). They follow a unified shape:

{
  "ok": false,
  "code": "unknown_product"
}

• ok indicates whether the request succeeded

• code a machine-readable error code present when ok is false

Error codes	Description
unknown_product	The provided symbol does not match any known product.
validation_error	The request payload failed validation (e.g. missing or invalid fields).
subscription_failed	The server was unable to subscribe to the requested topic.
unsubscribe_failed	The server was unable to unsubscribe from the requested topic.
rate_limit	Too many requests, the client has been rate-limited.
internal_error	An unexpected server-side error occurred.

A successful response would simply just return { "ok": true, ... }