WebSockets

The WebSocket gateway provides real-time streaming access to market data and trading updates on the Ethereal exchange. Clients subscribe to channels over a persistent connection and receive plain JSON payloads with short-form keys, optimized for low latency, minimal overhead, and fast parsing.

URL	Status
wss://ws2.ethereal.trade/v1/stream	Live on testnet

Native WebSocket (v2) is not yet live on mainnet. Early access is available on testnet via wss://ws2.etherealtest.net/v1/stream. Visit Socket.IO (v1) if you are looking for socket.io based websocket streams currently live on mainnet.

Subscription

The subscription gateway offers multiple data streams for real-time and periodic updates. Some channels e.g. OrderUpdate push messages immediately as they occur, while others e.g. L2Book emit messages at fixed intervals. Payload formats and message shapes are documented below.

L2Book

Provides L2 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",
  "t": <epoch>,
  "data": {
    "s": "<string>",
    "t": <epoch>,
    "pt": Optional<epoch>,
    "a": [[price: string, quantity: string]],
    "b": [[price: string, quantity: string]]
  }
}

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

• e - event name

• t - server timestamp (epoch in milliseconds)

• data - L2 Book price levels details

  • s - symbol e.g. BTCUSD

  • t - calculated book timestamp (epoch in milliseconds)

  • pt - previous calculated book timestamp (epoch in milliseconds) - optional

    • Using both the pt and data.t you can infer whether or not any events were missed during connection or during consumption

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

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

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.

TICKER

Delivers real-time ticker data feeds for a specified product.

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

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

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

• e - event name Ticker

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

• data - Real time ticker data

  • s - symbol e.g. BTCUSD

  • t - calculated best bid / ask book timestamp

  • bidPx - best bid price

  • askPx - best ask price

  • bidAmt - total quantity at the best bid

  • askAmt - total quantity at the best ask

  • markPx - current mark price

  • mark24hPx - 24h mark price

In extreme cases, Ticker will skip publishing if both bidPx & askPx are not available. All values are returned as decimals (9 precision).

TRADE_FILL

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

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

// Response message
{
    "e": "TradeFill",
    "t": <epoch>,
    "data": {
        "s": "<symbol>",
        "t": <epoch>,
        "fills":[{
            "id": "<uuid>",
            "px": "<string>",
            "sz": "<string>",
            "sd": 0|1,
            "sids": ["<uuid>", "<uuid>"]
        }]
    }
}

TRADE_FILL events are streamed in real-time as they occur and from the perspective of the taker (i.e. sz, sd).

• e - event name

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

• data

  • s - symbol of product traded

  • t - timestamp trade fills happened (epoch in milliseconds)

  • fills - array of fills that occurred on the product

    • s - symbol e.g. BTCUSD where the trade fill occurred on

    • id - trade fill identifier

    • px - execution price

    • sz - quantity traded

    • sd - side (0=BUY or 1=SELL) from the perspective of the taker

    • sids - tuple of the taker subaccount id and the maker subaccount id

SUBACCOUNT_LIQUIDATION

Provides an update when a subaccount is liquidated.

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

