Allow users to connect to your app by generating a Local Wallet directly in your application.

A local wallet is a low-level wallet that allows you to create wallets within your application or project. It is a non-custodial solution that simplifies the onboarding process and improves the user experience for web3 apps in two ways:

  • It enables non-web3 native users to get started easily without having to create a wallet.

  • It hides transaction confirmations from users.

After generating wallets for your users, you can offer multiple persistence and backup options.


import { ThirdwebSDK } from "@thirdweb-dev/sdk";
import { LocalWallet } from "@thirdweb-dev/wallets";
const wallet = new LocalWallet();
// generate a random wallet
await wallet.generate();
// connect the wallet to the application
await wallet.connect();
// at any point, you can save the wallet to persistent storage
// and load it back up
await wallet.load(config);
// you can also export the wallet out of the application
const exportedWallet = await wallet.export(config);
// and import it back in
await wallet.import(exportedWallet, config);
// You can then use this wallet to perform transactions via the SDK
const sdk = await ThirdwebSDK.fromWallet(wallet, "goerli");

Local Wallet Backup

Local wallets can be persisted on disk, or backed up to the cloud. Currently 3 formats are supported:

  • encryptedJSON - a standard format for encrypted wallets, this requires a password to encrypt/decrypt the wallet. Recommended for safe backups.

  • privateKey - the raw private key. This can be stored encrypted or un-encrypted. If not encrypted, make sure you store it somewhere safe.

  • mnemonic - the raw seed phrase. This can be stored encrypted or un-encrypted. If not encrypted, make sure you store it somewhere safe.

We provide encryption capabilities out of the box, but you can customize the type of encryption, and also turn it off completely.

The type of storage can also be overridden, allowing you to store wallets anywhere you want, including remote locations.

By default, wallets will be stored on the browser's storage for web (React), and on the secure storage of the device for mobile (React Native).

On Node.js, you can use LocalWalletNode which by default will save to the local file system of the machine.

import { LocalWalletNode } from "@thirdweb-dev/wallets/evm/wallets/local-wallet-node";
// wallet data will be saved in 'wallet.json' by default
// you can also pass a different file path by specifying 'storageJsonFile' in the constructor
const wallet = new LocalWalletNode();
await localWallet.loadOrCreate({
strategy: "privateKey",
encryption: false,

Customizing where the wallet data is persisted only requires implementing a simple interface. Here's an example of a Local Wallet with custom storage:

class MyStorage implements AsyncStorage {
getItem(key: string): Promise<string | null> { ... }
setItem(key: string, value: string): Promise<void> { ... }
removeItem(key: string): Promise<void> { ... }
const wallet = new LocalWallet({
storage: new MyStorage(),

You can implement this any way you like, file persistance, remote cloud storage, etc.

Encryption examples

Save an encrypted privateKey with default encryption a password as the encryption key:{
strategy: "privateKey",
encryption: {
password: "your-encryption-password", // uses default encryption

Import a raw private key or mnemonic (seed phrase) with no encryption:

// privateKey
privateKey: "your-raw-privateKey",
encryption: false, // no encryption
// mnemonic
mnemonic: "your-raw-mnemonic",
encryption: false, // no encryption

Save an encrypted mnemonic with a custom encryption:

// privateKey{
strategy: "mnemonic",
encryption: {
encrypt: (message: string, password: string) => {
return yourCustomEncryption(message, password);
password: "your-encryption-password",


Inherited Methods