Oracle Methods

OracleWebSocketClient manages the oracle WebSocket connection and subscribes to real-time price updates by symbolId.

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

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

connectionState

Returns the current state of the oracle WebSocket connection.

const state = oracleStream.connectionState;

connect

Opens the oracle WebSocket connection.

const result = await oracleStream.connect();

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

{
  "type": "connected",
  "message": "Send {\"type\":\"subscribe\",\"symbolId\":\"...\"} to receive prices"
}

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

subscribePrice

Subscribes to live oracle prices for a symbolId.

const unsubscribe =
  await oracleStream.subscribePrice("1", {
    onPrice: (update) => {
      console.log(
        "Price update",
        update.symbolId,
        update.price,
        update.ts,
      );
    },
    onError: (error) => {
      console.error("Subscription error", error);
    },
    onStale: (symbolId) => {
      console.warn("Oracle price is stale", symbolId);
    },
  });

The resolved value is an asynchronous unsubscribe function:

await unsubscribe();

The underlying WebSocket subscription message is:

{
  "type": "subscribe",
  "symbolId": "1"
}

After the subscription is accepted, the service sends:

{
  "type": "subscribed",
  "symbolId": "1"
}

Price updates

Price updates are delivered to the subscription’s onPrice handler.

{
  "type": "price",
  "symbolId": "1",
  "price": "123456789",
  "ts": 1730000000
}

The update contains:

Field	Type	Description
type	string	Always price for a price update
symbolId	string	Subscribed oracle symbol ID
price	string	Current oracle price
ts	number	Price timestamp

Example handler:

onPrice: (update) => {
  if (update.symbolId === "1") {
    console.log(update.price);
  }
}

Handler input:

{
  type: "price",
  symbolId: "1",
  price: "123456789",
  ts: 1730000000,
}

unsubscribePrice

Removes all local handlers for a symbolId and unsubscribes from that symbol’s server-side price feed.

const result =
  await oracleStream.unsubscribePrice("1");

The underlying WebSocket unsubscribe message is:

{
  "type": "unsubscribe",
  "symbolId": "1"
}

After the subscription is removed, the service sends:

{
  "type": "unsubscribed",
  "symbolId": "1"
}

unsubscribePrice removes every local handler for the symbol.

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

Unavailable symbols

If a symbol becomes unavailable after subscription, the service can send:

{
  "type": "unsubscribed",
  "symbolId": "1",
  "reason": "symbol unavailable"
}

The symbol is no longer subscribed after this message.

close

Closes the oracle WebSocket connection.

const result = oracleStream.close();

An optional WebSocket close code and reason can be supplied:

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

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

Error messages

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

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

Errors are delivered to:

• The subscription’s onError handler

• The client-level onError handler, where applicable

Stale prices

stalePriceTimeoutMs defines the maximum time the client waits without receiving a price update for a subscribed symbol.

The default is:

30_000

If no price arrives before the timeout, the client calls:

onStale("1");

The handler receives the stale symbolId:

"1"

The client also:

1. Emits an error.

2. Abandons the unhealthy socket.

3. Reconnects when active subscriptions remain.

The oracle stream does not provide sequence IDs or REST catch-up.

After reconnecting or receiving onStale, accept the next live price update for the symbol.

Subscription behavior

One client can subscribe to multiple symbol IDs.

When multiple handlers subscribe to the same symbol:

1. The client creates one server subscription.

2. Price 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
stalePriceTimeoutMs	30000

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
subscribePrice	Promise<unsubscribe function>
unsubscribePrice	Promise<void>