@swapcoffee/ui-sdk embeds the swap.coffee DEX aggregator — best-price routing across every major TON liquidity source — directly into your web app as a self-contained, themeable widget. Install it, mount it into a container element, and your users can swap, DCA, and place limit orders without leaving your product.

Framework-agnostic. Ships as a single ESM/CJS bundle with TypeScript types and styles included — works with React, Vue, Angular, Svelte, or plain HTML.

Migrating from @swap-coffee/ui-sdk? The package moved to @swapcoffee/ui-sdk (no hyphen). Just update the dependency name — version numbers are unchanged, so your pinned version still resolves.

Table of contents

• Features
• Installation
• Quick start
• Wallet connection modes
• Configuration
• Enums
• Theming
• Localization
• Events
• Build & browser notes
• Documentation
• License

Features

• Four swap surfaces in one widget — single swap, multi-swap (split routing), DCA, and limit orders.
• Best-price aggregation across TON liquidity sources — DeDust, STON.fi (v1 & v2), Coffee, Tonco, Torch Finance, Colossus, Tonstakers, TonRaffles, Moon, BidAsk.
• Two wallet connection modes — TonConnect, or a pre-signed payload for server-driven/read-only flows.
• Three built-in themes — light, dark, coffee — isolated via Shadow DOM (no CSS leakage in or out).
• Six locales — English, Russian, Ukrainian, Spanish, French, Persian.
• Monetization hooks — referral tag and custom fee / revenue-share settings.
• Token controls — community-token toggle, jetton allow-lists, liquidity-source filtering, preset amounts and pairs.
• Single importable file — CSS injected into the JS bundle, TypeScript declarations included.

Installation

npm install @swapcoffee/ui-sdk
# or
pnpm add @swapcoffee/ui-sdk
# or
yarn add @swapcoffee/ui-sdk

The widget connects wallets through TonConnect; for the default tonConnect mode you'll also use @tonconnect/ui.

Quick start

Add a container element to your page:

<div id="swap-widget-component"></div>

Then mount the widget into it:

import { createSwapWidget, SWAP_WIDGET_THEME, SWAP_WIDGET_LOCALE } from '@swapcoffee/ui-sdk';
import { TonConnectUI } from '@tonconnect/ui';

const tonConnectUi = new TonConnectUI({
  manifestUrl: 'https://your-app.com/tonconnect-manifest.json',
});

await createSwapWidget('#swap-widget-component', {
  injectionMode: 'tonConnect',
  theme: SWAP_WIDGET_THEME.DARK,
  locale: SWAP_WIDGET_LOCALE.EN,
  tonConnectUi,
  tonConnectManifest: { url: 'https://your-app.com/tonconnect-manifest.json' },
  widgetReferral: 'your-referral-tag',
});

createSwapWidget(selector, options) is async — it lazy-loads the active locale before mounting. selector is any CSS selector for your container element.

Wallet connection modes

Set with injectionMode. Each mode has its own required options.

tonConnect (recommended)

For apps already using TonConnect. Pass your TonConnectUI instance and manifest; the widget subscribes to wallet-status changes.

await createSwapWidget('#swap-widget-component', {
  injectionMode: 'tonConnect',
  tonConnectUi,                                    // required
  tonConnectManifest: { url: '…/tonconnect-manifest.json' }, // required
});

Configuration

All options are defined by DefaultSettingsInterface:

| Option | Type | Default | Description | | --- | --- | --- | --- | | injectionMode | 'tonConnect' \| 'payload' | 'tonConnect' | Wallet connection mode. Required. | | theme | SWAP_WIDGET_THEME | 'dark' | UI theme — light / dark / coffee. | | locale | SWAP_WIDGET_LOCALE | 'en' | UI language. | | tonConnectUi | TonConnectUI | — | TonConnect UI instance. Required for tonConnect. | | tonConnectManifest | { url: string } | — | TonConnect manifest URL. Required for tonConnect. | | payload | PayloadConnectionInterface | — | Pre-signed wallet payload. Required for payload. | | widgetReferral | string \| null | null | Referral tag attached to swaps. | | customFeeSettings | CustomFeeSettingsInterface | all null | Custom fee / revenue-share configuration. | | limitDcaVisibility | boolean | env default | Show the Limit and DCA tabs. | | liquiditySourcesList | SWAP_WIDGET_LIQUIDITY_SOURCES[] \| null | null (all) | Restrict routing to specific DEXes. | | limitedJettonLists | string[] \| null | null | Restrict selectable tokens to these jetton addresses. | | sendReceiveTokenAddresses | string[] \| null | null | Preset the from/to token pair by address. | | firstTokenAmount | number | 0 | Prefill the "you pay" amount. | | enableCommunityTokens | boolean | env default | Allow community (unverified) tokens. |

customFeeSettings (CustomFeeSettingsInterface):

| Field | Type | Description | | --- | --- | --- | | percentage_fee | number \| null | Percentage fee in basis points (e.g. 3000 = 0.3%). | | min_percentage_fee_fixed | string \| null | Minimum fee, in nano units. | | max_percentage_fee_fixed | string \| null | Maximum fee, in nano units. | | fixed_fee | number \| null | Optional flat fee. |

Theming

Pass theme and the widget applies a theme-{light|dark|coffee} class inside its Shadow DOM, so its styles never leak into — or inherit from — your page. Control the widget's size and position by styling the container element you mount into.

Localization

Set locale to any supported language and the matching message bundle is lazy-loaded before mount. Supported: en, ru, ua, es, fr, fa.

Events

The widget dispatches DOM events to the host page (for example, wallet connected / disconnected) so your application can react to widget state. See the documentation for the full event catalog.

Build & browser notes

• Ships ESM (dist/swap-sdk.esm.js) and CJS (dist/swap-sdk.cjs.js) with bundled TypeScript declarations.
• Styles are bundled into the JS — there is no separate CSS import.
• Built on TON tooling (@ton/core, TonConnect). In browser bundlers you may need Node polyfills (Buffer / global), as is standard for TON apps.

Documentation

Full integration guide: docs.swap.coffee › Aggregator Widget

License

MIT © 2025–2026 swap.coffee