1 of 1

Nodejs

Getting started

This package acts as a typescript wrapper on top of the Ston.fi Omniston protocol API and provides RxJS styled observables on top of the WebSocket API connection

Installation

via NPM

npm install @ston-fi/omniston-sdk

via YARN

yarn add @ston-fi/omniston-sdk

via PNPM

pnpm install @ston-fi/omniston-sdk

Create an instance

Create an Omniston instance, specifying the API URL.

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

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

The constructor 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.

omniston
  .requestForQuote({
    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
    },
  })
  .subscribe((quoteResponseEvent) => {
    // process the quote event
  });

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 or 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.

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 send messages to any library of your choice. Take a look at our transaction sending guide with examples of different popular packages

Listen for trade status updates

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

const tradeStatus = omniston.trackTrade({
  quoteId: quote.quoteId,
  traderWalletAddress: {
    blockchain: Blockchain.TON,
    address: "", // sender wallet address on `offerBlockchain`
  },
  outgoingTxHash: "", // Replace with the actual outgoingTxHash
});

tradeStatus.subscribe((status) => {
  console.log(JSON.stringify(status));
});

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

Nodejs

Getting started

This package acts as a typescript wrapper on top of the Ston.fi Omniston protocol API and provides RxJS styled observables on top of the WebSocket API connection

Installation

via NPM

npm install @ston-fi/omniston-sdk

via YARN

yarn add @ston-fi/omniston-sdk

via PNPM

pnpm install @ston-fi/omniston-sdk

Create an instance

Create an Omniston instance, specifying the API URL.

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

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

The constructor 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.

omniston
  .requestForQuote({
    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
    },
  })
  .subscribe((quoteResponseEvent) => {
    // process the quote event
  });

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 or 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.

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.

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 send messages to any library of your choice. Take a look at our transaction sending guide with examples of different popular packages

Listen for trade status updates

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

const tradeStatus = omniston.trackTrade({
  quoteId: quote.quoteId,
  traderWalletAddress: {
    blockchain: Blockchain.TON,
    address: "", // sender wallet address on `offerBlockchain`
  },
  outgoingTxHash: "", // Replace with the actual outgoingTxHash
});

tradeStatus.subscribe((status) => {
  console.log(JSON.stringify(status));
});

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

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