React

Getting started

This package provides binding for omniston-sdk to the React ecosystem. Using this package, you can access all Omniston methods as hooks powered by TanStack react query (out-of-box loading states, retries, error handling, and match more)

You can find all supported methods in our docs or take a look onto our demo app that use NextJs and omniston-sdk-react package

Installation

via NPM

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

via YARN

yarn add @ston-fi/omniston-sdk-react

via PNPM

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

Wrap you app in Omniston provider

You can pass custom queryClient if you want to apply shared behaviour to all of the queries

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

const App = () => (
  <OmnistonProvider
    apiUrl="wss://omni-ws.ston.fi"
  >
    {children}
  </OmnistonProvider>
);

The provider takes the following parameters:

Get list of supported assets

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

const {
  isLoading,
  error,
  data: assetList,
  ...restQuery
} = useAssetList();

An AssetsResponse has the following properties:

An AssetInfo has the following properties:

An Address has the following properties:

Send a quote request

Send a request for quote to swap an asset to another asset.

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

const {
  isLoading,
  error,
  data: quote,
  ...restQuery
} = useRfq({
    settlementMethods: [SettlementMethod.SETTLEMENT_METHOD_SWAP],
    askAssetAddress: {
      blockchain: Blockchain.TON,
      address: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
    },
    offerAssetAddress: {
      blockchain: Blockchain.TON,
      address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // USDT
    },
    amount: {
      offerUnits: "1000000", // 1 USDT
    },
});

A QuoteRequest has the following properties:

The server returns Observable<Quote | null>, which is a stream of quotes. Learn more about Observable types in the official RxJS documentation.

A Quote has the following properties:

Build a transaction

Now that we have a quote, we should request a server to build a transaction to initiate the trade that the user can verify and sign.

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

const omniston = useOmniston();

const tx = await omniston.buildTransfer({
  quote,
  sourceAddress: {
    blockchain: Blockchain.TON,
    address: "", // sender wallet address on `offerBlockchain`
  },
  destinationAddress: {
    blockchain: Blockchain.TON,
    address: "", // receiver wallet address on `askBlockchain`
  },
  maxSlippageBps: 100, // 1%
});

const messages = tx.transaction!.ton!.messages;

The buildTransfer method takes a TransactionRequest object as a parameter, having the following properties:

Sign the transaction

You can found the instruction on how to send transaction using the @tonconnect/ui-react package here.

import { useTonConnectUI } from "@tonconnect/ui-react";

const [tonConnect] = useTonConnectUI();

await tonConnect.sendTransaction({
  validUntil: Date.now() + 1000000,
  messages: messages.map((message) => ({
    address: message.targetAddress,
    amount: message.sendAmount,
    payload: message.payload,
  })),
});

Listen for trade status updates

After the user has signed and initiated the transaction, we can track the trade status.

import { useTrackTrade } from "@ston-fi/omniston-sdk-react";
import { useTonAddress } from "@tonconnect/ui-react";

const walletAddress = useTonAddress();

const {
  isLoading,
  error,
  data: status,
  ...restQuery
} = useTrackTrade({
  quoteId: quote.quoteId,
    traderWalletAddress: {
    blockchain: Blockchain.TON,
    address: walletAddress
  },
});

The trackTrade method has the following parameters:

It returns Observable<TrackTradeStatus>. For the different trade status values, see the source code. We are interested in the trade result enum which can be read from status.tradeSettled?.result? field. The enum has the following values:

Last updated