// Response message
{
  "e": "SubaccountLiquidation",
  "t": <epoch>,
  "data": {
    "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. SubaccountLiquidation events are emitted in real-time.

• e - event name

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

• data - Liquidation subaccount data

  • sid - id of liquidated sub-account

  • t - timestamp sub-account was liquidated (epoch in miliseconds)

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

    • price - mark price at the time of liquidation

    • sz - position size at liquidation (positive of long, negative if short)

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",
  "t": <epoch>,
  "data": {
    "t": <epoch>,
    "d": [
      {
        "id": "<uuid>",
        "cloid": "<string>",
        "otyp": "LIMIT" | "MARKET",
        "qty": "<string>",
        "aqty": "<string>",
        "fill": "<string>",
        "px": "<string>",
        "sd": 0|1,
        "s": "<string>",
        "sid": "<uuid>",
        "st": "<string>",
        "t": <epoch>,
        "ro": boolean,
        "cl": boolean,
        "tif": "<string>",
        "et": <epoch>,
        "po": boolean,
        "spx": "<string>",
        "styp": <number>,
        "spxtyp": <number>,
        "tr": "<string>",
        "gtyp": <number>,
        "gid": "<uuid>"
      }
    ]
  }
}

ORDER_UPDATE events are emitted in real-time, published per-subaccount whenever an order's state changes.

• e - event name

• t - server timestamp (epoch in milliseconds)

• data - order update details

  • t - update timestamp (epoch in milliseconds)

  • d - array of order updates

    • id - order ID (UUID)

    • cloid - client order ID - optional

    • otyp - order type

    • qty - original quantity

    • aqty - available (remaining) quantity

    • fill - filled amount

    • px - limit price - optional, omitted for market orders

    • sd - side (BUY=0, SELL=1)

    • s - symbol e.g. BTCUSD

    • sid - subaccount ID (UUID)

    • st - order status

    • t - order created timestamp (epoch in milliseconds)

    • ro - reduce only (boolean)

    • cl - close (boolean)

    • tif - time in force - optional

    • et - expires at (epoch in seconds) - optional

    • po - post only - optional

    • spx - stop price - optional

    • styp - stop type - optional

    • spxtyp - stop price type - optional

    • tr - triggered state

    • gtyp - group contingency type - optional

    • gid - group ID (UUID) - optional

ORDER_FILL

Notifies when orders are filled for a specific subaccount.

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

// Response message
{
  "e": "OrderFill",
  "t": <epoch>,
  "data": {
    "t": <epoch>,
    "d": [
      {
        "id": "<uuid>",
        "oid": "<uuid>",
        "cloid": "<string>",
        "px": "<string>",
        "sz": "<string>",
        "typ": "LIMIT" | "MARKET",
        "sd": 0|1,
        "s": "<string>",
        "sid": "<uuid>",
        "ro": boolean,
        "fee": "<string>",
        "m": boolean,
        "t": <epoch>
      }
    ]
  }
}

ORDER_FILL events are emitted in real-time as they occur, published per-subaccount whenever an order is filled (both maker and taker sides receive their own event).

• e - event name

• t - server timestamp (epoch in milliseconds)

• data - order fill details

  • t - fill timestamp (epoch in milliseconds)

  • d - array of order fills

    • id - fill ID (UUID)

    • oid - order ID (UUID)

    • cloid - client order ID - optional

    • px - fill price

    • sz - filled quantity

    • typ - order type

    • sd - side

    • s - symbol e.g. BTCUSD

    • sid - subaccount ID (UUID)

    • ro - reduce only

    • fee - fee in USD

    • m - is maker

    • t - created at timestamp (epoch in milliseconds)

TOKEN_TRANSFER

Provides updates for deposits / withdrawals for a specific subaccount.

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

// Response message
{
  "e": "TokenTransfer",
  "t": <epoch>,
  "data": {
    "t": <epoch>,
    "id": "<uuid>",
    "sid": "<uuid>",
    "tName": "<string>",
    "tAddr": "<hex>",
    "typ": "<string>",
    "st": "<string>",
    "amt": "<string>",
    "fee": "<string>",
    "iniBk": "Optional<string>",
    "finBk": "Optional<string>",
    "iniTx": "Optional<hex>",
    "finTx": "Optional<hex>",
    "lzAddr": "Optional<hex>",
    "lzEid": "Optional<string>"
  }
}

TOKEN_TRANSFER events are published per-subaccount when a deposit or withdrawal state changes.

• e - event name

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

• data - token transfer details

  • id - unique identifier of the transfer

  • t - timestamp token transfer event (epoch in miliseconds)

  • sid - subaccount id that owns this transfer

  • tName - token name

  • tAddr - token contract address

  • typ - transfer type, one of: "DEPOSIT", "WITHDRAW"

  • st - transfer status, one of: "SUBMITTED", "PENDING", "COMPLETED", "REJECTED"

  • amt - transfer amount

  • fee - transaction fee

  • iniBk - block number when the transfer was initiated (optional)

  • finBk - block number when the transfer was finalized (optional)

  • iniTx - Transaction hash of the initiation transaction (optional)

  • finTx - Transaction hash of the finalization transaction (optional)

  • lzAddr - LayerZero destination address for cross-chain bridge transfers (optional)

  • lzEid - LayerZero endpoint id identifying the destination chain

Unsubscribing from Channels

To unsubscribe from a channel, send the same payload used to subscribe but with unsubscribe as the event type. Alternatively, disconnecting your entire connection will end all subscriptions. Note that reconnecting will consume rate limits. See System Limits for more details.

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

Exception Handling

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, ... }