DEV Community: Ivan “Crypto Vazima” Zimanov

How to Reuse an Existing TON Connect Instance with Omniston Widget Integrated Mode

Ivan “Crypto Vazima” Zimanov — Mon, 28 Sep 2026 05:04:20 +0000

If your TON dApp already has wallet connectivity, you should not create another TON Connect instance just for the Omniston Widget. Instead, configure the widget in integrated mode and pass it the same initialized instance that the rest of your application already uses.

The result is one shared wallet session across your interface. A wallet connected through your navigation, account panel, or another TON feature can also be used by the embedded Omniston swap interface. More importantly, this follows the architecture required by the current STON.fi widget integration, which warns against running multiple TON Connect instances inside the same application.

Why reuse the connection instead of creating another one?

Imagine a TON dashboard that already has a wallet button in its header.

A visitor connects Tonkeeper or another compatible wallet, and your application uses that connection to display the wallet address, account state, or transaction controls. You later decide to add token swaps through the Omniston Widget.

At first, it may seem reasonable to give the widget its own TON Connect configuration. That would create two separate wallet connection layers:

the TON Connect instance owned by your application
another TON Connect instance initialized for the widget

That is exactly the situation integrated mode is designed to avoid.

STON.fi's current widget documentation states that an application with an existing TON Connect instance should reuse it with the widget. The documentation also warns that multiple instances can cause the application to fail because of TON Connect SDK limitations.

Integrated mode changes the ownership model. Your application continues to own TON Connect. Omniston simply receives access to that existing connection.

The architecture becomes:

Application
    |
    +-- Existing TON Connect instance
    |       |
    |       +-- Header wallet UI
    |       +-- Account features
    |       +-- Other TON actions
    |       +-- Omniston Widget
    |
    +-- Application state

There is one wallet session rather than parallel wallet systems competing inside the same page.

What integrated mode actually does

The Omniston Widget currently supports two TON Connect modes: standalone and integrated.

standalone is intended for applications where the widget itself can own the wallet integration. You provide a TON Connect manifest URL, and the widget creates the connection layer internally.

integrated assumes that your application has already done that work.

The configuration is deliberately small:

tonconnect: {
  type: 'integrated',
  instance: tonconnect,
}

The instance is the important part.

According to the current STON.fi reference, it can be an initialized TonConnect instance from @tonconnect/sdk or a TonConnectUI instance from the TON Connect UI tooling.

That lets Omniston participate in the wallet architecture you already maintain instead of introducing another one.

The practical difference

Mode	Who owns TON Connect?	What the widget receives
`standalone`	Omniston Widget	TON Connect manifest configuration
`integrated`	Your application	Existing TON Connect instance

For an established dApp, the second model is usually the relevant one because wallet connectivity often belongs to the application as a whole, not to one swap component.

Reuse a `TonConnect` SDK instance

Start with the simplest case: your application already uses the headless @tonconnect/sdk.

TON describes TonConnect as the connector responsible for wallet connections and transaction signing. The SDK also exposes restoreConnection(), which can restore an existing session when the application loads.

A simplified application setup might look like this:

import { TonConnect } from '@tonconnect/sdk';

export const tonconnect = new TonConnect({
  manifestUrl: 'https://myapp.com/tonconnect-manifest.json',
});

tonconnect.restoreConnection();

The important architectural decision happens here. Create the connector once and export or otherwise provide access to that same object wherever wallet functionality is needed.

Now install the Omniston widget loader:

npm install @ston-fi/omniston-widget-loader

If your project already depends on @tonconnect/sdk, you do not need another TON Connect installation specifically for the widget. STON.fi's widget guide explicitly notes this case for integrated applications.

Load the widget constructor:

import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

const OmnistonWidget = await OmnistonWidgetLoader.load();

Then pass the existing connector:

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'integrated',
    instance: tonconnect,
  },
});

Finally, mount it into a real DOM element:

<div id="omniston-widget-container"></div>

const container = document.querySelector(
  '#omniston-widget-container'
);

if (container) {
  widget.mount(container);
}

No second new TonConnect() appears in the widget integration.

That absence is the core of the pattern.

Keep the instance at the application level

Integrated mode works best when TON Connect already has a clear owner in your codebase.

Avoid creating the connector inside the component that renders the Omniston Widget:

function SwapPage() {
  const tonconnect = new TonConnect({
    manifestUrl: 'https://myapp.com/tonconnect-manifest.json',
  });

  // ...
}

A component can rerender, unmount, or mount again. Depending on the framework and component lifecycle, putting connection infrastructure directly inside the rendering path can make ownership harder to reason about.

A cleaner pattern is to initialize the wallet layer at application level and reuse the reference.

For example:

// tonconnect.ts

import { TonConnect } from '@tonconnect/sdk';

export const tonconnect = new TonConnect({
  manifestUrl: 'https://myapp.com/tonconnect-manifest.json',
});

tonconnect.restoreConnection();

Then:

// omniston.ts

import { tonconnect } from './tonconnect';
import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

export async function mountOmniston(container: HTMLElement) {
  const OmnistonWidget = await OmnistonWidgetLoader.load();

  const widget = new OmnistonWidget({
    tonconnect: {
      type: 'integrated',
      instance: tonconnect,
    },
  });

  widget.mount(container);

  return widget;
}

Now the same object can serve your wallet button, account logic, and Omniston integration.

One useful rule

When reviewing your project, ask:

Where is TON Connect instantiated?

Ideally, there should be one clear answer.

If you find one initialization in your navigation code and another near the Omniston Widget, you probably have an architectural problem to fix before adding more wallet-dependent features.

What about `TonConnectUI` and React?

Many TON applications do not interact with the headless SDK directly. React applications commonly use @tonconnect/ui-react, which provides TonConnectUIProvider, TonConnectButton, and hooks such as useTonConnectUI().

TON's current React documentation says useTonConnectUI() returns the active TonConnectUI instance. That instance exposes wallet and transaction functionality and can be shared with other components that need TON Connect access.

A React component can therefore retrieve the existing instance:

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

function SwapSection() {
  const [tonConnectUI] = useTonConnectUI();

  // tonConnectUI is the existing application instance

  return <div id="omniston-widget-container" />;
}

You would then use that tonConnectUI object as the widget's integrated instance rather than constructing another wallet layer.

Conceptually:

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'integrated',
    instance: tonConnectUI,
  },
});

STON.fi's widget configuration currently accepts TonConnectUI for the integrated tonconnect.instance field, while TON's React API exposes the shared UI instance through its provider and hook model.

Remember the client lifecycle

TON Connect UI is browser-facing infrastructure. Current TON documentation describes @tonconnect/ui-react as client-only and notes that Next.js integrations should keep the provider on the client side.

The Omniston Widget also needs a real DOM node for mounting.

So in a React or Next.js application, avoid treating widget construction as server rendering logic. Wait until the client has mounted and the container exists.

A typical sequence is:

Let the application establish its TON Connect provider.
Obtain the existing TonConnectUI instance.
Wait until the widget container exists in the DOM.
Load the Omniston widget constructor.
Create the widget in integrated mode.
Pass the existing instance.
Mount the widget.
Clean up appropriately if your application destroys or replaces the view.

The exact component code depends on your framework lifecycle, but the ownership rule does not change.

What happens to an already connected wallet?

This is where integrated mode becomes especially useful.

Suppose the visitor connects a wallet from your global navigation before opening the swap page.

Your application already knows about that connection through its existing TON Connect infrastructure. The Omniston Widget receives the same TON Connect object, so it works with the shared wallet context rather than starting an unrelated wallet session.

TON Connect itself supports connection restoration. The headless SDK exposes restoreConnection(), while TON Connect UI has restoration support enabled by default unless the application configures it differently.

You should therefore let the application-level wallet system remain responsible for connection restoration.

Do not interpret integrated mode as an instruction to manually synchronize two TON Connect instances. There should not be two instances to synchronize in the first place.

The flow should look like this:

App starts
   |
Existing TON Connect restores or establishes wallet session
   |
User opens swap interface
   |
Omniston Widget receives the same instance
   |
Widget uses that wallet context for swap interaction
   |
Wallet asks the user to approve the transaction

Integrated mode shares infrastructure. It does not bypass wallet authorization.

A complete integrated example

Here is the core setup in one place:

import { TonConnect } from '@tonconnect/sdk';
import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

const tonconnect = new TonConnect({
  manifestUrl: 'https://myapp.com/tonconnect-manifest.json',
});

await tonconnect.restoreConnection();

const OmnistonWidget = await OmnistonWidgetLoader.load();

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'integrated',
    instance: tonconnect,
  },

  widget: {
    defaultBidAsset:
      'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
  },
});

const container = document.querySelector(
  '#omniston-widget-container'
);

if (!container) {
  throw new Error('Omniston widget container not found');
}

widget.mount(container);

The widget settings are independent of the connection ownership decision. You can configure default assets, custom assets, referral parameters, and supported widget styling without creating another TON Connect instance.

Keep those concerns separate:

TON Connect configuration answers which wallet session the widget uses.
Widget configuration controls the swap experience.
Application lifecycle controls when the widget is created and mounted.

That separation makes the integration easier to maintain.

Common mistakes when switching to integrated mode

The most common error is leaving standalone configuration in place after the rest of the application gains TON Connect support.

For example, do not keep this:

tonconnect: {
  type: 'standalone',
  options: {
    manifestUrl: 'https://myapp.com/tonconnect-manifest.json',
  },
}

if another part of the same application already initializes TON Connect.

Instead, pass the existing instance:

tonconnect: {
  type: 'integrated',
  instance: tonconnect,
}

Also watch for these problems:

Creating the instance twice in different modules. Two files can both look correct individually while producing the wrong application architecture together.
Constructing TON Connect inside a frequently recreated component. Move wallet infrastructure to a stable application-level owner.
Passing a different connector than the rest of the UI uses. Integrated mode is useful because the instance is shared.
Mounting before the DOM container exists. Wait for the relevant client lifecycle stage.
Reimplementing connection restoration for the widget. Let your established TON Connect setup own session restoration.
Assuming a connected wallet removes transaction approval. The wallet still controls authorization for requested transactions.

Before shipping, test the application as one connected system rather than testing only whether the widget appears.

Connect from the global wallet button, navigate to the swap interface, disconnect, reconnect, reload the page, and repeat the flow on the environments you actually support.

Practical takeaway: if your application already owns TON Connect, keep it that way. Create or obtain one stable TonConnect or TonConnectUI instance, let the rest of the app manage its connection lifecycle, and give Omniston that exact instance through tonconnect.type: 'integrated'. The goal is not merely fewer lines of code. It is one coherent wallet session shared by every TON-enabled part of your application.

Frequently Asked Questions

What is integrated TON Connect mode in the Omniston Widget?

Integrated mode tells the Omniston Widget to use a TON Connect instance that your application has already initialized. Instead of receiving a manifest URL and constructing its own connection layer, the widget receives the existing TonConnect or supported TonConnectUI instance and participates in the wallet session already managed by your dApp.

When should I use integrated instead of standalone mode?

Use integrated mode when your application already manages TON Connect outside the widget. A common example is a dApp with a global connect button, account page, and several wallet-enabled features. Standalone mode is more appropriate when the Omniston Widget is effectively the only part of the application that needs TON Connect.

Can I create one TON Connect instance for my app and another for Omniston?

You should not. STON.fi's current widget documentation explicitly warns that only one TON Connect instance should exist in the application because of TON Connect SDK limitations. If an instance already exists, configure Omniston in integrated mode and reuse that same instance instead of creating a second one.

Can Omniston integrated mode use `TonConnectUI`?

Yes. The current STON.fi widget configuration lists both TonConnect from @tonconnect/sdk and TonConnectUI from the TON Connect UI stack as supported values for the integrated tonconnect.instance option. This allows applications that already use the higher-level wallet UI tooling to share that connection with Omniston.

Should Omniston call `restoreConnection()` itself?

Your application should continue owning the connection lifecycle when using integrated mode. If you use the headless SDK, TON documents restoreConnection() as the method for restoring an earlier session. If you use TON Connect UI, restoration behavior is managed through its configuration. Omniston receives the resulting shared instance rather than requiring a separate restoration system.

Does the TON Connect manifest still matter in integrated mode?

Yes, but it normally belongs to the application-level TON Connect initialization rather than the Omniston configuration. TON Connect uses the manifest to provide dApp information to wallets. Your existing connector or UI setup should already reference the appropriate manifest, while the Omniston Widget receives the initialized instance.

Can I use integrated mode in Next.js?

Yes, but TON Connect UI and widget mounting need to happen on the client side. TON's current React documentation describes @tonconnect/ui-react as client-only and recommends client components or disabled server-side rendering for the provider in Next.js. Mount Omniston only after its DOM container and TON Connect instance are available.

What should I verify before shipping an Omniston integrated-mode integration?

Verify that your application creates only one TON Connect instance, that Omniston receives exactly that instance, and that connection restoration works after a reload. Then test connecting and disconnecting from your main wallet UI, navigating to the widget, initiating a swap, and reviewing the wallet approval request. The important test is whether the whole application behaves as one wallet-connected system.

Sources and Further Reading

STON.fi Full Guide and Reference - Official Omniston Widget installation, TON Connect modes, integrated instance configuration, and the warning about multiple instances
STON.fi Omniston Widget - Official overview of widget capabilities and the distinction between standalone and integrated TON Connect modes
STON.fi Help Center - Official explanation of embedding the swap widget and choosing between standalone and integrated wallet connectivity
TON Connect SDK Reference - Official @tonconnect/sdk reference covering TonConnect, restoreConnection(), and transaction methods
TON Connect UI React Reference - Official React API reference for TonConnectUIProvider, useTonConnectUI(), and shared connector instances
TON Connect UI Reference - Official UI configuration reference covering connection restoration, manifest configuration, and the underlying connector model
TON Connect Get Started - Official TON documentation explaining headless SDK usage and application-level wallet integration
TON Connect Protocol Specification - The protocol-level definition of the wallet connection request and the role of manifestUrl

How to Configure Standalone TON Connect Mode in the Omniston Widget

Ivan “Crypto Vazima” Zimanov — Tue, 22 Sep 2026 06:20:43 +0000

Use the STON.fi swap widget with wallet connectivity built in, without creating or managing a separate TON Connect instance.

Standalone TON Connect mode is the simplest way to give an embedded Omniston Widget its own wallet connection flow. You provide the widget with the URL of your TON Connect manifest, mount the widget on the page, and the widget initializes TON Connect internally. You do not need to install or configure a separate TON Connect package just to make the swap widget work.

That makes standalone mode a good fit for landing pages, lightweight dApps, dashboards, and websites where the Omniston Widget is the main feature that needs wallet access. The important limitation is just as simple: if your application already has its own TON Connect instance, standalone mode is no longer the right choice. In that case, the widget should reuse the existing connection through integrated mode.

What standalone mode actually does

The Omniston Widget supports two TON Connect configurations: standalone and integrated.

With standalone mode, the responsibility boundary is clear. Your application provides the TON Connect manifest and a DOM element where the widget should appear. The widget handles its own TON Connect initialization and uses that connection when a user needs to connect a wallet and approve a swap.

The minimal structure is:

tonconnect: {
  type: 'standalone',
  options: {
    manifestUrl: 'https://myapp.com/tonconnect-manifest.json',
  },
}

You are not passing an existing TonConnect or TonConnectUI instance into the widget. The widget creates the TON Connect layer it needs internally. STON.fi documents this mode specifically for smaller applications or sites that only need the swap flow supplied by the widget.

The practical split looks like this:

Your app hosts the TON Connect manifest.
Your app loads and mounts the Omniston Widget.
The widget manages its TON Connect instance.
The wallet still presents connection and transaction requests to the user.
The user remains responsible for approving or rejecting the wallet action.

Standalone does not remove wallet approval. It removes the need for your application to build the wallet connection layer separately.

Prepare the TON Connect manifest first

Before initializing the widget, create a tonconnect-manifest.json file for your application.

The manifest tells compatible wallets which application is asking for a connection. TON Connect defines required fields for the application URL, application name, and icon, while terms of use and privacy policy URLs are optional.

A minimal manifest could look like this:

{
  "url": "https://myapp.com",
  "name": "My Omniston App",
  "iconUrl": "https://myapp.com/icon-180.png"
}

A more complete version might be:

{
  "url": "https://myapp.com",
  "name": "My Omniston App",
  "iconUrl": "https://myapp.com/icon-180.png",
  "termsOfUseUrl": "https://myapp.com/terms",
  "privacyPolicyUrl": "https://myapp.com/privacy"
}

The manifest needs to be publicly reachable. TON Connect documentation says wallets must be able to fetch it without authentication, restrictive CORS rules, or proxy challenges that block automated requests. HTTPS should be used, and the application icon should use a compatible raster format such as PNG or ICO rather than SVG.

STON.fi's widget guide specifically instructs integrators to create and host their own manifest and says the manifest URL should be hosted on the same domain as the application. For an Omniston Widget integration, following that stricter integration guidance is the safest approach.

Before writing any widget code, check these four things:

https://myapp.com/tonconnect-manifest.json opens without authentication.
The response is valid JSON.
url, name, and iconUrl contain real production values.
The icon URL itself can be opened publicly.

A surprising number of wallet connection problems start here rather than inside the widget.

Load the Omniston Widget

STON.fi currently provides the widget as a CDN-hosted bundle. You can either use the small npm loader package to fetch that bundle at runtime or include the CDN script directly. Both approaches expose the same OmnistonWidget constructor.

For a bundled JavaScript or TypeScript project, install the loader:

npm install @ston-fi/omniston-widget-loader

Then load the widget constructor:

import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

const OmnistonWidget = await OmnistonWidgetLoader.load();

The loader is useful when your application should control when the widget bundle is fetched and mounted.

For a static page, you can skip npm completely:

<script src="https://widget.ston.fi/v0/index.js"></script>

The constructor then becomes available as:

window.OmnistonWidget

STON.fi uses major-versioned CDN paths such as /v0/. Non-breaking updates can be delivered inside that major version without requiring you to change the script URL. A future breaking release can use another major-version path.

Configure standalone TON Connect mode

Once the manifest and widget loader are ready, the actual standalone configuration is small.

Create a container:

<div id="omniston-widget-container"></div>

Then initialize and mount the widget:

import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

const OmnistonWidget = await OmnistonWidgetLoader.load();

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'standalone',
    options: {
      manifestUrl: 'https://myapp.com/tonconnect-manifest.json',
    },
  },
});

widget.mount(
  document.querySelector('#omniston-widget-container')
);

That is enough for the basic standalone wallet setup. According to the STON.fi reference, tonconnect.options.manifestUrl is required for standalone mode, while a separately initialized TON Connect instance is not.

You can then add normal widget configuration without changing the wallet architecture. For example:

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'standalone',
    options: {
      manifestUrl: 'https://myapp.com/tonconnect-manifest.json',
    },
  },

  widget: {
    defaultBidAsset:
      'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',

    defaultAskAsset:
      'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO',
  },
});

Here the TON Connect configuration still answers only one question: who owns wallet connectivity? The answer remains the widget itself.

Options such as default assets, custom assets, styling, and integrator fee configuration belong to the swap experience and can be changed independently.

The CDN version is even smaller

Standalone mode is especially convenient when you want a swap interface on a page without maintaining a JavaScript build pipeline.

A compact CDN implementation looks like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Omniston Swap</title>
  </head>

  <body>
    <div id="omniston-widget-container"></div>

    <script src="https://widget.ston.fi/v0/index.js"></script>

    <script>
      const widget = new window.OmnistonWidget({
        tonconnect: {
          type: 'standalone',
          options: {
            manifestUrl:
              'https://myapp.com/tonconnect-manifest.json',
          },
        },
      });

      widget.mount(
        document.querySelector(
          '#omniston-widget-container'
        )
      );
    </script>
  </body>
</html>

There is no separate @tonconnect/ui, @tonconnect/ui-react, or @tonconnect/sdk setup in this version. That is the main value of standalone mode: wallet connectivity is part of the widget integration rather than another application-level dependency you need to wire together yourself.

When standalone becomes the wrong mode

The simplicity of standalone mode can become a problem if your application already uses TON Connect elsewhere.

Imagine a dashboard with:

a wallet button in the global navigation
account information in a profile panel
several TON-powered features
the Omniston Widget on one page

If the application already initializes TON Connect for the global wallet experience, the Omniston Widget should not initialize another independent instance.

