Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
Before initializing the TON Connect's WalletKit, install it in your web project:
```shell theme={null}
npm i @ton/walletkit
```
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.
```ts theme={null}
import {
TonWalletKit,
CHAIN,
createDeviceInfo,
createWalletManifest,
} 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,
// 2. Specify core information and constraints of the given wallet.
deviceInfo: createDeviceInfo({
// Version of your wallet
appVersion: '0.0.1',
// The rest of the params will have default values set for you,
// including the features your wallet should support,
// maximum supported TON Connect protocol version,
// human-readable name of your wallet,
// and a current platform ('browser').
}),
// 3. Specify the TON Connect's wallet manifest.
// The following function provides initial defaults,
// 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(),
});
```
See also: [TON Connect's wallet manifest](/ecosystem/ton-connect/manifest#wallet-manifest).
## TON wallet initialization
The [configuration before](#initialization) is enough to outline necessary wallet information and initialize the WalletKit, but it isn't enough for deeper interactions with the blockchain. For that, you need at least one TON wallet contract to be set up.
You may load or create a new TON wallet using one of these options:
Note that you can provide multiple TON wallets to WalletKit and switch between them as needed.
```ts theme={null}
await kit.addWallet(tonWalletConfig1);
await kit.addWallet(tonWalletConfig2);
// ...
await kit.addWallet(tonWalletConfigN);
```
### From mnemonic
To initialize a TON wallet from an existing BIP-39 or TON-specific mnemonic seed phrase, use the `createWalletInitConfigMnemonic()` function of WalletKit.
```ts theme={null}
import {
CHAIN,
createWalletInitConfigMnemonic,
} from '@ton/walletkit';
const walletConfig = createWalletInitConfigMnemonic({
// (REQUIRED)
// A 12 or 24-word seed phrase obtained with general BIP-39 or TON-specific derivation.
// The following value assumes a corresponding MNEMONIC environment variable
// that contains 24 space-separated seed phrase words as a single string:
mnemonic: process.env.MNEMONIC.split(" "), // list of 24 strings
// Type of derivation used to produce a mnemonic.
// If you've used a pure BIP-39 derivation, specify 'bip-39'.
// Otherwise, specify 'ton'.
// Defaults to: 'ton'
mnemonicType: 'ton',
// Specify an ID for this wallet when you plan
// on adding more than one wallet to the kit.
walletId: 0,
// Wallet contract version
// Defaults to: v5r1
version: 'v5r1',
// TON Blockchain network.
// Defaults to: CHAIN.MAINNET
network: CHAIN.TESTNET,
});
// Extend the kit with a wallet.
// Note that .addWallet() method returns an initialized TON wallet,
// which can be used on its own elsewhere.
const wallet = await kit.addWallet(walletConfig);
```
### From private key
To initialize a TON wallet from an existing private key, use the `createWalletInitConfigPrivateKey()` function of WalletKit.
If there is a [mnemonic](#from-mnemonic), one can convert it to an Ed25519 key pair with public and private key by using the `MnemonicToKeyPair()`.
```ts theme={null}
import {
CHAIN,
createWalletInitConfigPrivateKey,
MnemonicToKeyPair,
} from '@ton/walletkit';
// Pass either a TON-specific ('ton')
// or a general BIP-39 ('bip-39') seed phrase to obtain a key pair.
const keyPair = await MnemonicToKeyPair(
// The following value assumes a corresponding MNEMONIC environment variable
// that contains 24 space-separated seed phrase words as a single string:
process.env.MNEMONIC.split(" "),
'ton',
);
const walletConfig = createWalletInitConfigPrivateKey({
// (REQUIRED)
// Private key as a hex-encoded string or Uint8Array of bytes.
privateKey: keyPair.secretKey,
// Specify an ID for this wallet when you plan
// on adding more than one wallet to the kit.
walletId: 0,
// Wallet contract version
// Defaults to: v5r1
version: 'v5r1',
// TON Blockchain network.
// Defaults to: CHAIN.MAINNET
network: CHAIN.TESTNET,
});
// Extend the kit with a wallet.
// Note that .addWallet() method returns an initialized TON wallet,
// which can be used on its own elsewhere.
const wallet = await kit.addWallet(walletConfig);
```
### From signer
To provide a custom signing mechanism as an alternative to using a [mnemonic phrase](#from-mnemonic) or a [private key](#from-private-key), use the `createWalletInitConfigSigner()` function of WalletKit.
In that case, you would need to pass a public key and your custom signing function of type `WalletSigner`. It should take the `Uint8Array` of data bytes and then asynchronously produce an `Uint8Array` signature.
This approach is useful if you want to maintain full control over the signing process, such as when using a hardware wallet or signing data on the backend.
```ts theme={null}
import {
CHAIN,
createWalletInitConfigSigner,
type Hash,
} from '@ton/walletkit';
const walletConfig = createWalletInitConfigSigner({
// (REQUIRED)
// Public key as a hex-encoded string (Hash) or Uint8Array of bytes.
publicKey: "..." as Hash,
// (REQUIRED)
// Custom signing function.
// The following is a simple demo of such a function.
sign: async (data: Uint8Array): Promise => data,
// Specify an ID for this wallet when you plan
// on adding more than one wallet to the kit.
walletId: 0,
// Wallet contract version
// Defaults to: v5r1
version: 'v5r1',
// TON Blockchain network.
// Defaults to: CHAIN.MAINNET
network: CHAIN.TESTNET,
});
// Extend the kit with a wallet.
// Note that .addWallet() method returns an initialized TON wallet,
// which can be used on its own elsewhere.
const wallet = await kit.addWallet(walletConfig);
```
## Configuration parameters
### Required
The TON network to use.
```ts theme={null}
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"
```
Core information and constraints of the given wallet.
```ts theme={null}
interface DeviceInfo {
// Name of the wallet.
appName: string;
// The platform it works on. Select 'browser' for the web wallets.
platform: 'iphone' | 'ipad' | 'android' | 'windows' | 'mac' | 'linux' | 'browser';
// The current wallet version.
appVersion: string;
// Latest protocol version to use.
maxProtocolVersion: number;
// Which features are supported in the wallet.
features: Feature[];
}
```
There, `Feature` type is defined as:
```ts theme={null}
type Feature =
// Wallet can send transactions.
// This is a deprecated definition used in old versions of TON Connect protocol.
| "SendTransaction"
| {
// Wallet can send transactions.
name: "SendTransaction";
// Max number of messages that can be sent in a single transaction.
// Depends on the TON wallet used, because different kinds can handle
// different number of messages. For example,
// - ledger wallet would only handle 1 message per transaction
// - wallet v4r2 handles up to 4 messages
// - wallet v5r1 handles up to 255 messages
maxMessages: number;
// Are messages sending extra-currencies supported?
extraCurrencySupported?: boolean;
}
| {
// Wallet can sign data.
name: "SignData";
// A type of data to sign.
// Either of: "text", "binary", "cell".
types: SignDataType[];
}
```
The `maxMessages` number depends on the TON wallet used, because every wallet has its own limit on the volume of messages.
For example,
* Ledger wallet would only handle 1 message per transaction
* Wallet `v4r2` handles up to 4 messages
* Wallet `v5r1` handles up to 255 messages
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).
```ts expandable theme={null}
interface WalletInfo {
/**
* Human-readable name of the wallet.
*/
name: string;
/**
* ID of the wallet, equals to the `appName` property of the `deviceInfo`.
*/
appName: string;
/**
* Url to the icon of the wallet. Resolution 288×288px. On a non-transparent background, without rounded corners. PNG format.
*/
imageUrl: string;
/**
* Will be used in the protocol later.
*/
tondns?: string;
/**
* Info or landing page of your wallet. It may be useful for TON newcomers.
*/
aboutUrl: string;
/**
* List of features supported by the wallet.
*/
features?: Feature[];
/**
* OS and browsers where the wallet could be installed
*/
platforms: ('ios' | 'android' | 'macos' | 'windows' | 'linux' | 'chrome' | 'firefox' | 'safari')[];
/**
* Base part of the wallet universal url. The link should support TON Connect parameters: https://github.com/ton-connect/docs/blob/main/bridge.md#universal-link.
*/
universalLink: string;
/**
* Native wallet app deep link. The link should support TON Connect parameters: https://github.com/ton-connect/docs/blob/main/bridge.md#universal-link.
*/
deepLink?: string;
/**
* Url of the wallet's implementation of the HTTP bridge: https://github.com/ton-connect/docs/blob/main/bridge.md#http-bridge.
*/
bridgeUrl: string;
// JS-injectable wallet information
/**
* If the wallet handles JS Bridge connection, specifies the binding for the bridge object accessible through window. Example: the key "tonkeeper" means the bridge can be accessed as window.tonkeeper.
*/
jsBridgeKey: string;
/**
* Indicates if the wallet currently is injected to the webpage.
*/
injected: boolean;
/**
* Indicates if the dapp is opened inside this wallet's browser.
*/
embedded: boolean;
}
```
### Optional
Which API or RPC provider to use to interact with TON Blockchain.
```ts theme={null}
// 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.
```
Connectivity options: either an HTTP or JavaScript bridge setup. The former's `bridgeUrl` points to the publicly exposed bridge URL, while the latter's `jsBridgeKey` points to the property name within the `window` object on the same web page.
```ts theme={null}
interface BridgeConfig {
// Defaults to `walletInfo`'s `bridgeUrl`, if it exists
bridgeUrl?: string;
// Defaults to true if `walletInfo`'s `jsBridgeKey` exists
enableJsBridge?: boolean;
// Defaults to `walletInfo`'s `jsBridgeKey`, if it exists
jsBridgeKey?: string;
// Settings for bridge-sdk
heartbeatInterval?: number;
reconnectInterval?: number;
maxReconnectAttempts?: number;
}
```
How to store intermediate events.
```ts theme={null}
// Either a small object:
const _: {
prefix?: string;
cacheTimeout?: number;
maxCacheSize?: number;
allowMemory?: boolean;
}
// Or a complete StorageAdapter interface implementation.
```
Strictness and wallet checks.
```ts theme={null}
{
strictMode?: boolean,
allowUnknownWalletVersions?: boolean,
}
```
How TON Connect events are processed.
```ts theme={null}
interface EventProcessorConfig {
disableEvents?: boolean;
}
```
Collect and gather analytical data.
```ts theme={null}
interface AnalyticsConfig {
enabled?: boolean;
// A web URL to send analytics data to.
endpoint?: string;
}
```
## Next steps
## See also