npm.io
1.4.4 • Published 21h ago

@swapcoffee/ui-sdk

Licence
MIT
Version
1.4.4
Deps
17
Size
9.4 MB
Vulns
0
Weekly
0
Stars
3
SummaryDependencyVersions

swap.coffee logo

@swapcoffee/ui-sdk

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

npm version npm downloads license documentation

@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

  • 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

Keywords

swapcoffeededuststonfitondex