STON.fi explicitly warns that only one TON Connect instance should exist in the application and instructs developers to use integrated mode when an instance already exists. The widget can then reuse that connection instead of creating its own.

Situation	Recommended mode
Widget is the only feature that needs a TON wallet	`standalone`
Simple static website with an embedded swap	`standalone`
Landing page with no existing wallet architecture	`standalone`
App already initializes TON Connect	`integrated`
Global wallet state is shared across multiple features	`integrated`
React app already uses `TonConnectUIProvider`	Usually `integrated`

A useful rule is to decide who owns the wallet session.

If the Omniston Widget owns it, use standalone. If your application owns it, use integrated.

Following one standalone swap from page load to signing

Consider a simple site that only wants to offer Omniston-powered swaps.

When the page loads, your code fetches the widget bundle and constructs OmnistonWidget with type: 'standalone'. The configuration points to your public TON Connect manifest. The widget then mounts into the selected DOM container.

The visitor can browse the swap interface without your page creating a separate TON Connect UI layer.

When wallet access becomes necessary, TON Connect handles the connection request using the manifest metadata that identifies your application. At the protocol level, the wallet receives a connect request that contains the manifest URL and the requested connection data.

After the wallet is connected, the swap flow can proceed through the widget. Transaction authorization still happens in the wallet. Standalone mode changes the integration architecture, not the basic self-custodial principle that a wallet action needs the wallet holder's approval.

For a developer, the resulting flow is compact:

Host the manifest.
Load the widget.
Set tonconnect.type to standalone.
Pass manifestUrl.
Mount the widget.
Test connecting a wallet and initiating a swap.

You are not reproducing Omniston's swap UI or manually building a TON Connect wallet picker. You are giving the widget enough information to manage those parts of its own workflow.

What to test before shipping

A widget appearing correctly on the page does not prove that the wallet flow is configured correctly. Test the connection itself.

Start with the manifest in a normal browser window and then test the full flow from the production-like domain.

A useful release checklist is:

Open the exact manifestUrl configured in the widget.
Confirm that it returns JSON without login or access challenges.
Confirm that the application URL in the manifest is correct.
Open the iconUrl independently.
Test wallet connection from the deployed application.
Confirm that reconnecting does not create duplicate wallet systems.
Initiate a small test swap and inspect the wallet request before approval.
Test both desktop and mobile connection paths relevant to your audience.

If the wallet reports that the manifest cannot be loaded, check the URL, deployment state, CORS behavior, HTTPS configuration, and any CDN or security layer in front of the file. TON documentation identifies unavailable manifests and invalid manifest content as explicit connection errors.

For local or preview environments, remember that the wallet must still be able to reach the manifest URL. A file that exists inside your repository but is not publicly served does not satisfy the connection flow.

Practical takeaway: use standalone mode when the Omniston Widget can legitimately own the wallet connection for the page. Keep the configuration small, treat the manifest as part of the production integration rather than a placeholder file, and switch to integrated mode as soon as TON Connect becomes shared application infrastructure.

Frequently Asked Questions

What is standalone TON Connect mode in the Omniston Widget?

Standalone mode tells the Omniston Widget to initialize and manage TON Connect internally. You supply a public manifestUrl, while the widget handles the wallet connection layer it needs for its swap flow. You do not need to create a separate TonConnect instance only for the widget.

Do I need to install `@tonconnect/sdk` for standalone mode?

No. STON.fi states that standalone mode works with the manifest URL and does not require additional TON Connect packages. You still need a valid TON Connect manifest, but the Omniston Widget manages its own connection internally.

What fields does the TON Connect manifest need?

The current TON Connect specification requires url, name, and iconUrl. termsOfUseUrl and privacyPolicyUrl are optional. The manifest must be valid JSON and publicly reachable so wallets can fetch it when processing a connection request.

Can I use standalone mode in a React application?

Yes. Standalone mode is about who controls TON Connect, not which frontend framework you use. If your React application does not already initialize TON Connect elsewhere, the widget can run standalone. If you already use TonConnectUIProvider or another shared TON Connect instance, integrated mode is generally the appropriate architecture.

Can standalone mode and another TON Connect instance run together?

They should not. STON.fi warns that an application should not create multiple TON Connect instances. If your application already manages TON Connect, configure the Omniston Widget with type: 'integrated' and provide the existing instance instead.

Does standalone mode mean users do not need to approve swaps?

No. Standalone describes how the application integrates TON Connect. It does not bypass the wallet. TON Connect still provides the communication flow between the dApp and wallet, and transaction requests remain subject to the wallet holder's authorization.

Can I use standalone mode without npm?

Yes. Load https://widget.ston.fi/v0/index.js directly in the browser, create new window.OmnistonWidget(...), provide the standalone TON Connect descriptor, and mount it into your chosen DOM element. STON.fi documents the CDN approach as the no-bundler option.

What should I check first if the Omniston Widget cannot connect a TON wallet?

Check the manifest before debugging the swap logic. Confirm that the configured URL is correct, publicly accessible over HTTPS, valid JSON, and reachable without authentication, restrictive CORS, or proxy challenges. Then verify the application and icon URLs inside the manifest and retest the connection from your deployed domain.

Sources and Further Reading

STON.fi Widget - official overview of the swap widget, distribution options, TON Connect modes, and basic standalone configuration
STON.fi Widget Full Guide & Reference - detailed configuration reference for standalone and integrated TON Connect modes, CDN usage, assets, styling, and widget lifecycle
STON.fi Omniston Widget GitHub Repository - official widget repository with distribution and loader information
TON Connect Get Started - official TON documentation covering manifests, SDK choices, wallet connection, and transaction flows
TON Connect App Manifest Specification - normative reference for manifest fields, hosting requirements, caching, and icon requirements
TON Connect Connection Specification - normative description of the connection request and manifest URL used during wallet connection
TON Connect Bridge Specification - normative description of communication between dApps and wallets through HTTP and JavaScript bridges

How to Load the Omniston Widget with @ston-fi/omniston-widget-loader

Ivan “Crypto Vazima” Zimanov — Sat, 19 Sep 2026 04:45:45 +0000

Use the npm loader to fetch the current Omniston Widget bundle at runtime, connect TON Connect, and mount a complete swap interface inside your application.

If you are building a modern JavaScript application, @ston-fi/omniston-widget-loader gives you programmatic control over when the Omniston Widget enters the page. You install a small npm package, call its load() method, receive the OmnistonWidget constructor, create an instance, and mount that instance into a DOM element.

The important detail is that the npm package is a loader, not a packaged copy of the complete widget. The actual widget remains CDN-hosted. That distribution model lets STON.fi deliver compatible updates inside a major version without requiring every integrator to reinstall the full widget package.

Why does Omniston use a loader package?

A normal npm integration usually installs the complete library into your project. Your package manager resolves a particular version, your bundler includes it in the application, and that exact copy stays there until you update the dependency.

Omniston takes a different approach.

The @ston-fi/omniston-widget-loader package gives your application the code needed to load the widget, while the widget itself is distributed through STON.fi's CDN. According to the official documentation, CDN paths are major-versioned. Within one major version, integrators can receive compatible fixes and improvements without changing the integration every time the widget receives an update.

That creates a useful separation:

npm manages the loader inside your application.
The loader fetches the widget bundle when your code requests it.
The widget constructor is returned to your code after loading succeeds.
Your application decides when and where to mount it.

This is particularly useful in React, Vue, Svelte, Angular, and other bundled applications where a developer may not want a global <script> tag running immediately when the page loads.

It also means you should not assume that installing @ston-fi/omniston-widget-loader places the complete Omniston Widget inside your JavaScript bundle. The runtime loading step is part of the architecture.

What actually happens when you call `load()`?

At the application level, the flow is simple:

Your application
      |
      v
@ston-fi/omniston-widget-loader
      |
      | load()
      v
STON.fi widget CDN
      |
      v
OmnistonWidget constructor
      |
      v
new OmnistonWidget(config)
      |
      v
widget.mount(container)

The package exposes a loader with a load() function. When the promise resolves, you receive the constructor that you use to create the widget instance.

A minimal pattern looks like this:

import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

const OmnistonWidget = await OmnistonWidgetLoader.load();

const widget = new OmnistonWidget({
  // configuration
});

Loading and creating are therefore two different operations.

load() obtains the widget constructor. new OmnistonWidget(...) creates your configured widget instance. mount(...) finally attaches that instance to a real element on the page.

The widget also brings its own styles, so the official guide does not require a separate CSS package import.

That separation matters when you integrate it into an application lifecycle. You can wait until a component exists, lazy-load the widget only where swaps are needed, and clean up the mounted instance when the surrounding page changes.

Install the loader and mount your first widget

Install the package with your preferred package manager:

npm install @ston-fi/omniston-widget-loader

or:

yarn add @ston-fi/omniston-widget-loader

or:

pnpm add @ston-fi/omniston-widget-loader

Next, add a container to your page:

<div id="omniston-widget-container"></div>

Then load, configure, and mount the widget:

import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

const OmnistonWidget = await OmnistonWidgetLoader.load();

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'standalone',
    options: {
      manifestUrl: 'https://your-app.com/tonconnect-manifest.json',
    },
  },
});

const container = document.querySelector('#omniston-widget-container');

if (container) {
  widget.mount(container);
}

There are four operations worth noticing here:

Import the loader.
Await OmnistonWidgetLoader.load().
Create the widget with its configuration.
Mount it into an existing DOM node.

The container check is not cosmetic. mount() needs an element that actually exists, so your framework's rendering lifecycle matters. In a React component, for example, you normally wait until the component has mounted and the container ref is available.

You also need TON Connect configuration before the swap experience can connect to a wallet.

Choose the right TON Connect mode

The Omniston Widget supports two TON Connect patterns: standalone and integrated. They solve different application problems.

Mode	Wallet connection	Good fit
`standalone`	The widget manages its own TON Connect setup from your manifest	A site where the widget is the main wallet-enabled feature
`integrated`	The widget receives an existing TON Connect instance	A larger dApp that already manages wallet state

Standalone mode

Standalone mode keeps the integration compact:

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'standalone',
    options: {
      manifestUrl: 'https://your-app.com/tonconnect-manifest.json',
    },
  },
});

You provide the TON Connect manifest and let the widget handle the connection flow it needs.

This works well when you are adding a swap module to a landing page, product page, dashboard, or another application that does not already maintain a separate TON Connect session.

Integrated mode

If your dApp already has TON Connect, creating an independent connection just for the widget is usually unnecessary. Instead, pass the initialized instance to Omniston:

import { TonConnect } from '@tonconnect/sdk';
import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

const tonconnect = new TonConnect({
  manifestUrl: 'https://your-app.com/tonconnect-manifest.json',
});

const OmnistonWidget = await OmnistonWidgetLoader.load();

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'integrated',
    instance: tonconnect,
  },
});

The widget can then share the wallet connection already used by the rest of your application.

Your TON Connect manifest must also be publicly reachable. TON documentation specifies HTTPS access, no authentication requirement, and no blocking proxy challenge. STON.fi's widget guide additionally instructs integrators to host their own manifest on their application domain. Following the widget guide's deployment pattern is the safer choice for this particular integration.

Following one loader-based STON.fi integration

Imagine you already have a dashboard built with a modern frontend framework. Users can connect their TON wallet elsewhere in the application, but there is no swap interface yet.

You want to add Omniston without implementing token selectors, swap UI, routing integration, and transaction interaction from scratch.

First, install the loader:

npm install @ston-fi/omniston-widget-loader

Your application already maintains a TON Connect instance, so the widget should use integrated mode.

After the swap component appears, load the constructor:

const OmnistonWidget = await OmnistonWidgetLoader.load();

Now create the instance:

const widget = new OmnistonWidget({
  tonconnect: {
    type: 'integrated',
    instance: tonconnect,
  },
  widget: {
    defaultBidAsset:
      'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
    defaultAskAsset:
      'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO',
  },
});

The example above preselects TON as the asset to sell and STON as the asset to receive, using the addresses shown in STON.fi's current widget documentation. These defaults are optional.

Finally, mount the interface:

widget.mount(containerElement);

At that point, the loader's job is effectively finished. It got the constructor into your application. The configured OmnistonWidget instance now owns the widget lifecycle.

This distinction is useful when debugging. If load() fails, investigate the runtime loading stage. If construction succeeds but wallet interaction fails, inspect TON Connect configuration. If the instance exists but nothing appears, check the DOM container and mount timing.

A compact debugging checklist

When a loader-based integration does not behave as expected, check these areas separately:

Did OmnistonWidgetLoader.load() resolve successfully?
Does the mount container exist at the moment mount() runs?
Is the TON Connect manifest publicly accessible?
Are you using the intended standalone or integrated mode?
If using integrated mode, are you passing the initialized TON Connect instance?
Does your application remove or recreate the container during navigation?

Separating loading, configuration, and mounting usually makes the source of a problem much easier to identify.

Control mounting, unmounting, and runtime behavior

Loading a widget once does not mean it must remain mounted forever.

The official guide exposes mount and unmount lifecycle methods, along with events for mount, unmount, and error.

For example:

widget.on('mount', ({ container }) => {
  console.info('Omniston Widget mounted', container);
});

widget.on('unmount', () => {
  console.info('Omniston Widget unmounted');
});

widget.on('error', (error) => {
  console.error('Omniston Widget error', error);
});

You can explicitly remove the widget when it is no longer needed:

widget.unmount();

This becomes important in single-page applications. A route change can remove the original DOM node while your JavaScript still holds a reference to the widget instance.

A React component, for example, can load the widget inside an effect and unmount it during cleanup:

useEffect(() => {
  let active = true;
  let widget;

  OmnistonWidgetLoader.load().then((OmnistonWidget) => {
    if (!active || !containerRef.current) return;

    widget = new OmnistonWidget({
      tonconnect: {
        type: 'integrated',
        instance: tonconnect,
      },
    });

    widget.mount(containerRef.current);
  });

  return () => {
    active = false;
    widget?.unmount();
  };
}, [tonconnect]);

The active guard prevents asynchronous loading from mounting into a component that disappeared before the promise resolved.

That is one of the practical advantages of the loader approach. Widget loading can participate in the same lifecycle logic as the rest of your application instead of depending on a permanently declared global script.

Loader or direct CDN script?

STON.fi supports both approaches. They eventually give you access to the same widget constructor, but they fit different environments.

With the npm loader:

import OmnistonWidgetLoader from '@ston-fi/omniston-widget-loader';

const OmnistonWidget = await OmnistonWidgetLoader.load();

With the direct CDN approach, the script creates a browser global:

<script src="https://widget.ston.fi/v0/index.js"></script>

and your page uses:

const widget = new window.OmnistonWidget({
  // configuration
});

The direct CDN method is attractive for a small static page because there is almost nothing to install.

The loader is usually the more natural choice when your project already has a build system and application lifecycle. You can import it through your package manager, decide exactly when loading starts, keep the integration inside your JavaScript modules, and coordinate mounting with your framework.

One detail should not be overlooked: using the npm loader does not replace the CDN distribution model. The loader is a controlled way to access that model from a bundled application.

What should you verify before shipping?

A working local demo is only the first stage. Before deploying a loader-based Omniston Widget integration, test the complete path from page load to wallet interaction.

Loading

Confirm that the widget loads successfully in the actual production environment, not only through your development server.

Manifest

Verify that your TON Connect manifest and icon remain publicly available over HTTPS. TON documentation notes that inaccessible or invalid manifests can cause manifest-related connection errors.

Lifecycle

Navigate away from the widget and back again. Make sure your application does not accidentally create duplicate instances or retain a widget mounted to an obsolete container.

Wallet state

If your application already manages TON Connect, verify that the widget uses the same intended connection through integrated mode.

Swap configuration

If you set default assets, custom assets, or referral parameters, verify those values rather than assuming that a successfully rendered interface means every option is correct.

Error handling

Capture the widget's error event during development. A visible swap box is only one part of the integration. Wallet connection and transaction flows need testing as well.

The practical takeaway is simple: treat @ston-fi/omniston-widget-loader as the runtime boundary between your application and the CDN-delivered widget. Test the loader, widget configuration, wallet layer, and DOM lifecycle independently. Once those pieces are separated mentally, integrating Omniston becomes much easier to reason about.

Frequently Asked Questions

What is `@ston-fi/omniston-widget-loader`?

It is an npm package for programmatically loading the Omniston Widget bundle. Your application calls load(), waits for the bundle to become available, and receives the OmnistonWidget constructor. The complete widget itself uses STON.fi's CDN distribution model rather than being bundled as a fixed widget copy inside the loader package.

Does `npm install @ston-fi/omniston-widget-loader` install the complete widget?

Not in the conventional sense. The package acts as a loader for the CDN-hosted widget. STON.fi documents this as an intentional distribution model so compatible widget updates can be delivered within a major-version path while applications keep using the same integration pattern.

Do I need to import the Omniston Widget CSS separately?

No separate widget stylesheet import is required according to the current STON.fi integration guide. The widget bundle loads its own styles. You can then customize supported visual properties through CSS variables scoped to the element used for widget.mount(...).

Should I use `standalone` or `integrated` TON Connect mode?

Use standalone when the widget can manage the wallet connection required for its own swap flow. Use integrated when your application already maintains TON Connect and you want Omniston to share that existing instance. The second approach avoids treating the widget as a separate wallet-connected application inside your dApp.

Can I lazy-load the Omniston Widget?

Yes. Programmatic runtime loading is one of the main reasons to use the loader. You can call load() when a swap component opens, when a relevant route becomes active, or at another point chosen by your application rather than declaring the widget globally with a script tag.

What does `load()` return?

It resolves with the OmnistonWidget constructor. You still need to instantiate it with new OmnistonWidget(configuration) and then call mount() with an existing DOM element. Loading the constructor and rendering the configured widget are separate stages.

Can I remove the widget after mounting it?

Yes. The documented widget lifecycle includes unmount(), and the widget exposes lifecycle events including mount, unmount, and error. This is especially useful in applications where routes or components appear and disappear without a full browser refresh.

When should I use the loader instead of the CDN script?

Use the loader when your application already uses npm and a modern build system, especially when you want programmatic control over loading and component lifecycle. Use the direct CDN script when a small static integration benefits more from minimal setup. Both approaches ultimately expose the Omniston Widget constructor.

Sources and Further Reading

STON.fi Omniston Widget - Official overview of the widget, npm loader, CDN distribution, TON Connect modes, configuration, and customization
STON.fi Full Guide & Reference - Official installation guide covering @ston-fi/omniston-widget-loader, load(), configuration, lifecycle methods, assets, and TON Connect integration
STON.fi Omniston Widget GitHub repository - Official repository explaining the CDN distribution model and programmatic loader usage
npm package registry - Package information and usage example for @ston-fi/omniston-widget-loader
STON.fi Help Center - Official overview of embedding the swap widget, TON Connect modes, theming, assets, and referral configuration
TON Documentation - Official TON Connect guidance covering manifest hosting, accessibility requirements, and available SDK packages

How to Embed the Omniston Widget with a CDN Script

Ivan “Crypto Vazima” Zimanov — Sun, 13 Sep 2026 15:43:45 +0000

Add an Omniston swap interface to a website with a single CDN bundle, TON Connect, and a small amount of JavaScript.

You do not need a package manager or a full frontend build pipeline to embed the Omniston Widget. STON.fi provides the widget as a CDN-hosted JavaScript bundle. Add the script to your page, create an OmnistonWidget instance, connect it to a TON Connect manifest, and mount it into a DOM element.

The direct CDN approach is especially useful for static websites, prototypes, landing pages, dashboards, and projects where adding another npm dependency would be unnecessary. You still get the same widget constructor used by the npm loader, but the browser downloads the bundle directly from STON.fi.

What the CDN integration actually does

The essential script is only one line:

<script src="https://widget.ston.fi/v0/index.js"></script>

Once that file loads, it exposes the widget constructor as:

window.OmnistonWidget

That global constructor is the entry point for configuring and mounting the swap interface.

The /v0/ part of the CDN URL is important. STON.fi uses major-versioned CDN paths. Integrations on the same major version can receive non-breaking updates without changing the script URL. A future breaking release would use a different major path such as /v1/.

So the browser-side flow is straightforward:

Load the CDN script.
Create an OmnistonWidget instance.
Pass the TON Connect configuration.
Find the container where the widget should appear.
Call widget.mount(container).

You do not need to import a separate widget stylesheet. The widget bundle handles its own styles, while supported CSS custom properties let you change its appearance from the container around it.

What you need before adding the widget

