Class TonConnect

Headless TON Connect connector — implements the ITonConnect contract. Wraps the protocol handshake and the HTTP / JS bridge / WalletConnect transports.

Example

import TonConnect from '@tonconnect/sdk';

const connector = new TonConnect({
    manifestUrl: 'https://example.com/tonconnect-manifest.json',
});

Implements

ITonConnect

Index

Constructors

constructor

new TonConnect(options?: TonConnectOptions): TonConnect
Create a new connector. See TonConnectOptions for every option; the most common shape is { manifestUrl } in the browser, and { manifestUrl, storage } in Node.js / non-browser hosts.
Parameters
- Optionaloptions: TonConnectOptions
Returns TonConnect
Throws
DappMetadataError when manifestUrl is omitted and window.location.origin is not available.
- Defined in packages/sdk/lib/types/index.d.ts:2445

Properties

`Static`isInsideWalletBrowser

isInsideWalletBrowser: (walletJSKey: string) => boolean

true when the dApp is running inside the named wallet's in-app browser. Use it to pick the JS-bridge transport automatically and skip the QR-code modal.

Type declaration

- (walletJSKey: string): boolean
- Parameters
  - walletJSKey: string
    — value of the wallet's jsBridgeKey in the wallets list.
  Returns boolean

`Static`isWalletInjected

isWalletInjected: (walletJSKey: string) => boolean

true when a wallet identified by walletJSKey exposes a JS bridge on the current page. The fastest way to detect a browser extension before deciding which connect source to build.

Type declaration

- (walletJSKey: string): boolean
- Parameters
  - walletJSKey: string
    — value of the wallet's jsBridgeKey in the wallets list.
  Returns boolean

Accessors

account

get account(): null | Account
Current connected account or null if no account is connected.

Returns null | Account
Implementation of ITonConnect.account
- Defined in packages/sdk/lib/types/index.d.ts:2431

connected

get connected(): boolean
Shows if the wallet is connected right now.

Returns boolean
Implementation of ITonConnect.connected
- Defined in packages/sdk/lib/types/index.d.ts:2427

wallet

get wallet(): null | Wallet
Current connected wallet or null if no account is connected.

Returns null | Wallet
Implementation of ITonConnect.wallet
- Defined in packages/sdk/lib/types/index.d.ts:2435
set wallet(value: null | Wallet): void
Currently connected Wallet, or null when no wallet is connected.
Parameters
- value: null | Wallet
Returns void
Implementation of ITonConnect.wallet
- Defined in packages/sdk/lib/types/index.d.ts:2436

Methods

connect

connect<
    T extends
        | WalletConnectionSource
        | Pick<WalletConnectionSourceHTTP, "bridgeUrl">[],
>(
    wallet: T,
    options?: OptionalTraceable<
        {
            embeddedRequest?: ConsumableLike<EmbeddedRequest>;
            linkDisplayOnly?: boolean;
            openingDeadlineMS?: number;
            request?: ConnectAdditionalRequest;
            signal?: AbortSignal;
        },
    >,
): T extends WalletConnectionSourceJS
    ? void
    : T extends WalletConnectionSourceWalletConnect ? void : string
Generates universal link for an external wallet and subscribes to the wallet's bridge, or sends connect request to the injected wallet.
Type Parameters
- T extends WalletConnectionSource | Pick<WalletConnectionSourceHTTP, "bridgeUrl">[]
Parameters
- wallet: T
  wallet's bridge url and universal link for an external wallet or jsBridge key for the injected wallet.
- Optionaloptions: OptionalTraceable<
      {
          embeddedRequest?: ConsumableLike<EmbeddedRequest>;
          linkDisplayOnly?: boolean;
          openingDeadlineMS?: number;
          request?: ConnectAdditionalRequest;
          signal?: AbortSignal;
      },
  >
  (optional) openingDeadlineMS for the connection opening deadline and signal for the connection abort.
Returns T extends WalletConnectionSourceJS
? void
: T extends WalletConnectionSourceWalletConnect ? void : string
universal link if external wallet was passed or void for the injected wallet.
Implementation of ITonConnect.connect
- Defined in packages/sdk/lib/types/index.d.ts:2464
connect<
    T extends
        | WalletConnectionSource
        | Pick<WalletConnectionSourceHTTP, "bridgeUrl">[],
>(
    wallet: T,
    request?: ConnectAdditionalRequest,
    options?: OptionalTraceable<
        {
            embeddedRequest?: ConsumableLike<EmbeddedRequest>;
            linkDisplayOnly?: boolean;
            openingDeadlineMS?: number;
            signal?: AbortSignal;
        },
    >,
): T extends WalletConnectionSourceJS
    ? void
    : T extends WalletConnectionSourceWalletConnect ? void : string
