@tonconnect/sdk reference

npm i @tonconnect/sdk

<script src="https://unpkg.com/@tonconnect/sdk@latest/dist/tonconnect-sdk.min.js"></script>

new TonConnect(options?: TonConnectOptions)

getWallets(): Promise<WalletInfo[]>;

onStatusChange(
    callback: (wallet: Wallet | null) => void,
    errorsHandler?: (err: TonConnectError) => void
): () => void;

connect<T extends WalletConnectionSource | Pick<WalletConnectionSourceHTTP, 'bridgeUrl'>[]>(
    wallet: T,
    options?: OptionalTraceable<{
        request?: ConnectAdditionalRequest;
        openingDeadlineMS?: number;
        signal?: AbortSignal;
        embeddedRequest?: ConsumableLike<EmbeddedRequest>;
    }>
): T extends WalletConnectionSourceJS ? void : T extends WalletConnectionSourceWalletConnect ? void : string;

connect<T extends WalletConnectionSource | Pick<WalletConnectionSourceHTTP, 'bridgeUrl'>[]>(
    wallet: T,
    request?: ConnectAdditionalRequest,
    options?: OptionalTraceable<{
        openingDeadlineMS?: number;
        signal?: AbortSignal;
        embeddedRequest?: ConsumableLike<EmbeddedRequest>;
    }>
): T extends WalletConnectionSourceJS ? void : T extends WalletConnectionSourceWalletConnect ? void : string;

restoreConnection(
    options?: OptionalTraceable<{ openingDeadlineMS?: number; signal?: AbortSignal }>
): Promise<void>;

sendTransaction(
    transaction: SendTransactionRequest,
    options?: OptionalTraceable<{ onRequestSent?: () => void; signal?: AbortSignal }>
): Promise<Traceable<SendTransactionResponse>>;

sendTransaction(
    transaction: SendTransactionRequest,
    onRequestSent?: () => void
): Promise<Traceable<SendTransactionResponse>>;

signData(
    data: SignDataPayload,
    options?: OptionalTraceable<{ onRequestSent?: () => void; signal?: AbortSignal }>
): Promise<Traceable<SignDataResponse>>;

signMessage(
    message: SignMessageRequest,
    options?: OptionalTraceable<{ onRequestSent?: () => void; signal?: AbortSignal }>
): Promise<Traceable<SignMessageResponse>>;

setConnectionNetwork(network?: ChainId): void;

disconnect(options?: OptionalTraceable<{ signal?: AbortSignal }>): Promise<void>;

getSessionId(): Promise<string | null>;

pauseConnection(): void;

unPauseConnection(): Promise<void>;

interface ITonConnect {
    connected: boolean;
    account: Account | null;
    wallet: Wallet | null;
    /* see TonConnect.getWallets */
    getWallets(...): Promise<WalletInfo[]>;
    /* see TonConnect.onStatusChange */
    onStatusChange(...): () => void;
    /* see TonConnect.connect */
    connect(...): T extends WalletConnectionSourceJS ? void : T extends WalletConnectionSourceWalletConnect ? void : string;
    /* see TonConnect.restoreConnection */
    restoreConnection(...): Promise<void>;
    /* see TonConnect.pauseConnection */
    pauseConnection(...): void;
    /* see TonConnect.unPauseConnection */
    unPauseConnection(...): Promise<void>;
    /* see TonConnect.setConnectionNetwork */
    setConnectionNetwork(...): void;
    /* see TonConnect.disconnect */
    disconnect(...): Promise<void>;
    /* see TonConnect.sendTransaction */
    sendTransaction(...): Promise<OptionalTraceable<SendTransactionResponse>>;
    /* see TonConnect.signData */
    signData(...): Promise<OptionalTraceable<SignDataResponse>>;
    /* see TonConnect.signMessage */
    signMessage(...): Promise<OptionalTraceable<SignMessageResponse>>;
    /* see TonConnect.getSessionId */
    getSessionId(...): Promise<string | null>;
}

