TON Connect SDK

Use signMessage to ask a wallet to sign an internal message without broadcasting it. This is used for gasless or sponsored transactions where a dApp or relayer submits the signed BoC to the network (e.g., paying gas in Jettons instead of TON).

Key Differences from sendTransaction:

• Broadcasting: signMessage does NOT broadcast; sendTransaction DOES.
• Gas: signMessage does NOT deduct gas from the user's wallet; sendTransaction DOES.
• Result: signMessage returns an internalBoc (the signed message) which you must then wrap in an external message and submit via a relayer.

Implementation Note: To ensure users only see wallets that support this feature, initialize TonConnectUI with walletsRequiredFeatures: { signMessage: { minMessages: 1 } }.

const result = await tonConnectUI.signMessage({
    validUntil: Math.floor(Date.now() / 1000) + 300,
    network: '-239',
    messages: [
        {
            address: 'Ef8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAU',
            amount: '5000000',
            payload: bodyBoc, // base64
            stateInit: initBoc // base64
        }
    ]
});

const signedBoc = result.internalBoc; // base64 signed internal message
// Now submit signedBoc to a relayer (e.g., TonAPI gasless API)

Connecting a user involves different strategies depending on the wallet type:

1. Remote Wallets (Universal Link): Pass a source containing universalLink and bridgeUrl. The SDK returns a link that you must present to the user (e.g., via QR code or deep link).
2. Injected Wallets: Pass a source containing the jsBridgeKey.
3. Unified Link: Pass an array of sources to connector.connect(sources) to allow the SDK to handle multiple potential connection methods.
4. Embedded Wallets: If the app is running inside a wallet's browser, detect it using isWalletInfoCurrentlyEmbedded and connect immediately using the jsBridgeKey to improve UX.

// 1. Remote connection
const source = {
    universalLink: 'https://app.tonkeeper.com/ton-connect',
    bridgeUrl: 'https://bridge.tonapi.io/bridge'
};
const link = connector.connect(source);

// 2. Injected connection
connector.connect({ jsBridgeKey: 'tonkeeper' });

// 3. Unified connection
connector.connect([
    { bridgeUrl: 'https://bridge.tonapi.io/bridge' },
    { bridgeUrl: 'https://<OTHER_WALLET_BRIDGE>' }
]);

Use uiPreferences within uiOptions to adjust the visual style of the interface.

Border Radius

Supported modes are 'm' (default), 's', and 'none'. You can set this in the TonConnectUI constructor or dynamically via uiOptions.

Theme

Set the theme to THEME.LIGHT, THEME.DARK, or 'SYSTEM' (default). Import THEME from @tonconnect/ui.

Color Schemes

You can redefine colors for specific themes using colorsSet. This allows you to target [THEME.DARK] and [THEME.LIGHT] independently.

import { THEME } from '@tonconnect/ui';

// Set theme and border radius
tonConnectUI.uiOptions = {
    uiPreferences: {
        theme: THEME.DARK,
        borderRadius: 's',
        colorsSet: {
            [THEME.DARK]: {
                connectButton: {
                    background: '#29CC6A'
                }
            },
            [THEME.LIGHT]: {
                text: {
                    primary: '#FF0000'
                }
            }
        }
    }
};

The project uses changesets to manage package versions and changelogs.

For a standard release:

1. Run pnpm changeset add and select the modified packages. Choose the version type (MAJOR, MINOR, or PATCH) and write the changelog.
2. Run pnpm changeset version to update package.json and CHANGELOG.md across all affected packages.
3. Build the packages: pnpm build.
4. Publish the packages: pnpm publish -r --access=public.
5. Push changes and tags: git push origin HEAD && git push origin --tags.

For a beta release:

1. Enter beta mode: pnpm changeset pre enter beta.
2. Follow the standard release steps (add changeset, version, build).
3. Publish with the beta tag: cd packages/[package-name] && pnpm publish --access=public --tag=beta.
4. Exit beta mode: pnpm changeset pre exit.
5. Push changes and tags.

# Example: Adding a changeset
pnpm changeset add

# Example: Applying version updates
pnpm changeset version

# Example: Publishing all updated packages
pnpm publish -r --access=public

On iOS, universal links opened via window.open may fail to redirect to the wallet app if there is an asynchronous delay between the user's click and the redirect. To manage this, use the skipRedirectToWallet option.

Options

• 'ios' (default): Optimized for iOS behavior.
• 'never': Use this if your click handler performs no asynchronous calls before calling sendTransaction. This provides the best UX by allowing a synchronous redirect.
• 'always': Always skip the automatic redirect.

Usage

You can set this per-call or globally via uiOptions.

// Per-call configuration
const result = await tonConnectUI.sendTransaction(defaultTx, {
    modals: ['before', 'success', 'error'],
    notifications: ['before', 'success', 'error'],
    skipRedirectToWallet: 'ios' // 'ios', 'never', or 'always'
});

// Global configuration via uiOptions
tonConnectUI.uiOptions = {
    actionsConfiguration: {
        skipRedirectToWallet: 'ios'
    }
};

// Best practice: use 'never' if the handler is synchronous
const onClick = async () => {
    const txBody = packTxBodySynchrone();
    tonConnectUI.sendTransaction(txBody, { skipRedirectToWallet: 'never' });
    // ...
};