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 integration, zero overhead: Get started with the default configuration right away, or customize colors and token lists to match your brand. We deliver it as a CDN-hosted bundle for maximum performance.
Try it with Lovable
Want to see the widget in action quickly? Use Lovable to generate a working example:
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.jsonwith 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.
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 callload().CDN script – zero-build option that exposes
window.OmnistonWidgetin modern browsers:
<script src="https://swap.ston.fi/widget/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
widget.mdfor 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://swap.ston.fi/widget/v0/index.js"></script>
<script>
const widget = new window.OmnistonWidget({
tonconnect: {
type: 'standalone',
options: { manifestUrl: 'https://YOUR_APP_HOST/tonconnect-manifest.json' },
},
widget: {
// Optional: defaultBidAsset: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c', // TON
// Optional: defaultAskAsset: 'EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO', // STON
},
});
widget.mount('#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 manifestUrl="https://YOUR_APP_HOST/tonconnect-manifest.json">
<SwapWidget />
</TonConnectUIProvider>
);
}See widget.md for full CDN, React, and vanilla examples.
Earn fees and match your brand
Referral fees: set both
referrerAddressandreferrerFeeBpsto earn 0.01%–1% (1–100 bps) on every swap. See the Referral Fees guide for payouts and best practices.Brandable UI: override CSS custom properties on the element you pass to
widget.mount(...)to match your palette and layout; see widget.md for the full list.
Sensible Defaults or Fully Customizable Assets
The widget ships with sensible defaults and only requires your TON Connect manifest URL. For optional asset overrides and the complete configuration table, see widget.md.
Built-in Referral Fee Program
Provide referrerAddress and referrerFeeBps to earn on swaps. See widget.md and the Referral Fees guide for ranges, examples, and payout details.
Fully Customizable Theme
Override CSS custom properties on the container you pass to widget.mount(...) to align the widget with your brand. Refer to widget.md for the full variable list and styling examples.
CDN distribution is also available as a zero-build option; see the CDN distribution section in widget.md for implementation details.
Other capabilities: Lifecycle hooks, standalone and integrated TON Connect modes, TypeScript support, and more—see
widget.mdfor the complete reference.
TON Connect Integration 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 widget.md.
Next Steps
Full guide – Comprehensive installation, configuration, CDN usage, TON Connect wiring, referral fees, theming, and lifecycle events.
Last updated