new WalletsListManager(
    options?: {
        walletsListSource?: string;
        cacheTTLMs?: number;
        onDownloadDurationMeasured?: (duration: number | undefined) => void;
    }
)

getWallets(): Promise<WalletInfo[]>;

getEmbeddedWallet(): Promise<WalletInfoCurrentlyEmbedded | null>;

getRemoteWallet(appName: string): Promise<WalletInfoRemote>;

new BrowserEventDispatcher()

dispatchEvent<P extends `ton-connect-${string}` | `ton-connect-ui-${string}`>(
    eventName: P,
    eventDetails: T & { type: RemoveTonConnectPrefix<P> }
): Promise<void>;

addEventListener<P extends `ton-connect-${string}` | `ton-connect-ui-${string}`>(
    eventName: P,
    listener: (event: CustomEvent<T & { type: RemoveTonConnectPrefix<P> }>) => void,
    options?: AddEventListenerOptions
): Promise<() => void>;

new Consumable(value: ConsumableLike<T>)

peek(): T | undefined;

consume(): T | undefined;

interface IEnvironment {
    getLocale(): string;
    getBrowser(): string;
    getPlatform(): string;
    getTelegramUser(): TelegramUser | undefined;
    getClientEnvironment(): 'web' | 'miniapp' | (string & {});
}

interface DappMetadata {
    name: string;
    icon: string;
    url: string;
}

interface ConnectAdditionalRequest {
    tonProof?: string;
}

interface SendTransactionRequestBase {
    validUntil: number;
    network?: ChainId;
    from?: string;
}

interface SendTransactionRequestWithMessages {
    validUntil: number;
    network?: ChainId;
    from?: string;
    messages: { address: string; amount: string; stateInit?: string; payload?: string; extraCurrency?: { [k: number]: string } }[];
    items?: undefined;
}

interface SendTransactionRequestWithItems {
    validUntil: number;
    network?: ChainId;
    from?: string;
    items: StructuredItem[];
    messages?: undefined;
}

interface SendTransactionResponse {
    boc: string;
}

interface TonItem {
    type: 'gram';
    address: string;
    amount: string;
    payload?: string;
    stateInit?: string;
    extraCurrency?: { [k: number]: string };
}

interface JettonItem {
    type: 'jetton';
    master: string;
    destination: string;
    amount: string;
    attachAmount?: string;
    responseDestination?: string;
    customPayload?: string;
    forwardAmount?: string;
    forwardPayload?: string;
    queryId?: string;
}

interface NftItem {
    type: 'nft';
    nftAddress: string;
    newOwner: string;
    attachAmount?: string;
    responseDestination?: string;
    customPayload?: string;
    forwardAmount?: string;
    forwardPayload?: string;
    queryId?: string;
}

interface SignMessageResponse {
    internalBoc: string;
}

interface AnalyticsSettings {
    mode?: AnalyticsMode;
}

interface TonConnectOptions {
    manifestUrl?: string;
    storage?: IStorage;
    eventDispatcher?: EventDispatcher<SdkActionEvent>;
    walletsListSource?: string;
    walletsListCacheTTLMs?: number;
    walletsRequiredFeatures?: RequiredFeatures;
    disableAutoPauseConnection?: boolean;
    environment?: IEnvironment;
    analytics?: AnalyticsSettings;
}

interface Account {
    address: string;
    chain: ChainId;
    walletStateInit: string;
    publicKey?: string;
}

interface WalletConnectionSourceHTTP {
    universalLink: string;
    bridgeUrl: string;
}

interface WalletConnectionSourceJS {
    jsBridgeKey: string;
}

interface WalletConnectionSourceWalletConnect {
    type: 'wallet-connect';
}

interface WalletInfoBase {
    name: string;
    appName: string;
    imageUrl: string;
    tondns?: string;
    aboutUrl: string;
    features?: Feature[];
    platforms: ('ios' | 'android' | 'macos' | 'windows' | 'linux' | 'chrome' | 'firefox' | 'safari')[];
}

