WebSocket Reconnection

The market and oracle WebSocket clients reconnect automatically by default.

const marketStream =
  createExchangeWebSocketClient({
    websocketUrl:
      "wss://exchange-api.gammaswap.com/ws/",
    reconnect: true,
  });

const oracleStream =
  createOracleWebSocketClient({
    websocketUrl:
      "wss://exchange-api.gammaswap.com/oracle-ws/",
    reconnect: true,
  });

Reconnection keeps the transport available, but each stream has different recovery requirements.

Default reconnect configuration

Option	Default
reconnect	true
reconnectDelayMs	1000
maxReconnectDelayMs	30000
ackTimeoutMs	15000
Oracle stalePriceTimeoutMs	30000

Configure the reconnect delay when creating a client:

const marketStream =
  createExchangeWebSocketClient({
    websocketUrl:
      "wss://exchange-api.gammaswap.com/ws/",
    reconnect: true,
    reconnectDelayMs: 1_000,
    maxReconnectDelayMs: 30_000,
    ackTimeoutMs: 15_000,
    onError: (error) => {
      console.error(
        "Market WebSocket error",
        error,
      );
    },
  });

Market WebSocket recovery

Market updates include sequence IDs.

After the connection drops or the SDK determines that the socket is unhealthy, active handlers receive:

onResyncRequired(assetId);

Example:

const unsubscribe =
  await marketStream.subscribeOrderBook(
    assetId,
    {
      onUpdate: (update) => {
        applyMarketUpdate(update);
      },
      onResyncRequired: async (
        resyncAssetId,
      ) => {
        const freshBook =
          await info.getOrderBook({
            assetId: resyncAssetId,
            epoch,
          });

        replaceLocalBook(freshBook);
      },
      onError: (error) => {
        console.error(
          "Market subscription error",
          error,
        );
      },
    },
  );

Do not continue applying market updates to the old local order book after onResyncRequired is called.

Instead:

1. Mark the local order book as unsynchronized.

2. Buffer or pause new events.

3. Load a fresh HTTP order-book snapshot.

4. Replace the local state.

5. Apply only events newer than the snapshot sequence ID.

6. Resume normal processing.

Market reconnect flow

Connection becomes unhealthy
        ↓
onResyncRequired(assetId)
        ↓
SDK reconnects when subscriptions remain
        ↓
Reload GET /book/:assetId/:epoch
        ↓
Replace the local order book
        ↓
Resume live updates

Oracle WebSocket recovery

Oracle price updates do not include sequence IDs.

The oracle stream also does not provide a REST catch-up operation.

After reconnecting, accept the next live price update.

const unsubscribe =
  await oracleStream.subscribePrice(
    "1",
    {
      onPrice: (update) => {
        setCurrentPrice(
          update.symbolId,
          update.price,
          update.ts,
        );
      },
      onStale: (symbolId) => {
        markPriceAsStale(symbolId);
      },
      onError: (error) => {
        console.error(
          "Oracle subscription error",
          error,
        );
      },
    },
  );

Stale oracle prices

stalePriceTimeoutMs controls how long the client waits without a price update for a subscribed symbol.

const oracleStream =
  createOracleWebSocketClient({
    websocketUrl:
      "wss://exchange-api.gammaswap.com/oracle-ws/",
    stalePriceTimeoutMs: 30_000,
  });

If the timeout expires, the client:

1. Calls onStale(symbolId).

2. Emits an error.

3. Abandons the unhealthy socket.

4. Reconnects when active subscriptions remain.

Example stale callback:

onStale: (symbolId) => {
  console.warn(
    "Oracle price is stale",
    symbolId,
  );

  disablePriceDependentActions(symbolId);
}

When the next price arrives:

onPrice: (update) => {
  clearStaleState(update.symbolId);
  setCurrentPrice(
    update.symbolId,
    update.price,
    update.ts,
  );
}

Subscription acknowledgement timeout

The clients wait for subscribe and unsubscribe acknowledgements.

The default timeout is:

15_000

Configure it with ackTimeoutMs:

const marketStream =
  createExchangeWebSocketClient({
    websocketUrl:
      "wss://exchange-api.gammaswap.com/ws/",
    ackTimeoutMs: 20_000,
  });

