Configure WalletKit parameters on the Web platform
WalletKit parameters are settings added when initializing the kit. This includes network configuration, wallet information, bridge settings, and more.
This guide provides a full list of supported parameters and explains how to add them.
For the minimum functional setup and initialization instructions, see Get started guide.
Networks (required)
networksRecord<CHAIN, NetworkConfig>required
For one or more TON networks, configure their respective API or RPC providers to interact with.
import { Network } from '@ton/walletkit';
new TonWalletKit({
networks: {
// Production network. All contracts and funds are real.
[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: '<MAINNET_API_KEY>',
},
},
// Testing network. For experiments, beta tests, and feature previews.
[Network.testnet().chainId]: { // "-3"
apiClient: {
url: 'https://testnet.toncenter.com',
key: '<TESTNET_API_KEY>',
},
},
},
// ...later fields...
});It is also possible to provide an entirely custom provider with its own ApiClient interface implementation.
import { Network } from '@ton/walletkit';
new TonWalletKit({
networks: {
[Network.testnet().chainId]: { // "-3"
apiClient: /* A complete ApiClient interface implementation */,
},
},
// ...later fields...
});Core settings
deviceInfoDeviceInfo
Core information and constraints of the given wallet. If not provided, defaults will be used.
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:
type Feature =
| {
// 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
v4r2handles up to 4 messages - Wallet
v5r1handles up to 255 messages
Wallet info
walletManifestWalletInfo
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.
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-blockchain/ton-connect/blob/main/spec/bridge.md#universal-link.
*/
universalLink: string;
/**
* Native wallet app deep link. The link should support TON Connect parameters: https://github.com/ton-blockchain/ton-connect/blob/main/spec/bridge.md#universal-link.
*/
deepLink?: string;
/**
* Url of the wallet's implementation of the HTTP bridge: https://github.com/ton-blockchain/ton-connect/blob/main/spec/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;
}Bridge
bridgeBridgeConfig
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.
Bridges are used for dApp communication — if the dApp exists in the same web environment as the wallet, then the JavaScript bridge is enough. Otherwise, use an HTTP bridge setup.
For HTTP bridge setups, use a publicly available and production-ready bridge deployed at https://connect.ton.org/bridge.
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;
// Defaults to false
disableHttpConnection?: boolean;
// Settings for bridge-sdk
heartbeatInterval?: number;
reconnectInterval?: number;
maxReconnectAttempts?: number;
}Storage
storageStorageConfig | StorageAdapter
How to store intermediate events.
// Either a small object:
interface StorageConfig {
prefix?: string;
maxRetries?: number;
retryDelay?: number;
allowMemory?: boolean;
}
// Or a complete StorageAdapter interface implementation:
interface StorageAdapter {
get(key: string): Promise<string | null>;
set(key: string, value: string): Promise<void>;
remove(key: string): Promise<void>;
clear(): Promise<void>;
}Event processing
eventProcessorEventProcessorConfig
How TON Connect events are processed. This is useful for background scripts in browser extensions that process incoming events and log them, but do so outside a queue.
interface EventProcessorConfig {
disableEvents?: boolean;
// If true, transaction events will not be emulated,
// and their `preview` field will be undefined.
disableTransactionEmulation?: boolean;
}Analytics
analyticsAnalyticsConfig
Collect and gather analytical data.
interface AnalyticsConfig {
enabled?: boolean;
// A web URL to send analytics data to.
endpoint?: string;
}Extra config
devobject
Extra configuration used when developing WalletKit itself. Irrelevant in other cases.
It supports the following properties:
disableNetworkSend— WalletKit will not send transactions to the network. Use this if your wallet handles broadcasting itself, or to run tests without submitting real transactions.disableManifestDomainCheck— Disables the manifest validation error. Useful when testing manifest-related behavior in your app if the kit throws a validation error before you can proceed.
Next steps
After configuring WalletKit, you can do this:
- Initialize a wallet: This step is required for working with transactions.