Omniston Widget

Embed a swap feature and earn fees - in minutes

The Omniston Widget is a ready-to-use swap interface for your app or website. Simply embed our lightweight script, and your users get full swap functionality instantly — while you earn fees from every swap.

Quick setup, zero overhead. Start with the default configuration or customize it to match your brand. Delivered via CDN-hosted bundle for maximum performance. Looks and behaves like a native part of your UI.

Try it with Lovable

Want to see the widget in action quickly? Use Lovable to generate a working example:

🚀 Build with Lovable

Click the button above to automatically generate a working webpage with the STON.fi swap widget integrated.

⚠️ Note: If you see 'Failed to load Manifest: 404' that's because you are in Lovable website and you test it in preview mode. Publish the app, replace the URL inside manifest.json with the published URL, and then publish the app again after changes. If you're in free credit mode and can't manually change the manifest, prompt and paste the URL so the agent will replace it. Then go to the published URL to test the connection.

You can also follow along with a recorded walkthrough:

Integrate it yourself

If you want to integrate the widget yourself, continue reading below.

Two ways to embed:

Via NPM loader (for modern builds): Let the loader fetch the optimized bundle at runtime.
Direct CDN script (for simplicity): Drop one line of code into your project.

Both methods expose the same OmnistonWidget constructor, giving you full control.

@ston-fi/omniston-widget-loader (npm) – npm package that downloads the CDN bundle when you call load().
CDN script – zero-build option that exposes window.OmnistonWidget in modern browsers:

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

CDN URLs are major-versioned (/v0/, /v1/, ...). You receive all non-breaking updates within a major; bump the major path to adopt breaking changes.

Quick start in 30 seconds

Host your TON Connect manifest on your domain.
Choose CDN (no build) or npm (frameworks).
Paste one snippet to mount the widget; see Full Guide for full examples.

Option A — CDN (no build)

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Omniston Widget via CDN</title>
  </head>
  <body>
    <div id="omniston-widget-container" style="max-width: 420px; margin: 0 auto;"></div>

    <script src="https://widget.ston.fi/v0/index.js"></script>
    <script>
      const widget = new window.OmnistonWidget({
        tonconnect: {
          type: 'standalone',
          options: {
            // see https://docs.ton.org/ecosystem/ton-connect/manifest
            manifestUrl: 'https://[myapp.com]/tonconnect-manifest.json',
          },
        },
        widget: {
          // Optional: defaultBidAsset: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c', // TON
          // Optional: defaultAskAsset: 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO', // STON
        },
      });

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

Option B — npm (React, integrated TON Connect UI)

import { useEffect, useRef } from 'react';
import { TonConnectUIProvider, TonConnectButton, useTonConnectUI } from '@tonconnect/ui-react';
import omnistonWidgetLoader, { type OmnistonWidget } from '@ston-fi/omniston-widget-loader';

function SwapWidget() {
  const [tonconnect] = useTonConnectUI();
  const containerRef = useRef<HTMLDivElement | null>(null);
  const widgetRef = useRef<OmnistonWidget | null>(null);

  useEffect(() => {
    let isMounted = true;

    omnistonWidgetLoader.load().then((OmnistonWidgetConstructor) => {
      if (!isMounted || !containerRef.current || !tonconnect) return;

      widgetRef.current = new OmnistonWidgetConstructor({
        tonconnect: {
          type: 'integrated',
          instance: tonconnect,
        },
        widget: {
          defaultBidAsset: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c', // TON
          defaultAskAsset: 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO', // STON
        },
      });

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

    return () => {
      isMounted = false;
      widgetRef.current?.unmount();
      widgetRef.current = null;
    };
  }, [tonconnect]);

  return (
    <div
      style={{
        minHeight: '100vh',
        padding: '2rem',
        display: 'flex',
        flexDirection: 'column',
        gap: 16,
        alignItems: 'center',
        width: '100%',
      }}
    >
      <h1 style={{ textAlign: 'center', marginBottom: '1rem' }}>STON.fi Omniston Widget</h1>
      <div style={{ textAlign: 'center', marginBottom: '1.5rem' }}>
        <TonConnectButton />
      </div>
      <div
        ref={containerRef}
        style={{ width: '100%', maxWidth: 500, margin: '0 auto' }}
      />
    </div>
  );
}

export default function App() {
  return (
    <TonConnectUIProvider
      // see https://docs.ton.org/ecosystem/ton-connect/manifest
      manifestUrl="https://[myapp.com]/tonconnect-manifest.json"
    >
      <SwapWidget />
    </TonConnectUIProvider>
  );
}

See Full Guide for full CDN, React, and vanilla examples.

Quick customization without code: Use our visual widget constructor at widget.ston.fi/constructor to configure your widget interactively.

The constructor provides:

Theme customization — Start from light or dark and adapt to your brand
Asset list control — Use default assets, add your own, or replace the list entirely
Referral fees — Configure your referrer address and fee
Code export — Copy ready-to-use CSS and JS snippets

Prefer doing this in code? See Configure in code below.

Configure in code

All options from the visual constructor map directly to the OmnistonWidget configuration object. You control four main areas:

1. Referral fees

Set both referrerAddress and referrerFeeBps to earn 0.01%–1% (1–100 bps) on every swap. See the Referral Fees guide for payout details and best practices.

2. Asset list

The widget ships with sensible defaults and only requires your TON Connect manifest URL. For optional asset overrides and the complete configuration table, see Configuration options.

3. Theme (CSS variables)

Override CSS custom properties on the container you pass to widget.mount(...) to align the widget with your brand. Refer to Customize widget styles for the full variable list and styling examples.

4. TON Connect modes

standalone – Widget manages TON Connect with only your manifest URL.
integrated – Reuse an existing TON Connect instance from your app.

For wiring examples, warnings about multiple instances, and full configuration, see the TON Connect section in Full Guide.

Advanced capabilities

CDN distribution is also available as a zero-build option; see the CDN distribution section in Advanced: lifecycle events and manual mount/unmount for implementation details.

Next Steps

Full Guide – Comprehensive installation, configuration, CDN usage, TON Connect wiring, referral fees, theming, and lifecycle events.

PreviousReferral Fees NextFull Guide & Reference

Last updated 20 minutes ago

hashtagTry it with Lovable

hashtagIntegrate it yourself

hashtagQuick start in 30 seconds

hashtagVisual Widget Constructor

hashtagConfigure in code

hashtag1. Referral fees

hashtag2. Asset list

hashtag3. Theme (CSS variables)

hashtag4. TON Connect modes

hashtagAdvanced capabilities

hashtagNext Steps