interface WalletInfoRemote {
    name: string;
    appName: string;
    imageUrl: string;
    tondns?: string;
    aboutUrl: string;
    features?: Feature[];
    platforms: ('ios' | 'android' | 'macos' | 'windows' | 'linux' | 'chrome' | 'firefox' | 'safari')[];
    universalLink: string;
    deepLink?: string;
    bridgeUrl: string;
}

interface WalletInfoInjectable {
    name: string;
    appName: string;
    imageUrl: string;
    tondns?: string;
    aboutUrl: string;
    features?: Feature[];
    platforms: ('ios' | 'android' | 'macos' | 'windows' | 'linux' | 'chrome' | 'firefox' | 'safari')[];
    jsBridgeKey: string;
    injected: boolean;
    embedded: boolean;
}

interface WalletInfoCurrentlyInjected {
    name: string;
    appName: string;
    imageUrl: string;
    tondns?: string;
    aboutUrl: string;
    features?: Feature[];
    platforms: ('ios' | 'android' | 'macos' | 'windows' | 'linux' | 'chrome' | 'firefox' | 'safari')[];
    jsBridgeKey: string;
    embedded: boolean;
    injected: true;
}

interface WalletInfoCurrentlyEmbedded {
    name: string;
    appName: string;
    imageUrl: string;
    tondns?: string;
    aboutUrl: string;
    features?: Feature[];
    platforms: ('ios' | 'android' | 'macos' | 'windows' | 'linux' | 'chrome' | 'firefox' | 'safari')[];
    jsBridgeKey: string;
    injected: true;
    embedded: true;
}

interface WalletInfoInjected {
    name: string;
    appName: string;
    imageUrl: string;
    tondns?: string;
    aboutUrl: string;
    features?: Feature[];
    platforms: ('ios' | 'android' | 'macos' | 'windows' | 'linux' | 'chrome' | 'firefox' | 'safari')[];
    jsBridgeKey: string;
    injected: boolean;
    embedded: boolean;
}

interface Wallet {
    device: DeviceInfo;
    provider: 'http' | 'injected';
    account: Account;
    connectItems?: { tonProof?: TonProofItemReply };
    embeddedResponse?: EmbeddedResponse;
}

interface IStorage {
    setItem(key: string, value: string): Promise<void>;
    getItem(key: string): Promise<string | null>;
    removeItem(key: string): Promise<void>;
}

interface EventDispatcher {
    dispatchEvent<P extends `ton-connect-${string}` | `ton-connect-ui-${string}`>(
        eventName: P,
        eventDetails: T & { type: RemoveTonConnectPrefix<P> }
    ): Promise<void>;
    addEventListener<P extends `ton-connect-${string}` | `ton-connect-ui-${string}`>(
        eventName: P,
        listener: (event: CustomEvent<T & { type: RemoveTonConnectPrefix<P> }>) => void,
        options?: AddEventListenerOptions
    ): Promise<() => void>;
}

type AnalyticsMode = 'off' | 'telemetry' | 'full';

type TelegramUser = { id: number; isPremium: boolean };

type EmbeddedRequest =
    | { method: 'sendTransaction'; request: SendTransactionRequest }
    | { method: 'signData'; request: SignDataPayload }
    | { method: 'signMessage'; request: SignMessageRequest };

type SendTransactionRequest = SendTransactionRequestWithMessages | SendTransactionRequestWithItems;

type StructuredItem = TonItem | JettonItem | NftItem;

type SignDataResponse = { signature: string; address: string; timestamp: number; domain: string; payload: SignDataPayload };

type SignMessageRequest = SendTransactionRequest;

type RequiredFeatures = {
    sendTransaction?: RequiredSendTransactionFeature;
    signData?: RequiredSignDataFeature;
    signMessage?: RequiredSignMessageFeature;
    embeddedRequest?: RequiredEmbeddedRequestFeature;
};