The JavaScript is the easy part. Wallet connectivity requires one additional piece: a TON Connect manifest.

A minimal integration needs:

a page that can run JavaScript
a DOM element for the widget
the Omniston CDN script
a public TON Connect manifest
HTTPS in production

The TON Connect manifest tells compatible wallets which application is requesting the connection. It contains basic dApp metadata such as the application URL, name, and icon.

A minimal manifest can look like this:

{
  "url": "https://example.com",
  "name": "My Omniston App",
  "iconUrl": "https://example.com/icon-180.png"
}

TON documentation requires the manifest to be publicly reachable without authentication or blocking CORS rules. HTTPS should be used, and the referenced icon should be publicly accessible as PNG or ICO. STON.fi's widget documentation specifically instructs integrators to host their own manifest on the application domain, so following that stricter layout is the safest approach for this integration.

For example:

https://example.com/tonconnect-manifest.json

Do not point a production application at somebody else's manifest. It represents the identity shown to the wallet during connection.

The smallest working CDN example

Here is the core integration in one HTML document:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Omniston Widget</title>
</head>

<body>
  <div
    id="omniston-widget-container"
    style="max-width: 420px; margin: 40px auto;"
  ></div>

  <script src="https://widget.ston.fi/v0/index.js"></script>

  <script>
    const widget = new window.OmnistonWidget({
      tonconnect: {
        type: "standalone",
        options: {
          manifestUrl:
            "https://example.com/tonconnect-manifest.json",
        },
      },
    });

    const container = document.querySelector(
      "#omniston-widget-container"
    );

    widget.mount(container);
  </script>
</body>
</html>

Replace example.com with your actual domain and publish the TON Connect manifest there.

The standalone option is useful because the widget manages TON Connect internally. You provide the manifest URL, and you do not need to create a separate TON Connect instance just to get the widget running. STON.fi recommends this mode for smaller sites that only need the wallet connection as part of the embedded swap experience.

The important line is:

widget.mount(container);

The constructor only creates the widget instance. mount() attaches its interface to the page.

That distinction becomes useful later if your application needs to open, close, or move the swap experience dynamically.

What happens after the widget is mounted

Embedding the component does more than place a form on the page.

Omniston is STON.fi's liquidity aggregation protocol for TON. Instead of requiring your frontend to implement each liquidity venue separately, Omniston can obtain quotes from connected liquidity sources and resolvers and find a route for the requested swap.

From the developer's perspective, the widget provides the user-facing layer around that process.

A typical interaction looks like this:

The visitor opens your page.
The CDN bundle creates the swap interface.
The visitor chooses the assets and amount.
TON Connect handles wallet connectivity.
Omniston obtains swap quotes from its available liquidity sources.
The visitor reviews the resulting swap and authorizes the required transaction through the wallet.
The resulting operation proceeds through the selected route.

This is why the widget can be useful when your goal is to add a ready-made swap surface rather than build quote management, asset selection, wallet interaction, and swap UI yourself.

The widget does not remove the user's wallet from the transaction flow. Wallet authorization remains part of the process.

CDN script or npm loader?

STON.fi offers two ways to obtain the same widget constructor.

Approach	Direct CDN script	npm loader
Package installation	Not required	Required
Build system	Not required	Usually used with one
Constructor access	`window.OmnistonWidget`	Returned by `load()`
Good fit	Static pages, simple sites, prototypes	Bundled JavaScript applications
Widget delivery	STON.fi CDN	STON.fi CDN through the loader

The distinction is mainly about how your application loads the code. The widget itself is distributed through the CDN rather than as a conventional fixed widget package. STON.fi explains that this model allows integrations to receive fixes and compatible updates within their selected major version.

If you already have a modern React, Vue, Svelte, or similar build process, the loader may fit the project architecture better. If you simply want a swap widget on a web page, the CDN script removes an unnecessary installation step.

Configure the assets shown to users

The minimal configuration is enough to get started, but you can also control which assets appear.

For example:

<script>
  const widget = new window.OmnistonWidget({
    tonconnect: {
      type: "standalone",
      options: {
        manifestUrl:
          "https://example.com/tonconnect-manifest.json",
      },
    },

    widget: {
      defaultBidAsset:
        "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c",

      defaultAskAsset:
        "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO",
    },
  });

  widget.mount(
    document.querySelector("#omniston-widget-container")
  );
</script>

STON.fi's current documentation uses the first address above for TON and the second as an example STON jetton address. For production integrations, verify asset addresses from authoritative sources rather than copying unfamiliar addresses from third-party examples.

You can also use customAssets to add token root addresses. If defaultAssets remains enabled, those custom assets supplement the built-in list.

If you set:

defaultAssets: false

then your custom list becomes the entire selector. Do not disable the default list without supplying assets, because the widget would have nothing to display.

Add referral fees only if you need them

The widget can also pass referral configuration.

For example:

widget: {
  referrerAddress: "YOUR_TON_WALLET_ADDRESS",
  referrerFeeBps: 50
}

The fee value uses basis points. 50 basis points equals 0.5%.

STON.fi currently documents a widget referral range from 1 to 100 basis points, corresponding to 0.01% to 1%. Both the referral address and fee should be configured when you intend to use this feature.

Referral settlement can differ depending on the liquidity source used by Omniston. That detail matters if you plan to build reporting or withdrawal tooling around referral revenue. The Omniston referral documentation should therefore be treated as the source of truth for the settlement mechanism rather than assuming every route pays referrals in exactly the same way.

For a simple embed whose only goal is swaps, you can leave referral settings out entirely.

Make the widget fit your interface

The container passed into mount() also acts as the scope for supported theme overrides.

For example:

<style>
  #omniston-widget-container {
    --background-color: #0f172a;
    --border-width: 1px;
    --text-primary-color: #f8fafc;
  }
</style>

Because these variables are attached to the widget container, they can be adjusted without applying the same values across the rest of your page.

You can also force the widget's dark styling through the container:

<div
  id="omniston-widget-container"
  class="dark"
></div>

STON.fi provides a visual widget constructor at:

https://widget.ston.fi/constructor

It can generate configuration and CSS values for a chosen appearance, token setup, and referral configuration. That can be faster than manually experimenting with every available CSS custom property.

Control mounting and catch errors

A production integration should account for more than the happy path.

The widget exposes lifecycle events including mount, unmount, and error.

widget.on("mount", ({ container }) => {
  console.log("Omniston Widget mounted", container);
});

widget.on("error", (error) => {
  console.error("Omniston Widget error", error);
});

widget.on("unmount", () => {
  console.log("Omniston Widget unmounted");
});

You can also remove the component:

widget.unmount();

The same widget instance can later be mounted again when needed. This is useful for interfaces that show swaps inside a modal, expandable panel, or page controlled by client-side navigation.

A few checks are worth making before deployment:

Confirm that https://widget.ston.fi/v0/index.js loads successfully.
Confirm that the widget container exists before calling mount().
Open your manifest URL directly and verify that it returns JSON.
Test the manifest from a clean browser session without authentication.
Check that its icon is publicly reachable.
Test wallet connection on both desktop and mobile flows.
Watch the widget's error event during development.

Manifest failures deserve particular attention. TON documentation notes that CORS restrictions, authentication, unreachable files, proxy challenges, invalid content, and inaccessible icons can prevent a wallet from accepting the manifest.

Practical takeaway: If your website already serves static HTML and JavaScript, start with the direct CDN script and standalone TON Connect mode. Verify the manifest independently first, then mount the default widget before adding custom assets, referral fees, or visual overrides. That sequence makes it much easier to tell whether a problem comes from wallet connectivity, widget loading, or your own configuration.

Frequently Asked Questions

Can I use the Omniston Widget without npm?

Yes. Load https://widget.ston.fi/v0/index.js with a normal <script> tag. The bundle exposes window.OmnistonWidget, which you can instantiate directly in browser JavaScript. This is the official zero-build integration path and is suitable for static pages as well as applications that can execute ordinary client-side scripts.

Do I need the Omniston SDK as well?

Not for a basic widget integration. The widget provides a ready-made interface around the swap workflow. The lower-level Omniston SDK is more appropriate when you want to design your own swap interface, quote logic, transaction flow, or deeper application behavior instead of embedding the existing widget.

Why does the URL contain `/v0/`?

It represents the widget's major version. STON.fi uses major-versioned CDN paths so an integration can receive compatible updates within the same major release. If a future release introduces breaking changes, it can use another path such as /v1/, allowing developers to adopt that major version deliberately.

Does the CDN method automatically connect the wallet?

The script loads the widget, but wallet connectivity still depends on TON Connect configuration. In standalone mode, you give the widget your manifest URL and it manages the TON Connect integration internally. The wallet still asks the person using the site to connect and authorize relevant actions.

Why does my TON Connect manifest fail even though the URL exists?

Reachability alone is not enough. The manifest must return valid JSON and be accessible without authentication or restrictive CORS rules. Proxy challenges can also interfere. Check the response itself, the iconUrl, HTTPS availability, and whether a wallet can fetch the file independently of your browser session.

Can I use my existing TON Connect instance?

Yes. Omniston Widget supports an integrated mode for applications that already manage TON Connect. STON.fi warns against creating multiple TON Connect instances in the same application because of SDK limitations. If your app already owns the connection state, reuse that instance instead of starting another one inside the widget.

Can I choose which tokens appear in the widget?

Yes. You can set default bid and ask assets, add token root addresses through customAssets, or disable the standard asset list and provide your own list. If you disable the default assets, make sure your custom list is populated or the asset selector will have nothing useful to show.

What is the simplest production setup for the Omniston Widget?

Use the major-versioned STON.fi CDN script, host a valid TON Connect manifest on your application domain, initialize the widget in standalone mode, mount it into an existing DOM element, and test wallet connectivity before adding optional configuration. Once the basic swap flow works, introduce theming, asset restrictions, lifecycle handling, or referral settings as separate changes.

Sources and Further Reading

STON.fi Omniston Widget - Official overview, CDN quick start, configuration areas, and widget constructor
STON.fi Omniston Widget Full Guide and Reference - Detailed CDN integration, TON Connect modes, configuration, styling, lifecycle events, and examples
STON.fi Omniston Widget GitHub Repository - Official widget repository with CDN distribution model and loading examples
STON.fi Omniston Overview - Official explanation of Omniston aggregation, routing, liquidity sources, and developer integration
STON.fi Omniston Referral Fees - Current referral parameters and settlement behavior across supported liquidity sources
TON Connect Get Started - Official requirements for manifests, wallet integration, hosting, and supported JavaScript approaches
TON Connect Core Concepts - Official manifest fields, connection concepts, and protocol requirements
TON Connect Troubleshooting - Official guidance for manifest errors, CORS problems, inaccessible icons, and hosting issues

How to Handle a Failed STON.fi Swap in an App

Ivan “Crypto Vazima” Zimanov — Mon, 07 Sep 2026 16:27:12 +0000

How to distinguish wallet rejection, submission failure, on-chain execution failure, and a STON.fi refund without showing users the wrong status.

A failed STON.fi swap should not be handled as one generic exception. In an app, the failure can happen while you simulate the trade, build the transaction, ask the wallet to sign, submit the message to TON, or execute the swap through STON.fi contracts. Those stages have different meanings and require different recovery actions.

The most important rule is simple: a resolved TonConnect sendTransaction() call does not prove that the entire swap succeeded. It gives your app the BoC of the broadcast external message. Your app still needs to determine what happened on-chain before presenting the swap as complete.

Start by separating the failure stages

A "Swap failed" toast hides too much information. Your application should first identify where execution stopped.

Stage	What happened	What your app should do
Simulation	No usable quote was produced	Keep funds untouched and request a fresh simulation
Transaction building	SDK or contract parameters could not be created	Log the technical error and do not open the wallet
Wallet approval	The request was rejected or could not be sent	Return to a retryable pre-submission state
Submitted	Wallet signed and broadcast the message	Do not call the swap successful yet
On-chain execution	TON or STON.fi processing failed	Inspect the transaction trace and possible refund
Swap completed	Requested output reached the intended receiver	Mark the operation successful

That distinction matters particularly on TON because contract interactions are asynchronous. A swap can involve several internal messages instead of one atomic execution step. TON documentation explicitly notes that different recipient contracts process messages independently, and failures can produce bounced messages under the appropriate conditions.

Your frontend therefore needs at least one state between wallet approved and swap succeeded.

Design the swap as a state machine

A small state machine is more reliable than a single isLoading flag.

type SwapStatus =
  | "idle"
  | "simulating"
  | "ready"
  | "awaiting_wallet"
  | "submitted"
  | "confirming"
  | "success"
  | "refunded"
  | "failed";

type SwapFailureStage =
  | "simulation"
  | "build"
  | "wallet"
  | "submission"
  | "execution";

The critical transition is:

ready
  -> awaiting_wallet
  -> submitted
  -> confirming
  -> success | refunded | failed

Do not replace it with:

ready
  -> awaiting_wallet
  -> success

TonConnect's sendTransaction() asks the connected wallet to sign and broadcast the transaction. Its response contains a base64 BoC of the broadcast external message. TON documentation recommends using that BoC to find and inspect what happened on-chain.

This lets your UI say something accurate such as "Transaction submitted" while confirmation is pending rather than prematurely displaying "Swap successful."

Prevent avoidable failures before the wallet opens

Good failure handling starts before try/catch.

STON.fi's current v2 integration guidance recommends an API-driven workflow: simulate the swap, use the router information returned by the API, construct the matching contracts through dexFactory(), then build the transaction parameters. Hardcoding a Router can make an integration incompatible with Router versions or types that the API actually selected.

Before opening TonConnect, verify:

the connected wallet is on the expected network
the offer amount is positive and converted using the token's actual decimals
the wallet has the offered asset
sufficient TON is available for execution costs when required
the quote is still current
minAskAmount comes from the simulation you intend to execute
the Router and pTON contracts correspond to the simulation result
the transaction has not already been submitted

STON.fi's React quickstart follows the same broad sequence: fetch assets, simulate the trade, derive contracts from Router information, build the swap parameters, and finally pass the resulting message to TonConnect.

For the TonConnect request itself, validUntil is a Unix timestamp in seconds. A typical request looks like this:

const response = await tonConnectUI.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 300,
  network: "-239",
  messages: [
    {
      address: swapParams.to.toString(),
      amount: swapParams.value.toString(),
      payload: swapParams.body?.toBoc().toString("base64"),
    },
  ],
});

Keeping quote creation and transaction submission close together also reduces the chance that market conditions change enough to violate the swap's minimum output.

Handle wallet errors without lying to the user

A wallet rejection is not an on-chain swap failure. No STON.fi troubleshooting is required if the transaction never reached the blockchain.

Keep the wallet layer separate:

try {
  setStatus("awaiting_wallet");

  const result = await tonConnectUI.sendTransaction(tx);

  setStatus("submitted");

  await confirmSwapOnChain(result.boc);
} catch (error) {
  setStatus("failed");
  handleWalletOrSubmissionError(error);
}

TonConnect defines errors for cases such as a rejected request, bad request, unsupported method, wrong network, or disconnected wallet. A user declining a transaction should normally produce something like "Transaction cancelled" rather than "STON.fi swap failed."

Also avoid automatic blind retries when submission is ambiguous. Current TonConnect UI documentation specifically warns that some connect-and-send flows can leave the app without a response even though the request may already have reached the wallet. Retrying silently could submit the operation twice.

Give the user an explicit retry action after you have checked whether a matching transaction already exists.

Verify the outcome on-chain after broadcast

Once TonConnect returns the BoC, move the operation to submitted or confirming.

Store enough context to investigate it:

const pendingSwap = {
  walletAddress,
  offerAddress,
  askAddress,
  offerUnits,
  minAskUnits,
  routerAddress: simulationResult.router.address,
  submittedAt: Date.now(),
  boc: result.boc,
};

Then use your TON data provider or indexer to locate the external message and follow the resulting trace.

Do not stop at the wallet transaction alone. TON ordinary transactions contain separate compute, action, and possible bounce phases. A contract can execute its compute phase but still encounter a later action failure. The aborted, compute result, action result, and bounce data help distinguish those cases.

For a swap, the application-level question is ultimately:

Did the intended output arrive, or did the STON.fi execution take another path such as a refund?

That is stronger evidence than simply observing that the initiating wallet transaction exists.

Read STON.fi refund signals correctly

STON.fi DEX v2 has explicit failure and refund mechanics. The Router payload includes a refund_address, and the contract API defines several operation codes that explain why swap execution could not continue.

Examples include:

swap_refund_reserve_err: insufficient liquidity for the swap
swap_refund_0_out: calculated output is zero
swap_refund_slippage: output is below the required minimum
swap_pool_locked: the pool is locked
transfer_bounce_low_gas: insufficient gas for the operation
transfer_bounce_invalid_pool: invalid pool configuration
transfer_bounce_tx_expired: the transaction expired at the Router

Slippage failure is especially important for applications. STON.fi's Pool specification states that a swap fails when the amount the user would receive is below min_out. That protects the user from accepting execution worse than the limit encoded in the transaction.

The recovery action is usually not "retry immediately with a larger slippage tolerance." Instead, fetch a new simulation, show the new expected output, and let the user make another decision.

There is another TON-specific complication with routed swaps. STON.fi documents that multi-contract transactions on TON are not atomic. If a cross-swap fails after an intermediate step, a complete rollback to the original asset is not always possible. The user can receive an intermediate routing token instead.

Your balance reconciliation logic should therefore check actual resulting assets instead of assuming every failed swap returns exactly the original token.

Following one failed swap from start to finish

Imagine your app is swapping Jetton A for Jetton B.

The app simulates the trade and receives a route with an expected output and minAskUnits. It uses the Router metadata from that simulation with dexFactory(), builds the STON.fi message, and opens TonConnect.

The user approves it.

At this point, your UI should display:

Swap submitted
Waiting for on-chain execution...

not:

Swap successful

While TON processes the message chain, the pool price changes. The amount available from the swap falls below the encoded minimum.

STON.fi can reject that execution condition as a slippage failure rather than deliver an output below the user's limit. Your monitoring layer detects the resulting execution or refund path. The app changes the status to refunded, refreshes balances, and explains what happened:

Swap was not executed because the available output
fell below your minimum. Funds were refunded.

Get a new quote before trying again.

Compare that with a wallet rejection:

Transaction cancelled.
No swap was submitted.

And with an unresolved submitted transaction:

Transaction submitted.
Confirmation is still pending.
Do not submit the same swap again yet.

Those messages describe three genuinely different states and prevent users from taking the wrong recovery action.

Practical takeaway: treat the STON.fi transaction builder, TonConnect, TON execution, and the final swap outcome as separate checkpoints. Simulate immediately before submission, build from current Router metadata, store the returned BoC, verify the resulting trace, refresh balances, and only display success after the requested asset outcome has been confirmed.

Frequently Asked Questions

Does `sendTransaction()` succeeding mean my STON.fi swap succeeded?

No. It means the wallet successfully returned the BoC for the transaction it signed and broadcast. Contract execution still occurs on TON. Your app should move to a submitted or confirming state and inspect the resulting on-chain transaction flow before declaring the swap successful.

Should I automatically retry every failed swap?

No. First determine whether the original transaction was never submitted, definitively failed, was refunded, or has an unknown outcome. Automatic retries are risky when submission status is uncertain because the first transaction may still have reached the network. A user-triggered retry after reconciliation is safer.

Why can a swap fail after the wallet approved it?

Wallet approval only authorizes and broadcasts the initial message. TON contracts then process the operation through their execution phases and internal messages. STON.fi can encounter conditions such as insufficient output, expired execution, insufficient gas, a locked pool, or another contract-level failure after approval.

What should I do when a swap fails because of slippage?

Request a new simulation and present the updated quote. Do not silently increase the user's slippage tolerance. In STON.fi, the minimum output is an execution constraint, and the swap can be refunded when calculated output falls below that minimum. Changing the tolerance changes the trade the user is agreeing to.

Can a failed STON.fi swap return a different token?

It can in a routed cross-swap. STON.fi explains that TON multi-contract transactions are not fully atomic, so if a routed swap fails after an intermediate conversion, the user may receive an intermediate token rather than a complete rollback into the original asset. Your app should reconcile actual balances after failure.

Should I hardcode the STON.fi Router address in my app?

For current production integrations, STON.fi recommends an API-driven approach. The simulation provides Router information that can be passed into dexFactory() so the SDK selects the appropriate contracts. This also reduces problems caused by Router versions or types changing while your application continues using an old hardcoded configuration.