Type Parameters
- T extends WalletConnectionSource | Pick<WalletConnectionSourceHTTP, "bridgeUrl">[]
Parameters
- wallet: T
- Optionalrequest: ConnectAdditionalRequest
- Optionaloptions: OptionalTraceable<
      {
          embeddedRequest?: ConsumableLike<EmbeddedRequest>;
          linkDisplayOnly?: boolean;
          openingDeadlineMS?: number;
          signal?: AbortSignal;
      },
  >
Returns T extends WalletConnectionSourceJS
? void
: T extends WalletConnectionSourceWalletConnect ? void : string
Deprecated
use connect(wallet, options) instead
Implementation of ITonConnect.connect
- Defined in packages/sdk/lib/types/index.d.ts:2477

disconnect

disconnect(options?: OptionalTraceable<{ signal?: AbortSignal }>): Promise<void>
Disconnect from the connected wallet and drop current session.
Parameters
- Optionaloptions: OptionalTraceable<{ signal?: AbortSignal }>
Returns Promise<void>
Implementation of ITonConnect.disconnect
- Defined in packages/sdk/lib/types/index.d.ts:2526

getSessionId

getSessionId(): Promise<null | string>
Gets the current session ID if available.

Returns Promise<null | string>
session ID string or null if not available.
Implementation of ITonConnect.getSessionId
- Defined in packages/sdk/lib/types/index.d.ts:2533

getWallets

getWallets(): Promise<WalletInfo[]>
Returns available wallets list.

Returns Promise<WalletInfo[]>
Implementation of ITonConnect.getWallets
- Defined in packages/sdk/lib/types/index.d.ts:2449

onStatusChange

onStatusChange(
callback: (wallet: null | Wallet) => void,
errorsHandler?: (err: TonConnectError) => void,
): () => void
Allows to subscribe to connection status changes and handle connection errors.
Parameters
- callback: (wallet: null | Wallet) => void
  will be called after connections status changes with actual wallet or null.
- OptionalerrorsHandler: (err: TonConnectError) => void
  (optional) will be called with some instance of TonConnectError when connect error is received.
Returns () => void
unsubscribe callback.
Implementation of ITonConnect.onStatusChange
- Defined in packages/sdk/lib/types/index.d.ts:2456

pauseConnection

pauseConnection(): void
Pause bridge HTTP connection. Might be helpful, if you want to pause connections while browser tab is unfocused, or if you use SDK with NodeJS and want to save server resources.

Returns void
Implementation of ITonConnect.pauseConnection
- Defined in packages/sdk/lib/types/index.d.ts:2541

restoreConnection

restoreConnection(
    options?: OptionalTraceable<
        { openingDeadlineMS?: number; signal?: AbortSignal },
    >,
): Promise<void>
Try to restore existing session and reconnect to the corresponding wallet. Call it immediately when your app is loaded.
Parameters
- Optionaloptions: OptionalTraceable<{ openingDeadlineMS?: number; signal?: AbortSignal }>
Returns Promise<void>
Implementation of ITonConnect.restoreConnection
- Defined in packages/sdk/lib/types/index.d.ts:2491

sendTransaction

sendTransaction(
    transaction: SendTransactionRequest,
    options?: OptionalTraceable<
        { onRequestSent?: () => void; signal?: AbortSignal },
    >,
): Promise<Traceable<SendTransactionResponse>>
Asks connected wallet to sign and send the transaction.
Parameters
- transaction: SendTransactionRequest
  transaction to send.
- Optionaloptions: OptionalTraceable<{ onRequestSent?: () => void; signal?: AbortSignal }>
  (optional) onRequestSent will be called after the request was sent to the wallet and signal for the transaction abort.
Returns Promise<Traceable<SendTransactionResponse>>
signed transaction boc that allows you to find the transaction in the blockchain. If user rejects transaction, method will throw the corresponding error.
Implementation of ITonConnect.sendTransaction
- Defined in packages/sdk/lib/types/index.d.ts:2502
sendTransaction(
transaction: SendTransactionRequest,
onRequestSent?: () => void,
): Promise<Traceable<SendTransactionResponse>>
Parameters
- transaction: SendTransactionRequest
- OptionalonRequestSent: () => void
Returns Promise<Traceable<SendTransactionResponse>>
Deprecated
use sendTransaction(transaction, options) instead
Implementation of ITonConnect.sendTransaction
- Defined in packages/sdk/lib/types/index.d.ts:2507

setConnectionNetwork

setConnectionNetwork(network?: string): void
Set desired network for the connection. Can only be set before connecting. If wallet connects with a different chain, the SDK will throw an error and abort connection.
Parameters
- Optionalnetwork: string
  desired network id (e.g., '-239', '-3', or custom). Pass undefined to allow any network.
