> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/ecosystem/walletkit/web/wallets",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# How to manage TON wallets with WalletKit on the Web platform

export const Aside = ({type = "note", title = "", icon = "", iconType = "regular", children}) => {
  const asideVariants = ["note", "tip", "caution", "danger"];
  const asideComponents = {
    note: {
      outerStyle: "border-sky-500/20 bg-sky-50/50 dark:border-sky-500/30 dark:bg-sky-500/10",
      innerStyle: "text-sky-900 dark:text-sky-200",
      calloutType: "note",
      icon: <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="w-4 h-4 text-sky-500" aria-label="Note">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
        </svg>
    },
    tip: {
      outerStyle: "border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10",
      innerStyle: "text-emerald-900 dark:text-emerald-200",
      calloutType: "tip",
      icon: <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="text-emerald-600 dark:text-emerald-400/80 w-3.5 h-auto" aria-label="Tip">
          <path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path>
        </svg>
    },
    caution: {
      outerStyle: "border-amber-500/20 bg-amber-50/50 dark:border-amber-500/30 dark:bg-amber-500/10",
      innerStyle: "text-amber-900 dark:text-amber-200",
      calloutType: "warning",
      icon: <svg className="flex-none w-5 h-5 text-amber-400 dark:text-amber-300/80" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-label="Warning">
          <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path>
        </svg>
    },
    danger: {
      outerStyle: "border-red-500/20 bg-red-50/50 dark:border-red-500/30 dark:bg-red-500/10",
      innerStyle: "text-red-900 dark:text-red-200",
      calloutType: "danger",
      icon: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor" className="text-red-600 dark:text-red-400/80 w-4 h-4" aria-label="Danger">
          <path d="M17.1 292c-12.9-22.3-12.9-49.7 0-72L105.4 67.1c12.9-22.3 36.6-36 62.4-36l176.6 0c25.7 0 49.5 13.7 62.4 36L494.9 220c12.9 22.3 12.9 49.7 0 72L406.6 444.9c-12.9 22.3-36.6 36-62.4 36l-176.6 0c-25.7 0-49.5-13.7-62.4-36L17.1 292zm41.6-48c-4.3 7.4-4.3 16.6 0 24l88.3 152.9c4.3 7.4 12.2 12 20.8 12l176.6 0c8.6 0 16.5-4.6 20.8-12L453.4 268c4.3-7.4 4.3-16.6 0-24L365.1 91.1c-4.3-7.4-12.2-12-20.8-12l-176.6 0c-8.6 0-16.5 4.6-20.8 12L58.6 244zM256 128c13.3 0 24 10.7 24 24l0 112c0 13.3-10.7 24-24 24s-24-10.7-24-24l0-112c0-13.3 10.7-24 24-24zM224 352a32 32 0 1 1 64 0 32 32 0 1 1 -64 0z"></path>
        </svg>
    }
  };
  let variant = type;
  let gotInvalidVariant = false;
  if (!asideVariants.includes(type)) {
    gotInvalidVariant = true;
    variant = "danger";
  }
  const iconVariants = ["regular", "solid", "light", "thin", "sharp-solid", "duotone", "brands"];
  if (!iconVariants.includes(iconType)) {
    iconType = "regular";
  }
  return <>
      <div className={`callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border ${asideComponents[variant].outerStyle}`} data-callout-type={asideComponents[variant].calloutType}>
        <div className="mt-0.5 w-4" data-component-part="callout-icon">
          {}
          {icon === "" ? asideComponents[variant].icon : <Icon icon={icon} iconType={iconType} size={14} />}
        </div>
        <div className={`text-sm prose min-w-0 w-full ${asideComponents[variant].innerStyle}`} data-component-part="callout-content">
          {gotInvalidVariant ? <p>
              <span className="font-bold">
                Invalid <code>type</code> passed!
              </span>
              <br />
              <span className="font-bold">Received: </span>
              {type}
              <br />
              <span className="font-bold">Expected one of: </span>
              {asideVariants.join(", ")}
            </p> : <>
              {title && <p className="font-bold">{title}</p>}
              {children}
            </>}
        </div>
      </div>
    </>;
};

<Aside>
  [Initialize the WalletKit](/ecosystem/walletkit/web/init) before using examples on this page.
</Aside>

