React

Flow-based guide for integrating the Omniston React SDK in applications

The React SDK gives you Omniston as ready-to-use hooks on top of the base SDK. 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

Migrating an existing app from @ston-fi/omniston-sdk-react@0.7 and Omniston API v1beta7? Use the React SDK v0.7 to v0.8 migration guide.

Installation

• Source code

• @ston-fi/omniston-sdk-react NPM Package

Install the SDK in your project:

npm install @ston-fi/omniston-sdk-react

Creating an instance

Create an Omniston instance, then provide it through OmnistonProvider.

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

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

export function AppProviders({ children }: React.PropsWithChildren) {
  return <OmnistonProvider omniston={omniston}>{children}</OmnistonProvider>;
}

If you are integrating against the sandbox environment, use:

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

If your application already uses a TanStack Query client, you can pass it to OmnistonProvider to reuse the same client instead of creating a separate one:

export function AppProviders({ children }: React.PropsWithChildren) {
  return (
    <QueryClientProvider client={queryClient}>
      <OmnistonProvider omniston={omniston} queryClient={queryClient}>
        {children}
      </OmnistonProvider>
    </QueryClientProvider>
  );
}

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-react";

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. useRfq() is backed by the same RFQ stream as requestForQuote(), so your integration should handle it as a stream of updates rather than as a one-shot request.

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

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,
};

function QuoteStream() {
  const { data: event, error } = useRfq(quoteRequest);

  if (error) {
    return <div>RFQ stream failed: {String(error)}</div>;
  }

  switch (event?.$case) {
    case "ack":
      return <div>RFQ id: {event.value.rfqId}</div>;
    case "quoteUpdated":
      return <div>Received quote: {event.value.quoteId}</div>;
    case "noQuote":
      return <div>No quote available for RFQ {event.rfqId}</div>;
    case "unsubscribed":
      return <div>Quote stream was closed by server</div>;
    default:
      return <div>Waiting for quote...</div>;
  }
}

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 useTonBuildSwap(), then pass the resulting messages to the wallet or signing library you use in your application.

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

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

function SwapBuild({ quote }: { quote: QuoteOfType<"swap"> }) {
  const { data: swapTx } = useTonBuildSwap({
    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.

import { useEffect } from "react";
import { useOmniston, type ChainAddress, type Quote } from "@ston-fi/omniston-sdk-react";

function SwapTracking({
  quote,
  traderAddress,
  outgoingTxQuery,
}: {
  quote: Quote;
  traderAddress: ChainAddress;
  outgoingTxQuery: string;
}) {
  const omniston = useOmniston();

  useEffect(() => {
    let unsubscribe = () => {};

    void omniston
      .swapTrack({
        quoteId: quote.quoteId,
        traderAddress,
        outgoingTxQuery,
      })
      .then((stream) => {
        const subscription = stream.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;
            }
          },
        });

        unsubscribe = () => subscription.unsubscribe();
      });

    return () => unsubscribe();
  }, [omniston, quote.quoteId, traderAddress, outgoingTxQuery]);

  return null;
}

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 {
  useTonBuildEscrowTransfer,
  type QuoteOfType,
} from "@ston-fi/omniston-sdk-react";

function TonOrderBuild({ quote }: { quote: QuoteOfType<"order"> }) {
  const { data: tonOrderTx } = useTonBuildEscrowTransfer({
    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:

import {
  useEvmBuildOrderPayload,
  useOmniston,
  isHtlcOrderQuote,
  type ChainAddress,
  type HtlcSecrets,
  type QuoteOfType,
} from "@ston-fi/omniston-sdk-react";

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

function EvmOrderBuild({ quote }: { quote: QuoteOfType<"order"> }) {
  const omniston = useOmniston();

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

  const { data: orderPayload } = useEvmBuildOrderPayload({
    quoteId: quote.quoteId,
    ownerSrcAddress: evmTraderAddress,
    traderDstAddress: traderAddress,
    htlcSecrets,
    traderDstDiscloseAddress: traderAddress,
  });

  async function registerSignedOrder() {
    if (!orderPayload) return;

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

  return <button onClick={registerSignedOrder}>Register signed order</button>;
}

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.

import { useEffect } from "react";
import { useOmniston, type ChainAddress, type Quote } from "@ston-fi/omniston-sdk-react";

function OrderTracking({
  quote,
  traderAddress,
}: {
  quote: Quote;
  traderAddress: ChainAddress;
}) {
  const omniston = useOmniston();

  useEffect(() => {
    let unsubscribe = () => {};

    void omniston
      .orderTrack({
        quoteId: quote.quoteId,
        traderAddress,
      })
      .then((stream) => {
        const subscription = stream.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;
            }
          },
        });

        unsubscribe = () => subscription.unsubscribe();
      });

    return () => unsubscribe();
  }, [omniston, quote.quoteId, traderAddress]);

  return null;
}

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

import { useOmniston, type Quote } from "@ston-fi/omniston-sdk-react";

function DiscloseSecret({ quote }: { quote: Quote }) {
  const omniston = useOmniston();

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

  return <button onClick={disclose}>Disclose secret</button>;
}

Active orders list

If your application needs to restore existing order state or show all active orders for a trader, call useActiveOrders().

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

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

function ActiveOrdersList() {
  const { data: activeOrders } = useActiveOrders({
    traderAddress,
  });

  return (
    <ul>
      {activeOrders?.activeOrders.map((activeOrder) => (
        <li key={activeOrder.quote.quoteId}>
          {activeOrder.quote.quoteId} - {activeOrder.order.status}
        </li>
      ))}
    </ul>
  );
}