What is the safest flow for handling a failed STON.fi swap in an app?

Simulate first, build the transaction from current Router metadata, request the wallet signature, mark the operation as submitted when TonConnect returns, verify the on-chain result, detect success or refund, refresh balances, and only then show the final status. If the outcome is uncertain, prevent blind retries until your app has reconciled the transaction.

Sources and Further Reading

STON.fi Swap Guide (React) - official example covering simulation, dynamic Router selection, SDK transaction building, and TonConnect submission
STON.fi Swap v2 SDK documentation - current API-driven workflow for building production swaps from simulation and Router metadata
STON.fi DEX v2 smart contracts - overview of v2 swap mechanics, refunds, deadlines, and production SDK guidance
STON.fi Router v2 - Router swap payload fields including minimum output, refund address, receiver, and execution deadline
STON.fi DEX v2 Op Codes - reference for successful swaps, slippage refunds, liquidity errors, low gas, expired transactions, and other execution outcomes
STON.fi Swap Examples - official diagrams and explanations for simple swaps, routed swaps, and refund behavior
TON Connect Send Transaction - official specification of transaction submission, returned BoC, request expiration, network selection, and wallet errors
TON Ordinary Transactions and Execution Phases - official TON documentation explaining compute, action, bounce, aborted transactions, and asynchronous message execution

How to Estimate Gas for a STON.fi Transaction

Ivan “Crypto Vazima” Zimanov — Sat, 05 Sep 2026 10:44:22 +0000

Estimating gas for a STON.fi transaction is less about guessing a fixed fee and more about understanding the TON message path your operation will create. A swap can involve your wallet, a jetton wallet, a STON.fi Router, a liquidity pool, and additional token transfers before the result reaches you.

For most users and integrations, the safest approach is simple: simulate the exact STON.fi operation, use the gas parameters returned for that route, let the current SDK construct the transaction, and keep enough TON in the wallet to cover the attached execution budget.

The harder part is understanding what those numbers actually mean.

Why TON gas is different from the Ethereum mental model

Developers coming from Ethereum often think about transaction cost as roughly:

gas used × gas price

TON works differently at the transaction level. Contract execution still consumes gas, but the amount ultimately spent by a transaction can include several categories of fees.

A TON transaction can pass through storage, compute, action, and sometimes bounce phases. The network may charge for contract computation, persistent storage, and forwarding messages to other contracts. A multi-contract DeFi operation can therefore create several transactions rather than one isolated smart contract call.

For a STON.fi swap, that distinction matters because the initial wallet message may trigger a sequence such as:

Your wallet sends the operation.
A jetton or pTON contract processes the asset transfer.
The STON.fi Router receives the swap request.
The Router communicates with the appropriate pool.
Contracts send the resulting asset toward the destination wallet.
Remaining TON intended for excesses may be returned according to the transaction flow.

Each step can require computation or another internal message.

So when an interface says a transaction needs a certain amount of TON for "gas," it often refers to an execution budget attached to the transaction, not simply the exact compute fee that validators will eventually keep.

What actually contributes to a TON transaction cost

TON documentation separates several fee components. Understanding them makes STON.fi gas estimates much easier to interpret.

Component	What it covers	Why it matters for STON.fi
Compute fee	TVM execution of smart contract code	Routers, pools, wallets, and related contracts perform computation
Forward fee	Delivery of internal messages	A swap normally moves messages between multiple contracts
Storage fee	Persistent blockchain storage	Contracts can owe storage fees when they are processed
Action-related fees	Actions created after successful computation	Token transfers and subsequent internal messages can add cost
Attached TON budget	TON carried with a message to fund downstream execution	A STON.fi operation needs enough value to complete its message chain

TON processes fees at different stages of execution. Official documentation lists import, storage, gas, action, and forwarding costs in the transaction lifecycle.

This is why the phrase "gas fee" can be misleading in a DEX interface. The amount attached to a transaction may be larger than the amount ultimately consumed.

Budget is not the same as final cost

Suppose an integration prepares a transaction with a conservative TON execution budget. That does not automatically mean the whole budget becomes a fee.

Part of the attached value may fund downstream messages, while unused value can be handled as excess according to the contracts and message modes involved. TON's message model explicitly allows value to move between contracts while fees are deducted along the route.

For this reason, two numbers are useful to distinguish:

required transaction budget, which needs to be available for the operation to run safely
actual network consumption, which is what the completed transaction trace ultimately spent

The first number matters before signing. The second becomes fully observable after execution.

Start with the exact STON.fi operation

There is no single universal gas number that should be hardcoded for every STON.fi transaction.

A TON to jetton swap does not have exactly the same message flow as a jetton to jetton swap. Liquidity provision is different again. Contract versions, token behavior, optional payloads, and the route chosen for the transaction can also affect execution.

STON.fi currently recommends an API-driven workflow for DEX v2 integrations. The application first simulates the swap, obtains the router and transaction information associated with that simulation, and then uses the correct SDK contracts for that router.

That makes the route itself the starting point for gas estimation.

A practical rule is:

Estimate the transaction you are about to send, not an abstract "STON.fi swap."

Consider two swaps for the same monetary value:

TON to a jetton
one jetton to another jetton

Their trade value could be identical, but the token transfer and message sequences can differ. Gas therefore follows execution structure more closely than trade value.

A 10 TON swap does not automatically require ten times as much gas as a 1 TON swap. Increasing the token amount usually does not multiply the amount of smart contract computation by the same factor.

Use STON.fi swap simulation as the primary estimate

For a current integration, the most useful first step is STON.fi's swap simulation endpoint.

The DEX API exposes POST /v1/swap/simulate. STON.fi describes the endpoint as calculating expected swap output, fees, and gas costs before execution.

The @ston-fi/api package exposes the same workflow through simulateSwap().

A simplified example looks like this:

import { StonApiClient } from "@ston-fi/api";

const apiClient = new StonApiClient();

const simulation = await apiClient.simulateSwap({
  offerAddress: "<offer asset>",
  askAddress: "<ask asset>",
  offerUnits: "<amount in blockchain units>",
  slippageTolerance: "0.005",
});

console.log(simulation.gasParams);

The STON.fi API added a gasParams structure to swap simulation responses. Its documented fields include:

gasBudget: an optional TON gas budget for the transaction
forwardGas: the TON amount intended for forwarding
estimatedGasConsumption: estimated gas consumption

These fields were introduced specifically so an integration can work from a route-specific estimate rather than relying only on fixed assumptions.

How to interpret the three fields

gasBudget is the practical budget signal. It tells the integration how much TON should be available for the execution requirements associated with the simulated operation.

forwardGas relates to the TON value that must travel farther through the operation's message chain.

estimatedGasConsumption is useful for understanding expected consumption. It should not automatically be treated as an interchangeable replacement for the amount that needs to be attached to the originating transaction.

In other words, avoid taking estimatedGasConsumption, adding an arbitrary percentage, and assuming that number can replace the transaction parameters expected by the STON.fi contracts.

The API and SDK know more about the route than that simplified calculation does.

Let the SDK build the transaction budget

After simulation, STON.fi's current v2 documentation recommends taking the router object returned by the API and passing it to dexFactory(). This selects the contract implementation that matches the router used by the simulated swap.

Conceptually, the flow becomes:

Swap request
    |
    v
STON.fi simulation
    |
    +--> expected output
    +--> minimum output
    +--> router information
    +--> gas parameters
    |
    v
Correct SDK contracts
    |
    v
Transaction parameters
    |
    v
Wallet review and signature

The value sent with the transaction should come from the transaction construction logic for that exact operation rather than from a stale constant copied from another example.

This is especially important because STON.fi has multiple DEX contract generations. The current SDK documentation identifies v2 as the latest major architecture while v1 remains supported for backward compatibility. The SDK has also received changes related to gas efficiency and contract routing.

Be careful when TON itself is the asset being swapped

When the input asset is TON, the amount leaving the wallet can include both economic value and execution funding.

Imagine that you want to swap 5 TON into a jetton. The wallet may need to send more than exactly 5 TON because the transaction also needs enough TON to execute the operation.

That does not mean the difference is automatically the final network fee.

By contrast, when swapping a jetton for another jetton, the jetton amount is transferred through its token contracts while a separate amount of TON is attached to finance execution.

This distinction is one of the easiest places to misread a wallet confirmation screen.

When should you calculate fees yourself?

For a normal STON.fi integration, starting from the official simulation and SDK is usually more robust than reconstructing every fee component manually.

Manual estimation becomes useful when you are building infrastructure, auditing contract behavior, testing custom payloads, or trying to understand why actual execution differs from your expected budget.

TON provides tools for both approaches.

Its API includes an estimateFee method that accepts a destination address and serialized message body and returns categories including gas, storage, and forwarding fees. It can be used as an additional check once you have a concrete message to evaluate.

At a lower level, TON documentation explains how contract developers can estimate:

compute gas from known gas usage
forward fees from message size
storage requirements
fees across a multi-contract transaction trace

The important detail is that a DeFi operation is a system of messages. If contract A sends to contract B, which sends to contract C, estimating only the first compute phase does not describe the whole operation. TON's own gas estimation guidance explicitly treats multi-contract traces as value flows that need enough attached TON for subsequent execution.

For most STON.fi applications, this gives you a useful hierarchy:

STON.fi simulation for route-specific gas parameters.
STON.fi SDK transaction construction for the value and payload that should actually be sent.
TON fee estimation tools when you need a lower-level validation of the constructed message.
Post-transaction trace analysis when you want to compare the estimate with real execution.

How to validate your estimate after the swap

A good gas estimation system should learn from completed transactions instead of treating every estimate as an unquestionable constant.

After submitting a test transaction, inspect its trace.

Check:

whether every expected contract action completed
how much TON was originally attached
the actual transaction fees across the trace
whether excess TON was returned
whether any message bounced
whether a downstream action ran out of funds
whether a custom payload introduced additional forwarding work

STON.fi provides endpoints for investigating swap status and transaction action trees, which can help connect the originating transaction to the resulting protocol actions.

TON explorers and APIs can then expose the underlying blockchain transactions and fee components.

This gives developers a useful feedback loop:

simulate
   |
build
   |
send
   |
inspect trace
   |
compare estimate with actual execution
   |
adjust only when there is evidence to do so

Do not optimize by cutting the attached TON budget until a transaction barely succeeds. A small saving in temporarily attached TON is rarely worth making the operation fragile.

Common mistakes to avoid

Hardcoding an old recommended gas value. STON.fi has multiple contract versions, and execution patterns can change. Use current simulation data whenever possible.

Treating the attached TON amount as the final fee. The amount sent to finance the operation and the amount eventually consumed are different concepts.

Looking only at compute gas. Forwarding and other transaction phases also matter on TON.

Ignoring the route. Different asset types and contract paths can produce different message flows.

Removing safety budget aggressively. A transaction that works in one test does not prove that a lower budget is safe for every equivalent-looking operation.

Using a v1 example as a universal v2 constant. Older STON.fi documentation contains recommended fixed gas values for specific v1 swap types, but those values describe that implementation. They should not be blindly generalized to current v2 routing.

The practical takeaway is straightforward: simulate the exact swap shortly before execution, use the router and gas information returned by STON.fi, build the transaction through the matching SDK contracts, and inspect the final wallet transaction before signing. If you are developing an integration, compare the attached budget with actual transaction traces during testing rather than replacing route-specific values with one permanent gas constant.

Frequently Asked Questions

Does every STON.fi swap use the same amount of gas?

No. The required execution budget depends on the operation and its message path. TON to jetton, jetton to jetton, and jetton to TON swaps can involve different transfers and forwarding steps. Contract versions and additional payloads can matter as well. Use the estimate associated with the actual transaction rather than assuming that all STON.fi swaps have one fixed cost.

Does a larger swap require proportionally more gas?

Usually not simply because the token amount is larger. Gas primarily reflects the computation and messaging required to execute an operation. A larger trade can affect pricing, price impact, and minimum output, but changing 1 TON to 10 TON does not by itself imply ten times the computational work.

Is the TON attached for gas the same as the final transaction fee?

Not necessarily. Attached TON is a budget available to fund execution and downstream messages. Actual network fees are deducted as transactions execute. Depending on the contract flow, some value can continue through subsequent messages or be handled as excess rather than being consumed entirely as a fee.

What happens if too little TON is attached?

A later step in the transaction chain may not have enough value to pay for computation or forwarding. Depending on where and how the failure occurs, the operation can bounce or fail to complete as intended. Multi-contract TON systems therefore need enough value at the beginning to finance the relevant downstream trace.

Can I use TON's `estimateFee` API for a STON.fi swap?

Yes, it can be useful as a lower-level check once you have constructed the relevant message. TON's API returns estimates for categories such as gas, storage, and forwarding fees. For a STON.fi integration, however, it is better treated as complementary to STON.fi's route-aware simulation and SDK rather than a reason to ignore protocol-specific gas parameters.

What is `forwardGas` in a STON.fi simulation?

It represents TON intended to support forwarding farther through the transaction flow. STON.fi swaps can create multiple internal messages, so enough value must move with the operation for later contracts to continue processing it. It should not be confused with the final amount of network fees paid by the wallet.

Should developers hardcode STON.fi gas values?

Avoid hardcoding a universal value when current simulation data is available. Historical STON.fi SDK versions published recommended constants for particular swap types, but current integrations have access to route-specific gas information through the API. Hardcoded values can become inaccurate as contract versions, routes, or transaction structures change.

What is the safest way to estimate gas before a STON.fi transaction?

Simulate the exact operation through the current STON.fi API, read its gas parameters, use the returned router with the matching STON.fi SDK contracts, and let that workflow construct the transaction you present to the wallet. During development, execute representative test transactions and compare the estimates against their completed TON traces.

Sources and Further Reading

STON.fi DEX API Reference - Covers swap simulation, transaction inspection, and DEX API endpoints
STON.fi DEX v2 Swap Guide - Describes the current API-driven v2 swap workflow and router selection
STON.fi SDK Documentation - Covers the supported SDK generations and current v2 integration tooling
STON.fi API Changelog - Documents the addition of gasBudget, forwardGas, and estimatedGasConsumption to swap simulation responses
STON.fi SDK Changelog - Provides contract version, routing, and SDK implementation changes relevant to current integrations
TON Gas Estimation Guide - Explains compute, forward, storage, and multi-contract fee estimation on TON
TON Transaction Execution Phases - Explains storage, compute, action, bounce, and the sequence in which fees are charged
TON Estimate Fee API - Describes the network API for estimating storage, gas, and forwarding fees for a message
TON Message Sending Modes - Explains how message value, gas fees, and forwarding fees interact during internal message delivery

How to Calculate Minimum Received for a STON.fi Swap

Ivan “Crypto Vazima” Zimanov — Thu, 03 Sep 2026 05:41:23 +0000

Understanding the number that protects your swap when the market moves between quote and execution.

When STON.fi shows a swap quote, the amount you expect to receive and the minimum amount you are willing to receive are not necessarily the same number. The second value is your protection against unfavorable price movement while the transaction is being processed.

The basic calculation is simple:

Minimum received = expected output × (1 - slippage tolerance)

If a swap is expected to return 1,000 tokens and the allowed slippage is 1%, the minimum received is approximately 990 tokens.

The arithmetic takes seconds. The more important part is understanding which number should be used as the expected output, what slippage actually protects you from, and why price impact should not be subtracted twice.

The formula behind minimum received

Suppose STON.fi calculates that your swap should currently return 2,500 USDT.

If your slippage tolerance is 1%, convert the percentage into decimal form:

1% = 0.01

Then calculate:

2,500 × (1 - 0.01) = 2,475

Your minimum received is therefore approximately 2,475 USDT.

At 0.5% tolerance:

2,500 × (1 - 0.005) = 2,487.5 USDT

At 2% tolerance:

2,500 × (1 - 0.02) = 2,450 USDT

The relationship is straightforward: increasing the tolerated slippage lowers the minimum amount that the transaction is allowed to deliver.

A useful mental model is to treat the quote as the current target and minimum received as the lowest acceptable outcome.

Quick reference

For an expected output of 1,000 tokens:

0.1% slippage gives a minimum of about 999 tokens
0.5% slippage gives a minimum of about 995 tokens
1% slippage gives a minimum of about 990 tokens
2% slippage gives a minimum of about 980 tokens
5% slippage gives a minimum of about 950 tokens

These examples illustrate the calculation rather than recommending a particular tolerance. The appropriate level depends on liquidity, volatility, trade size, route conditions, and how much execution uncertainty you are willing to accept.

Expected output and minimum received are different numbers

A swap interface has to answer two separate questions.

First: What should this trade return under current conditions?

Second: How bad can the execution become before the transaction should no longer proceed?

Those questions produce different values.

Quote element	What it tells you	What affects it
Expected output	Estimated tokens you should receive now	Pool reserves, route, fees, trade size, current price
Price impact	How much your own trade changes the execution price	Trade size relative to available liquidity
Slippage tolerance	Maximum additional price movement you accept	Your execution protection setting
Minimum received	Lowest output permitted by the swap	Expected output and slippage tolerance
Network fee	Cost of processing messages on TON	TON network and transaction structure

STON.fi's own educational material distinguishes price impact from slippage. Price impact is caused by the trade itself, while slippage concerns changes between the price expected and the price available when execution occurs.

That distinction prevents one of the most common calculation mistakes.

Do not subtract price impact twice

Imagine you are swapping enough TON to move the price inside the relevant liquidity pool.

Before you confirm, the quote already reflects the execution conditions produced by that order. If the trade size causes significant price impact, the estimated output will already be worse than the simple spot-price calculation you might have made before opening the swap interface.

Now suppose the resulting quote is 5,000 tokens and you allow 1% slippage.

The calculation is:

5,000 × 0.99 = 4,950 tokens

You should not first reduce 5,000 by the displayed price impact and then reduce the result again by 1%.

Doing that would count the effect of your trade twice.

The sequence is better understood like this:

STON.fi calculates the swap under current liquidity conditions.
The resulting quote incorporates the execution effect of the trade.
Slippage protection creates a floor below that quote.
The transaction can proceed only while the resulting output satisfies that floor.

This is why minimum received is calculated from the quoted output rather than from a theoretical external market price.

Why can the quote move before your swap executes?

A DEX quote describes the state of liquidity when it is calculated. Blockchain execution happens afterward.

During that interval, other traders may interact with the same liquidity. Pool reserves can change, the relative price of the assets can move, or the conditions along a route can become less favorable.

Consider a quote for 800 tokens.

At the moment you see it:

Expected output = 800

With 1% tolerance:

Minimum received = 792

If conditions move slightly and the swap would return 797 tokens, the output remains above your 792-token floor.

If conditions deteriorate enough that the swap would return only 788 tokens, the protection becomes relevant.

A slippage limit therefore does not promise that you will receive exactly the quoted amount. It defines the point at which a worse outcome is no longer acceptable.

This trade-off also explains why extremely tight tolerances can increase the chance of failed execution, while very loose tolerances permit a wider range of unfavorable outcomes.

How STON.fi enforces minimum received

The calculation becomes more meaningful when you look at how STON.fi represents it at the contract level.

In STON.fi DEX v2, the Router passes a min_out value as part of the swap data. The Pool documentation describes min_out as the minimum required amount of tokens to receive and states that a swap fails if the amount due to the user would be below this value.

So minimum received is not merely an informational estimate displayed by an interface.

It becomes a condition attached to the swap.

Conceptually, the flow is:

Quote → slippage protection → minimum output → contract execution

Suppose the current expected output is 12,000 tokens and your tolerance produces an 11,880-token minimum.

If execution still supports 11,950 tokens, the condition is satisfied.

If it supports only 11,850, the minimum-output condition is not satisfied.

For a simple swap, this prevents the trade from deliberately accepting an arbitrarily worse output just because conditions changed after the quote appeared.

STON.fi's v2 Pool documentation explicitly connects the swap's success condition to min_out.

Calculating minimum received from a STON.fi quote

For someone reviewing a swap manually, the process only requires the quoted output and the applicable slippage tolerance.

1. Start with the current expected output

Use the amount generated by the swap quote rather than multiplying the amount you are selling by a price copied from another exchange.

For example:

STON.fi expected output: 3,250 tokens

That quote is the useful starting point because it reflects the actual swap being considered.

2. Convert slippage into decimal form

For example:

0.5% becomes 0.005
1% becomes 0.01
1.5% becomes 0.015
2% becomes 0.02