Returns void
Implementation of ITonConnect.setConnectionNetwork
- Defined in packages/sdk/lib/types/index.d.ts:2522

signData

signData(
    data: SignDataPayload,
    options?: OptionalTraceable<
        { onRequestSent?: () => void; signal?: AbortSignal },
    >,
): Promise<Traceable<SignDataResponse>>
Ask the connected wallet to sign opaque data (SignDataPayload). The signature is bound to the user's wallet address, the dApp's domain, a timestamp, and the payload — verify on the backend or on-chain.
Parameters
- data: SignDataPayload
- Optionaloptions: OptionalTraceable<{ onRequestSent?: () => void; signal?: AbortSignal }>
Returns Promise<Traceable<SignDataResponse>>
The SignDataResponse plus, when available, the traceId * the SDK propagated through the bridge. * *

Throws
WalletNotConnectedError — no wallet is connected. *

Throws
WalletNotSupportFeatureError — wallet does not advertise the * requested SignData.types. *

Throws
UserRejectsError — user declined. *

Throws
WalletWrongNetworkError — wallet network differs from the request. *

Throws
TonConnectError — bridge / validation error. * *

See
Sign data (docs)
Implementation of ITonConnect.signData
- Defined in packages/sdk/lib/types/index.d.ts:2509

signMessage

signMessage(
    message: SendTransactionRequest,
    options?: OptionalTraceable<
        { onRequestSent?: () => void; signal?: AbortSignal },
    >,
): Promise<Traceable<SignMessageResponse>>
Ask the connected wallet to sign an internal message without broadcasting it.

Same payload shape as sendTransaction; supported by wallets that advertise the SignMessage feature (typically Wallet V5).
Parameters
- message: SendTransactionRequest
- Optionaloptions: OptionalTraceable<{ onRequestSent?: () => void; signal?: AbortSignal }>
Returns Promise<Traceable<SignMessageResponse>>
a signed BoC the dApp can wrap in an external * message and submit through a relayer (e.g. for a gasless jetton * transfer). * *

Throws
WalletNotConnectedError — no wallet is connected. *

Throws
WalletNotSupportFeatureError — wallet does not advertise SignMessage. *

Throws
UserRejectsError — user declined. *

Throws
WalletWrongNetworkError — wallet network differs from the request. *

Throws
TonConnectError — bridge / validation error. * *

See
Sign and relay a message (gasless) (docs)
Implementation of ITonConnect.signMessage
- Defined in packages/sdk/lib/types/index.d.ts:2513

unPauseConnection

unPauseConnection(): Promise<void>
Unpause bridge HTTP connection if it is paused.

Returns Promise<void>
Implementation of ITonConnect.unPauseConnection
- Defined in packages/sdk/lib/types/index.d.ts:2545

`Static`getWallets

getWallets(): Promise<WalletInfo[]>
Fetch the wallets-list registry without instantiating a connector. Equivalent to ITonConnect.getWallets but usable before constructing a TonConnect.

Returns Promise<WalletInfo[]>
- Defined in packages/sdk/lib/types/index.d.ts:2406

Class TonConnect

Example

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns TonConnect

Throws

Properties

StaticisInsideWalletBrowser

Type declaration

Parameters

Returns boolean

StaticisWalletInjected

Type declaration

Parameters

Returns boolean

Accessors

account

Returns null | Account

connected

Returns boolean

wallet

Returns null | Wallet

Parameters

Returns void

Methods

connect

Type Parameters

Parameters

Returns T extends WalletConnectionSourceJS ? void : T extends WalletConnectionSourceWalletConnect ? void : string

Type Parameters

Parameters

Returns T extends WalletConnectionSourceJS ? void : T extends WalletConnectionSourceWalletConnect ? void : string

Deprecated

disconnect

Parameters

Returns Promise<void>

getSessionId

Returns Promise<null | string>

getWallets

Returns Promise<WalletInfo[]>

onStatusChange

Parameters

Returns () => void

pauseConnection

Returns void

restoreConnection

Parameters

Returns Promise<void>

sendTransaction

Parameters

Returns Promise<Traceable<SendTransactionResponse>>

Parameters

Returns Promise<Traceable<SendTransactionResponse>>

Deprecated

setConnectionNetwork

Parameters

Returns void

signData

Parameters

Returns Promise<Traceable<SignDataResponse>>

Throws

Throws

Throws

Throws

Throws

See

signMessage

Parameters

Returns Promise<Traceable<SignMessageResponse>>

Throws

Throws

Throws

Throws

`Static`isInsideWalletBrowser

`Static`isWalletInjected

Returns T extends WalletConnectionSourceJS
? void
: T extends WalletConnectionSourceWalletConnect ? void : string

Returns T extends WalletConnectionSourceJS
? void
: T extends WalletConnectionSourceWalletConnect ? void : string

`Static`getWallets