From 884a683f05c8a5e6f176b216d638b04904e9d1d4 Mon Sep 17 00:00:00 2001 From: "V. K." Date: Tue, 23 Dec 2025 11:21:06 +0400 Subject: [PATCH 01/14] docs: update walletkit docs for version 0.0.4 --- .../ton-connect/walletkit/web/events.mdx | 8 +- ecosystem/ton-connect/walletkit/web/init.mdx | 99 ++++++++++--------- .../ton-connect/walletkit/web/wallets.mdx | 36 +++---- 3 files changed, 74 insertions(+), 69 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/events.mdx b/ecosystem/ton-connect/walletkit/web/events.mdx index a16eaa599..cef3c76be 100644 --- a/ecosystem/ton-connect/walletkit/web/events.mdx +++ b/ecosystem/ton-connect/walletkit/web/events.mdx @@ -83,18 +83,18 @@ kit.onSignDataRequest(async (event) => { } if (confirm('Do you confirm this data sign request?')) { try { - // Sign the data receiver with the user's approval - const result = await kit.signDataRequest(event); + // Sign the data with the user's approval + const result = await kit.approveSignDataRequest(event); console.log('Signed successfully:', result); } catch (error) { console.error('Signing failed:', error); } } else { - await kit.rejectTransactionRequest(event, 'User rejected'); + await kit.rejectSignDataRequest(event, 'User rejected'); } } catch (error) { console.error('Data sign handler error:', error); - await kit.rejectTransactionRequest(event, 'Fatal error in the data sign handler'); + await kit.rejectSignDataRequest(event, 'Fatal error in the data sign handler'); } }); ``` diff --git a/ecosystem/ton-connect/walletkit/web/init.mdx b/ecosystem/ton-connect/walletkit/web/init.mdx index 41f44d317..7a44f8a44 100644 --- a/ecosystem/ton-connect/walletkit/web/init.mdx +++ b/ecosystem/ton-connect/walletkit/web/init.mdx @@ -33,25 +33,34 @@ Alternatively, explore the complete demo wallet with WalletKit integration: ## Initialization -The basic kit initialization consists of creating a corresponding object by passing it a minimal set of necessary arguments. One needs to pick a TON network to operate on, provide the necessary device and wallet manifest configurations. +The basic kit initialization consists of creating a corresponding object by passing it a minimal set of necessary arguments. One needs to configure TON networks to operate on and provide necessary bridge settings. ```ts -import { - // Main class - TonWalletKit, - // Network constants (MAINNET/TESTNET) - CHAIN, - // Helper functions - createDeviceInfo, - createWalletManifest, +import { + TonWalletKit, // Main SDK class + Signer, // Handles cryptographic signing + WalletV5R1Adapter, // Latest wallet version (recommended) + CHAIN, // Network constants (MAINNET/TESTNET) } from '@ton/walletkit'; // 0. Create a kit object const kit = new TonWalletKit({ - // 1. Pick a network — prefer CHAIN.TESTNET during development, - // and only switch to CHAIN.MAINNET and production deployments - // after rigorous testing. - network: CHAIN.TESTNET, + // 1. Configure networks + networks: { + [CHAIN.MAINNET]: { + apiClient: { + url: 'https://toncenter.com', // Default. Or use self-hosted from https://github.com/toncenter/ton-http-api + key: 'your-api-key', // Optional API key for Toncenter. Get on https://t.me/toncenter + }, + }, + // Optionally configure testnet as well + // [CHAIN.TESTNET]: { + // apiClient: { + // url: 'https://testnet.toncenter.com', + // key: 'your-api-key-testnet', + // }, + // }, + }, // 2. Specify core information and constraints of the given wallet. deviceInfo: createDeviceInfo({ @@ -70,9 +79,16 @@ const kit = new TonWalletKit({ // but you may want to specify some custom values, // such as the human-readable name of your wallet or its icon image url. walletManifest: createWalletManifest(), + + // 4. Specify the TON Connect's bridge settings. + bridge: { + // TON Connect bridge for dApp communication + bridgeUrl: 'https://connect.ton.org/bridge', + // or use self-hosted bridge from https://github.com/ton-connect/bridge + }, }); -// 4. Finally, wait for the initialization to complete +// 5. Finally, wait for the initialization to complete await kit.waitForReady(); ``` @@ -100,29 +116,39 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet ### Required - The TON network to use. + The TON networks to use. Configure one or more networks with their API clients. ```ts import { CHAIN } from '@ton/walletkit'; - // Testing network of TON Blockchain. For experiments, beta tests, and feature previews. - CHAIN.TESTNET; // "-3" - - // Production network of TON Blockchain. All contracts and funds are real. - CHAIN.MAINNET; // "-239" + networks: { + [CHAIN.MAINNET]: { // "-239" - Production network + apiClient: { + url: 'https://toncenter.com', + key: 'your-api-key', + }, + }, + [CHAIN.TESTNET]: { // "-3" - Testing network + apiClient: { + url: 'https://testnet.toncenter.com', + key: 'your-api-key-testnet', + }, + }, + } ``` +### Optional + - Core information and constraints of the given wallet. + Core information and constraints of the given wallet. If not provided, defaults will be used. ```ts interface DeviceInfo { @@ -184,9 +210,8 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet - How your wallet interacts with the TON Connect. This field is closely related to the [corresponding JSON manifest file](/ecosystem/ton-connect/manifest#wallet-manifest). + How your wallet interacts with the TON Connect. If not provided, defaults will be used. This field is closely related to the [corresponding JSON manifest file](/ecosystem/ton-connect/manifest#wallet-manifest). ```ts expandable interface WalletInfo { @@ -260,27 +285,6 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet ``` -### Optional - - - Which API or RPC provider to use to interact with TON Blockchain. - - ```ts - // Either a small object: - const _: { - // Defaults to "https://toncenter.com". - url?: string; - - // A key to access higher RPS limits. - key?: string; - } - // Or a complete ApiClient interface implementation. - ``` - - Date: Tue, 23 Dec 2025 11:40:46 +0400 Subject: [PATCH 02/14] feat(walletkit): fix format issues --- ecosystem/ton-connect/walletkit/web/init.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/init.mdx b/ecosystem/ton-connect/walletkit/web/init.mdx index 7a44f8a44..f7d2c25ef 100644 --- a/ecosystem/ton-connect/walletkit/web/init.mdx +++ b/ecosystem/ton-connect/walletkit/web/init.mdx @@ -36,7 +36,7 @@ Alternatively, explore the complete demo wallet with WalletKit integration: The basic kit initialization consists of creating a corresponding object by passing it a minimal set of necessary arguments. One needs to configure TON networks to operate on and provide necessary bridge settings. ```ts -import { +import { TonWalletKit, // Main SDK class Signer, // Handles cryptographic signing WalletV5R1Adapter, // Latest wallet version (recommended) @@ -396,4 +396,3 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet - [WalletKit overview](/ecosystem/ton-connect/walletkit/overview) - [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet-manifest) - [TON Connect overview](/ecosystem/ton-connect/overview) - From 1680866dd8fc90b3dd5b984ec7b6784a49b39bcf Mon Sep 17 00:00:00 2001 From: "V. K." Date: Tue, 23 Dec 2025 13:24:57 +0400 Subject: [PATCH 03/14] docs: update some models --- .../ton-connect/walletkit/web/connections.mdx | 8 ++-- .../ton-connect/walletkit/web/events.mdx | 43 ++++++------------- ecosystem/ton-connect/walletkit/web/init.mdx | 4 +- .../ton-connect/walletkit/web/wallets.mdx | 28 +++++++++--- 4 files changed, 40 insertions(+), 43 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/connections.mdx b/ecosystem/ton-connect/walletkit/web/connections.mdx index d3a8e8f9e..73bcf9f4e 100644 --- a/ecosystem/ton-connect/walletkit/web/connections.mdx +++ b/ecosystem/ton-connect/walletkit/web/connections.mdx @@ -52,8 +52,8 @@ kit.onConnectRequest(async (event) => { await kit.rejectConnectRequest(event, 'No wallets available'); return; } - const dappName = event.preview.manifest?.name || 'Unknown dApp'; - const dappUrl = event.preview.manifest?.url || 'Unknown URL'; + const dappName = event.preview.dAppInfo?.name || 'Unknown dApp'; + const dappUrl = event.preview.dAppInfo?.url || event.preview.dAppInfo?.manifestUrl || 'Unknown URL'; // Show the connection confirmation UI to the user of the wallet service if (confirm(`Connect to ${dappName} from ${dappUrl}?`)) { // Set wallet address on the request before approving @@ -101,8 +101,8 @@ kit.onConnectRequest(async (event) => { await kit.rejectConnectRequest(event, 'No wallet selected'); return; } - const dappName = event.preview.manifest?.name || 'Unknown dApp'; - const dappUrl = event.preview.manifest?.url || 'Unknown URL'; + const dappName = event.preview.dAppInfo?.name || 'Unknown dApp'; + const dappUrl = event.preview.dAppInfo?.url || event.preview.dAppInfo?.manifestUrl || 'Unknown URL'; // Show the connection confirmation UI to the user of the wallet service if (confirm(`Connect to ${dappName} from ${dappUrl}?`)) { // Set wallet address on the request before approving diff --git a/ecosystem/ton-connect/walletkit/web/events.mdx b/ecosystem/ton-connect/walletkit/web/events.mdx index cef3c76be..6fdb3ce64 100644 --- a/ecosystem/ton-connect/walletkit/web/events.mdx +++ b/ecosystem/ton-connect/walletkit/web/events.mdx @@ -33,12 +33,12 @@ On TON, transactions are initiated by sending an external message to the TON wal ```ts title="TypeScript" kit.onTransactionRequest(async (event) => { try { - if (event.preview.result === 'success') { + if (event.preview.data.result === 'success') { // If the emulation was successful, // show net asset changes to the user for a confirmation. // There, positive amounts mean incoming transfers, // and negative mean outgoing ones. - console.log(event.preview.moneyFlow.ourTransfers); + console.log(event.preview.data.moneyFlow?.ourTransfers ?? []); } else { // Transaction emulation was not successful, // but you can still allow a user to proceed — with a warning. @@ -67,18 +67,20 @@ kit.onSignDataRequest(async (event) => { try { // Data to be signed can be of three distinct types. // Depending on a type, show it to the user for a confirmation. - switch (event.request.type) { + const dataToSign = event.payload.data; + + switch (dataToSign.type) { case 'text': - console.log(event.request.text); + console.log(dataToSign.value.content); break; case 'binary': - console.log(event.request.bytes); + console.log(dataToSign.value.content); break; case 'cell': // The `request.cell` contains a hex-encoded string with a serialized cell // and the `request.schema` describes a TL-B schema to parse the `request.cell` - console.log(event.request.cell); - console.log(event.request.schema); + console.log(dataToSign.value.content); + console.log(dataToSign.value.schema); break; } if (confirm('Do you confirm this data sign request?')) { @@ -104,29 +106,10 @@ kit.onSignDataRequest(async (event) => { Upon any error in any of the requests, the `onRequestError()` method is invoked. Provide it with a callback function that would handle arbitrary errors and display useful information to the user. ```ts title="TypeScript" -await kit.onRequestError(async (event) => { - // To distinguish incoming events, look for their corresponding type: - console.error(event.incomingEvent.method); - - // Event's .method can be one of the following: - // - connect (failure in onConnectRequest) - // - disconnect (failure in onDisconnect) - // - transaction (failure in onTransactionRequest) - // - signData (failure in onSignDataRequest) - // - restoreConnection (JS bridge failures) - // - none (generic request errors) - console.error(event.incomingEvent); - - // The result is a following object: - // { - // id: string, - // error: { - // code: number, - // message: string, - // data?: unknown, - // } - // } - console.error(event.result); +kit.onRequestError(async (event) => { + console.error('Request error occurred:', event.id); + console.error('Error details:', event.error); + console.error('Context:', event.data); }); ``` diff --git a/ecosystem/ton-connect/walletkit/web/init.mdx b/ecosystem/ton-connect/walletkit/web/init.mdx index f7d2c25ef..11e63901e 100644 --- a/ecosystem/ton-connect/walletkit/web/init.mdx +++ b/ecosystem/ton-connect/walletkit/web/init.mdx @@ -329,8 +329,8 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet // Either a small object: interface StorageConfig { prefix?: string; - cacheTimeout?: number; - maxCacheSize?: number; + maxRetries?: number; + retryDelay?: number; allowMemory?: boolean; } diff --git a/ecosystem/ton-connect/walletkit/web/wallets.mdx b/ecosystem/ton-connect/walletkit/web/wallets.mdx index f1fb06874..ce2d5d750 100644 --- a/ecosystem/ton-connect/walletkit/web/wallets.mdx +++ b/ecosystem/ton-connect/walletkit/web/wallets.mdx @@ -248,7 +248,7 @@ const signer: WalletSigner = { }, // Public key as a Hex - publicKey: Uint8ArrayToHex(keyPair.publicKey), + publicKey: Uint8ArrayToHex(keyPair.publicKey) as Hex, }; // 2. @@ -278,11 +278,22 @@ Providing the same wallet adapter to the kit multiple times will return the wall ### Get a single wallet -To get a single wallet by its address, use the `getWallet()` method of the initialized kit. +`TonWalletKit.getWallet()` expects a wallet identifier in the `:
` format. Build it via `createWalletId()` or rely on `getWalletByAddressAndNetwork()`: ```ts title="TypeScript" -const wallet: IWallet = kit.getWallet(walletAdapter.getAddress()); -console.log('TON wallet address:', wallet.getAddress()); +import { createWalletId, Network, type Wallet } from '@ton/walletkit'; + +const walletId = createWalletId(Network.mainnet(), walletAdapter.getAddress()); +const wallet: Wallet | undefined = kit.getWallet(walletId); + +if (wallet) { + console.log('TON wallet address:', wallet.getAddress()); +} +``` + +```ts title="TypeScript" +const wallet = + kit.getWalletByAddressAndNetwork(walletAdapter.getAddress(), Network.mainnet()); ``` ### Get all wallets @@ -290,16 +301,19 @@ console.log('TON wallet address:', wallet.getAddress()); To obtain all added wallets, use the `getWallets()` method of the initialized kit. ```ts title="TypeScript" -const wallets: IWallet[] = kit.getWallets(); +const wallets: Wallet[] = kit.getWallets(); wallets.forEach(w => console.log('TON wallet address:', w.getAddress())); ``` ### Remove a single wallet -To remove a single wallet by its address, use the `removeWallet()` method of the initialized kit. +`kit.removeWallet()` accepts either a `walletId` or the adapter instance itself. Reuse the same identifier as in `getWallet()`, or pass the adapter you used when adding the wallet: ```ts title="TypeScript" -await kit.removeWallet(wallet.getAddress()); +const walletId = createWalletId(Network.mainnet(), walletAdapter.getAddress()); +await kit.removeWallet(walletId); +// or +await kit.removeWallet(walletAdapter); ``` ### Clear all wallets From a03bba3c9db0a6da41d018f91d76a106deefc628 Mon Sep 17 00:00:00 2001 From: "V. K." Date: Thu, 8 Jan 2026 14:12:40 +0400 Subject: [PATCH 04/14] feat(walletkit): update toncoin.mdx --- .../ton-connect/walletkit/web/toncoin.mdx | 66 +++++++++---------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/toncoin.mdx b/ecosystem/ton-connect/walletkit/web/toncoin.mdx index c1d41494c..5b1bea3b8 100644 --- a/ecosystem/ton-connect/walletkit/web/toncoin.mdx +++ b/ecosystem/ton-connect/walletkit/web/toncoin.mdx @@ -31,9 +31,9 @@ Use the `getBalance()` method to check the wallet contract balance in TON wallet ```ts title="TypeScript" -async function getBalance(address: string): Promise { +async function getBalance(walletId: string): Promise { // Get TON wallet instance - const wallet = kit.getWallet(address); + const wallet = kit.getWallet(walletId); if (!wallet) return; // Query its balance in nanoToncoin @@ -52,7 +52,7 @@ The most practical use of one-off balance checks is right before approving a tra import { SEND_TRANSACTION_ERROR_CODES } from '@ton/walletkit'; kit.onTransactionRequest(async (event) => { - const wallet = kit.getWallet(event.walletAddress ?? ''); + const wallet = kit.getWallet(event.walletId ?? ''); if (!wallet) { console.error('Wallet not found for a transaction request', event); await kit.rejectTransactionRequest(event, { @@ -94,13 +94,13 @@ This example should be modified according to the wallet service's logic: const POLLING_INTERVAL_MS = 10_000; /** - * Starts the monitoring of a given wallet contract `address`, + * Starts the monitoring of a given wallet id, * calling `onBalanceUpdate()` each `intervalMs` milliseconds * * @returns a function to stop monitoring */ export function startBalanceMonitoring( - address: string, + walletId: string, onBalanceUpdate: (balance: bigint) => void, intervalMs: number = POLLING_INTERVAL_MS, ): () => void { @@ -108,7 +108,7 @@ export function startBalanceMonitoring( const poll = async () => { while (isRunning) { - const wallet = kit.getWallet(address); + const wallet = kit.getWallet(walletId); if (wallet) { const balance = await wallet.getBalance(); onBalanceUpdate(balance); @@ -128,7 +128,7 @@ export function startBalanceMonitoring( // Usage const stopMonitoring = startBalanceMonitoring( - walletAddress, + walletId, // The updateUI() function is exemplary and should be replaced by // a wallet service function that refreshes the // state of the balance displayed in the interface @@ -172,9 +172,9 @@ WalletKit automatically emulates every incoming transaction request before prese ```ts title="TypeScript" kit.onTransactionRequest(async (event) => { - if (event.preview.result === 'success') { + if (event.preview.data.result === 'success') { // Emulation succeeded — show the predicted money flow - const { ourTransfers } = event.preview.moneyFlow; + const { ourTransfers } = event.preview.data.moneyFlow; // This is an array of values, // where positive amounts mean incoming funds @@ -200,18 +200,18 @@ After showing the preview, handle the user's decision: ```ts title="TypeScript" expandable // An enumeration of various common error codes -import { SEND_TRANSACTION_ERROR_CODES } from '@ton/walletkit'; +import { SEND_TRANSACTION_ERROR_CODES, type TransactionTraceMoneyFlowItem } from '@ton/walletkit'; kit.onTransactionRequest(async (event) => { try { // Show the emulation preview to the wallet service user const preview = event.preview; - const isEmulationSuccessful = preview.result === 'success'; + const isEmulationSuccessful = preview.data.result === 'success'; // Build a confirmation message let confirmMessage = 'Confirm this transaction?'; if (isEmulationSuccessful) { - const transfers = preview.moneyFlow.ourTransfers; + const transfers = event.preview.data.moneyFlow?.ourTransfers || []; confirmMessage = `Send ${formatTransfers(transfers)}?`; } else { confirmMessage = 'Emulation failed. Proceed anyway?'; @@ -239,14 +239,12 @@ kit.onTransactionRequest(async (event) => { } }); -function formatTransfers( - transfers: Array<{ amount: bigint; asset: string }>, -): string { - const formatNano = (value: bigint, decimals: number = 9): string => { - const isNegative = value < 0n; - const str = (isNegative ? -value : value) - .toString() - .padStart(decimals + 1, '0'); +function formatTransfers(transfers: Array): string { + const formatNano = (value: string, decimals: number = 9): string => { + const bigintValue = BigInt(value) + const isNegative = bigintValue < 0n; + const absoluteValue = bigintValue < 0n ? -bigintValue : bigintValue; + const str = absoluteValue.toString().padStart(decimals + 1, '0'); const intPart = str.slice(0, -decimals) || '0'; const fracPart = str.slice(-decimals).replace(/0+$/, ''); @@ -255,9 +253,7 @@ function formatTransfers( return `${isNegative ? '-' : ''}${formatted}`; }; - return transfers - .map((t) => `${formatNano(t.amount)} ${t.asset}`) - .join(', '); + return transfers.map((t) => `${formatNano(t.amount)} ${t.assetType}`).join(', '); } ``` @@ -278,11 +274,13 @@ Transactions can be created directly from the wallet service (not from dApps) an This example should be modified according to the wallet service's logic: ```ts title="TypeScript" -import { type TonTransferParams } from '@ton/walletkit'; +import { type TONTransferRequest } from '@ton/walletkit'; async function sendToncoin( - // Recipient's TON wallet contract address as a string - address: string, + // Sender's TON wallet id as a string + walletId: string, + // Recipient's TON wallet address as a string + recipientAddress: string, // Amount in nanoToncoins nanoAmount: BigInt, // Optional comment string @@ -295,25 +293,27 @@ async function sendToncoin( return; } - const from = kit.getWallet(address); - if (!from) { + const fromWallet = kit.getWallet(walletId); + if (!fromWallet) { console.error('No wallet contract found'); return; } - const transferParams: TonTransferParams = { - toAddress: address, - amount: nanoAmount.toString(), + const transferParams: TONTransferRequest = { + recipientAddress: recipientAddress, + transferAmount: nanoAmount.toString(), // Optional comment OR payload, not both ...(comment && { comment: comment }), } // Build transaction content - const tx = await from.createTransferTonTransaction(transferParams); + const tx = await fromWallet.createTransferTonTransaction(transferParams); // Route into the normal flow, // triggering the onTransactionRequest() handler - await kit.handleNewTransaction(from, tx); + await kit.handleNewTransaction(fromWallet, tx); + // or send transaction without triggering the onTransactionRequest() handler + await fromWallet.sendTransaction(tx); } ``` From 94d9feefc0ae990a1a05ec931a3188d56e215aab Mon Sep 17 00:00:00 2001 From: "V. K." Date: Fri, 9 Jan 2026 14:07:01 +0400 Subject: [PATCH 05/14] feat(walletkit): move sendTransaction example to separate block --- ecosystem/ton-connect/walletkit/web/toncoin.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/toncoin.mdx b/ecosystem/ton-connect/walletkit/web/toncoin.mdx index 5b1bea3b8..0c6ce2bae 100644 --- a/ecosystem/ton-connect/walletkit/web/toncoin.mdx +++ b/ecosystem/ton-connect/walletkit/web/toncoin.mdx @@ -312,11 +312,15 @@ async function sendToncoin( // Route into the normal flow, // triggering the onTransactionRequest() handler await kit.handleNewTransaction(fromWallet, tx); - // or send transaction without triggering the onTransactionRequest() handler - await fromWallet.sendTransaction(tx); } ``` +Alternatively, you can send the transaction directly without calling `handleNewTransaction()` and without triggering the `onTransactionRequest()` handler: + +```ts title="TypeScript" +await fromWallet.sendTransaction(tx); +``` + ## See also - [Handle transaction requests](/ecosystem/ton-connect/walletkit/web/events#handle-ontransactionrequest) From e2eabcc0dbc367d952ad0dd91f0f1ba9fbf6f277 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Tue, 13 Jan 2026 09:47:49 +0100 Subject: [PATCH 06/14] Enhance! --- .../ton-connect/walletkit/web/events.mdx | 2 +- ecosystem/ton-connect/walletkit/web/init.mdx | 103 +++++++++++++----- .../ton-connect/walletkit/web/toncoin.mdx | 38 +++++-- .../ton-connect/walletkit/web/wallets.mdx | 60 +++++++--- 4 files changed, 148 insertions(+), 55 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/events.mdx b/ecosystem/ton-connect/walletkit/web/events.mdx index a28c27254..989e79b2d 100644 --- a/ecosystem/ton-connect/walletkit/web/events.mdx +++ b/ecosystem/ton-connect/walletkit/web/events.mdx @@ -27,7 +27,7 @@ If a dApp is connected to the wallet service, the former can request to initiate On TON, transactions are initiated by sending an external message to the TON wallet contract, which then processes it and sends internal messages as requested. To estimate money flows for planned transactions, WalletKit uses emulation via the configured API client, if supported. ```ts title="TypeScript" diff --git a/ecosystem/ton-connect/walletkit/web/init.mdx b/ecosystem/ton-connect/walletkit/web/init.mdx index 11e63901e..97c979956 100644 --- a/ecosystem/ton-connect/walletkit/web/init.mdx +++ b/ecosystem/ton-connect/walletkit/web/init.mdx @@ -33,33 +33,44 @@ Alternatively, explore the complete demo wallet with WalletKit integration: ## Initialization -The basic kit initialization consists of creating a corresponding object by passing it a minimal set of necessary arguments. One needs to configure TON networks to operate on and provide necessary bridge settings. +The basic kit initialization consists of creating a corresponding object by passing it a minimal set of necessary arguments: TON networks to operate on. + +Yet, it's often useful to configure optional parameters right away — the following example also specifies core wallet information, TON Connect manifest, and bridge settings. ```ts import { - TonWalletKit, // Main SDK class - Signer, // Handles cryptographic signing - WalletV5R1Adapter, // Latest wallet version (recommended) - CHAIN, // Network constants (MAINNET/TESTNET) + // Main class + TonWalletKit, + // Network constants (MAINNET/TESTNET) + CHAIN, + // Helper functions + createDeviceInfo, + createWalletManifest, } from '@ton/walletkit'; -// 0. Create a kit object +// 0. Create a kit object. const kit = new TonWalletKit({ - // 1. Configure networks + // 1. Configure networks. networks: { + // Production network. All contracts and funds are real. [CHAIN.MAINNET]: { apiClient: { - url: 'https://toncenter.com', // Default. Or use self-hosted from https://github.com/toncenter/ton-http-api - key: 'your-api-key', // Optional API key for Toncenter. Get on https://t.me/toncenter + // Most commonly used, official API provider. + // To self-host, see https://github.com/toncenter/ton-http-api-cpp + url: 'https://toncenter.com', + + // A key to access higher RPS limits. + // Get it from https://t.me/toncenter + key: '', + }, + }, + // Testing network. For experiments, beta tests, and feature previews. + [CHAIN.TESTNET]: { + apiClient: { + url: 'https://testnet.toncenter.com', + key: '', }, }, - // Optionally configure testnet as well - // [CHAIN.TESTNET]: { - // apiClient: { - // url: 'https://testnet.toncenter.com', - // key: 'your-api-key-testnet', - // }, - // }, }, // 2. Specify core information and constraints of the given wallet. @@ -80,11 +91,13 @@ const kit = new TonWalletKit({ // such as the human-readable name of your wallet or its icon image url. walletManifest: createWalletManifest(), - // 4. Specify the TON Connect's bridge settings. + // 4. Specify the TON Connect's bridge settings bridge: { - // TON Connect bridge for dApp communication + // The main TON Connect bridge for dApp communication. + // It is capable to withstand significant load. + // + // To self-host, see https://github.com/ton-connect/bridge bridgeUrl: 'https://connect.ton.org/bridge', - // or use self-hosted bridge from https://github.com/ton-connect/bridge }, }); @@ -120,26 +133,49 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet type="Record" required > - The TON networks to use. Configure one or more networks with their API clients. + For one or more TON networks, configure their respective API or RPC providers to interact with. ```ts import { CHAIN } from '@ton/walletkit'; - networks: { - [CHAIN.MAINNET]: { // "-239" - Production network - apiClient: { - url: 'https://toncenter.com', - key: 'your-api-key', + new TonWalletKit({ + networks: { + // Production network. All contracts and funds are real. + [CHAIN.MAINNET]: { // "-239" + apiClient: { + // Most commonly used, official API provider. + url: 'https://toncenter.com', + // Optional key to access higher RPS limits. + key: '', + }, + }, + // Testing network. For experiments, beta tests, and feature previews. + [CHAIN.TESTNET]: { // "-3" + apiClient: { + url: 'https://testnet.toncenter.com', + key: '', + }, }, }, - [CHAIN.TESTNET]: { // "-3" - Testing network - apiClient: { - url: 'https://testnet.toncenter.com', - key: 'your-api-key-testnet', + // ...later fields... + }); + ``` + + It is also possible to provide an entirely custom provider with its own `ApiClient` interface implementation. + + ```ts + import { CHAIN } from '@ton/walletkit'; + + new TonWalletKit({ + networks: { + [CHAIN.TESTNET]: { // "-3" + apiClient: /* A complete ApiClient interface implementation */, }, }, - } + // ...later fields... + }); ``` + ### Optional @@ -389,6 +425,13 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet horizontal="true" href="/ecosystem/ton-connect/walletkit/web/wallets" /> + + ## See also diff --git a/ecosystem/ton-connect/walletkit/web/toncoin.mdx b/ecosystem/ton-connect/walletkit/web/toncoin.mdx index 0c6ce2bae..c7940722c 100644 --- a/ecosystem/ton-connect/walletkit/web/toncoin.mdx +++ b/ecosystem/ton-connect/walletkit/web/toncoin.mdx @@ -18,7 +18,7 @@ Blockchain state changes constantly as new blocks are produced. This has implica - [Discrete one-off checks](#on-demand-balance-check) have almost no value on their own — the state might change immediately after the query completes, invalidating its results. Thus, such checks are only practical when handling `transaction` requests. - [Continuous monitoring](#continuous-balance-monitoring) is useful for UI display, showing the most recent balance to users, but should not be used for transaction confirmations. -Notice that both cases require querying the blockchain data via the API client set during the [WalletKit initialization](/ecosystem/ton-connect/walletkit/web/init#param-api-client). Obtain and provide the key from the selected client to access higher requests-per-second limits. +Notice that both cases require querying the blockchain data via the API client set during the [WalletKit initialization](/ecosystem/ton-connect/walletkit/web/init#param-networks). Obtain and provide the key from the selected client to access higher requests-per-second limits. ### On-demand balance check @@ -94,7 +94,7 @@ This example should be modified according to the wallet service's logic: const POLLING_INTERVAL_MS = 10_000; /** - * Starts the monitoring of a given wallet id, + * Starts the monitoring of a given `walletId`, * calling `onBalanceUpdate()` each `intervalMs` milliseconds * * @returns a function to stop monitoring @@ -191,7 +191,7 @@ kit.onTransactionRequest(async (event) => { ``` ### Approve or reject @@ -199,8 +199,12 @@ kit.onTransactionRequest(async (event) => { After showing the preview, handle the user's decision: ```ts title="TypeScript" expandable -// An enumeration of various common error codes -import { SEND_TRANSACTION_ERROR_CODES, type TransactionTraceMoneyFlowItem } from '@ton/walletkit'; +import { + // An enumeration of various common error codes + SEND_TRANSACTION_ERROR_CODES, + // The transfer type + type TransactionTraceMoneyFlowItem, +} from '@ton/walletkit'; kit.onTransactionRequest(async (event) => { try { @@ -241,7 +245,7 @@ kit.onTransactionRequest(async (event) => { function formatTransfers(transfers: Array): string { const formatNano = (value: string, decimals: number = 9): string => { - const bigintValue = BigInt(value) + const bigintValue = BigInt(value); const isNegative = bigintValue < 0n; const absoluteValue = bigintValue < 0n ? -bigintValue : bigintValue; const str = absoluteValue.toString().padStart(decimals + 1, '0'); @@ -277,7 +281,7 @@ This example should be modified according to the wallet service's logic: import { type TONTransferRequest } from '@ton/walletkit'; async function sendToncoin( - // Sender's TON wallet id as a string + // Sender's TON `walletId` as a string walletId: string, // Recipient's TON wallet address as a string recipientAddress: string, @@ -315,11 +319,23 @@ async function sendToncoin( } ``` -Alternatively, you can send the transaction directly without calling `handleNewTransaction()` and without triggering the `onTransactionRequest()` handler: + ## See also diff --git a/ecosystem/ton-connect/walletkit/web/wallets.mdx b/ecosystem/ton-connect/walletkit/web/wallets.mdx index ce2d5d750..05e50ad99 100644 --- a/ecosystem/ton-connect/walletkit/web/wallets.mdx +++ b/ecosystem/ton-connect/walletkit/web/wallets.mdx @@ -64,6 +64,10 @@ The [basic configuration earlier](/ecosystem/ton-connect/walletkit/web/init#init console.log('Wallet address:', wallet.getAddress()); ``` + + See the complete example for each signer kind: @@ -278,22 +282,33 @@ Providing the same wallet adapter to the kit multiple times will return the wall ### Get a single wallet -`TonWalletKit.getWallet()` expects a wallet identifier in the `:
` format. Build it via `createWalletId()` or rely on `getWalletByAddressAndNetwork()`: +The `getWallet()` method expects a wallet identifier in the `:
` format. Compose it via the `createWalletId()` helper function or rely on the `getWalletByAddressAndNetwork()` method: ```ts title="TypeScript" import { createWalletId, Network, type Wallet } from '@ton/walletkit'; -const walletId = createWalletId(Network.mainnet(), walletAdapter.getAddress()); -const wallet: Wallet | undefined = kit.getWallet(walletId); +// Using the helper function, +// the walletId holds a string in chainId:address format. +const walletId = createWalletId( + Network.mainnet(), + walletAdapter.getAddress(), +); +const walletViaHelper: Wallet | undefined = kit.getWallet(walletId); -if (wallet) { - console.log('TON wallet address:', wallet.getAddress()); -} -``` +// With the wallet adapter present, +// it is possible to utilize the method directly. +const walletViaMethod: Wallet | undefined = kit.getWalletByAddressAndNetwork( + walletAdapter.getAddress(), + Network.mainnet(), +); -```ts title="TypeScript" -const wallet = - kit.getWalletByAddressAndNetwork(walletAdapter.getAddress(), Network.mainnet()); +if (walletViaHelper && walletViaMethod) { + console.log( + 'TON wallets have the same address, i.e., they are the same wallet: ', + walletViaHelper.getAddress() === walletViaMethod.getAddress(), + ); + console.log('Address: ', walletViaHelper.getAddress()); +} ``` ### Get all wallets @@ -307,12 +322,20 @@ wallets.forEach(w => console.log('TON wallet address:', w.getAddress())); ### Remove a single wallet -`kit.removeWallet()` accepts either a `walletId` or the adapter instance itself. Reuse the same identifier as in `getWallet()`, or pass the adapter you used when adding the wallet: +The `kit.removeWallet()` method accepts either a `walletId` or the adapter instance itself. Compose the identifier via the `createWalletId()` helper function or pass the adapter used when adding the wallet: ```ts title="TypeScript" -const walletId = createWalletId(Network.mainnet(), walletAdapter.getAddress()); +import { createWalletId, Network } from '@ton/walletkit'; + +// Using the helper function, +// the walletId holds a string in chainId:address format. +const walletId = createWalletId( + Network.mainnet(), + walletAdapter.getAddress(), +); await kit.removeWallet(walletId); -// or + +// Alternatively, pass the adapter directly. await kit.removeWallet(walletAdapter); ``` @@ -324,6 +347,17 @@ To remove all previously added wallets from the kit, use the `clearWallets()` me await kit.clearWallets(); ``` +## Next steps + + + + + ## See also - [WalletKit overview](/ecosystem/ton-connect/walletkit/overview) From ef93cfea0cb48a77267e3a965cbb4bf4fba20f57 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Tue, 13 Jan 2026 09:50:21 +0100 Subject: [PATCH 07/14] fmt --- ecosystem/ton-connect/walletkit/web/init.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/ecosystem/ton-connect/walletkit/web/init.mdx b/ecosystem/ton-connect/walletkit/web/init.mdx index 97c979956..4e22df549 100644 --- a/ecosystem/ton-connect/walletkit/web/init.mdx +++ b/ecosystem/ton-connect/walletkit/web/init.mdx @@ -175,7 +175,6 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet // ...later fields... }); ``` - ### Optional From 2a358f4455bc498fc13692cc1c5b7e1a841ec66a Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Wed, 14 Jan 2026 10:40:12 +0100 Subject: [PATCH 08/14] make example runnable and complete the safety callout --- ecosystem/ton-connect/walletkit/web/toncoin.mdx | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/toncoin.mdx b/ecosystem/ton-connect/walletkit/web/toncoin.mdx index c7940722c..b6d1ab247 100644 --- a/ecosystem/ton-connect/walletkit/web/toncoin.mdx +++ b/ecosystem/ton-connect/walletkit/web/toncoin.mdx @@ -322,19 +322,17 @@ async function sendToncoin( ## See also From 8ba5f31b107b0280b9f0f7fc884dfd80a19fe76d Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Wed, 14 Jan 2026 23:25:35 +0100 Subject: [PATCH 09/14] use walletId here too! --- ecosystem/ton-connect/walletkit/web/connections.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/connections.mdx b/ecosystem/ton-connect/walletkit/web/connections.mdx index 73bcf9f4e..f1a708501 100644 --- a/ecosystem/ton-connect/walletkit/web/connections.mdx +++ b/ecosystem/ton-connect/walletkit/web/connections.mdx @@ -56,8 +56,8 @@ kit.onConnectRequest(async (event) => { const dappUrl = event.preview.dAppInfo?.url || event.preview.dAppInfo?.manifestUrl || 'Unknown URL'; // Show the connection confirmation UI to the user of the wallet service if (confirm(`Connect to ${dappName} from ${dappUrl}?`)) { - // Set wallet address on the request before approving - event.walletAddress = wallets[0].getAddress(); + // Set `walletId` on the request before approving + event.walletId = wallets[0].getWalletId(); await kit.approveConnectRequest(event); console.log('Connected to:', dappName); } else { @@ -105,8 +105,8 @@ kit.onConnectRequest(async (event) => { const dappUrl = event.preview.dAppInfo?.url || event.preview.dAppInfo?.manifestUrl || 'Unknown URL'; // Show the connection confirmation UI to the user of the wallet service if (confirm(`Connect to ${dappName} from ${dappUrl}?`)) { - // Set wallet address on the request before approving - event.walletAddress = selectedWallet.wallet.getAddress(); + // Set `walletId` on the request before approving + event.walletId = selectedWallet.wallet.getWalletId(); await kit.approveConnectRequest(event); console.log('Connected to:', dappName); } else { From 729d701349100ffca4bbb23c94e5a3622d603b28 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Wed, 14 Jan 2026 23:49:21 +0100 Subject: [PATCH 10/14] from CHAIN enum to Network object, everywhere --- ecosystem/ton-connect/walletkit/web/init.mdx | 22 ++++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/init.mdx b/ecosystem/ton-connect/walletkit/web/init.mdx index 4e22df549..cb2e658f9 100644 --- a/ecosystem/ton-connect/walletkit/web/init.mdx +++ b/ecosystem/ton-connect/walletkit/web/init.mdx @@ -41,8 +41,8 @@ Yet, it's often useful to configure optional parameters right away — the follo import { // Main class TonWalletKit, - // Network constants (MAINNET/TESTNET) - CHAIN, + // Network object + Network, // Helper functions createDeviceInfo, createWalletManifest, @@ -53,7 +53,7 @@ const kit = new TonWalletKit({ // 1. Configure networks. networks: { // Production network. All contracts and funds are real. - [CHAIN.MAINNET]: { + [Network.mainnet().chainId]: { apiClient: { // Most commonly used, official API provider. // To self-host, see https://github.com/toncenter/ton-http-api-cpp @@ -65,7 +65,7 @@ const kit = new TonWalletKit({ }, }, // Testing network. For experiments, beta tests, and feature previews. - [CHAIN.TESTNET]: { + [Network.testnet().chainId]: { apiClient: { url: 'https://testnet.toncenter.com', key: '', @@ -136,12 +136,12 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet For one or more TON networks, configure their respective API or RPC providers to interact with. ```ts - import { CHAIN } from '@ton/walletkit'; + import { Network } from '@ton/walletkit'; new TonWalletKit({ networks: { // Production network. All contracts and funds are real. - [CHAIN.MAINNET]: { // "-239" + [Network.mainnet().chainId]: { // "-239" apiClient: { // Most commonly used, official API provider. url: 'https://toncenter.com', @@ -150,7 +150,7 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet }, }, // Testing network. For experiments, beta tests, and feature previews. - [CHAIN.TESTNET]: { // "-3" + [Network.testnet().chainId]: { // "-3" apiClient: { url: 'https://testnet.toncenter.com', key: '', @@ -164,11 +164,11 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet It is also possible to provide an entirely custom provider with its own `ApiClient` interface implementation. ```ts - import { CHAIN } from '@ton/walletkit'; + import { Network } from '@ton/walletkit'; new TonWalletKit({ networks: { - [CHAIN.TESTNET]: { // "-3" + [Network.testnet().chainId]: { // "-3" apiClient: /* A complete ApiClient interface implementation */, }, }, @@ -388,6 +388,10 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet ```ts interface EventProcessorConfig { disableEvents?: boolean; + + // If true, transaction events will not be emulated, + // and their `preview` field will be undefined. + disableTranscationEmulation?: boolean; } ``` From 66bb4a4795ff6d08a021d403e50898ed254017e5 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Thu, 15 Jan 2026 00:08:26 +0100 Subject: [PATCH 11/14] emulation can now be skipped or disabled As per https://github.com/ton-connect/kit/pull/187 --- ecosystem/ton-connect/walletkit/web/connections.mdx | 8 ++++---- ecosystem/ton-connect/walletkit/web/events.mdx | 13 +++++++------ ecosystem/ton-connect/walletkit/web/toncoin.mdx | 12 +++++++----- 3 files changed, 18 insertions(+), 15 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/connections.mdx b/ecosystem/ton-connect/walletkit/web/connections.mdx index f1a708501..d3bc337af 100644 --- a/ecosystem/ton-connect/walletkit/web/connections.mdx +++ b/ecosystem/ton-connect/walletkit/web/connections.mdx @@ -52,8 +52,8 @@ kit.onConnectRequest(async (event) => { await kit.rejectConnectRequest(event, 'No wallets available'); return; } - const dappName = event.preview.dAppInfo?.name || 'Unknown dApp'; - const dappUrl = event.preview.dAppInfo?.url || event.preview.dAppInfo?.manifestUrl || 'Unknown URL'; + const dappName = event.dAppInfo?.name || 'Unknown dApp'; + const dappUrl = event.dAppInfo?.url || event.dAppInfo?.manifestUrl || 'Unknown URL'; // Show the connection confirmation UI to the user of the wallet service if (confirm(`Connect to ${dappName} from ${dappUrl}?`)) { // Set `walletId` on the request before approving @@ -101,8 +101,8 @@ kit.onConnectRequest(async (event) => { await kit.rejectConnectRequest(event, 'No wallet selected'); return; } - const dappName = event.preview.dAppInfo?.name || 'Unknown dApp'; - const dappUrl = event.preview.dAppInfo?.url || event.preview.dAppInfo?.manifestUrl || 'Unknown URL'; + const dappName = event.dAppInfo?.name || 'Unknown dApp'; + const dappUrl = event.dAppInfo?.url || event.dAppInfo?.manifestUrl || 'Unknown URL'; // Show the connection confirmation UI to the user of the wallet service if (confirm(`Connect to ${dappName} from ${dappUrl}?`)) { // Set `walletId` on the request before approving diff --git a/ecosystem/ton-connect/walletkit/web/events.mdx b/ecosystem/ton-connect/walletkit/web/events.mdx index 989e79b2d..36a629175 100644 --- a/ecosystem/ton-connect/walletkit/web/events.mdx +++ b/ecosystem/ton-connect/walletkit/web/events.mdx @@ -33,7 +33,9 @@ On TON, transactions are initiated by sending an external message to the TON wal ```ts title="TypeScript" kit.onTransactionRequest(async (event) => { try { - if (event.preview.data.result === 'success') { + if (!event.preview.data) { + console.log('Transaction emulation skipped'); + } else if (event.preview.data.result === 'success') { // If the emulation was successful, // show net asset changes to the user for a confirmation. // There, positive amounts mean incoming transfers, @@ -42,7 +44,7 @@ kit.onTransactionRequest(async (event) => { } else { // Transaction emulation was not successful, // but you can still allow a user to proceed — with a warning. - console.log('Transaction emulation failed'); + console.warn('Transaction emulation failed'); } if (confirm('Do you confirm this transaction?')) { await kit.approveTransactionRequest(event); @@ -68,7 +70,6 @@ kit.onSignDataRequest(async (event) => { // Data to be signed can be of three distinct types. // Depending on a type, show it to the user for a confirmation. const dataToSign = event.payload.data; - switch (dataToSign.type) { case 'text': console.log(dataToSign.value.content); @@ -107,9 +108,9 @@ Upon any error in any of the requests, the `onRequestError()` method is invoked. ```ts title="TypeScript" kit.onRequestError(async (event) => { - console.error('Request error occurred:', event.id); - console.error('Error details:', event.error); - console.error('Context:', event.data); + console.error('Error in request ID:', event.id); + console.error('Details:', event.error); + console.error('Data:', event.data); }); ``` diff --git a/ecosystem/ton-connect/walletkit/web/toncoin.mdx b/ecosystem/ton-connect/walletkit/web/toncoin.mdx index b6d1ab247..133a1a133 100644 --- a/ecosystem/ton-connect/walletkit/web/toncoin.mdx +++ b/ecosystem/ton-connect/walletkit/web/toncoin.mdx @@ -168,11 +168,13 @@ sequenceDiagram ### Emulation and preview -WalletKit automatically emulates every incoming transaction request before presenting it to the user. The emulation result is available in the `event.preview` object: +WalletKit tries to automatically emulate every incoming transaction request before presenting it to the user. The emulation result is available in the `event.preview.data` object, which can be `undefined` if emulation was skipped: ```ts title="TypeScript" kit.onTransactionRequest(async (event) => { - if (event.preview.data.result === 'success') { + if (!event.preview.data) { + console.log('Transaction emulation skipped'); + } else if (event.preview.data.result === 'success') { // Emulation succeeded — show the predicted money flow const { ourTransfers } = event.preview.data.moneyFlow; @@ -210,15 +212,15 @@ kit.onTransactionRequest(async (event) => { try { // Show the emulation preview to the wallet service user const preview = event.preview; - const isEmulationSuccessful = preview.data.result === 'success'; + const isEmulationSuccessful = preview.data?.result === 'success'; // Build a confirmation message let confirmMessage = 'Confirm this transaction?'; if (isEmulationSuccessful) { - const transfers = event.preview.data.moneyFlow?.ourTransfers || []; + const transfers = preview.data.moneyFlow?.ourTransfers || []; confirmMessage = `Send ${formatTransfers(transfers)}?`; } else { - confirmMessage = 'Emulation failed. Proceed anyway?'; + confirmMessage = 'Emulation failed or skipped. Proceed anyway?'; } // Handle user's decision From 476d27b6ffde36ac5f0cec42c3dc7208b7472312 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Thu, 15 Jan 2026 00:44:32 +0100 Subject: [PATCH 12/14] improve self-hosted info for apis --- ecosystem/ton-connect/walletkit/web/init.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/ecosystem/ton-connect/walletkit/web/init.mdx b/ecosystem/ton-connect/walletkit/web/init.mdx index cb2e658f9..7f60ea2b0 100644 --- a/ecosystem/ton-connect/walletkit/web/init.mdx +++ b/ecosystem/ton-connect/walletkit/web/init.mdx @@ -56,7 +56,6 @@ const kit = new TonWalletKit({ [Network.mainnet().chainId]: { apiClient: { // Most commonly used, official API provider. - // To self-host, see https://github.com/toncenter/ton-http-api-cpp url: 'https://toncenter.com', // A key to access higher RPS limits. @@ -144,7 +143,13 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet [Network.mainnet().chainId]: { // "-239" apiClient: { // Most commonly used, official API provider. + // + // To self-host, see: + // * Real-time API: https://github.com/toncenter/ton-http-api-cpp + // * Indexer: https://github.com/toncenter/ton-indexer + // It is important to put real-time API under `/api/v2` route and indexer API under `/api/v3` route. url: 'https://toncenter.com', + // Optional key to access higher RPS limits. key: '', }, From 3e670af2c4638ee7e910fb20f327e92db744b00c Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Thu, 15 Jan 2026 09:06:51 +0100 Subject: [PATCH 13/14] correct types --- ecosystem/ton-connect/walletkit/web/toncoin.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ecosystem/ton-connect/walletkit/web/toncoin.mdx b/ecosystem/ton-connect/walletkit/web/toncoin.mdx index 133a1a133..9bb16ee99 100644 --- a/ecosystem/ton-connect/walletkit/web/toncoin.mdx +++ b/ecosystem/ton-connect/walletkit/web/toncoin.mdx @@ -101,7 +101,7 @@ const POLLING_INTERVAL_MS = 10_000; */ export function startBalanceMonitoring( walletId: string, - onBalanceUpdate: (balance: bigint) => void, + onBalanceUpdate: (balance: string) => void, intervalMs: number = POLLING_INTERVAL_MS, ): () => void { let isRunning = true; From dde14b4ae5f3cb47e567875a222a0bc82a6411bf Mon Sep 17 00:00:00 2001 From: "V. K." Date: Thu, 15 Jan 2026 17:09:52 +0400 Subject: [PATCH 14/14] feat(walletkit): delete getWalletByAddressAndNetwork and fix typo for disableTransactionEmulation --- .../ton-connect/walletkit/web/connections.mdx | 8 +++--- ecosystem/ton-connect/walletkit/web/init.mdx | 2 +- .../ton-connect/walletkit/web/wallets.mdx | 25 +++++-------------- 3 files changed, 11 insertions(+), 24 deletions(-) diff --git a/ecosystem/ton-connect/walletkit/web/connections.mdx b/ecosystem/ton-connect/walletkit/web/connections.mdx index d3bc337af..f1a708501 100644 --- a/ecosystem/ton-connect/walletkit/web/connections.mdx +++ b/ecosystem/ton-connect/walletkit/web/connections.mdx @@ -52,8 +52,8 @@ kit.onConnectRequest(async (event) => { await kit.rejectConnectRequest(event, 'No wallets available'); return; } - const dappName = event.dAppInfo?.name || 'Unknown dApp'; - const dappUrl = event.dAppInfo?.url || event.dAppInfo?.manifestUrl || 'Unknown URL'; + const dappName = event.preview.dAppInfo?.name || 'Unknown dApp'; + const dappUrl = event.preview.dAppInfo?.url || event.preview.dAppInfo?.manifestUrl || 'Unknown URL'; // Show the connection confirmation UI to the user of the wallet service if (confirm(`Connect to ${dappName} from ${dappUrl}?`)) { // Set `walletId` on the request before approving @@ -101,8 +101,8 @@ kit.onConnectRequest(async (event) => { await kit.rejectConnectRequest(event, 'No wallet selected'); return; } - const dappName = event.dAppInfo?.name || 'Unknown dApp'; - const dappUrl = event.dAppInfo?.url || event.dAppInfo?.manifestUrl || 'Unknown URL'; + const dappName = event.preview.dAppInfo?.name || 'Unknown dApp'; + const dappUrl = event.preview.dAppInfo?.url || event.preview.dAppInfo?.manifestUrl || 'Unknown URL'; // Show the connection confirmation UI to the user of the wallet service if (confirm(`Connect to ${dappName} from ${dappUrl}?`)) { // Set `walletId` on the request before approving diff --git a/ecosystem/ton-connect/walletkit/web/init.mdx b/ecosystem/ton-connect/walletkit/web/init.mdx index 7f60ea2b0..d6a68d1a0 100644 --- a/ecosystem/ton-connect/walletkit/web/init.mdx +++ b/ecosystem/ton-connect/walletkit/web/init.mdx @@ -396,7 +396,7 @@ See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet // If true, transaction events will not be emulated, // and their `preview` field will be undefined. - disableTranscationEmulation?: boolean; + disableTransactionEmulation?: boolean; } ``` diff --git a/ecosystem/ton-connect/walletkit/web/wallets.mdx b/ecosystem/ton-connect/walletkit/web/wallets.mdx index 05e50ad99..146ce233d 100644 --- a/ecosystem/ton-connect/walletkit/web/wallets.mdx +++ b/ecosystem/ton-connect/walletkit/web/wallets.mdx @@ -282,32 +282,20 @@ Providing the same wallet adapter to the kit multiple times will return the wall ### Get a single wallet -The `getWallet()` method expects a wallet identifier in the `:
` format. Compose it via the `createWalletId()` helper function or rely on the `getWalletByAddressAndNetwork()` method: +The `getWallet()` method expects a wallet identifier string. Note that the same wallet on different chains must have different identifiers. Compose it via the `createWalletId()` helper function: ```ts title="TypeScript" import { createWalletId, Network, type Wallet } from '@ton/walletkit'; -// Using the helper function, -// the walletId holds a string in chainId:address format. +// Using the helper function to create a wallet identifier. const walletId = createWalletId( Network.mainnet(), walletAdapter.getAddress(), ); -const walletViaHelper: Wallet | undefined = kit.getWallet(walletId); +const wallet: Wallet | undefined = kit.getWallet(walletId); -// With the wallet adapter present, -// it is possible to utilize the method directly. -const walletViaMethod: Wallet | undefined = kit.getWalletByAddressAndNetwork( - walletAdapter.getAddress(), - Network.mainnet(), -); - -if (walletViaHelper && walletViaMethod) { - console.log( - 'TON wallets have the same address, i.e., they are the same wallet: ', - walletViaHelper.getAddress() === walletViaMethod.getAddress(), - ); - console.log('Address: ', walletViaHelper.getAddress()); +if (wallet) { + console.log('Wallet address: ', wallet.getAddress()); } ``` @@ -327,8 +315,7 @@ The `kit.removeWallet()` method accepts either a `walletId` or the adapter insta ```ts title="TypeScript" import { createWalletId, Network } from '@ton/walletkit'; -// Using the helper function, -// the walletId holds a string in chainId:address format. +// Using the helper function to create a wallet identifier. const walletId = createWalletId( Network.mainnet(), walletAdapter.getAddress(),