Subscription Methods

ExchangeWebSocketClient manages the market WebSocket connection and subscribes to real-time order, trade, cancel, and resolution updates by assetId.

import {
  createExchangeWebSocketClient,
} from "@gammaswap/v2-exchange-sdk";

const marketStream = createExchangeWebSocketClient({
  websocketUrl: "wss://exchange-api.gammaswap.com/ws/",
  onError: (error) => console.error(error),
});

connectionState

Returns the current state of the market WebSocket connection.

const state = marketStream.connectionState;

SDK response:

state

connect

Opens the market WebSocket connection.

const result = await marketStream.connect();

After the socket opens, the WebSocket service sends a connected control message:

{
  "type": "connected",
  "message": "Send {\"type\":\"subscribe\",\"assetId\":\"...\"} to receive market updates"
}

Calling connect() before subscribing is optional. subscribeOrderBook establishes the connection when necessary.

subscribeOrderBook

Subscribes to market updates for an assetId.

const unsubscribe =
  await marketStream.subscribeOrderBook(
    "261336857817713630688382311349658711122006440411137",
    {
      onUpdate: (update) => {
        console.log("Market update", update);
      },
      onOrder: (update) => {
        console.log("Order update", update);
      },
      onTrade: (update) => {
        console.log("Trade update", update);
      },
      onCancel: (update) => {
        console.log("Cancel update", update);
      },
      onResolution: (update) => {
        console.log("Resolution update", update);
      },
      onError: (error) => {
        console.error("Subscription error", error);
      },
      onResyncRequired: (assetId) => {
        console.log("Reload REST order book", assetId);
      },
    },
  );

SDK response:

async () => {
  // Removes this handler.
}

The resolved value is an asynchronous unsubscribe function:

await unsubscribe();

The underlying WebSocket subscription message is:

{
  "type": "subscribe",
  "assetId": "261336857817713630688382311349658711122006440411137"
}

After the subscription is accepted, the service sends:

{
  "type": "subscribed",
  "assetId": "261336857817713630688382311349658711122006440411137"
}

unsubscribeOrderBook

Removes all local handlers for an assetId and unsubscribes from that asset’s server-side market feed.

const result =
  await marketStream.unsubscribeOrderBook(
    "261336857817713630688382311349658711122006440411137",
  );

SDK response:

undefined

The underlying WebSocket unsubscribe message is:

{
  "type": "unsubscribe",
  "assetId": "261336857817713630688382311349658711122006440411137"
}

After the subscription is removed, the service sends:

{
  "type": "unsubscribed",
  "assetId": "261336857817713630688382311349658711122006440411137"
}

unsubscribeOrderBook removes every local handler for the asset.

The unsubscribe function returned by subscribeOrderBook removes only the handler associated with that call.

close

Closes the market WebSocket connection.

const result = marketStream.close();

An optional WebSocket close code and reason can be supplied:

marketStream.close(1000, "Client shutdown");

The client does not reconnect after an intentional close unless a new connection or subscription is started.

Order updates

Order updates are delivered to onOrder and onUpdate.

{
  "type": "order",
  "seqId": 123,
  "data": {}
}

Trade updates

Trade updates are delivered to onTrade and onUpdate.

{
  "type": "trade",
  "seqId": 124,
  "data": {}
}

Cancel updates

Cancel updates are delivered to onCancel and onUpdate.

{
  "type": "cancel",
  "seqId": 125,
  "data": {}
}

Resolution updates

Resolution updates are delivered to onResolution and onUpdate.

{
  "type": "resolution",
  "seqId": 126,
  "data": {}
}

Error messages

If a subscription message cannot be processed, the service sends an error message:

{
  "type": "error",
  "message": "AssetId 123 is not available"
}

Errors are delivered to:

• The subscription’s onError handler

• The client-level onError handler, where applicable

Resynchronization

Market updates include a sequence ID.

If the connection drops or the client determines that the socket is unhealthy, active subscriptions receive:

onResyncRequired(assetId);

Reload the complete order-book snapshot through InfoClient before applying subsequent updates:

const freshBook = await info.getOrderBook({
  assetId,
  epoch,
});

Subscription behavior

One client can subscribe to multiple asset IDs.

When multiple handlers subscribe to the same asset:

1. The client creates one server subscription.

2. Updates are distributed to every local handler.

3. The returned unsubscribe function removes only its handler.

4. The server subscription is removed after the last handler unsubscribes.

Reconnection defaults

Option	Default
reconnect	true
reconnectDelayMs	1000
maxReconnectDelayMs	30000
ackTimeoutMs	15000

Heartbeats

The server sends protocol-level WebSocket ping frames.

Browser WebSockets and the Node ws client respond with protocol pong frames automatically.

Do not send an application-level pong message:

{
  "type": "pong"
}

Available methods and properties

Name	SDK response
connectionState	Current connection-state value
connect	Promise<void>
close	void
subscribeOrderBook	Promise<unsubscribe function>
unsubscribeOrderBook	Promise<void>