type RequiredSendTransactionFeature = { minMessages?: number; extraCurrencyRequired?: boolean; itemTypes?: StructuredItemType[] };

type RequiredSignDataFeature = { types: SignDataType[] };

type RequiredSignMessageFeature = { minMessages?: number; extraCurrencyRequired?: boolean; itemTypes?: StructuredItemType[] };

type RequiredEmbeddedRequestFeature = {};

type WalletConnectionSource = WalletConnectionSourceHTTP | WalletConnectionSourceJS | WalletConnectionSourceWalletConnect;

type WalletInfo = WalletInfoRemote | WalletInfoInjectable | (WalletInfoRemote & WalletInfoInjectable);

type EmbeddedResponse =
    | { ok: true; result: SendTransactionResponse | SignDataResponse | SignMessageResponse }
    | { ok: false; error: { code: number; message: string; data?: unknown } };

type WalletConnectMetadata = { name: string; description: string; url: string; icons: string[] };

type WalletConnectOptions = { projectId: string; metadata: WalletConnectMetadata };

type RemoveTonConnectPrefix<T> = T extends `ton-connect-ui-${infer Rest}` ? Rest : T extends `ton-connect-${infer Rest}` ? Rest : T;

type AddTonConnectPrefix<T extends string> = `ton-connect-${T}` | `ton-connect-ui-${T}`;

type RequestVersionEvent = { type: 'request-version' };

type ResponseVersionEvent = { type: 'response-version'; version: string };

type VersionEvent = RequestVersionEvent | ResponseVersionEvent;

type Version = { ton_connect_sdk_lib: string | null; ton_connect_ui_lib: string | null };

type SessionInfo = { clientId: string | null; walletId: string | null };

type AuthType = ConnectItem['name'];

type ConnectionInfo = {
    wallet_address: string | null;
    wallet_state_init: string | null;
    wallet_type: string | null;
    wallet_version: string | null;
    auth_type: AuthType;
    custom_data:
        & {
            chain_id: string | null;
            provider: 'http' | 'injected' | null;
            client_id: string | null;
            wallet_id: string | null;
        }
        & Version;
};

type ConnectionStartedEvent = { type: 'connection-started'; custom_data: Version; trace_id?: string | null };

type ConnectionCompletedEvent = { type: 'connection-completed'; is_success: true; trace_id?: string | null } & ConnectionInfo;

type ConnectionErrorEvent = {
    type: 'connection-error';
    is_success: false;
    error_message: string;
    error_code: CONNECT_EVENT_ERROR_CODES | null;
    custom_data: { client_id: string | null; wallet_id: string | null } & Version;
    trace_id?: string | null;
};

type ConnectionEvent = ConnectionStartedEvent | ConnectionCompletedEvent | ConnectionErrorEvent;

type ConnectionRestoringStartedEvent = { type: 'connection-restoring-started'; custom_data: Version; trace_id?: string | null };

type ConnectionRestoringCompletedEvent =
    & { type: 'connection-restoring-completed'; is_success: true; trace_id?: string | null }
    & ConnectionInfo;

type ConnectionRestoringErrorEvent = {
    type: 'connection-restoring-error';
    is_success: false;
    error_message: string;
    custom_data: Version;
    trace_id?: string | null;
};

type ConnectionRestoringEvent = ConnectionRestoringStartedEvent | ConnectionRestoringCompletedEvent | ConnectionRestoringErrorEvent;

type TransactionMessage = { address: string | null; amount: string | null };

type TransactionFullMessage = { address: string | null; amount: string | null; payload: string | null; state_init: string | null };

type TransactionInfo = { valid_until: string | null; from: string | null; messages: TransactionMessage[] };

type TransactionFullInfo = Omit<TransactionInfo, 'messages'> & { messages: TransactionFullMessage[] };

type TransactionSentForSignatureEvent =
    & { type: 'transaction-sent-for-signature'; trace_id?: string | null }
    & ConnectionInfo
    & TransactionInfo;