A failed subscription acknowledgement rejects the subscription operation or emits an error through the configured handlers.

Unsubscribe failures

Unsubscribe acknowledgements are best-effort.

If an unsubscribe acknowledgement fails:

• The local subscription is still removed.

• The error is emitted.

• The client reconnects only when other active subscriptions remain.

The application should treat the local handler as removed even if the server acknowledgement is not received.

Multiple subscriptions

One WebSocket client can manage multiple asset or symbol subscriptions.

Market example:

const unsubscribeAssetOne =
  await marketStream.subscribeOrderBook(
    assetOne,
    assetOneHandlers,
  );

const unsubscribeAssetTwo =
  await marketStream.subscribeOrderBook(
    assetTwo,
    assetTwoHandlers,
  );

Oracle example:

const unsubscribeSymbolOne =
  await oracleStream.subscribePrice(
    "1",
    symbolOneHandlers,
  );

const unsubscribeSymbolTwo =
  await oracleStream.subscribePrice(
    "2",
    symbolTwoHandlers,
  );

The client maintains active local handlers across transport failures. Recovery logic must still restore application state:

• Reload market order books after market reconnects.

• Accept the next live price after oracle reconnects.

Shared server subscriptions

Multiple local handlers for the same asset or symbol share one server subscription.

const unsubscribeA =
  await marketStream.subscribeOrderBook(
    assetId,
    handlersA,
  );

const unsubscribeB =
  await marketStream.subscribeOrderBook(
    assetId,
    handlersB,
  );

Calling:

await unsubscribeA();

removes only handlersA.

The server subscription remains active while handlersB is still registered.

Calling:

await marketStream.unsubscribeOrderBook(
  assetId,
);

removes all local handlers for the asset.

Intentional close

Calling close() intentionally closes the connection.

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

oracleStream.close(
  1000,
  "Application shutdown",
);

An intentional close should be part of the application’s shutdown process.

Run returned unsubscribe functions before closing when practical:

await unsubscribe();
marketStream.close();

Browser and Node.js behavior

Browser WebSocket implementations support close() but do not provide a forceful termination method.

The Node ws implementation can provide terminate().

When a socket is already considered unhealthy, the SDK:

• Uses terminate() when the WebSocket implementation provides it

• Falls back to close() in browser-compatible environments

• Ignores events from abandoned sockets so stale events do not affect a newer connection

If an abandoned browser socket does not close cleanly, the server heartbeat or TCP timeout eventually removes it.

Heartbeats

The services send protocol-level WebSocket ping frames.

Standard browser WebSockets and the Node ws package automatically respond with protocol pong frames.

Do not send an application-level pong:

{
  "type": "pong"
}

Error handling

Configure a client-level error handler:

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

Also configure subscription-level error handlers:

await marketStream.subscribeOrderBook(
  assetId,
  {
    onUpdate: applyMarketUpdate,
    onError: (error) => {
      console.error(
        "Asset subscription error",
        error,
      );
    },
    onResyncRequired: () => {
      void reloadOrderBook();
    },
  },
);

Disable automatic reconnection

Automatic reconnection can be disabled:

const marketStream =
  createExchangeWebSocketClient({
    websocketUrl:
      "wss://exchange-api.gammaswap.com/ws/",
    reconnect: false,
  });

When disabled, the application is responsible for:

• Detecting connection failure

• Opening a new connection

• Recreating subscriptions

• Reloading market state

• Marking oracle prices as stale

Recommended reconnect behavior

For market subscriptions:

1. Enable automatic reconnection.

2. Implement onResyncRequired.

3. Pause or buffer market events during resynchronization.

4. Reload the full HTTP order-book snapshot.

5. Validate sequence continuity before resuming.

For oracle subscriptions:

1. Enable automatic reconnection.

2. Configure stalePriceTimeoutMs.

3. Implement onStale.

4. Mark stale prices as unusable.

5. Accept the next live price after reconnecting.

For both clients:

• Log errors without exposing secrets.

• Monitor repeated reconnect attempts.

• Avoid creating a new client for every subscription.

• Close clients during application shutdown.

• Keep client and subscription error handlers lightweight.