3. Subtract the tolerance from 1

For 0.5%:

1 - 0.005 = 0.995

4. Multiply the quote by the result

3,250 × 0.995 = 3,233.75

The theoretical minimum received is therefore 3,233.75 tokens.

The actual transaction uses blockchain units and token-specific decimals, so an integration should not casually reproduce UI arithmetic with floating-point numbers and then invent its own rounding rules.

That is where STON.fi's simulation tools become useful.

For developers, use `minAskUnits` from the simulation

STON.fi's current DEX v2 SDK documentation recommends an API-driven workflow for production swaps.

The example first calls simulateSwap() with the offered asset, requested asset, amount, and slippageTolerance. The resulting simulation contains values including offerUnits, minAskUnits, asset addresses, and Router metadata. STON.fi specifically instructs developers to reuse the simulation values when constructing the actual transaction so the signed transaction matches the simulated swap.

A simplified example looks like this:

const simulationResult = await apiClient.simulateSwap({
  offerAddress: "ton",
  askAddress: tokenAddress,
  offerUnits,
  slippageTolerance: "0.01",
});

const minimumOutput = simulationResult.minAskUnits;

Here, "0.01" represents a 1% tolerance.

For a production integration, minAskUnits is more important than a manually formatted number such as 123.45. Smart contracts work with the asset's base units, and different tokens can use different decimal precision.

Practical developer checklist

Before building the transaction:

simulate the current swap rather than relying on an old quote
pass the intended slippage tolerance into the simulation
use the simulation's minAskUnits
preserve the asset addresses and Router information returned by the simulation
avoid converting the minimum into floating-point values and rebuilding it unnecessarily
request a fresh simulation if the quote has become stale

STON.fi's API also provides swap simulation specifically to calculate swap results before execution, including expected swap information, fees, and gas-related data.

What minimum received does not include

Minimum received is easy to misuse when every cost associated with a swap is treated as "slippage."

They are not the same thing.

Trading economics affect the quote. Pool pricing, liquidity, trade size, and relevant trading fees influence the output calculated for the swap.

Slippage protection applies to movement away from that quote. It defines how much additional deterioration can be tolerated before the minimum-output condition is violated.

TON network costs are separate. Gas and message-processing costs exist because TON must execute and forward blockchain messages. TON documentation describes contract execution and forward fees as separate blockchain costs.

If STON.fi quotes 1,000 units of an asset and your minimum received is 990, you should not subtract the TON network fee from 990 as though the fee were another percentage of the destination token.

Keeping those layers separate makes the calculation much easier to audit.

A practical STON.fi example

Imagine you want to swap TON into another token and STON.fi currently quotes:

Expected output: 10,000 ABC

Assume the swap uses a 1% slippage tolerance.

The manual calculation is:

10,000 × (1 - 0.01)

10,000 × 0.99 = 9,900 ABC

So:

Expected output: 10,000 ABC
Slippage tolerance: 1%
Minimum received: approximately 9,900 ABC

Now imagine liquidity changes while your transaction is moving through the execution process.

If the updated swap result is 9,970 ABC, it is still above the minimum.

If it falls to 9,910 ABC, it is still above the minimum.

If it falls below the contract's required min_out, the minimum-output protection is triggered rather than simply accepting the worse exchange result.

For developers, the same logic should normally be represented by the fresh minAskUnits returned by STON.fi's swap simulation rather than a hand-calculated decimal value.

Practical takeaway: when reviewing a STON.fi swap, start from the current quoted output, distinguish price impact from slippage, and treat minimum received as your execution floor. If you are integrating STON.fi programmatically, let the current swap simulation produce minAskUnits and carry that value into the transaction instead of reconstructing it from an older or rounded quote.

Frequently Asked Questions

What is minimum received in a crypto swap?

Minimum received is the lowest amount of the destination asset that your swap is allowed to deliver under its slippage protection. If the current quote is 1,000 tokens and a 1% tolerance is applied, the approximate minimum is 990. It is a protective floor, not a prediction that you will necessarily receive exactly that amount.

How do I calculate minimum received from slippage?

Multiply the expected output by one minus the slippage tolerance expressed as a decimal. For example, with an expected output of 4,000 tokens and 0.5% slippage, calculate 4,000 × 0.995, which gives 3,980 tokens. Blockchain implementations may apply base-unit precision and rounding, so integrations should use protocol-provided values where available.

Is price impact included in minimum received?

Price impact should first affect the expected swap output because it comes from executing your trade against available liquidity. Slippage protection is then applied relative to that quote. Subtracting displayed price impact from the quote again before calculating minimum received can therefore double-count the same effect.

Does higher slippage increase minimum received?

No. Higher slippage tolerance lowers the minimum received because you are allowing the transaction to accept a wider deterioration from the original quote. A 2% tolerance creates a lower floor than a 0.5% tolerance. That can make execution less restrictive, but it also allows a less favorable result.

What is `min_out` on STON.fi?

min_out is the contract-level minimum output requirement used in STON.fi swap execution. STON.fi's DEX v2 Pool documentation states that the swap fails if the amount to be received would be below this minimum. It is the on-chain expression of the minimum-output protection discussed in the swap quote.

What is `minAskUnits` in the STON.fi API?

minAskUnits is the minimum requested output returned as part of STON.fi's swap simulation workflow. The DEX v2 SDK documentation shows it in simulationResult together with the offered amount, asset addresses, and Router metadata. Production integrations should reuse these simulation values when building the corresponding swap transaction.

Should I calculate STON.fi minimum received manually before every swap?

Manual calculation is useful for understanding and checking the number shown by a quote. For actual execution, especially in a software integration, use a fresh STON.fi simulation and its minAskUnits. That avoids problems with token decimals, stale quotes, floating-point calculations, and inconsistent rounding between your application and the swap transaction.

What should I check before confirming a STON.fi swap?

Check the asset pair, input amount, expected output, price impact, minimum received, and network costs. Make sure you understand that expected output is the current estimate while minimum received is the lower execution boundary. If the quote looks unexpectedly poor, review liquidity and trade size rather than simply increasing the tolerated slippage.

Sources and Further Reading

STON.fi DEX v2 Swap SDK - Official production swap workflow, swap simulation, slippageTolerance, minAskUnits, and Router handling
STON.fi DEX v2 Pool - Official smart contract documentation for min_out and the minimum-output swap condition
STON.fi DEX v2 Router - Official Router swap structure and the min_out field passed during swap execution
STON.fi DEX API Reference - Official API overview covering swap simulation before execution
STON.fi DEX v2 Smart Contracts - Official overview of the current v2 smart contract architecture and swap functionality
STON.fi Blog, All You Need to Know About Price Impact on Decentralized Exchanges - Explanation of price impact, slippage, and their distinction in a STON.fi swap context
TON Documentation, How to Estimate Gas Usage in TON Contracts - Official explanation of TON gas and forward-fee mechanics

How to Build a STON.fi Pool Explorer

Ivan “Crypto Vazima” Zimanov — Sun, 30 Aug 2026 17:33:03 +0000

A practical TypeScript guide to discovering pools, joining token metadata, displaying meaningful metrics, handling multiple AMM types, and verifying pool state on TON.

A STON.fi pool explorer is essentially a read-only DeFi application that turns raw pool contracts and indexed protocol data into something people can understand. At minimum, it should answer a few questions quickly: which assets are in a pool, how much liquidity is there, what fees apply, how active is the pool, which STON.fi contract version powers it, and where can the underlying addresses be verified?

The good news is that you do not need to index TON from scratch. STON.fi exposes a public REST API for pools, assets, routers, statistics, simulations, and other protocol data. You can use that API as the discovery layer, then optionally read the pool contract directly when you want stronger on-chain verification.

This guide builds that architecture step by step.

What a useful STON.fi pool explorer should show

A pool explorer becomes useful when it combines several kinds of information that exist separately at the protocol level.

For each pool, a practical interface should expose:

token names, symbols, images, decimals, and contract addresses
both pool reserves in readable token units
LP fee and other relevant fee information
24-hour trading volume
recent APY values when available
LP token supply and its USD value
pool contract and router addresses
router version and pool type
warnings for deprecated or problematic assets
pool-specific parameters for specialized AMMs

STON.fi's API already exposes much of this data. The main engineering problem is joining it correctly.

A pool response identifies its assets through token0_address and token1_address, while token metadata lives in the asset dataset. The pool also contains router_address, which you can join with the router dataset to identify the contract version and router type.

A simple data flow therefore looks like this:

Load pools from /v1/pools.
Load assets from /v1/assets.
Load routers from /v1/routers.
Index assets and routers by address.
Enrich every pool with token metadata and router information.
Normalize raw blockchain amounts using token decimals.
Render searchable pool cards and detailed pool pages.

That is enough for a surprisingly capable first version.

Model the data around pools, assets, and routers

It is tempting to treat the pool response as a complete object, but keeping the three protocol concepts separate makes the application easier to maintain.

The current STON.fi pool schema includes fields such as:

address
token0_address
token1_address
reserve0
reserve1
lp_fee
protocol_fee
ref_fee
router_address
lp_total_supply
lp_total_supply_usd
volume_24h_usd
apy_1d
apy_7d
apy_30d
deprecated
amp
rate
w0
tags

The asset API provides the presentation layer around those addresses, including display_name, symbol, decimals, image_url, pricing fields, tags, and status flags.

The router endpoint adds another important dimension. Routers expose their major and minor contract versions as well as a router_type. Current router types can include Constant Product, Stable Swap, Weighted Stable Swap, Weighted Constant Product, and Constant Sum variants.

That distinction matters because your explorer should not assume that every pool behaves like a basic x * y = k AMM.

A useful mental model is:

Layer	What your explorer gets from it
Pool	reserves, fees, LP data, volume, APY, pool parameters
Asset	symbol, name, decimals, image, pricing metadata, safety flags
Router	DEX version, router type, contract context
TON contract	direct verification of current on-chain state

Keep these layers separate internally even if the UI eventually merges them into a single pool card.

Fetch and join the STON.fi API data

You can use the official @ston-fi/api TypeScript client, but raw HTTP requests make the underlying explorer architecture especially easy to see.

Start with a small loader:

const STON_API = "https://api.ston.fi";

async function getJson<T>(path: string): Promise<T> {
  const response = await fetch(`${STON_API}${path}`);

  if (!response.ok) {
    throw new Error(
      `STON.fi API returned ${response.status} for ${path}`
    );
  }

  return response.json() as Promise<T>;
}

type Pool = {
  address: string;
  token0_address: string;
  token1_address: string;
  reserve0: string;
  reserve1: string;
  router_address: string;
  lp_fee: string;
  protocol_fee: string;
  ref_fee: string | null;
  lp_total_supply: string;
  lp_total_supply_usd: string | null;
  volume_24h_usd: string | null;
  apy_1d: string | null;
  apy_7d: string | null;
  apy_30d: string | null;
  deprecated: boolean;
  amp: string | null;
  rate: string | null;
  w0: string | null;
  tags: string[];
};

type Asset = {
  contract_address: string;
  display_name: string | null;
  symbol: string;
  decimals: number;
  image_url: string | null;
  deprecated: boolean;
  blacklisted: boolean;
  kind: string;
  tags: string[];
};

type Router = {
  address: string;
  major_version: number;
  minor_version: number;
  router_type: string;
};

Then retrieve the datasets together:

async function loadExplorerData() {
  const [poolData, assetData, routerData] = await Promise.all([
    getJson<{ pool_list: Pool[] }>("/v1/pools?dex_v2=true"),
    getJson<{ asset_list: Asset[] }>("/v1/assets"),
    getJson<{ router_list: Router[] }>("/v1/routers?dex_v2=true"),
  ]);

  const assets = new Map(
    assetData.asset_list.map((asset) => [
      asset.contract_address,
      asset,
    ])
  );

  const routers = new Map(
    routerData.router_list.map((router) => [
      router.address,
      router,
    ])
  );

  return poolData.pool_list.map((pool) => ({
    ...pool,
    asset0: assets.get(pool.token0_address),
    asset1: assets.get(pool.token1_address),
    router: routers.get(pool.router_address),
  }));
}

You now have one object that the frontend can render without repeatedly searching arrays.

For a prototype, loading the complete datasets is convenient. Once your explorer becomes larger, investigate /v1/pools/query, which supports search terms, sorting, limits, and other query conditions. Server-side filtering can reduce unnecessary data transfer.

Turn raw blockchain values into readable metrics

The next problem is units.

STON.fi reserves are returned in basic token units. A jetton with six decimals and a raw reserve of "2500000000" represents 2,500 tokens, not 2.5 billion tokens.

You therefore need the decimals from the asset metadata before displaying reserves.

A BigInt-safe formatter can look like this:

function formatUnits(raw: string, decimals: number): string {
  const value = BigInt(raw);
  const base = 10n ** BigInt(decimals);

  const whole = value / base;
  const fraction = value % base;

  if (fraction === 0n) {
    return whole.toString();
  }

  const fractionString = fraction
    .toString()
    .padStart(decimals, "0")
    .replace(/0+$/, "");

  return `${whole}.${fractionString}`;
}

Then:

const reserve0 = pool.asset0
  ? formatUnits(pool.reserve0, pool.asset0.decimals)
  : pool.reserve0;

const reserve1 = pool.asset1
  ? formatUnits(pool.reserve1, pool.asset1.decimals)
  : pool.reserve1;

Fees deserve similar care. STON.fi pool contract documentation defines fee values against a divider of 10,000. A fee value of 100, for example, corresponds to 1%.

For display:

function formatFee(value: string): string {
  return `${Number(value) / 100}%`;
}

For sorting and presentation, converting USD metrics to JavaScript numbers is usually acceptable:

const volume24h = pool.volume_24h_usd
  ? Number(pool.volume_24h_usd)
  : null;

For financial calculations where precision matters, keep the original integer or decimal strings and use BigInt or a decimal arithmetic library rather than binary floating-point math.

APY should also be labeled carefully. Fields such as apy_1d, apy_7d, and apy_30d describe recent annualized conditions. They are useful historical signals, not promised future returns.

Build the pool list and detail views

With normalized data, the frontend becomes straightforward.

A compact explorer card might contain:

function PoolCard({ pool }: { pool: any }) {
  const token0 = pool.asset0;
  const token1 = pool.asset1;

  return (
    <article>
      <h3>
        {token0?.symbol ?? "Unknown"} /{" "}
        {token1?.symbol ?? "Unknown"}
      </h3>

      <p>
        Type: {pool.router?.router_type ?? "Unknown"}
      </p>

      <p>
        Version:{" "}
        {pool.router
          ? `v${pool.router.major_version}.${pool.router.minor_version}`
          : "Unknown"}
      </p>

      <p>
        24h volume:{" "}
        {pool.volume_24h_usd
          ? `$${Number(pool.volume_24h_usd).toLocaleString()}`
          : "N/A"}
      </p>

      <p>LP fee: {formatFee(pool.lp_fee)}</p>

      <code>{pool.address}</code>
    </article>
  );
}

The list page should optimize for comparison. Pair, liquidity value, 24-hour volume, fee, recent APY, pool type, and version are usually enough.

The detail page can go deeper.

Useful detail fields include:

full pool, router, and token contract addresses
normalized and raw reserves
LP token supply
protocol and referral fee settings
collected protocol fees
amp, rate, or w0 when applicable
pool and asset tags
deprecated status
1-day, 7-day, and 30-day APY
links to a TON blockchain explorer

Always display the underlying token addresses somewhere accessible. TON's token metadata documentation explicitly warns that anyone can create a jetton with a copied name, symbol, description, or image. A professional pool explorer should never identify an asset by ticker alone.

You can also use STON.fi's asset flags, such as deprecated or blacklisted status, to add visible warnings rather than silently treating every returned token as equivalent.

Handle pricing and pool types correctly

One of the easiest mistakes when building an AMM explorer is calculating:

price = reserve1 / reserve0

and calling the result the pool's current execution price.

That shortcut can be informative for a conventional constant product pool after adjusting both reserves for token decimals. It is not a universal pricing formula.

STON.fi supports multiple pool and router types, and the API exposes specialized parameters such as amp, rate, and w0. Those exist because different pool designs do not share one invariant.

A better explorer separates three concepts:

Reserve ratio: a description of the pool's current token composition.
Reference or statistical price: a price derived from indexed market statistics.
Executable quote: the expected result for a particular trade size under the current pool conditions.

If the reader wants to know what a trade would actually return, use STON.fi's swap simulation endpoint rather than extrapolating from reserves. POST /v1/swap/simulate is designed to calculate expected swap output, fees, gas information, and other execution data before a transaction is built.

Trade size matters. A quote for 1 TON and a quote for 10,000 TON can imply different effective prices because the trade itself moves through pool liquidity.

This gives your explorer a useful optional feature: a small "simulate swap" panel on each pool page. It turns a static pool viewer into a tool for understanding liquidity depth without requiring a wallet connection or transaction.

Add on-chain verification and production hardening

The STON.fi REST API is the convenient discovery and analytics layer. The pool contract remains the source of on-chain state.

For DEX v2 pools, the documented get_pool_data getter exposes values including the router address, LP supply, token reserves, token wallet addresses, and liquidity pool fee. A verification mode can query the relevant contract through a TON RPC provider and compare selected values with the indexed API response.

That creates two complementary modes:

Fast mode: use STON.fi API data for discovery, metadata, statistics, search, and normal page rendering.
Verification mode: read selected contract state directly from TON when the reader wants to inspect the underlying pool.

Do not treat a temporary difference as automatic evidence that something is wrong. An indexed API and the latest blockchain state can briefly differ because they are observed at different moments.

Before publishing the explorer, I would also add this checklist:

Cache pool, asset, and router requests instead of refetching everything on every render.
Add graceful handling for missing metadata and nullable USD values.
Search by token symbol, token address, and pool address.
Make contract addresses copyable.
Show deprecated and blacklisted warnings prominently.
Never use token symbols as unique database keys.
Distinguish pool types before calculating derived metrics.
Keep the raw API values available for debugging.
Record when your application last refreshed its data.
Treat API schemas as external dependencies and validate responses at runtime.

The official STON.fi documentation currently states that the DEX API has no usage limits. That is useful for development, but production software should still cache sensible responses and avoid unnecessary traffic because service policies can change.

Practical takeaway: start the explorer with three STON.fi datasets: pools, assets, and routers. Join them by contract address, normalize reserves using token decimals, and render only metrics whose meaning you can explain precisely. Once that works, add simulation for executable pricing and direct TON contract reads for verification. That architecture keeps the first version simple without locking you into an inaccurate data model.

Frequently Asked Questions

Do I need to run a TON node to build a STON.fi pool explorer?

No. A basic explorer can use the public STON.fi REST API for pool discovery, token metadata, router information, volume, APY, and other indexed data. A TON RPC provider becomes useful when you want to verify contract state directly or add deeper blockchain functionality, but it is not required for the first working version.

Which STON.fi endpoint should I start with?

Start with GET /v1/pools, then join its token addresses with GET /v1/assets and its router addresses with GET /v1/routers. This combination gives you the core information needed for a pool directory. You can later use /v1/pools/{address} for individual pages and /v1/pools/query for more selective discovery.

Can I calculate a token's price directly from pool reserves?

Sometimes, but you should not use one reserve-ratio formula for every STON.fi pool. Different AMM types can use different pricing mechanics. A reserve ratio is useful as a pool-composition metric. For an expected trade result, STON.fi's swap simulation endpoint is a safer source because it evaluates a specific amount against the relevant routing and pool logic.

What should I use as the pool's liquidity or TVL figure?

STON.fi pool responses expose LP supply information, including lp_total_supply_usd when available, alongside the underlying reserves. You can use the USD LP supply value as a convenient liquidity-value metric in your interface, while keeping the field's actual meaning clear. If you calculate your own value from reserves and asset prices, document exactly how that calculation works.

Why do I need the router endpoint if I already have the pool?

The router tells you important context about the contract behind the pool, including its major and minor version and router type. That information matters once your explorer supports multiple STON.fi pool designs. It prevents the frontend from assuming that every pool follows the same pricing model or exposes the same specialized parameters.

Should a STON.fi pool explorer trust token names and symbols?

No. Names and symbols are presentation metadata, not unique identities. TON documentation warns that jettons can copy another token's name, symbol, or image. Display contract addresses and use STON.fi metadata flags where appropriate. Internally, index tokens by their contract addresses rather than by symbols such as USDT, TON, or STON.

How can I verify that the STON.fi API reserves match the blockchain?