type TransactionSignedEvent =
    & {
        type: 'transaction-signed';
        is_success: true;
        signed_transaction: string;
        trace_id?: string | null;
    }
    & ConnectionInfo
    & TransactionInfo;

type TransactionSigningFailedEvent =
    & {
        type: 'transaction-signing-failed';
        is_success: false;
        error_message: string;
        error_code: SEND_TRANSACTION_ERROR_CODES | null;
        trace_id?: string | null;
    }
    & ConnectionInfo
    & TransactionFullInfo;

type TransactionSigningEvent = TransactionSentForSignatureEvent | TransactionSignedEvent | TransactionSigningFailedEvent;

type DataSentForSignatureEvent =
    & { type: 'sign-data-request-initiated'; data: SignDataPayload; trace_id?: string | null }
    & ConnectionInfo;

type DataSignedEvent =
    & {
        type: 'sign-data-request-completed';
        is_success: true;
        data: SignDataPayload;
        signed_data: SignDataResponse;
        trace_id?: string | null;
    }
    & ConnectionInfo;

type DataSigningFailedEvent =
    & {
        type: 'sign-data-request-failed';
        is_success: false;
        error_message: string;
        error_code: SIGN_DATA_ERROR_CODES | null;
        data: SignDataPayload;
        trace_id?: string | null;
    }
    & ConnectionInfo;

type DataSigningEvent = DataSentForSignatureEvent | DataSignedEvent | DataSigningFailedEvent;

type DisconnectionEvent = { type: 'disconnection'; scope: 'dapp' | 'wallet'; trace_id?: string | null } & ConnectionInfo;

type WalletModalOpenedEvent = {
    type: 'wallet-modal-opened';
    client_id: string | null;
    visible_wallets: string[];
    custom_data: Version;
    trace_id: string | null;
};

type SelectedWalletEvent = {
    type: 'selected-wallet';
    client_id: string | null;
    visible_wallets: string[];
    wallets_menu: 'explicit_wallet' | 'main_screen' | 'other_wallets';
    wallet_redirect_method?: 'tg_link' | 'external_link';
    wallet_redirect_link?: string;
    wallet_type: string | null;
    custom_data: Version;
    trace_id: string | null;
};

type SdkActionEvent =
    | VersionEvent
    | ConnectionEvent
    | ConnectionRestoringEvent
    | DisconnectionEvent
    | TransactionSigningEvent
    | DataSigningEvent
    | WalletModalOpenedEvent
    | SelectedWalletEvent;

type WithoutVersion<T> = T extends [Version, ...infer Rest] ? [...Rest] : never;

type ConsumableLike<T> = T | Consumable<T>;

type Traceable<T extends {} = {}> = { traceId: string } & T;

type OptionalTraceable<T extends {} = {}> = { traceId?: string } & T;

type UUIDTypes<TBuf extends Uint8Array = Uint8Array> = string | TBuf;

type Version7Options = { random?: Uint8Array; msecs?: number; seq?: number; rng?: () => Uint8Array };

function initializeWalletConnect(
    UniversalConnectorCls: Function,
    walletConnectOptions: WalletConnectOptions
): void;

import { UniversalConnector } from '@reown/appkit-universal-connector';

initializeWalletConnect(UniversalConnector, {
    projectId: 'abcd1234abcd1234abcd1234abcd1234',
    metadata: {
        name: 'Demo DApp',
        icons: [
            'https://example.com/my-icon.png'
        ],
        url: window.location.origin,
        description: 'Demo DApp'
    }
});

function isWalletConnectInitialized(): boolean;

function toUserFriendlyAddress(hexAddress: string, testOnly: boolean = false): string;

function checkRequiredWalletFeatures(
    features: Feature[],
    walletsRequiredFeatures?: RequiredFeatures
): boolean;

function enableQaMode(): void;

function isQaModeEnabled(): boolean;

function UUIDv7(options?: Version7Options, buf?: undefined, offset?: number): string;