How to Configure Standalone TON Connect Mode in the Omniston Widget

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:

1. Host the manifest.
2. Load the widget.
3. Set tonconnect.type to standalone.
4. Pass manifestUrl.
5. Mount the widget.
6. 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

Comments

[Ivan “Crypto Vazima” Zimanov]

Hello. If you find an error in the text or code, please write about it in the comments. This will greatly help others who read this article and encounter the same problems. Thank you very much in advance.