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:

Name	Type	Description
client	ApiClient | undefined	Optional. Provide this if you want to override the default API client. By default, this will be an ApiClient using ReconnectingTransport
apiUrl	URL | string	Omniston WebSocket API URL.

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
  },
  settlementParams: {
    maxPriceSlippageBps: 500, // 5% max slippage
    maxOutgoingMessages: 4, // default for TON
  },
});

A QuoteRequest has the following properties:

Name	Type	Description
settlementMethods	SettlementMethod[]	Supported methods of swap settlement
askAssetAddress	Address	Blockchain-specific address of ask asset
offerAssetAddress	Address	Blockchain-specific address of offer asset
amount	{ offerUnits: string } | { askUnits: string }	Either the amount of offer asset or ask asset
amount.offerUnits	string	The amount of offer asset the trader wants to pay, including all fees, in base asset units
amount.askUnits	string	The amount of ask asset the trader wants to get after all fees, in base asset units
referrerAddress	Address | undefined	The address of referrer that will receive the fees
referrerFeeBps	number | undefined	The amount of fees required by the referrer in basis points (1/10000 = 0.01%)
settlementParams	RequestSettlementParams | undefined	Additional parameters of RFQ related to settlement. See the table below.

RequestSettlementParams

Name	Type	Description
max_price_slippage_bps	number | undefined	Maximum price slippage, in basis points (0.01%). For example, 100 = 1% slippage.
max_outgoing_messages	number | undefined	Maximum number of outgoing messages supported by the wallet. For TON blockchain, this defaults to 4 if omitted.

Note: Some parameters in RequestSettlementParams may only be relevant for certain blockchains or certain settlement methods. If your settlement method or wallet does not require them, you can omit them or set them to default values.

The server returns Observable<QuoteResponseEvent>, which is a stream of quote updates.

A QuoteResponseEvent might be one of the following:

• { type: "quoteUpdated"; quote: Quote; }

• { type: "noQuote"; }

• { type: "unsubscribed"; }

A Quote has the following properties:

Name	Type	Description
quoteId	string	ID of the quote generated by the platform (32 characters)
resolverId	string	ID of the resolver
resolverName	string	Name of the resolver
offerAssetAddress	Address	Blockchain-specific address of offer asset
askAssetAddress	Address	Blockchain-specific address of ask asset
offerUnits	string	The amount of offer asset the trader must pay, including all fees
askUnits	string	The amount of ask asset the trader will get after all fees
referrerAddress	Address | undefined	The address of referrer that will receive the fees
referrerFeeUnits	string	The amount of fees that the referrer will get (in units of offerAssetAddress)
protocolFeeUnits	string	The amount of fees charged by the protocol (in units of offerAssetAddress).
quoteTimestamp	number	The timestamp (UTC seconds) of Quote sent by resolver
tradeStartDeadline	number	Max timestamp (UTC seconds) of start of the trade
gasBudget	string	The amount of gas budget for the trade
params	object | undefined	Various parameters specific to the settlement method. See the source code for more details.

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

const messages = tx.ton?.messages ?? [];

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

Name	Type	Description
quote	Quote	The valid quote received from Omniston.requestForQuote
sourceAddress	Address	The address on offerBlockchain that will send initial transaction to start the trade
destinationAddress	Address	The address on askBlockchain that will receive result of the trade

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

Get the outgoing transaction hash

See TON Cookbook for detailed instructions.

For tutorial purposes, we'll use the @ton/core package to get the external transaction hash and find the internal hash with TonAPI v2.

import { Cell } from "@ton/core";

const externalTxHash = Cell.fromBase64(boc).hash().toString("hex");
const response = await fetch(`https://tonapi.io/v2/traces/${externalTxHash}`);
const outgoingTxHash = (await response.json()).transaction.hash;

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,
  },
  outgoingTxHash: "", // Replace with the actual outgoingTxHash
});

The trackTrade method has the following parameters:

Name	Type	Description
quoteId	string	ID of the quote received from Omniston.requestFromQuote
traderWalletAddress	Address	The address of trader's wallet that initiated transaction
outgoingTxHash	string	Hash of the transaction that initiated the trade

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:

Name	Description
TRADE_RESULT_FULLY_FILLED	The trade has been completed and fully filled.
TRADE_RESULT_PARTIALLY_FILLED	The trade has been partially filled. Something went wrong.
TRADE_RESULT_ABORTED	The trade has been aborted.
TRADE_RESULT_UNKNOWN
UNRECOGNIZED