SDK

Omniston SDK reference - TypeScript/JavaScript tools for building cross-chain liquidity aggregation

Software Development Kits for integrating Omniston liquidity aggregation across swap and order settlement flows.

Features

• Best Price Discovery: Automatically finds optimal swap and order routes

• Cross-chain Aggregation: Supports cross-chain settlement flows

• Real-time Quotes: Live RFQ updates via WebSocket

• Settlement-specific APIs: TON transaction builders, EVM order payload flows, and TRON order settlement

• Error Handling: Comprehensive error types and recovery

Reference Implementation

The open source React demo app shows a configured multi-chain Omniston integration, including TON, EVM chains, and TRON.

Use the chain-specific guides below when studying how network-specific wallet and settlement logic is wired.

SDKs

We provide two packages for different use cases:

• @ston-fi/omniston-sdk for direct SDK usage in backend services, bots, scripts, and custom application architectures

• @ston-fi/omniston-sdk-react for React applications that want Omniston exposed as ready-to-use hooks

Node.js SDK

Use the Node.js SDK when you want direct access to the Omniston API surface and full control over request, quote, and settlement handling.

Key benefits:

• Low-level access to RFQ, tracking, and settlement APIs

• Direct Observable-based integration without React dependencies

• Best fit for backend services, bots, server actions, and custom app architectures

• Easier to build your own abstractions on top of the raw SDK primitives

Installation:

npm install @ston-fi/omniston-sdk

Quick start:

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

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

omniston.requestForQuote({ /** */ }).subscribe((quoteEvent) => {
  switch (quoteEvent?.$case) {
    case 'ack':
      console.log('RFQ id:', quoteEvent.value.rfqId);
      break;
    case 'quoteUpdated':
      console.log('Quote:', quoteEvent.value);
      break;
    case 'noQuote':
      console.log('No quote available');
      break;
  }
});

Detailed guide:

• Node.js SDK Documentation

React SDK

Use the React SDK when you are building a React application and want Omniston exposed as ready-to-use hooks.

Key benefits:

• React-first API built on top of the base SDK

• TanStack Query integration for loading, caching, and stream-driven updates

• Less boilerplate for binding RFQ, tracking, and settlement flows to UI state

• Best fit for browser apps, wallet-connected UIs, and dashboards

Installation:

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

Quick start:

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

function SwapComponent() {
  const { data: quoteEvent, error } = useRfq({ /** */ });

  if (error) {
    return <ErrorState error={error} />;
  }

  switch (quoteEvent?.$case) {
    case 'quoteUpdated':
      return <QuotePreview quote={quoteEvent.value} />;
    case 'noQuote':
      return <NoQuote />;
    case 'ack':
    default:
      return <Loading />;
  }
}

Detailed guide:

• React SDK Documentation

• React SDK v0.7 to v0.8 Migration

Chain-specific Guides

• EVM chain

• TRON chain