Read the pool contract's documented get_pool_data getter through a TON provider and compare its reserves and other relevant state with the indexed API values. Small temporary differences can occur because indexing and direct blockchain reads happen at different times. For an explorer, API-first rendering plus optional on-chain verification is usually a practical architecture.

Sources and Further Reading

STON.fi DEX API Reference - official list of pool, asset, router, statistics, simulation, wallet, and market endpoints
STON.fi REST API documentation - overview of the public DEX data API and integration options
STON.fi Swagger UI - current REST API schemas, including PoolInfoSchema, AssetInfoSchema, RouterInfoSchema, query parameters, and supported router types
STON.fi API TypeScript client - official @ston-fi/api client with methods for retrieving pools, assets, routers, wallet positions, and other protocol data
STON.fi DEX Architecture - official explanation of routers, pools, LP contracts, liquidity flows, and the protocol contract model
STON.fi Pool v2 smart contract reference - documents get_pool_data, reserves, LP supply, fee fields, router address, and other on-chain pool state
STON.fi v1 to v2 SDK migration guide - explains typed pool support and architectural differences developers should account for across STON.fi versions
TON Token Metadata - official guidance on jetton metadata fields and why applications should distinguish tokens by contract address rather than names or symbols
TON Run Get Method API - official TON API documentation for executing read-only smart contract getter methods when adding direct on-chain verification

How to Query STON.fi Token and Asset Metadata

Ivan “Crypto Vazima” Zimanov — Mon, 24 Aug 2026 06:04:19 +0000

How to fetch token names, symbols, decimals, images, prices, tags, and contract addresses with the STON.fi REST API and TypeScript client.

If you are building a token selector, portfolio view, swap interface, analytics dashboard, or any other TON application, you rarely want to decode every jetton's metadata yourself. STON.fi provides an HTTP API that exposes normalized asset information and a TypeScript client that makes those endpoints easier to use.

For most applications, the workflow is simple: query STON.fi for an asset list, identify every asset by its contract address, read the metadata you need for display, and keep transaction-critical logic separate from labels such as token names and symbols. The API currently provides endpoints for listing assets, fetching one asset by address, and querying assets with search and filtering conditions.

What does STON.fi mean by an asset?

On TON, fungible tokens normally use the jetton standard. Their metadata can include a name, symbol, decimals, image, and other fields. TEP-64 allows metadata to be stored on-chain, off-chain, or through a semi-chain combination where some values come from the contract and others come from an external document.

STON.fi gives developers a more convenient application-level view of assets used around the DEX. Instead of decoding cells and resolving metadata yourself for every token, you can query the STON.fi API.

Depending on the endpoint, an asset can contain information such as:

contract address
asset kind
token name and symbol
decimals
image URL
STON.fi DEX price in USD
tags
popularity information
wallet balance when a wallet-aware endpoint is used
optional extensions and scaling information

The API currently distinguishes asset kinds such as Ton, Wton, Jetton, and NotAnAsset. Its newer asset schema groups display metadata under a meta object, while the older asset response exposes fields such as symbol, display_name, decimals, and image_url directly.

That schema difference is worth noticing because code written for getAsset() and code written for queryAssets() may access metadata differently.

Pick the query that matches your UI

STON.fi provides several related asset endpoints, but they answer different questions.

What you need	REST endpoint	TypeScript client
Every available DEX asset	`GET /v1/assets`	`getAssets()`
One known asset	`GET /v1/assets/{address}`	`getAsset(address)`
Search and filter assets	`POST /v1/assets/query`	`queryAssets(...)`
Assets held by a wallet	`GET /v1/wallets/{address}/assets`	`getWalletAssets(address)`
One wallet asset and its balance	`GET /v1/wallets/{address}/assets/{asset}`	`getWalletAsset(...)`

For a production token selector, queryAssets() is usually more useful than downloading every known asset. It lets you search by text or address and combine the search with STON.fi asset conditions.

If you already know the contract address, however, fetching that specific asset is simpler and removes the ambiguity that comes with searching by a ticker.

Query one token directly by address

The most deterministic asset lookup starts with the contract address.

Using the REST API:

async function getStonAsset(address: string) {
  const response = await fetch(
    `https://api.ston.fi/v1/assets/${encodeURIComponent(address)}`
  );

  if (!response.ok) {
    throw new Error(`STON.fi API returned ${response.status}`);
  }

  const data = await response.json();
  return data.asset;
}

The official API base URL is:

https://api.ston.fi

The equivalent operation with the official TypeScript package is shorter:

npm install @ston-fi/api

import { StonApiClient } from "@ston-fi/api";

const client = new StonApiClient();

const asset = await client.getAsset("EQ...");

console.log(asset);

StonApiClient uses https://api.ston.fi by default, so no API configuration is required for a basic request. The current client source maps getAsset() directly to GET /v1/assets/{assetAddress}.

This pattern is ideal when an address comes from a trusted configuration, a pool response, a swap quote, or another part of your application where the asset has already been identified.

Search for tokens without downloading the whole list

A token picker has a different problem. The visitor may type USD, STON, or part of a token name, so you need discovery rather than an exact lookup.

STON.fi provides POST /v1/assets/query for this.

A direct REST request can look like this:

async function searchAssets(search: string) {
  const response = await fetch(
    "https://api.ston.fi/v1/assets/query",
    {
      method: "POST",
      headers: {
        "content-type": "application/json",
      },
      body: JSON.stringify({
        search_terms: [search],
        condition:
          "asset:liquidity:very_high | asset:liquidity:high",
        limit: 20,
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`Asset query failed: ${response.status}`);
  }

  const data = await response.json();
  return data.asset_list;
}

The request schema supports search terms containing addresses or text such as token names and symbols. It also supports a condition, sorting parameters, a result limit, unconditional assets, and an optional wallet address.

With @ston-fi/api, the same query becomes easier to read:

import {
  StonApiClient,
  AssetTag,
} from "@ston-fi/api";

const client = new StonApiClient();

const assets = await client.queryAssets({
  searchTerms: ["USD"],
  condition: [
    AssetTag.LiquidityVeryHigh,
    AssetTag.LiquidityHigh,
  ].join(" | "),
  limit: 20,
});

console.log(assets);

STON.fi's own quickstart uses the same approach to populate token selectors, combining LiquidityVeryHigh, LiquidityHigh, and LiquidityMedium tags and then storing the returned AssetInfoV2 objects in application state.

The older searchAssets() client method still exists, but the current source marks it as deprecated and redirects it through queryAssets(). New integrations should therefore use queryAssets() directly.

Turn the response into clean application data

A raw API object usually contains more information than a component needs. Normalizing it once makes the rest of your frontend much easier to maintain.

The newer query response exposes display metadata under meta.

import type { AssetInfoV2 } from "@ston-fi/api";

type TokenOption = {
  address: string;
  name: string;
  symbol: string;
  decimals?: number;
  imageUrl?: string;
  priceUsd?: string;
  tags: string[];
};

function toTokenOption(asset: AssetInfoV2): TokenOption {
  return {
    address: asset.contractAddress,
    name: asset.meta?.displayName ?? "Unknown token",
    symbol: asset.meta?.symbol ?? "TOKEN",
    decimals: asset.meta?.decimals,
    imageUrl: asset.meta?.imageUrl,
    priceUsd: asset.dexPriceUsd,
    tags: asset.tags ?? [],
  };
}

Then your UI can work with a small predictable model:

const options = assets.map(toTokenOption);

The official AssetInfoV2 structure includes the contract address, asset kind, optional balance, DEX price, meta, popularity information, tags, wallet address, scale, and extensions. Inside meta, fields such as decimals, symbol, display name, image URL, and custom payload API URI are optional.

That optionality matters. A robust token selector should not assume that every asset has a complete name, icon, or even every display field.

A reasonable display fallback is:

Show displayName when available.
Fall back to symbol.
Keep the contract address available as the definitive identifier.
Use a local placeholder when no usable image exists.

Decimals are metadata that affect real amounts

A missing icon is mostly a visual problem. Incorrect decimals are different because decimals determine how integer token units become human-readable balances.

Suppose an API returns:

{
  meta: {
    symbol: "EXAMPLE",
    decimals: 6
  }
}

An on-chain amount of:

represents:

1.25 EXAMPLE

not 1,250,000 tokens.

Avoid normal JavaScript floating-point arithmetic when converting transaction amounts. A simple display helper can use BigInt:

function formatUnits(value: string, decimals: number) {
  const units = BigInt(value);
  const base = 10n ** BigInt(decimals);

  const whole = units / base;
  const fraction = (units % base)
    .toString()
    .padStart(decimals, "0")
    .replace(/0+$/, "");

  return fraction
    ? `${whole}.${fraction}`
    : whole.toString();
}

TON's token metadata standard defines decimals as a jetton metadata attribute and specifies 9 as the default when the field is absent. Still, if your application receives incomplete or unexpected STON.fi metadata, treating that object carefully is safer than blindly assuming every response represents a normal jetton.

Use tags to improve token discovery

STON.fi does more than return names and icons. Its TypeScript client currently exposes a range of asset tags that can help shape search results and token lists.

Examples include:

AssetTag.Essential
AssetTag.Popular
AssetTag.LiquidityVeryHigh
AssetTag.LiquidityHigh
AssetTag.LiquidityMedium
AssetTag.WalletHasBalance
AssetTag.Deprecated
AssetTag.Blacklisted
AssetTag.Suspicious
AssetTag.Fake
AssetTag.Honeypot
AssetTag.NonSearchable

The exact tag set can evolve, so import the constants from the package instead of copying string values throughout your application. The current client source also includes tags for scaled assets, taxable assets, DMCA complaints, wallet liquidity, and several liquidity levels.

A wallet-aware selector can combine discovery with the connected wallet:

const walletAssets = await client.queryAssets({
  condition: [
    AssetTag.Essential,
    AssetTag.Popular,
    AssetTag.WalletHasBalance,
  ].join(" | "),
  walletAddress,
});

That gives you a useful foundation for sections such as "Your tokens" or "Popular assets" without maintaining a separate token registry in your frontend.

Tags should still be treated as API classification data, not as cryptographic proof that an asset is safe.

Never identify a token by its symbol alone

Imagine your application searches for USD and receives several assets. Choosing the first item because its ticker looks familiar is a dangerous shortcut.

TON's own token metadata documentation explicitly warns that anyone can create a jetton using any name, description, or image. Applications should distinguish tokens by their addresses rather than relying on names or tickers.

For a production STON.fi integration, keep these rules simple:

Use contractAddress as the asset identifier.
Treat symbol and display name as presentation metadata.
Preserve the selected address when requesting quotes or constructing transactions.
Do not infer authenticity from an icon.
Consider STON.fi tags when deciding which assets should appear prominently.
Give users a way to inspect or verify the contract address for unfamiliar assets.

This becomes especially important for symbols such as USDT, USD, TON, or any popular project ticker that someone could imitate.

The interface may display:

Example USD
USD
$1.00

but the application state should fundamentally remember:

{
  contractAddress: "EQ..."
}

The address is what connects the display object to the actual TON asset.

A practical STON.fi token selector

Putting the pieces together, a small React application might query STON.fi as the user types instead of loading the entire asset catalog.

import {
  AssetTag,
  StonApiClient,
  type AssetInfoV2,
} from "@ston-fi/api";

const stonApi = new StonApiClient();

export async function findTokens(
  searchTerm: string
): Promise<AssetInfoV2[]> {
  const searchTerms = searchTerm.trim()
    ? [searchTerm.trim()]
    : undefined;

  return stonApi.queryAssets({
    searchTerms,
    condition: [
      AssetTag.LiquidityVeryHigh,
      AssetTag.LiquidityHigh,
      AssetTag.LiquidityMedium,
    ].join(" | "),
    limit: 30,
  });
}

Your component can then render the fields STON.fi already normalized:

{assets.map((asset) => (
  <button
    key={asset.contractAddress}
    onClick={() => setSelectedAsset(asset)}
  >
    {asset.meta?.imageUrl && (
      <img
        src={asset.meta.imageUrl}
        alt=""
        width={32}
        height={32}
      />
    )}

    <strong>
      {asset.meta?.symbol ?? "Unknown"}
    </strong>

    <span>
      {asset.meta?.displayName ?? asset.contractAddress}
    </span>
  </button>
))}

For a real product, add loading states, request cancellation or debouncing for live search, image fallbacks, error handling, and caching. Metadata images and other external resources should also be treated as untrusted input. If your backend fetches arbitrary remote resources, apply normal URL validation and server-side request protections.

STON.fi's own Omniston quickstart follows the same core architecture: fetch assets through StonApiClient, keep AssetInfoV2 objects in state, display meta.symbol or meta.displayName, and pass the selected contract addresses into later swap operations.

Practical takeaway: use getAsset() when the contract address is already known and queryAssets() when you are building discovery or search. Keep the contract address as your canonical identifier, normalize optional metadata before it reaches your UI, and use STON.fi's tags to make large token lists easier to navigate.

Frequently Asked Questions

Can I query STON.fi token metadata without installing an SDK?

Yes. The REST API is available at https://api.ston.fi, so any environment capable of making HTTP requests can use it. GET /v1/assets/{address} retrieves a specific asset, while POST /v1/assets/query supports filtered discovery. The @ston-fi/api package is mainly a convenience layer for TypeScript and JavaScript applications.

What metadata does STON.fi return for a token?

Depending on the endpoint and schema, you can receive a contract address, kind, symbol, display name, decimals, image URL, prices, tags, popularity information, optional extensions, and wallet-related fields. Query responses use the newer model where core display metadata is grouped under meta, and those metadata fields can be optional.

Should I use `getAssets()` or `queryAssets()`?

Use getAssets() when you genuinely need the complete DEX asset collection. Use queryAssets() for most interactive interfaces because it supports search terms, conditions, wallet-aware queries, sorting, and limits. A search box usually does not need the full asset catalog before the user has typed anything.

Can two TON tokens have the same symbol?

Yes. Names and symbols are metadata, and token creators can choose them. A familiar ticker therefore does not uniquely identify a jetton. TON documentation recommends distinguishing tokens by address. Your frontend can display the symbol prominently, but your application logic should retain and use the contract address.

What should I do if `meta.imageUrl` or `meta.displayName` is missing?

Use a fallback. Display the symbol or a shortened address when a name is unavailable, and use a local placeholder image when no valid icon exists. Do not make rendering a token dependent on optional cosmetic metadata. AssetInfoV2 deliberately represents several metadata properties as optional.

Does STON.fi provide token prices together with metadata?

The asset schemas include optional STON.fi DEX price information such as dex_price_usd, exposed in camelCase by the TypeScript client. Treat price data separately from identity metadata because a price can be absent or change frequently, while the contract address is the persistent identifier used by your application.

Can I use STON.fi metadata to build a wallet token list?

Yes. STON.fi exposes wallet-specific asset endpoints, and queryAssets() can also accept a wallet address together with conditions such as AssetTag.WalletHasBalance. That makes it possible to combine searchable DEX assets with wallet-aware token selection without maintaining a completely separate metadata database.

What is the safest way to query a STON.fi asset before using it in a swap?

Start from the exact contract address whenever possible. Retrieve the asset, display its metadata for readability, but keep the address as the selected value passed into your swap logic. For search-based selection, show enough identifying information for the user to distinguish similar tokens and avoid treating a matching name, ticker, or image as proof of identity.

Sources and Further Reading

STON.fi DEX API Reference - Official overview of asset, pool, wallet, swap, and other REST endpoints
STON.fi REST API - Official introduction to the STON.fi HTTP API and TypeScript client
STON.fi Swagger UI - Current interactive REST API schemas, asset endpoints, request parameters, and response models
STON.fi API GitHub repository - Official source and usage examples for the @ston-fi/api TypeScript client
STON.fi asset types - Official AssetInfo, AssetInfoV2, AssetKind, and AssetTag definitions
STON.fi Omniston Quickstart - Official React example showing how StonApiClient and queryAssets() populate token selectors
TON Token Metadata Documentation - Official explanation of on-chain, off-chain, and semi-chain token metadata and token identity considerations
TEP-64 Token Data Standard - TON specification defining token metadata layouts and jetton metadata fields

How to Display STON.fi Pool Data in a Web App

Ivan “Crypto Vazima” Zimanov — Fri, 21 Aug 2026 10:52:22 +0000

Build a small React and TypeScript dashboard that fetches STON.fi liquidity pools, resolves token metadata, formats reserves, and presents useful market data.

Displaying STON.fi pool data in a web app does not require reading TON smart contracts directly. For most dashboards, analytics pages, token explorers, and liquidity interfaces, the simplest route is the official STON.fi REST API or its TypeScript client, @ston-fi/api.

The API already organizes contract data into application-friendly structures. You can request pools, retrieve asset metadata, find pools for a specific token pair, and expose fields such as reserves, USD liquidity values, and 24-hour volume.

In this guide, we will build a small React interface that turns those responses into readable pool cards without adding wallet connections or transaction logic.

What we will build:

fetch the current STON.fi pool list
resolve token addresses into symbols
format reserves using each token's decimals
display liquidity and 24-hour volume
handle loading, errors, and stale data
keep the data layer ready for filtering or a larger dashboard

Why use the STON.fi API instead of reading contracts directly?

A liquidity pool ultimately lives on-chain. STON.fi pool contracts contain reserves and other state, and the protocol documentation exposes contract getters such as get_pool_data. The V2 pool getter, for example, includes the LP token supply, both reserves, token wallet addresses, and fee-related fields.

You could query those contracts yourself. For a web interface whose job is simply to show pool information, however, that creates work you often do not need.

STON.fi provides a REST API specifically to organize protocol data for applications. Its current pool endpoints include:

GET  /v1/pools
GET  /v1/pools/{address}
GET  /v1/pools/by_market/{asset0}/{asset1}
POST /v1/pools/query

The base URL is:

https://api.ston.fi

The official TypeScript package wraps these endpoints with methods such as getPools(), getPool(), getPoolsByAssetPair(), and queryPools(). The current client also normalizes API response keys from snake_case to camelCase, which is convenient in a TypeScript frontend.

For a read-only pool dashboard, that is the layer we want.

Which pool fields are actually useful in a UI?

The pool response contains considerably more information than most users need to see. The current STON.fi schema includes fields for the pool address, token addresses, reserves, LP supply, protocol fees, LP price, USD LP supply, recent APY values, 24-hour USD volume, router address, and parameters used by different pool types.

A compact market interface can start with just a few fields:

API value	What it gives your UI
`token0Address` and `token1Address`	Identifies the pool pair
`reserve0` and `reserve1`	Current token reserves in base units
`lpTotalSupplyUsd`	USD value associated with total LP supply
`volume24hUsd`	Trading volume during the last 24 hours
`address`	Pool contract address
`deprecated`	Helps avoid presenting deprecated pools as normal active choices

There are two important display details here.

First, token addresses are not good labels. A visitor wants to see something like TON / USDT, not two long TON addresses. We therefore need the asset list as well as the pool list.

Second, reserves are raw blockchain quantities. Token metadata defines the number of decimals that must be applied to convert a base-unit balance into a human-readable amount. TON documentation explicitly warns applications to respect token decimals rather than assuming every asset uses the same value.

Set up the React project

A basic React and TypeScript application is enough for the example.

npm create vite@latest stonfi-pools -- --template react-ts
cd stonfi-pools
npm install
npm install @ston-fi/api
npm run dev

For this dashboard, we do not need @ston-fi/sdk.

That distinction is useful. @ston-fi/api is the HTTP API client and is appropriate for retrieving application data. @ston-fi/sdk is aimed at interaction with STON.fi DEX contracts, including swaps and liquidity operations.

Create a small API module:

// src/stonfi.ts
import { StonApiClient } from "@ston-fi/api";

export const stonApi = new StonApiClient();

The client requires no special configuration for the standard API endpoint. The package uses https://api.ston.fi as its default base URL.

Fetch pools and token metadata together

Calling getPools() gives us the pool data, while getAssets() gives us the metadata required to turn token addresses into recognizable names and symbols.

Fetching both in parallel keeps the first render simple:

import { useEffect, useState } from "react";
import { stonApi } from "./stonfi";

type Pool = Awaited<
  ReturnType<typeof stonApi.getPools>
>[number];

type Asset = Awaited<
  ReturnType<typeof stonApi.getAssets>
>[number];

export default function App() {
  const [pools, setPools] = useState<Pool[]>([]);
  const [assets, setAssets] = useState<Asset[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    let ignore = false;

    async function loadData() {
      try {
        setLoading(true);
        setError(null);

        const [poolList, assetList] = await Promise.all([
          stonApi.getPools(),
          stonApi.getAssets(),
        ]);

        if (ignore) return;

        setPools(poolList);
        setAssets(assetList);
      } catch (err) {
        if (!ignore) {
          setError(
            err instanceof Error
              ? err.message
              : "Unable to load STON.fi data"
          );
        }
      } finally {
        if (!ignore) {
          setLoading(false);
        }
      }
    }

    loadData();

    return () => {
      ignore = true;
    };
  }, []);

  if (loading) return <p>Loading STON.fi pools...</p>;
  if (error) return <p>Error: {error}</p>;

  return <p>Loaded {pools.length} pools.</p>;
}

React documents useEffect as one way to synchronize a component with an external system, including manual data fetching. It also recommends cleanup logic so a response does not update a component after the relevant effect has been discarded.

For a production Next.js, Remix, or similar application, you may prefer the framework's server-side data fetching or a caching library. The STON.fi-specific part does not change.

Turn contract addresses into readable pool pairs

The asset response includes fields such as the contract address, symbol, display name, decimals, and price information. The STON.fi client converts the raw API keys into camelCase before returning them.

Build a lookup map once:

import { useMemo } from "react";

// inside App

const assetByAddress = useMemo(() => {
  return new Map(
    assets.map((asset) => [asset.contractAddress, asset])
  );
}, [assets]);

Now each pool's token addresses can be resolved efficiently:

function getSymbol(
  address: string,
  assetByAddress: Map<string, Asset>
) {
  return assetByAddress.get(address)?.symbol ?? "Unknown";
}

The same metadata lets us convert reserves into display values.

function formatUnits(value: string, decimals: number) {
  if (decimals === 0) return value;

  const padded = value.padStart(decimals + 1, "0");
  const whole = padded.slice(0, -decimals);

  const fraction = padded
    .slice(-decimals)
    .replace(/0+$/, "")
    .slice(0, 4);

  return fraction ? `${whole}.${fraction}` : whole;
}

Do not silently assume nine decimals when metadata is unavailable. Nine is common on TON, but tokens can use another value. USDT, for example, uses six decimals.

For unknown assets, showing the raw amount or an explicit unavailable state is safer than presenting a confidently formatted but incorrect number.

Render the pool data

We can now turn the two API responses into a small dashboard.

Add a USD formatter:

const usd = new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
  maximumFractionDigits: 0,
});

