Skip to main content

​
Overview

The WalletManager class is the central orchestrator of use-wallet. It manages wallet initialization, network configuration, state persistence, and provides access to wallet functionality through a reactive store.

​
Initialization

1

Import and configure

Create a new WalletManager instance with your desired wallets and networks:
import { WalletManager, WalletId } from '@txnlab/use-wallet'

const walletManager = new WalletManager({
  wallets: [
    WalletId.PERA,
    WalletId.DEFLY,
    {
      id: WalletId.WALLETCONNECT,
      options: { projectId: 'your-project-id' }
    }
  ],
  networks: {
    // Optional: Override default network configs
  },
  defaultNetwork: 'testnet',
  options: {
    debug: false,
    resetNetwork: false
  }
})
2

Resume sessions

Resume any previously active wallet sessions:
await walletManager.resumeSessions()
The manager is now ready to use.

​
Configuration

​
WalletManagerConfig

The WalletManager constructor accepts a configuration object:
​
wallets
SupportedWallet[]
default:"[]"
Array of wallet IDs or wallet configuration objects. See Supported wallets for details.
wallets: [
  WalletId.PERA,  // Simple wallet ID
  {               // Wallet with options
    id: WalletId.WALLETCONNECT,
    options: { projectId: 'abc123' },
    metadata: { name: 'Custom Name' }
  }
]
​
networks
Record<string, NetworkConfig>
default:"DEFAULT_NETWORK_CONFIG"
Network configurations for different Algorand networks. See Network configuration for details.Defaults to mainnet, testnet, betanet, fnet, and localnet configurations using Nodely API endpoints.
​
defaultNetwork
string
default:"'testnet'"
The network to use by default. Must match a key in the networks configuration.
​
options
WalletManagerOptions
Optional manager configuration:
​
options.resetNetwork
boolean
default:"false"
If true, ignores the persisted active network and uses defaultNetwork on initialization.
​
options.debug
boolean
default:"false"
Shortcut to set log level to DEBUG. Overridden by logLevel if both are provided.
​
options.logLevel
LogLevel
default:"LogLevel.WARN"
Explicit log level: LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR, or LogLevel.NONE.

​
Type definitions

​
WalletManagerConfig

interface WalletManagerConfig {
  wallets?: SupportedWallet[]
  networks?: Record<string, NetworkConfig>
  defaultNetwork?: string
  options?: WalletManagerOptions
}

interface WalletManagerOptions {
  resetNetwork?: boolean
  debug?: boolean
  logLevel?: LogLevel
}

​
SupportedWallet

type SupportedWallet = WalletId | WalletIdConfig<WalletId>

type WalletIdConfig<T extends WalletId> = {
  id: T
  options?: WalletOptions<T>
  metadata?: Partial<WalletMetadata>
}

type WalletMetadata = {
  name: string
  icon: string
}

​
Core properties

​
Store and subscriptions

​
store
Store<State>
The TanStack Store instance managing reactive state. See State management for details.
​
subscribe
(callback: (state: State) => void) => () => void
Subscribe to state changes. Returns an unsubscribe function.
const unsubscribe = walletManager.subscribe((state) => {
  console.log('Active wallet:', state.activeWallet)
  console.log('Active network:', state.activeNetwork)
})

// Later: unsubscribe()

​
Manager status

​
status
'initializing' | 'ready'
Current manager status. Use isReady for a boolean check.
​
isReady
boolean
Returns true when the manager has completed initialization and session resumption.

​
Wallet access

​
wallets
BaseWallet[]
Array of all initialized wallet instances.
​
activeWallet
BaseWallet | null
The currently active wallet instance, or null if no wallet is active.
​
activeWalletAccounts
WalletAccount[] | null
All accounts from the active wallet.
​
activeWalletAddresses
string[] | null
Array of addresses from the active wallet’s accounts.
​
activeAccount
WalletAccount | null
The active account within the active wallet.
type WalletAccount = {
  name: string
  address: string
}
​
activeAddress
string | null
The address of the active account. Commonly used for transaction building.

