DEV Community

Cover image for How to Embed the Omniston Widget with a CDN Script
Ivan “Crypto Vazima” Zimanov
Ivan “Crypto Vazima” Zimanov

Posted on

How to Embed the Omniston Widget with a CDN Script

#javascript #tutorial #web3 #webdev

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

What the CDN integration actually does

The essential script is only one line:

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

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

window.OmnistonWidget
Enter fullscreen mode Exit fullscreen mode

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:

  1. Load the CDN script.
  2. Create an OmnistonWidget instance.
  3. Pass the TON Connect configuration.
  4. Find the container where the widget should appear.
  5. 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

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"
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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

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:

  1. The visitor opens your page.
  2. The CDN bundle creates the swap interface.
  3. The visitor chooses the assets and amount.
  4. TON Connect handles wallet connectivity.
  5. Omniston obtains swap quotes from its available liquidity sources.
  6. The visitor reviews the resulting swap and authorizes the required transaction through the wallet.
  7. 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?

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

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>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

STON.fi provides a visual widget constructor at:

https://widget.ston.fi/constructor
Enter fullscreen mode Exit fullscreen mode

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

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");
});
Enter fullscreen mode Exit fullscreen mode

You can also remove the component:

widget.unmount();
Enter fullscreen mode Exit fullscreen mode

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

Top comments (1)

Collapse
 
ivan_cryptovazimazima profile image
Ivan “Crypto Vazima” Zimanov •

Hi. If you find any errors in the text or code, please leave them in the comments. This will help future readers. Thank you very much for your support.