function formatUsd(value?: string) {
  if (!value) return "N/A";

  const number = Number(value);

  return Number.isFinite(number)
    ? usd.format(number)
    : "N/A";
}

Then render the pools:

return (
  <main>
    <h1>STON.fi Pools</h1>

    <div className="pool-grid">
      {pools
        .filter((pool) => !pool.deprecated)
        .sort(
          (a, b) =>
            Number(b.lpTotalSupplyUsd ?? 0) -
            Number(a.lpTotalSupplyUsd ?? 0)
        )
        .slice(0, 20)
        .map((pool) => {
          const token0 = assetByAddress.get(pool.token0Address);
          const token1 = assetByAddress.get(pool.token1Address);

          const reserve0 = token0
            ? formatUnits(pool.reserve0, token0.decimals)
            : `${pool.reserve0} base units`;

          const reserve1 = token1
            ? formatUnits(pool.reserve1, token1.decimals)
            : `${pool.reserve1} base units`;

          return (
            <article className="pool-card" key={pool.address}>
              <h2>
                {token0?.symbol ?? "Unknown"} /{" "}
                {token1?.symbol ?? "Unknown"}
              </h2>

              <p>
                <strong>Liquidity:</strong>{" "}
                {formatUsd(pool.lpTotalSupplyUsd)}
              </p>

              <p>
                <strong>24h volume:</strong>{" "}
                {formatUsd(pool.volume24hUsd)}
              </p>

              <p>
                <strong>Reserve 0:</strong>{" "}
                {reserve0} {token0?.symbol ?? ""}
              </p>

              <p>
                <strong>Reserve 1:</strong>{" "}
                {reserve1} {token1?.symbol ?? ""}
              </p>

              <small>
                Pool: {pool.address.slice(0, 10)}...
                {pool.address.slice(-6)}
              </small>
            </article>
          );
        })}
    </div>
  </main>
);

At this point the app has moved from protocol-oriented data to UI-oriented data:

STON.fi API
    |
    +-- pools
    |    +-- reserves
    |    +-- liquidity value
    |    +-- volume
    |    +-- pool address
    |
    +-- assets
         +-- symbols
         +-- names
         +-- decimals
              |
              v
       React view model
              |
              v
       readable pool cards

That transformation layer is worth keeping separate from the markup. It becomes much easier to add search, sorting, charts, or token filters later.

Fetch less data when the page becomes more specific

getPools() is a good starting point because it lets you explore the dataset. It should not automatically become the request used by every future screen.

If a page is about one pool, request one pool:

const pool = await stonApi.getPool(poolAddress);

If the user has selected two assets, request pools for that pair:

const pools = await stonApi.getPoolsByAssetPair({
  asset0Address,
  asset1Address,
});

For more advanced discovery, STON.fi also exposes queryPools(). The current client supports search terms, conditions, sorting, limits, wallet-specific context, and a DEX V2 option.

That gives you a useful progression:

Use getPools() while building a general explorer.
Move to pair-specific requests when the visitor selects assets.
Use getPool() on detail pages.
Use queryPools() when your interface needs server-side filtering or ranking.

The UI stays the same. Only the retrieval strategy becomes more precise.

Treat pool data as live application data

A working first render is not the end of the integration. Pool reserves and trading volume change as swaps and liquidity operations occur.

Before shipping, decide how fresh the interface actually needs to be.

For a pool directory, refreshing every few minutes may be enough. A trading interface may need a different data path and much fresher quoting logic. Do not confuse a periodically refreshed pool dashboard with an executable swap quote.

A practical production checklist:

cache responses instead of requesting the complete pool list on every render
show a loading state during the initial request
preserve a clear error state when the API is unavailable
display when the data was last refreshed
remove or visually mark deprecated pools
never use rounded UI numbers as transaction inputs
keep original string values for financial calculations

The STON.fi documentation currently states that the DEX API has no rate limits, but that should not be treated as a reason to make wasteful requests. API behavior and operational limits can change, and caching makes the application faster regardless.

Also remember that the STON.fi REST API is intended for mainnet data. If your development workflow depends on testnet contract state, do not assume the same REST endpoint is a testnet indexer.

Common mistakes when displaying STON.fi pools

Showing raw addresses as the main identity. Addresses are essential identifiers, but they make poor primary labels. Resolve them through the asset metadata response and use addresses as secondary verification information.

Formatting every reserve with nine decimals. Token decimals belong to the token metadata. A wrong decimal assumption can produce a dramatically wrong displayed amount.

Calling getPools() after every state update. Pool data is external network data. Fetch it intentionally, cache it where appropriate, and separate filters that can run locally from filters that genuinely require another API request.

Treating lpTotalSupplyUsd as a universal definition of TVL without explanation. The API schema describes this field as the USD value of total LP token supply. If your product labels a metric "TVL," document exactly how your application defines it.

Mixing analytics values with transaction calculations. A rounded reserve or USD number that looks good in a card is not a substitute for a swap simulation or exact base-unit value.

For a useful first STON.fi integration, keep the exercise narrow: load pools, resolve their assets, inspect the exact API values in your browser, and compare the displayed reserves with the token decimals before adding more features. Once that layer is reliable, search, sorting, charts, pool detail pages, and wallet-specific liquidity views become incremental improvements rather than a rewrite.

Frequently Asked Questions

Can I display STON.fi pool data without connecting a wallet?

Yes. Public pool and asset information can be retrieved through the STON.fi REST API without asking the visitor to connect a wallet. A wallet becomes relevant when you want wallet-specific positions or when the application starts constructing transactions. A read-only pool explorer can remain completely independent of TonConnect.

Do I need `@ston-fi/sdk` to fetch liquidity pools?

No. For the workflow in this article, @ston-fi/api is the relevant package. It provides methods such as getPools(), getPool(), getAssets(), and getPoolsByAssetPair(). The separate DEX SDK is intended for interaction with protocol contracts and becomes useful when your application moves beyond displaying data.

What does `GET /v1/pools` return?

The endpoint returns the STON.fi pool collection. Pool records contain identifiers and state including pool and router addresses, token addresses, reserves, LP-related values, fee fields, recent APY fields, and 24-hour USD volume where available. The exact live schema should always be checked in the official Swagger interface.

How should I display token reserves correctly?

Retrieve the corresponding asset metadata and use its decimals value to convert the base-unit reserve into a human-readable amount. Do not assume that all tokens use the same number of decimals. Keep the original string or integer representation for calculations and perform formatting only at the presentation boundary.

Should I refresh pool data every second?

Usually not for a general pool dashboard. Choose a refresh interval that matches the purpose of the page, cache shared data, and avoid repeated full-list requests. A fast-changing execution interface should use purpose-built quote or simulation data rather than assuming that a periodically fetched pool card represents an executable price.

Can I request only pools for one token pair?

Yes. STON.fi exposes GET /v1/pools/by_market/{asset0}/{asset1}, and the TypeScript client wraps it with getPoolsByAssetPair(). That is preferable to loading every pool and filtering in the browser when the application already knows the two selected assets.

Can I show a user's STON.fi liquidity positions with the same API?

Yes. The REST API includes wallet-specific pool endpoints, and @ston-fi/api exposes getWalletPools() and getWalletPool(). That is a different UI state from the public pool directory because the response is enriched with information relevant to the specified wallet.

What should I verify before publishing a STON.fi pool dashboard?

Compare your field names against the current Swagger schema, verify token decimals, confirm that deprecated pools are handled correctly, and test missing optional values such as USD metrics. Also inspect the actual API response rather than copying an old example, since the STON.fi API and TypeScript client continue to evolve.

Sources and Further Reading

STON.fi REST API - Official overview of the REST interface, API viewers, and current usage notes
STON.fi API Reference - Official list of pool, asset, wallet, statistics, and other DEX endpoints
STON.fi Swagger UI - Current interactive REST API schema and response definitions
STON.fi API TypeScript client - Official source repository for @ston-fi/api, including pool and asset client methods
@ston-fi/api on npm - Package installation and TypeScript client usage examples
STON.fi V2 Pool contract reference - On-chain pool state and get_pool_data fields behind pool information
TON token metadata - Official explanation of token metadata and decimal handling for human-readable amounts
React useEffect reference - Official React guidance for synchronizing components with external systems and manual data fetching

How to Track STON.fi Swap Status with an Indexer

Ivan “Crypto Vazima” Zimanov — Tue, 18 Aug 2026 06:42:55 +0000

How to turn TON transaction data into a reliable pending, processing, completed, or failed state for a STON.fi swap.

When a user signs a STON.fi swap, your application still has an important job to do: determine what actually happened on-chain.

On TON, that is not always as simple as waiting for one transaction hash. A swap can involve several contracts and internal messages, so the wallet transaction that starts the operation is only the beginning of the execution path. A blockchain indexer lets you locate that transaction, follow its trace, inspect the resulting actions, and turn low-level blockchain data into a useful swap status.

For a production integration, the safest approach is to separate two questions: Has the TON trace finished? and Did the STON.fi swap itself succeed?

Why one transaction hash is not enough

Developers coming from EVM networks often expect a swap to map neatly to one transaction. TON works differently.

A transaction on TON records a state change for one account. If that account sends internal messages to other contracts, those messages can trigger additional transactions. The related messages and transactions form a trace. Because TON uses asynchronous message processing, different parts of that trace may execute across different blocks.

A simplified STON.fi swap can therefore look conceptually like this:

Your wallet sends the initiating message.
The wallet transaction sends an internal message toward the swap contracts.
Router and pool contracts process the request.
Jetton wallets may process token transfers.
The output asset reaches the destination wallet.
Excess TON or other follow-up messages may also be processed.

The exact path depends on the swap and protocol version, but the monitoring lesson stays the same: finding the first transaction does not prove that the entire swap has completed successfully.

TON defines traces specifically to connect these causally related transactions and messages. An indexer makes those traces much easier to query than reconstructing them manually from raw node data.

What an indexer adds to swap tracking

An indexer continuously reads blockchain data, parses transactions and messages, and stores structured results in a query-friendly database.

TON Center API v3 is one example. TON documentation describes it as an indexed access layer that supports historical transactions, traces, decoded Jetton data, and higher-level actions. Its mainnet endpoint is https://toncenter.com/api/v3.

For a STON.fi integration, that gives you several useful capabilities:

find the transaction associated with the message sent by the wallet
retrieve the full trace related to that transaction
see whether the trace is still incomplete
inspect pending messages
request classified actions when available
recover historical status after a page reload or backend restart

This is much more useful than repeatedly asking whether a single account has a new transaction.

A good architecture treats the indexer as an observation layer. Your application stores the swap identifiers, queries indexed blockchain state, and then maps the returned data into a much smaller set of statuses that make sense to the person waiting for the swap.

Build a status model for your application

Do not expose every low-level TON state directly to the UI. Define your own swap lifecycle instead.

Application status	What you know	Typical evidence
Submitted	Wallet accepted the request	TON Connect returned the outgoing message BoC
Locating	Message was sent, but the indexed transaction is not available yet	No matching indexed transaction yet
Processing	Initial transaction exists and the trace is still progressing	Trace is incomplete or still has pending messages
Verifying	Trace is complete, but the protocol outcome still needs interpretation	Complete trace and available actions
Succeeded	Swap completed with the expected protocol result	Successful STON.fi swap status or validated swap action
Failed	Execution completed without a successful swap result	Failed or aborted protocol action, refund path, or other terminal failure

The key distinction is between trace completion and swap success.

An indexer can tell you that the chain of messages has stopped progressing. It does not automatically mean your application's intended business operation succeeded. For a STON.fi swap, you should also interpret STON.fi-specific data rather than relying only on a generic transaction success flag.

Start with the message returned by TON Connect

After a user signs through TON Connect, sendTransaction() returns a serialized external message as a BoC.

That BoC is a useful tracking anchor, but TON recommends using the normalized hash of the external message for message lookup. Normalization exists because equivalent external messages can otherwise have different hashes depending on serialization details. TON documents the normalization rules in its TON Connect message lookup guide and notes that normalized message lookup is supported by many providers.

A shortened TypeScript version follows the same approach:

import {
  beginCell,
  Cell,
  loadMessage,
  storeMessage,
} from "@ton/core";

function getNormalizedHash(boc: string): string {
  const message = loadMessage(
    Cell.fromBase64(boc).beginParse()
  );

  if (message.info.type !== "external-in") {
    throw new Error("Expected an external-in message");
  }

  const normalized = {
    ...message,
    init: null,
    info: {
      ...message.info,
      src: undefined,
      importFee: 0n,
    },
  };

  return beginCell()
    .store(storeMessage(normalized, { forceRef: true }))
    .endCell()
    .hash()
    .toString("hex");
}

Save this tracking identifier with the swap record in your backend.

Do not depend on React component state alone. If the user closes the tab immediately after signing, you still want to be able to reconstruct the operation later.

Your stored swap record might contain:

wallet address
normalized external message hash
STON.fi router used for the swap
input and output assets
expected output or minimum output
STON.fi query ID when available
creation time
your current application status

Those fields give you enough context to recover after temporary API failures or user disconnects.

Follow the transaction into its trace

Once you know the transaction hash, TON Center API v3 can retrieve a trace with GET /traces.

The endpoint supports filters including trace_id, tx_hash, and msg_hash. You can also request classified actions with include_actions=true. The returned trace data includes fields such as is_incomplete, transaction information, actions, and trace metadata.

A simple backend request can look like this:

async function getTrace(txHash: string) {
  const url = new URL(
    "https://toncenter.com/api/v3/traces"
  );

  url.searchParams.append("tx_hash", txHash);
  url.searchParams.set("include_actions", "true");

  const response = await fetch(url, {
    headers: {
      "X-API-Key": process.env.TONCENTER_API_KEY!,
    },
  });

  if (!response.ok) {
    throw new Error(
      `Indexer returned ${response.status}`
    );
  }

  return response.json();
}

Keep API keys on the server. TON Center accepts API keys through the X-API-Key header, and its documentation explicitly recommends not exposing them in client-side applications or public repositories.

Your first status function can remain deliberately simple:

function getTraceState(data: any) {
  const trace = data.traces?.[0];

  if (!trace) {
    return "locating";
  }

  if (
    trace.is_incomplete ||
    (trace.trace_info?.pending_messages ?? 0) > 0
  ) {
    return "processing";
  }

  return "verifying";
}

Notice that the final state is verifying, not succeeded.

That extra step prevents one of the most common monitoring mistakes: treating a completed trace as proof that the desired swap completed.

Verify the STON.fi result, not only TON execution

STON.fi provides protocol-specific APIs that are useful once you need to interpret what happened.

The current STON.fi DEX API documents:

GET /v1/swap/status for checking a swap using router address, owner address, and query ID
POST /v1/transaction/query for resolving a transaction from identifiers such as wallet address plus query ID or an external message hash
POST /v1/transaction/action_tree for obtaining STON.fi actions and their statuses from an originating transaction

The API base URL is https://api.ston.fi.

These endpoints solve a different problem from a generic TON indexer.

The indexer answers:

What transactions and messages happened on TON?

STON.fi-specific decoding answers:

What did those transactions mean for this swap?

For a direct STON.fi DEX integration, combining both gives you a stronger status pipeline:

TON Connect
    |
    v
External message
    |
    v
Indexer finds transaction
    |
    v
Indexer follows TON trace
    |
    v
Trace completes
    |
    v
STON.fi status or action verification
    |
    +--> succeeded
    |
    +--> failed / aborted / recovery path

This also makes debugging much easier. If your UI says that a swap failed, you can distinguish between "the initiating transaction was never found", "the TON trace is still executing", and "execution completed but the swap did not produce the intended result."

What changes when the swap uses Omniston?

Do not confuse generic indexer tracking with Omniston's own trade tracking interface.

For Omniston swaps, STON.fi provides trackTrade functionality through its SDKs and the underlying trade.track API. Tracking uses the quote ID, trader wallet address, and outgoing transaction hash. Omniston can report states such as waiting for the initial transfer, transferring, swapping, receiving funds, and a final settled trade result.

If you are already building with the Omniston SDK, its native trade tracker should usually be your primary protocol-level status source.

An indexer is still valuable for:

independent on-chain verification
debugging failed or unusual traces
rebuilding state after an application restart
storing your own transaction history
linking protocol status to raw TON transactions

The two approaches complement each other. They are not competing definitions of the same status.

Polling or streaming?

Polling is usually the easiest starting point.

After submission, poll quickly while the swap is active, then reduce the frequency after several unsuccessful attempts. Stop polling once you reach a terminal state. Add a maximum tracking window, but do not automatically classify a temporary timeout as an on-chain failure.

For faster interfaces, TON Center also provides a Streaming API using SSE and WebSockets. It can stream transactions, actions, and traces with pending, confirmed, and finalized finality levels. TON documentation warns that the streaming API does not replay events missed during a connection interruption, so applications that require complete state should resynchronize from API v3 after reconnecting.

A practical production pattern is therefore:

stream for responsiveness, query the indexer for recovery and truth reconstruction.

A practical STON.fi tracking checklist

Before shipping your status component, test more than the happy path.

Check that your application can recover a swap after a browser refresh, distinguish "not indexed yet" from "failed", follow the complete trace instead of only the wallet transaction, and validate the STON.fi-level result before displaying success.

Also store enough identifiers to investigate a transaction later. A wallet address by itself is usually not a strong correlation key when the same wallet can initiate several swaps close together.

Most importantly, make your status names describe what you actually know. Processing is safer than Success while internal messages are still active, and Verifying is safer than assuming every completed TON trace represents a completed swap.

Frequently Asked Questions

What is an indexer in TON?

An indexer reads blockchain data, parses transactions and messages, and stores them in a database optimized for queries. TON Center API v3 is an indexed API that supports traces, historical transactions, actions, Jetton data, and other structured information that is harder to obtain efficiently from raw node access.

Why can a STON.fi swap involve multiple transactions?

TON smart contracts communicate asynchronously through messages. One transaction processes a message for one account, and that account may send messages that trigger transactions on other accounts. A DEX operation can therefore become a trace containing wallet, router, pool, and token-related transactions rather than one monolithic transaction.

