@swapcoffee/ui-sdk

Embeddable widget for the swap.coffee DEX aggregator on TON — drop a full swap UI into any web app.

---

@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