Node.js

Flow-based guide for integrating the Omniston SDK in Node.js with the v1beta8 API

The Node.js SDK gives you direct access to the Omniston API surface. In v1beta8, the main integration flow is:

1. prepare settlementParams for the settlement methods you want to allow

2. subscribe to RFQ updates and select a quote from the stream

3. branch on quote.settlementData?.$case

4. build and sign either a swap flow or an order flow

5. track the resulting settlement

An end-to-end open source reference implementation is also available in our example app: examples/react-app

Installation

• Source code

• @ston-fi/omniston-sdk NPM Package

Install the SDK in your project:

npm install @ston-fi/omniston-sdk

Creating an instance

Create an Omniston instance pointing to the desired API endpoint.

import { Omniston } from "@ston-fi/omniston-sdk";

const omniston = new Omniston({
  apiUrl: "wss://omni-ws.ston.fi",
});

If you are integrating against the sandbox environment, use:

const omniston = new Omniston({
  apiUrl: "wss://omni-ws-sandbox.ston.fi",
});

Preparing settlement params

Before requesting a quote, decide which settlement methods you want the resolver network to consider. In v1beta8, this is controlled through settlementParams, where each item enables one settlement branch.

Use swap-only when you want classic swap execution, typically for simple TON flows. Use order-only when you want order settlement only, for example when your application is built specifically around signed orders or HTLC flows. Use both when you want Omniston to return the best available option and decide later based on the returned quote.

import {
  type SettlementParams,
  type SwapSettlementParams,
  type OrderSettlementParams,
} from "@ston-fi/omniston-sdk";

const swapOnlySettlementParams: SettlementParams[] = [
  {
    params: {
      $case: "swap",
      value: {
        maxPriceSlippagePips: 10_000, // 1%
        flexibleIntegratorFee: true,
      } satisfies SwapSettlementParams,
    },
  },
];

const orderOnlySettlementParams: SettlementParams[] = [
  {
    params: {
      $case: "order",
      value: {} satisfies OrderSettlementParams,
    },
  },
];

const swapAndOrderSettlementParams: SettlementParams[] = [
  ...swapOnlySettlementParams,
  ...orderOnlySettlementParams,
];

Quote receiving based on parameters

After preparing settlement params, request a quote and subscribe to the RFQ stream. requestForQuote() is a live stream and may emit multiple quoteUpdated events over time, so your integration should handle it as an ongoing subscription rather than as a one-shot request.

import type { AssetId, QuoteRequest } from "@ston-fi/omniston-sdk";

const inputAsset: AssetId = {
  chain: {
    $case: "ton",
    value: {
      kind: {
        $case: "jetton",
        value: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // example: USDT
      },
    },
  },
};

const outputAsset: AssetId = {
  chain: {
    $case: "ton",
    value: {
      kind: {
        $case: "jetton",
        value: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // example: STON
      },
    },
  },
};

const quoteRequest: QuoteRequest = {
  inputAsset,
  outputAsset,
  amount: {
    $case: "inputUnits",
    value: "1000000",
  },
  settlementParams: swapAndOrderSettlementParams,
};

omniston.requestForQuote(quoteRequest).subscribe({
  next(event) {
    switch (event?.$case) {
      case "ack":
        console.log("RFQ id:", event.value.rfqId);
        break;
      case "quoteUpdated":
        console.log("Received quote:", event.value.quoteId);
        break;
      case "noQuote":
        console.log(`No quote available for RFQ ${event.rfqId}`);
        break;
      case "unsubscribed":
        console.log("Quote stream was closed by server");
        break;
    }
  },
  error(error) {
    console.error("RFQ stream failed", error);
  },
});

Settlement flows

Once you have selected a quote from the RFQ stream, branch on quote.settlementData?.$case and follow the corresponding settlement flow.

Swap quotes

Transaction building and sign

Once you have selected a quote from the stream and it uses swap settlement, build a TON transaction with tonBuildSwap(), then pass the resulting messages to the wallet or signing library you use in your application.

import { isSwapQuote, type ChainAddress } from "@ston-fi/omniston-sdk";

if (!isSwapQuote(quote)) {
  throw new Error("Expected a swap quote");
}

const traderAddress: ChainAddress = {
  chain: {
    $case: "ton",
    value: "EQ...",
  },
};

const swapTx = await omniston.tonBuildSwap({
  quoteId: quote.quoteId,
  transferSrcAddress: traderAddress,
  refundSrcAddress: traderAddress,
  gasExcessAddress: traderAddress,
  traderDstAddress: traderAddress,
});

