★★How to integrate Omniston into your React app

Last updated 3 days ago

★★How to integrate Omniston into your React app

Want to add powerful, decentralized swaps to your TON-based app? Omniston makes it surprisingly easy. This guide walks you through the essentials of integrating Omniston using the official React SDK.

What Is Omniston?

Omniston is a decentralized liquidity aggregation protocol built for the TON blockchain. It connects multiple DEXs and market makers into one unified system, ensuring your users always get the best possible price when swapping tokens. By routing trades through the most liquid paths using a Request-for-Quote (RFQ) mechanism, it handles the complexity of price discovery — so you don’t have to.

Who Should Integrate Omniston?

From wallets to DeFi platforms, Omniston unlocks functionality, efficiency, and new revenue streams:

Wallets & Portfolio Apps → Keep users in your app with in-wallet swaps and generate referral income.
Games & NFT Marketplaces → Let players convert tokens natively in the UI, driving more purchases and smoother UX.
DeFi dApps → Instantly aggregate liquidity and offer optimal prices — no need to manage multiple DEX APIs.
TON Startups → Accelerate development and offer DeFi-grade functionality from day one.

Now, let’s see how to bring it into your app.

🛠 Quick Start: 6 Steps to Integration

1. Install the SDK

Start by adding the SDK to your project:

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

This package includes all the React hooks and utilities you’ll need.

2. Wrap Your App with OmnistonProvider

In your app’s root component (e.g., _app.tsx or index.tsx), wrap your application with the provider:

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

<OmnistonProvider apiUrl="wss://omni-ws.ston.fi">

{/* your app components */}

</OmnistonProvider>

This establishes the WebSocket connection to Omniston’s aggregation backend.

🧠 Pro Tip: No backend needed. The SDK handles blockchain comms and quote management via WebSocket — your integration stays lightweight and frontend-only.

3. Add TON Wallet Support

You can use TON Connect to integrate wallet connectivity:

pnpm install @tonconnect/ui-react

Then create a "Connect Wallet" button using TonConnect’s hooks. This allows users to approve transactions using familiar wallets like Tonkeeper or TON Space.

4. Request a Quote

Use Omniston’s hook useRfq to fetch swap quotes.

Omniston automatically routes through intermediate tokens if needed and returns the best available price.

🧠 Pro Tip: No pool for your token pair? No problem. Omniston uses smart routing to find paths through intermediary tokens — your users can swap any available tokens on TON.

5. Execute the Swap

Once the user confirms the quote, use the useOmniston hook to execute the transaction.

Omniston uses HTLC-based smart contracts to securely execute swaps on-chain.

🧠 Pro Tip: Omniston’s RFQ system locks in the rate before the user signs. No slippage surprises — users get exactly the rate they agreed to.

6. Track Swap Status (optional)

Use useTrackTrade to monitor the trade’s progress and update your UI accordingly. This is great for giving feedback to the user — for example, you might show a loading spinner until the trade is confirmed on-chain, then display a success message once tokens have swapped.

🔍 Want to Learn More?

You can fork the live Replit example and experiment instantly in the browser.

🧠 Pro Tip

Omniston supports revenue-sharing via referral fees. Set a referrer address in the swap request to earn a fee for each trade executed through your app.

Omniston abstracts away the complexity of blockchain-based token swaps and delivers a high-level SDK that feels just like any modern React library. Whether you're building a wallet, a game, or a full DeFi app — adding Omniston puts deep liquidity and smart routing in your hands with just a few lines of code.

Previous★★ Liquidity pool types