Maintaining an Order Book

Use the HTTP API to load a complete order-book snapshot and the market WebSocket to apply real-time changes.

The order-book snapshot and every market update include a sequence ID.

A reliable client should use the sequence ID to:

• Ignore events already included in the snapshot

• Apply updates in order

• Detect missing events

• Determine when a complete resynchronization is required

Order-book data flow

Subscribe to market updates
        ↓
Buffer incoming updates
        ↓
Load the HTTP order-book snapshot
        ↓
Discard buffered updates at or below the snapshot sequence ID
        ↓
Apply later updates in sequence
        ↓
Reload the snapshot after a gap or resync notification

Create the clients

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

const info = createInfoClient({
  apiUrl: "https://exchange-api.gammaswap.com/api",
});

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

Identify the market

Order books are identified by:

• assetId

• epoch

const assetId =
  "261336857817713630688382311349658711122006440411137";

const epoch = "12";

The market WebSocket subscription uses assetId.

The HTTP order-book snapshot uses both assetId and epoch.

Subscribe before loading the snapshot

Subscribe first and temporarily buffer updates.

This prevents updates that occur during the HTTP request from being missed.

const bufferedUpdates: MarketUpdate[] = [];
let synchronized = false;

const unsubscribe =
  await marketStream.subscribeOrderBook(
    assetId,
    {
      onUpdate: (update) => {
        if (!synchronized) {
          bufferedUpdates.push(update);
          return;
        }

        applyUpdate(update);
      },
      onResyncRequired: () => {
        void resynchronize();
      },
      onError: (error) => {
        console.error(
          "Order-book subscription error",
          error,
        );
      },
    },
  );

MarketUpdate represents the market-update type exported by the SDK. Use the SDK’s actual exported type name in the implementation.

Load the initial snapshot

let book = await info.getOrderBook({
  assetId,
  epoch,
});

Example response:

{
  "assetId": "261336857817713630688382311349658711122006440411137",
  "epoch": "12",
  "ts": 1730000000,
  "seqId": 123,
  "bids": [
    {
      "price": "999000",
      "size": "1025",
      "orderCount": 1,
      "orders": []
    }
  ],
  "asks": [
    {
      "price": "1000000",
      "size": "500",
      "orderCount": 1,
      "orders": []
    }
  ]
}

Record the snapshot sequence ID:

let lastSeqId = book.seqId;

Apply buffered updates

Discard updates that are already represented by the snapshot.

const pendingUpdates = bufferedUpdates
  .filter((update) => update.seqId > lastSeqId)
  .sort((a, b) => a.seqId - b.seqId);

Apply the remaining events in sequence:

for (const update of pendingUpdates) {
  applyUpdate(update);
}

bufferedUpdates.length = 0;
synchronized = true;

Validate sequence IDs

Before applying an update, confirm that it follows the last applied update.

function applyUpdate(update: MarketUpdate) {
  if (update.seqId <= lastSeqId) {
    return;
  }

  const expectedSeqId = lastSeqId + 1;

  if (update.seqId !== expectedSeqId) {
    void resynchronize();
    return;
  }

  applyMarketEvent(book, update);
  lastSeqId = update.seqId;
}

This example assumes sequence IDs increase by one for each applicable market event. Confirm that behavior against the SDK’s exported market-update contract before enforcing it in production.

At minimum, clients should reject updates that move backward and resynchronize whenever continuity cannot be established.

Market update types

The market WebSocket publishes four update types.

Order

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

Trade

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

Cancel

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

Resolution

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

The development team’s WebSocket document does not define the fields inside data.

The exact order-book mutation logic should be implemented from the SDK’s exported event types rather than inferred from the empty examples.

Use specific handlers

Applications can use one general handler:

onUpdate: (update) => {
  applyUpdate(update);
}

They can also use event-specific handlers:

await marketStream.subscribeOrderBook(
  assetId,
  {
    onOrder: (update) => {
      console.log("Order", update);
    },
    onTrade: (update) => {
      console.log("Trade", update);
    },
    onCancel: (update) => {
      console.log("Cancel", update);
    },
    onResolution: (update) => {
      console.log("Resolution", update);
    },
  },
);