// `swapTx.messages` should be signed and sent with the TON wallet package used by your project.

Tracking

After the swap transaction is sent, track the swap with swapTrack(). You need the quoteId, the trader wallet address, and an identifier that lets Omniston find the outgoing transaction.

const swapTrackStream = await omniston.swapTrack({
  quoteId: quote.quoteId,
  traderAddress,
  outgoingTxQuery, // tx hash, message hash, or outgoing message body
});

swapTrackStream.subscribe({
  next(event) {
    switch (event?.$case) {
      case "awaitingTransfer":
        console.log("Waiting for transfer");
        break;
      case "progress":
        console.log("Swap status:", event.value.status);
        break;
      case "unsubscribed":
        console.log("Swap tracking stream closed");
        break;
    }
  },
});

Order quotes

Transaction building and sign

Once you have selected a quote from the stream and it uses order settlement, the build-and-sign flow depends on the source chain.

For TON order settlement, build an escrow transfer and sign the resulting TON messages:

import {
  isHtlcOrderQuote,
  isOrderQuote,
  type HtlcSecrets,
} from "@ston-fi/omniston-sdk";

if (!isOrderQuote(quote)) {
  throw new Error("Expected an order quote");
}

const tonOrderTx = await omniston.tonBuildEscrowTransfer({
  quoteId: quote.quoteId,
  ownerSrcAddress: traderAddress,
  transferSrcAddress: traderAddress,
  refundSrcAddress: traderAddress,
  gasExcessAddress: traderAddress,
  traderDstAddress: traderAddress,
});

// `tonOrderTx.messages` should be signed and sent with the TON wallet package used by your project.

For EVM order settlement, build the order payload, sign it with your EVM wallet, and register the signed order with Omniston:

if (!isOrderQuote(quote)) {
  throw new Error("Expected an order quote");
}

const evmTraderAddress: ChainAddress = {
  chain: {
    $case: "base",
    value: "0x...",
  },
};

const htlcSecrets: HtlcSecrets | undefined = isHtlcOrderQuote(quote)
  ? {
      secretMode: {
        $case: "provided",
        value: {
          hashes: myGeneratedHashlocks,
        },
      },
    }
  : undefined;

const orderPayload = await omniston.evmBuildOrderPayload({
  quoteId: quote.quoteId,
  ownerSrcAddress: evmTraderAddress,
  traderDstAddress: traderAddress,
  htlcSecrets,
  traderDstDiscloseAddress: traderAddress,
});

const signedOrder = await buildSignedOrderSomehow(orderPayload);

await omniston.orderRegisterSignedOrder({
  quoteId: quote.quoteId,
  ownerSrcAddress: evmTraderAddress,
  signedOrder,
  serializedOrderDetails: orderPayload.serializedOrderDetails,
});

Tracking

Once the order is submitted, use orderTrack() to monitor its lifecycle. For HTLC-based partial fills, the application must generate secrets on its own, pass their hashes when building the order payload, and later disclose the original secrets with orderDiscloseHtlcSecret() when executions reach the appropriate phase.

const orderTrackStream = await omniston.orderTrack({
  quoteId: quote.quoteId,
  traderAddress,
});

orderTrackStream.subscribe({
  next(event) {
    switch (event?.$case) {
      case "order":
        console.log("Order status:", event.value.status);
        console.log("Executions:", event.value.executions.length);
        break;
      case "unsubscribed":
        console.log("Order tracking stream closed");
        break;
    }
  },
});

If you are using HTLC order settlement and manage secrets yourself, disclose them once an execution is ready:

await omniston.orderDiscloseHtlcSecret({
  quoteId: quote.quoteId,
  executionIndex: 0,
  secret: mySecretBytes,
});

Active orders list

If your application needs to restore existing order state or show all active orders for a trader, call orderGetActive(). Unlike requestForQuote(), this is a regular request-response method, so you should call it on demand or poll it from your application if you need periodic refresh.

import type { ChainAddress } from "@ston-fi/omniston-sdk";

const traderAddress: ChainAddress = {
  chain: {
    $case: "ton",
    value: "EQ...",
  },
};

const activeOrders = await omniston.orderGetActive({
  traderAddress,
});

for (const activeOrder of activeOrders.activeOrders) {
  console.log("Order quote id:", activeOrder.quote.quoteId);
  console.log("Order status:", activeOrder.order.status);
}