Does finding the wallet transaction mean the swap succeeded?

No. It proves that the initiating message was processed, not necessarily that the entire swap completed successfully. Follow the resulting trace and then verify the protocol-level swap result before showing a final success state.

What should I store after sending the swap?

Store a stable correlation record containing the wallet address, tracking hash or transaction identifier, swap creation time, and STON.fi-specific identifiers such as the query ID or router when your integration provides them. This lets your backend reconstruct status even if the frontend disappears.

Should I poll an indexer continuously?

Only while the operation is unresolved. Poll relatively frequently immediately after submission, then apply backoff. Once the swap reaches a terminal state, stop. For higher responsiveness, use streaming notifications while retaining historical polling as a recovery mechanism.

Can I use the STON.fi API instead of a TON indexer?

For some status questions, yes. STON.fi exposes swap status, transaction query, and transaction action-tree endpoints that understand STON.fi operations. A generic TON indexer is still useful when you need raw trace visibility, independent verification, historical analysis, or debugging outside STON.fi-specific abstractions.

How should I track an Omniston swap?

Use Omniston's native trade tracking when possible. Its SDK tracking accepts the quote ID, trader wallet address, and outgoing transaction hash and provides trade-specific lifecycle information. A TON indexer can then serve as an additional on-chain verification and debugging layer.

What is the safest way to display STON.fi swap status?

Use several stages rather than jumping directly from "sent" to "success": record the wallet submission, locate the transaction, wait for the trace to finish, and then verify the STON.fi-specific outcome. That model reflects TON's asynchronous execution much more accurately and produces a status UI that remains useful when something goes wrong.

Sources and Further Reading

STON.fi DEX API Reference - official REST endpoints for swap status, transaction resolution, and STON.fi action trees
STON.fi Omniston Swap Overview - official description of Omniston swap execution and the trade.track lifecycle
STON.fi Omniston React SDK - official SDK guidance for tracking an initiated Omniston trade
TON Center API v3 Overview - official description of TON's indexed API layer and available trace and action endpoints
TON Center Get Traces - official reference for querying traces by transaction, message, or trace identifiers
TON Connect Message Lookup - official guidance for identifying transactions from messages returned after wallet submission
TON Traces - explanation of how related messages and transactions form a TON execution trace
TON Center Streaming API - official documentation for real-time transaction, action, and trace monitoring

How to Decode a STON.fi Swap Transaction

Ivan “Crypto Vazima” Zimanov — Sun, 16 Aug 2026 06:59:27 +0000

How to read the TON trace behind a swap, identify the STON.fi contracts involved, and verify what actually happened on-chain.

Decoding a STON.fi swap is less about finding one transaction and more about reconstructing a sequence of messages. TON uses an asynchronous execution model, so a swap that looks like one action in the STON.fi interface can produce several transactions across a wallet, jetton wallets, the STON.fi Router, a liquidity pool, and other contracts.

The practical method is simple: start from the transaction initiated by your wallet, open its full trace, identify each contract, decode the important message bodies, and follow the asset flow until the output tokens reach their destination.

Start with the trace, not a single transaction

If you come from Ethereum, the word "transaction" can create the wrong mental model.

An Ethereum swap commonly appears as one transaction containing multiple contract calls. TON works differently. A TON transaction records the processing of a message and the resulting state change on one account. When that account sends messages to other accounts, those messages trigger additional transactions.

The connected sequence is called a trace. TON documentation describes traces as causally connected messages, with explorers usually displaying transactions as nodes and messages as edges.

That distinction matters immediately when investigating a STON.fi swap. Seeing a successful transaction on your wallet contract does not necessarily tell you that the entire swap finished successfully. It tells you that one part of the trace was processed.

Think about the operation as three different layers:

Interface action: You select two assets, review a quote, and approve a swap.
Blockchain trace: Multiple accounts process messages and send new messages.
Human-readable interpretation: An explorer or indexer groups those low-level events into labels such as token transfer or swap.

The third layer is useful, but it is not the blockchain itself. TON's API documentation explicitly notes that higher-level "actions" are classifications produced by indexer logic rather than objects stored directly on-chain.

For serious debugging, read both the convenient interpretation and the underlying trace.

What should you collect before decoding?

You usually need one reliable starting point.

That may be the transaction displayed by your wallet, the transaction linked by the application, or the wallet address and approximate time when you approved the swap. Developers may also have a query ID or the external message hash.

TON explorers can expose transaction history, messages, fees, execution phases, traces, contract information, and token activity. That makes an explorer the natural first tool for manual investigation.

STON.fi also exposes transaction-oriented API methods. Its API reference includes endpoints for resolving a transaction, checking swap status, and returning the STON.fi actions triggered by an originating transaction.

Before digging into individual cells, write down what you already expect:

the wallet that initiated the swap
the token you offered
the approximate input amount
the token you expected to receive
the expected or minimum output
the approximate execution time

These facts give you anchors. If the trace contains dozens of addresses, you do not have to understand every one immediately. You can follow the assets and identify the important contracts first.

Which accounts matter in a STON.fi swap?

A simple jetton-to-jetton swap can involve more contracts than its interface suggests because jettons themselves use distributed wallet contracts.

Under the TON jetton standard, each holder has a separate jetton wallet contract for a particular token. The jetton master represents the asset, while individual jetton wallets maintain balances and process transfers.

For a basic STON.fi swap, these are the main actors to look for:

Actor	What it does	What to inspect
Your TON wallet	Starts the operation	Initial message and destination
Your offer jetton wallet	Sends the input tokens	Transfer amount and destination
Router side	Receives the token transfer and routes the swap	Transfer notification and swap payload
STON.fi Pool	Executes the AMM exchange	Swap message, output conditions, execution result
Router payout side	Coordinates the output transfer	`pay_to` and outgoing token movement
Your ask jetton wallet	Receives output tokens	Final token balance change

STON.fi describes the Router as the entry point for DEX calls. For jetton operations, it receives the relevant jetton notification and routes the operation toward the appropriate pool. The Pool handles swap logic and returns the result for settlement.

Do not identify contracts only by friendly explorer labels. When accuracy matters, compare their addresses and message behavior with the documented STON.fi architecture.

Message op codes turn the trace into a readable story

Raw TON messages contain serialized data rather than English instructions. One of the fastest ways to understand them is to inspect the operation code at the beginning of the message body.

An op code tells a contract which operation the message is requesting.

Several identifiers are especially useful when following a STON.fi jetton swap:

Message or payload	Identifier	What it tells you
Jetton `transfer`	`0x0f8a7ea5`	A jetton wallet has been asked to transfer tokens
Jetton `transfer_notification`	`0x7362d09c`	The receiving owner is being notified about the transferred jettons
STON.fi v2 `swap` payload	`0x6664de2a`	The transferred tokens are intended for a swap
STON.fi v2 `pay_to`	`0x657b54f5`	The Router is being instructed to perform settlement
Jetton `excesses`	`0xd53276db`	Remaining attached TON is being returned

The standard jetton values come from TEP-74, while STON.fi publishes its own DEX v2 operation code reference.

You do not need to memorize these numbers. Their value is diagnostic. If an explorer exposes raw or decoded message bodies, the op code lets you verify that a message really represents the operation you think it does.

A friendly label saying "Swap" is useful. A matching STON.fi swap payload inside the expected part of the trace is stronger evidence.

Following one jetton-to-jetton swap from start to finish

Consider a simple case: you swap Token A for Token B through a STON.fi liquidity pool.

The exact trace can vary depending on contract versions, token implementation, wallet deployment state, routing, and other parameters. Still, the basic asset flow gives you a reliable framework.

1. Your wallet starts the operation

A STON.fi frontend can use TON Connect to ask your wallet to send the required blockchain message. TON Connect itself does not take possession of your private keys. It establishes the wallet connection and lets the dApp request transaction signing.

In the explorer, begin at your wallet transaction.

Ask:

Where did the outgoing message go?
How much TON was attached?
Is there a payload?
Does the destination correspond to the expected jetton wallet or swap entry path?

For a jetton input, the first relevant contract is commonly your wallet for Token A rather than the liquidity pool itself.

2. Your offer jetton wallet moves Token A

TON jetton transfers are message chains of their own.

The standard transfer request tells your jetton wallet how many tokens to send and where they should go. The jetton wallet updates its balance and causes the receiving side's jetton wallet to receive the transferred amount. If forwarding is requested, a transfer_notification can then reach the owner of that receiving jetton wallet.

At this point, check the jetton amount, not only the TON attached to the internal message.

A common decoding mistake is to see a small TON value traveling with the message and assume it represents the size of the trade. For jetton swaps, the trade amount is encoded in the jetton operation. Attached TON is also used to fund execution and message forwarding.

3. The STON.fi Router recognizes the swap request

The Router is where the generic jetton transfer becomes a DEX operation.

STON.fi's Router documentation describes handling transfer_notification messages and forwarding swap requests to the appropriate Pool. STON.fi's v2 swap documentation also defines the swap payload that accompanies the token transfer.

This part of the trace is especially useful for debugging.

You want to establish that:

the correct input token arrived
the expected amount was recognized
the payload requested a swap
the request was routed to the intended pool

If the trace never reaches the expected Pool, the failure happened before actual AMM execution.

4. The Pool executes the exchange

The Pool is the point where the input becomes an output amount according to the pool's state and swap rules.

STON.fi's v2 Pool specification includes swap-related parameters such as the minimum output and receiver information. After successful execution, the Pool can send the swap result toward the Router for settlement through the documented payout flow.

When examining the Pool transaction, check more than whether an explorer colors it green.

Look for:

successful compute and action phases
no relevant bounce or error downstream
the output amount
the receiver
whether the minimum output condition was satisfied

This is often the most informative transaction in the entire trace because it connects the trade request with the resulting amount.

5. The Router settles the output

After the Pool calculates the result, the output still has to reach you.

STON.fi documents the pay_to operation on the Router. This operation initiates the required jetton transfer from the Router side during swap settlement.

You can now follow Token B in the opposite direction from the input:

Pool result -> Router settlement -> output jetton transfer -> your Token B jetton wallet

If you lose the trail in a large trace, search for the expected output jetton and receiver address.

6. Your destination jetton wallet receives Token B

The strongest practical confirmation is the final asset movement.

Find the transaction that credits the Token B jetton wallet owned by your receiving address. Confirm the token identity and amount rather than relying only on a high-level "swap successful" label.

The trace may continue with excess TON refunds or other bookkeeping messages after the economic result of the swap is already clear. The jetton standard defines an excesses message specifically for returning remaining TON associated with an operation.

How do you prove the swap actually succeeded?

A green first transaction is not enough.

TON's asynchronous model allows one contract to process its message successfully while a later part of the trace encounters a different outcome. A swap should therefore be verified end to end.

A strong verification uses several signals together:

The input moved: the correct quantity of the offer jetton left your jetton wallet.
The Router received the intended operation: the relevant notification and STON.fi payload are visible.
The Pool processed the swap: the pool-side transaction completed as expected.
No later failure invalidated the intended path: inspect bounced or failed messages when present.
The output moved: the correct ask jetton was transferred toward your receiver.
The destination balance changed: your output jetton wallet received the resulting tokens.

STON.fi's API provides another convenient layer. Its swap status and transaction action endpoints can help summarize what the protocol recognized, while the raw trace remains the source for inspecting individual TON transactions and messages.

This combination is much more reliable than reading only the first or last line shown by a wallet.

Do not confuse attached TON with swap value or total fees

TON messages frequently carry TON because downstream contracts need funds to execute and send further messages.

That TON can move through several contracts during one trace. Some may pay transaction and forwarding fees, and unused amounts may later return as excesses.

TON's documentation describes this carry-value pattern: incoming value becomes part of the receiving contract balance, and contracts use message modes and reserve logic to fund subsequent execution.

So when you see several internal transfers such as 0.05 TON, 0.03 TON, or smaller amounts, do not simply add them together and call the result the swap fee.

Instead, separate three things:

The asset being traded, such as a jetton amount.
TON attached for execution, which can continue through the trace.
Actual blockchain fees, recorded for the individual transactions.

TON transactions expose their own fee information, and a multi-contract trace contains multiple transactions.

For a technical investigation, inspect the fee fields rather than estimating cost from visible message values.

Use the STON.fi action tree and raw trace together

There are two useful ways to decode the same swap.

The raw TON view answers questions such as:

Which account processed this message?
What was the incoming body?
Which messages did it create?
What were the exit results?
How much TON was attached?
Which token wallet received the output?

The STON.fi protocol view answers the higher-level question: what STON.fi actions were triggered by the originating transaction?

STON.fi's REST API includes POST /v1/transaction/action_tree, which returns a flattened list of STON.fi actions and their statuses triggered by an originating transaction. The API reference also documents transaction resolution and swap-status functionality.

For most investigations, use both.

Start with the action tree to understand the likely story. Then use the blockchain trace to prove each important part of that story.

That approach is faster than manually decoding every cell from the beginning, but it does not make you dependent on an indexer's interpretation.

A compact STON.fi swap decoding checklist

When inspecting an unfamiliar swap, work through these checks in order:

Find the complete trace, not just your wallet transaction.
Identify the token wallets, Router, Pool, and final receiver.
Follow the offer asset, from your balance toward STON.fi.
Inspect the swap payload and Pool transaction, including output conditions.
Follow the ask asset, from settlement to your receiving jetton wallet.
Review failures, bounces, excesses, and fees only after the main asset path is clear.

If the trace is complicated, ignore unrelated branches initially. The central question is always the same: where did the input asset go, what contract converted it, and where did the output asset arrive?

Once those three points are established, op codes, query IDs, fees, and excess messages become supporting evidence rather than noise.

Frequently Asked Questions

Does a STON.fi swap have one transaction hash?

Not necessarily in the sense Ethereum users usually expect. A TON transaction describes a state change on one account after processing a message. A STON.fi swap can involve several such transactions connected through internal messages. The useful object to inspect is therefore the full trace that begins with the wallet operation and continues through the contracts involved in the swap.

Why does my STON.fi swap contain so many transactions?

Because TON smart contracts communicate asynchronously. Your wallet, jetton wallets, Router, Pool, and destination token wallet can each process separate messages and therefore generate separate transactions. Additional transactions may appear for wallet deployment, refunds, excess TON, or other execution details. A long trace does not by itself indicate that anything went wrong.

Can I identify a STON.fi swap from its op code?

An op code is strong evidence, but it should not be your only check. STON.fi documents protocol-specific swap operation identifiers, while TON's jetton standard defines codes for transfers and notifications. Confirm the op code together with the contract address, message direction, token identities, amounts, and surrounding trace.

How do I know whether the swap really delivered my tokens?

Follow the output asset until the receiving jetton wallet is credited. Also confirm that the Pool and settlement transactions completed without a downstream failure that prevented the expected payout. A successful initiating wallet transaction alone is weaker evidence than seeing the actual output token movement in the trace.

Why is the TON amount in an internal message different from my swap amount?

For jetton swaps, the amount being traded is encoded as a jetton amount. TON attached to messages is also used to pay for contract execution and forwarding through the trace. Some unused TON can later be returned. Treat attached TON, jetton quantities, and blockchain fees as separate values when decoding the operation.

Does a TON-to-jetton swap have exactly the same trace?

No. Native TON requires a different token path from an ordinary jetton-to-jetton exchange, so the exact contracts and messages can differ. STON.fi provides dedicated TON-to-jetton and jetton-to-TON swap methods in its DEX tooling. The same decoding principle still works: identify the input path, find the Pool execution, then follow the output to its final owner.

What is the fastest way to decode a STON.fi swap transaction?

Start with the full TON trace, identify the offer and ask token flows, and compare what you see with STON.fi's transaction action tree. Use friendly explorer labels to navigate quickly, but verify important conclusions from contract addresses, message bodies, op codes, amounts, and the final token transfer. That gives you both a readable summary and low-level confirmation.

Sources and Further Reading

STON.fi DEX v2 Swap Examples - official message-flow examples for swaps and multi-step execution
STON.fi DEX v2 Op Codes - official reference for STON.fi smart contract operation identifiers
STON.fi Router v2 - official documentation for Router message handling and settlement operations
STON.fi Pool v2 - official documentation for Pool state and swap-related operations
STON.fi API Reference - transaction resolution, swap status, and transaction action tree endpoints
TON Messages and Transactions Overview - explains how messages, account transactions, fees, and traces relate
TON Traces - official explanation of causal message traces and their representation in explorers
TON Jetton Standard - overview of jetton masters and per-owner jetton wallet contracts
TON Connect Send Transaction - official documentation for wallet transaction requests from dApps

DEV Community: Ivan “Crypto Vazima” Zimanov

How to Reuse an Existing TON Connect Instance with Omniston Widget Integrated Mode

Why reuse the connection instead of creating another one?

What integrated mode actually does

The practical difference

Reuse a TonConnect SDK instance

Keep the instance at the application level

One useful rule

What about TonConnectUI and React?

Remember the client lifecycle

What happens to an already connected wallet?

A complete integrated example

Common mistakes when switching to integrated mode

Frequently Asked Questions

What is integrated TON Connect mode in the Omniston Widget?

When should I use integrated instead of standalone mode?

Can I create one TON Connect instance for my app and another for Omniston?

Can Omniston integrated mode use TonConnectUI?

Should Omniston call restoreConnection() itself?

Does the TON Connect manifest still matter in integrated mode?

Can I use integrated mode in Next.js?

What should I verify before shipping an Omniston integrated-mode integration?

Sources and Further Reading

How to Configure Standalone TON Connect Mode in the Omniston Widget

What standalone mode actually does

Prepare the TON Connect manifest first

Load the Omniston Widget

Configure standalone TON Connect mode

The CDN version is even smaller

When standalone becomes the wrong mode

Following one standalone swap from page load to signing

What to test before shipping

Frequently Asked Questions

What is standalone TON Connect mode in the Omniston Widget?

Do I need to install @tonconnect/sdk for standalone mode?

What fields does the TON Connect manifest need?

Can I use standalone mode in a React application?

Can standalone mode and another TON Connect instance run together?

Does standalone mode mean users do not need to approve swaps?

Can I use standalone mode without npm?

What should I check first if the Omniston Widget cannot connect a TON wallet?

Sources and Further Reading

How to Load the Omniston Widget with @ston-fi/omniston-widget-loader

Why does Omniston use a loader package?

What actually happens when you call load()?

Install the loader and mount your first widget

Choose the right TON Connect mode

Standalone mode

Integrated mode

Following one loader-based STON.fi integration

A compact debugging checklist

Control mounting, unmounting, and runtime behavior

Loader or direct CDN script?

What should you verify before shipping?

Frequently Asked Questions

What is @ston-fi/omniston-widget-loader?

Does npm install @ston-fi/omniston-widget-loader install the complete widget?

Do I need to import the Omniston Widget CSS separately?

Should I use standalone or integrated TON Connect mode?

Can I lazy-load the Omniston Widget?

What does load() return?

Can I remove the widget after mounting it?

When should I use the loader instead of the CDN script?

Sources and Further Reading

How to Embed the Omniston Widget with a CDN Script

What the CDN integration actually does

What you need before adding the widget

The smallest working CDN example

What happens after the widget is mounted

CDN script or npm loader?

Configure the assets shown to users

Add referral fees only if you need them

Make the widget fit your interface

Control mounting and catch errors

Frequently Asked Questions

Can I use the Omniston Widget without npm?

Do I need the Omniston SDK as well?

Why does the URL contain /v0/?

Does the CDN method automatically connect the wallet?

Why does my TON Connect manifest fail even though the URL exists?

Reuse a `TonConnect` SDK instance

What about `TonConnectUI` and React?

Can Omniston integrated mode use `TonConnectUI`?

Should Omniston call `restoreConnection()` itself?

Do I need to install `@tonconnect/sdk` for standalone mode?

What actually happens when you call `load()`?

What is `@ston-fi/omniston-widget-loader`?

Does `npm install @ston-fi/omniston-widget-loader` install the complete widget?

Should I use `standalone` or `integrated` TON Connect mode?

What does `load()` return?

Why does the URL contain `/v0/`?

Does `sendTransaction()` succeeding mean my STON.fi swap succeeded?

Can I use TON's `estimateFee` API for a STON.fi swap?

What is `forwardGas` in a STON.fi simulation?

For developers, use `minAskUnits` from the simulation

What is `min_out` on STON.fi?

What is `minAskUnits` in the STON.fi API?