​
Network access

​
activeNetwork
string
The ID of the currently active network (e.g., 'testnet').
​
activeNetworkConfig
NetworkConfig
Configuration for the active network.
​
networkConfig
Record<string, NetworkConfig>
All configured networks.
​
algodClient
algosdk.Algodv2
The algod client for the active network. Automatically updated when switching networks.

​
Methods

​
Wallet management

​
getWallet
(walletKey: WalletKey) => BaseWallet | undefined
Get a wallet instance by its wallet key.
const peraWallet = walletManager.getWallet(WalletId.PERA)
​
resumeSessions
() => Promise<void>
Resume all previously active wallet sessions. Call this after initialization.
await walletManager.resumeSessions()
​
disconnect
() => Promise<void>
Disconnect all connected wallets.

​
Network management

​
setActiveNetwork
(networkId: string) => Promise<void>
Switch to a different network. Updates algodClient and persists the change.
await walletManager.setActiveNetwork('mainnet')
​
updateAlgodConfig
(networkId: string, algodConfig: Partial<AlgodConfig>) => void
Update the algod configuration for a specific network. If the network is active, the algodClient is updated immediately.
walletManager.updateAlgodConfig('testnet', {
  baseServer: 'https://my-custom-node.com',
  token: 'my-token'
})
​
resetNetworkConfig
(networkId: string) => void
Reset a network’s configuration to its original default. Removes any customizations from persisted state.
walletManager.resetNetworkConfig('testnet')

​
Transaction signing

​
signTransactions
(txnGroup: Transaction[] | Uint8Array[], indexesToSign?: number[]) => Promise<(Uint8Array | null)[]>
Sign transactions using the active wallet. Returns an array where signed transactions are Uint8Array and unsigned transactions (skipped by indexesToSign) are null.
const signedTxns = await walletManager.signTransactions([txn1, txn2], [0])
// signedTxns = [Uint8Array, null] - only first transaction signed
Throws an error if no wallet is active.
​
transactionSigner
algosdk.TransactionSigner
An algosdk.TransactionSigner compatible function for use with AtomicTransactionComposer.
import algosdk from 'algosdk'

const atc = new algosdk.AtomicTransactionComposer()
atc.addMethodCall({
  appID: 123,
  method: myMethod,
  sender: walletManager.activeAddress!,
  signer: walletManager.transactionSigner,
  // ...
})

​
State persistence

The WalletManager automatically persists state to localStorage under the key @txnlab/use-wallet:v4. The following data is persisted:
  • Connected wallets and their accounts
  • Active wallet and active account
  • Active network
  • Custom network configuration overrides
The manager automatically saves state changes and loads persisted state on initialization. No manual intervention is required.

​
Example usage

import { WalletManager, WalletId } from '@txnlab/use-wallet'
import algosdk from 'algosdk'

// Initialize manager
const manager = new WalletManager({
  wallets: [WalletId.PERA, WalletId.DEFLY],
  defaultNetwork: 'testnet'
})

// Resume sessions
await manager.resumeSessions()

// Connect a wallet
const pera = manager.getWallet(WalletId.PERA)
if (pera) {
  await pera.connect()
}

// Build and sign a transaction
const txn = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
  from: manager.activeAddress!,
  to: 'RECEIVER_ADDRESS',
  amount: 1000000,
  suggestedParams: await manager.algodClient.getTransactionParams().do()
})

const signedTxns = await manager.signTransactions([txn])
const { txId } = await manager.algodClient.sendRawTransaction(signedTxns[0]!).do()

console.log('Transaction sent:', txId)

Supported wallets

View all supported wallets and their configuration options

Network configuration

Learn about network configuration and customization

State management

Understand the reactive state system

Build docs developers (and LLMs) love

Get started for freeTalk to us