# STON.fi (swap) Widget
The STON.fi 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:
{% embed url="" %}
### Integrate it yourself
If you want to integrate the widget yourself, continue reading below.
Two ways to embed:
1. **Via NPM loader** (for modern builds): Let the loader fetch the optimized bundle at runtime.
2. **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](https://www.npmjs.com/package/@ston-fi/omniston-widget-loader/v/latest)) – npm package that downloads the CDN bundle when you call `load()`.
* **CDN script** – zero-build option that exposes `window.OmnistonWidget` in modern browsers:
```html
```
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
1. Host your [TON Connect manifest](https://docs.ton.org/v3/guidelines/ton-connect/creating-manifest) on your domain.
2. Choose CDN (no build) or npm (frameworks).
3. Paste one snippet to mount the widget; see [Full Guide](https://docs.ston.fi/developer-section/widget/widget) for full examples.
**Option A — CDN (no build)**
```html
STON.fi (swap) Widget via CDN
```
**Option B — npm (React, integrated TON Connect UI)**
```tsx
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(null);
const widgetRef = useRef(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 (
STON.fi (swap) Widget
);
}
export default function App() {
return (
);
}
```
See [Full Guide](https://docs.ston.fi/developer-section/widget/widget) for full CDN, React, and vanilla examples.
## Visual Widget Constructor
**Quick customization without code:** Use our visual widget constructor at [widget.ston.fi/constructor](https://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](https://docs.ston.fi/developer-section/omniston/referral-fees) 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](https://docs.ston.fi/developer-section/widget#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](https://docs.ston.fi/developer-section/widget#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](https://docs.ston.fi/developer-section/widget/widget).
### Advanced capabilities
CDN distribution is also available as a zero-build option; see the [CDN distribution section](https://docs.ston.fi/developer-section/widget#cdn-distribution-no-bundler-required) in [Advanced: lifecycle events and manual mount/unmount](https://docs.ston.fi/developer-section/widget#advanced-lifecycle-events-and-manual-mount-unmount) for implementation details.
## Next Steps
* [Full Guide](https://docs.ston.fi/developer-section/widget/widget) – Comprehensive installation, configuration, CDN usage, TON Connect wiring, referral fees, theming, and lifecycle events.