The [basic configuration earlier](/ecosystem/walletkit/web/init#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 to set up at least one TON wallet contract.

## Initialization

1. First, obtain the signer. It can be instantiated [from a mnemonic](#from-mnemonic), from [a private key](#from-private-key), or be [made custom](#from-custom-signer).

2. Then, select a wallet adapter — it is an implementation of the `WalletInterface` type for a particular TON wallet contract. Currently, WalletKit provides two: `WalletV5R1Adapter` (recommended) and `WalletV4R2Adapter`.

   Adapter takes in a signer from the previous step and a number of options, namely:

   * `network` — TON Blockchain network: `Network.mainnet()`, `Network.testnet()`, or `Network.custom(chainId)`.
   * `client` — API client to communicate with TON Blockchain. Use `kit.getApiClient(network)` to get the client for the specified network from the `networks` configuration passed during [WalletKit initialization](/ecosystem/walletkit/web/init).
   * `walletId` — identifier of the new wallet, which is used to make its smart contract address unique.
   * `workchain` — either `0` for the basechain (default), or `-1` for the masterchain.

   ```ts title="TypeScript" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
   import {
     // Network object
     Network,
     // Latest wallet version (recommended)
     WalletV5R1Adapter,
     defaultWalletIdV5R1,
     // Legacy wallet version
     WalletV4R2Adapter,
     defaultWalletIdV4R2,
   } from '@ton/walletkit';

   const walletAdapter = await WalletV5R1Adapter.create(signer, {
     network: Network.mainnet(),
     client: kit.getApiClient(Network.mainnet()),

     // Either 0 for the basechain (default),
     // or -1 for the masterchain
     workchain: 0,

     // Specify an ID for this wallet when you plan
     // on adding more than one wallet to the kit
     // under the same mnemonic or private key.
     //
     // In such cases, ID is used to make wallet addresses unique,
     // because the same ID for the same mnemonic results in wallets
     // with the same address, i.e., the same smart contract.
     walletId: defaultWalletIdV5R1, // 2147483409
   });
   ```

3. Finally, pass the adapter to the `addWallet()` method of the kit to complete the wallet initialization process:

   ```ts title="TypeScript" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
    // Notice that addWallet() method returns an initialized TON wallet,
    // which can be used on its own elsewhere.
    const wallet = await kit.addWallet(walletAdapter);
    console.log('Wallet address:', wallet.getAddress());
   ```

   <Aside>
     Apart from adding a new wallet, an adapter is also helpful when [removing one](#remove-a-single-wallet) too.
   </Aside>

See the complete example for each signer kind:

<Columns cols={3}>
  <Card title="Mnemonic" horizontal="true" href="#from-mnemonic" />

  <Card title="Private key" horizontal="true" href="#from-private-key" />

  <Card title="Custom signer" horizontal="true" href="#from-custom-signer" />
</Columns>

### From mnemonic

To initialize a TON wallet from an existing BIP-39 or TON-specific mnemonic seed phrase, the signer should be instantiated with the `fromMnemonic()` method of the utility `Signer` class of the WalletKit.

<Aside type="danger">
  Never specify the mnemonic phrase directly in your code. It is a "password" to your wallet and all its funds.

  Instead, prefer sourcing the seed phrase from a secure storage, backend environment variables, or a special `.env` file that is Git-ignored and handled with care.
</Aside>

```ts title="TypeScript" expandable theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import {
  // Handles cryptographic signing
  Signer,
  // Latest wallet version (recommended)
  WalletV5R1Adapter,
  // Network object
  Network,
} from '@ton/walletkit';

// 1.
const signer = await Signer.fromMnemonic(
  // (REQUIRED)
  // A 12 or 24-word seed phrase obtained with general BIP-39 or TON-specific derivation.
  // The following value assumes a corresponding MNEMONIC localStorage entry
  // that contains 24 space-separated seed phrase words as a single string:
  localStorage.getItem('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'
    type: 'ton',
  },
);

// 2.
const walletAdapter = await WalletV5R1Adapter.create(signer, {
  network: Network.mainnet(),
  client: kit.getApiClient(Network.mainnet()),
});

// 3.
const wallet = await kit.addWallet(walletAdapter);
```

<Aside type="caution">
  If you do not yet have a mnemonic for an existing TON wallet or you want to create a new one, you can generate a TON-specific mnemonic with the `CreateTonMnemonic()` function. However, it is crucial to use that function only **once per wallet** and then save it securely.

  You **must NOT** invoke this function amidst the rest of your project code.

  The following is an example of a simple one-off standalone script to produce a new mnemonic that then should be saved somewhere private:

  ```ts theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  import { CreateTonMnemonic } from '@ton/walletkit';

  console.log(await CreateTonMnemonic()); // word1, word2, ..., word24
  ```
</Aside>

### From private key

To initialize a TON wallet from an existing private key, the signer should be instantiated with the `fromPrivateKey()` method of the utility `Signer` class of the 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()` function.

<Aside type="danger" title="Private keys are sensitive data!">
  Handle private keys carefully. Use test keys, keep them in a secure keystore, and avoid logs or commits.
</Aside>

```ts title="TypeScript" expandable theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import {
  // Handles cryptographic signing
  Signer,
  // Latest wallet version (recommended)
  WalletV5R1Adapter,
  // Conversion function
  MnemonicToKeyPair,
  // Network object
  Network,
} from '@ton/walletkit';

// 1.
const signer = await Signer.fromPrivateKey(
  // Private key as a hex-encoded string or Uint8Array of bytes.
  // The following value assumes a corresponding PRIVATE_KEY localStorage entry
  // that contains the private key as a hex-encoded string:
  localStorage.getItem('PRIVATE_KEY')!,
);

// 2.
const walletAdapter = await WalletV5R1Adapter.create(signer, {
  network: Network.mainnet(),
  client: kit.getApiClient(Network.mainnet()),
});

// 3.
const wallet = await kit.addWallet(walletAdapter);
```

### From custom signer

To provide a custom signing mechanism as an alternative to using a [mnemonic phrase](#from-mnemonic) or a [private key](#from-private-key), create an object of type `WalletSigner` and then pass it to the target wallet adapter's `create()` method.

The signer object has to have two fields:

* Signing function of type `ISigner`, which takes an iterable bytes object, such as `array`, `Uint8Array`, or `Buffer`, and asynchronously produces an Ed25519-encoded signature of the input as `Hex`. The `Hex` type is a string containing a hexadecimal value that starts with an explicit `0x` prefix.

  ```ts title="TypeScript" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  type ISigner = (bytes: Iterable<number>) => Promise<Hex>;
  ```

* Relevant Ed25519 public key of type `Hex`.

  ```ts title="TypeScript" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  type Hex = `0x${string}`;
  ```

A custom signer is useful to maintain complete control over the signing process, such as when using a hardware wallet or signing data on the backend.

```ts title="TypeScript" expandable theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import {
  // Network object
  Network,
  // Latest wallet version (recommended)
  WalletV5R1Adapter,
  // Conversion function
  MnemonicToKeyPair,
  // Utility function to convert an array of bytes into a string of type Hex
  Uint8ArrayToHex,
  // Utilify function to obtain an Ed25519 signature
  DefaultSignature,
  // Handles cryptographic signing
  type WalletSigner,
  // String with a hexadecimal value, which starts with the `0x` prefix
  type Hex,
} from '@ton/walletkit';

// A Ed25519 key pair from a mnemonic
const keyPair = await MnemonicToKeyPair(
  // The following value assumes a corresponding MNEMONIC localStorage entry
  // that contains 24 space-separated seed phrase words as a single string:
  localStorage.getItem('MNEMONIC')!.split(' '),
  'ton',
);

// 1.
const signer: WalletSigner = {
  // The following is a simple demo of a signing function.
  // Make sure to replace it with a production-ready one!
  sign: async (bytes: Iterable<number>): Promise<Hex> => {
    return DefaultSignature(Uint8Array.from(bytes), keyPair.secretKey);
  },

  // Public key as a Hex
  publicKey: Uint8ArrayToHex(keyPair.publicKey) as Hex,
};

// 2.
const walletAdapter = await WalletV5R1Adapter.create(signer, {
  network: Network.mainnet(),
  client: kit.getApiClient(Network.mainnet()),
});

// 3.
const wallet = await kit.addWallet(walletAdapter);
```

### Multiple wallets

You can add multiple TON wallets to WalletKit and switch between them as needed.

```ts title="TypeScript" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
const wallet1 = await kit.addWallet(walletAdapter1);
const wallet2 = await kit.addWallet(walletAdapter2);
// ...
const walletN = await kit.addWallet(walletAdapterN);
```

Providing the same wallet adapter to the kit multiple times will return the wallet that was already added in the first attempt.

## Methods

### Get a single wallet

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" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import { createWalletId, Network, type Wallet } from '@ton/walletkit';

// Using the helper function to create a wallet identifier.
const walletId = createWalletId(
  Network.mainnet(),
  walletAdapter.getAddress(),
);
const wallet: Wallet | undefined = kit.getWallet(walletId);

if (wallet) {
  console.log('Wallet address: ', wallet.getAddress());
}
```

### Get all wallets

To obtain all added wallets, use the `getWallets()` method of the initialized kit.

```ts title="TypeScript" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
const wallets: Wallet[] = kit.getWallets();
wallets.forEach(w => console.log('TON wallet address:', w.getAddress()));
```

### Remove a single 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" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import { createWalletId, Network } from '@ton/walletkit';

// Using the helper function to create a wallet identifier.
const walletId = createWalletId(
  Network.mainnet(),
  walletAdapter.getAddress(),
);
await kit.removeWallet(walletId);

// Alternatively, pass the adapter directly.
await kit.removeWallet(walletAdapter);
```

### Clear all wallets

To remove all previously added wallets from the kit, use the `clearWallets()` method of the initialized kit.

```ts title="TypeScript" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
await kit.clearWallets();
```

## Next steps

<Columns cols={2}>
  <Card title="Handle connections" icon="plug" horizontal="true" href="/ecosystem/walletkit/web/connections" />
</Columns>

## See also

* [WalletKit overview](/ecosystem/walletkit/overview)
* [TON Connect overview](/ecosystem/ton-connect/overview)