Do not apply the same update through both onUpdate and an event-specific handler.

Use onUpdate for one centralized order-book reducer, or use the specific handlers without also processing the general callback.

Resynchronize the order book

Reload the entire snapshot when:

• onResyncRequired is called

• A sequence gap is detected

• The connection reconnects

• An update cannot be applied

• The local book fails an integrity check

• The market epoch changes

let resyncing = false;

async function resynchronize() {
  if (resyncing) {
    return;
  }

  resyncing = true;
  synchronized = false;
  bufferedUpdates.length = 0;

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

    book = freshBook;
    lastSeqId = freshBook.seqId;

    const pendingUpdates = bufferedUpdates
      .filter(
        (update) =>
          update.seqId > lastSeqId,
      )
      .sort(
        (a, b) =>
          a.seqId - b.seqId,
      );

    for (const update of pendingUpdates) {
      applyUpdate(update);
    }

    bufferedUpdates.length = 0;
    synchronized = true;
  } catch (error) {
    console.error(
      "Order-book resynchronization failed",
      error,
    );
  } finally {
    resyncing = false;
  }
}

In production, retain updates received while the snapshot request is in progress. Do not clear the same buffer after new events have been added to it.

A safer implementation swaps active buffers:

let updateBuffer: MarketUpdate[] = [];

async function loadSnapshotWithBuffer() {
  synchronized = false;

  const activeBuffer = updateBuffer;
  updateBuffer = [];

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

  const allBufferedUpdates = [
    ...activeBuffer,
    ...updateBuffer,
  ];

  book = snapshot;
  lastSeqId = snapshot.seqId;

  const pendingUpdates = allBufferedUpdates
    .filter(
      (update) =>
        update.seqId > lastSeqId,
    )
    .sort(
      (a, b) =>
        a.seqId - b.seqId,
    );

  updateBuffer = [];

  for (const update of pendingUpdates) {
    applyUpdate(update);
  }

  synchronized = true;
}

Top-of-book applications

Applications that only need the best bid and ask can use:

const top = await info.getTopOfBook({
  assetId,
  epoch,
});

Response:

{
  "assetId": "261336857817713630688382311349658711122006440411137",
  "epoch": "12",
  "seqId": 123,
  "ts": 1730000000,
  "bid": {
    "price": "999000",
    "size": "1025",
    "orderCount": 1,
    "orders": []
  },
  "ask": {
    "price": "1000000",
    "size": "500",
    "orderCount": 1,
    "orders": []
  },
  "last": "999500",
  "lastTs": "1730000000"
}

The same resynchronization principles apply: reload the HTTP value after a disconnect or sequence failure.

Account-owned orders

Use getBookOrders to load resting orders for one account.

const accountOrders =
  await info.getBookOrders({
    assetId,
    epoch,
    account:
      "0x1111111111111111111111111111111111111111",
  });

Response:

{
  "assetId": "261336857817713630688382311349658711122006440411137",
  "epoch": "12",
  "seqId": 123,
  "ts": 1730000000,
  "buys": [],
  "sells": []
}

Reload this snapshot after a resynchronization event if the application maintains a separate account-order view.

Unsubscribe

The function returned by subscribeOrderBook removes only the handler created by that subscription call.

await unsubscribe();

To remove every local handler for an asset:

await marketStream.unsubscribeOrderBook(
  assetId,
);

Close the socket when the application no longer needs market updates:

marketStream.close();

Recommended safeguards

A production order-book consumer should:

• Buffer events during snapshot loading

• Track the last applied sequence ID

• Ignore duplicate or stale events

• Detect sequence discontinuity

• Allow only one resynchronization at a time

• Reload after onResyncRequired

• Validate that bid and ask levels remain sorted

• Validate that sizes do not become negative

• Replace the local state atomically after a new snapshot

• Record resynchronization failures and retry with backoff