WalletManager
The WalletManager class handles wallet creation, HD derivation, balance checking, and keystore management. All private keys are encrypted at rest using AES-256-GCM.
Constructor
class WalletManager {
constructor(password: string, keystoreDir?: string)
}
Password for encrypting/decrypting wallet keys
Custom directory for storing encrypted keystores (optional)
import { WalletManager } from 'karen'
const walletManager = new WalletManager('my-secure-password')
Wallet Creation
createWallet()
Create a new random wallet with a generated keypair.
async createWallet(
name: string,
tags?: string[]
): Promise<WalletInfo>
Human-readable name for the wallet
Optional tags for categorizing wallets (default: [])
Unique wallet identifier (UUID)
Solana public key (base58 encoded)
const wallet = await walletManager.createWallet('my-agent-wallet', ['agent', 'trading'])
console.log(wallet.id) // "abc-123-def-456"
console.log(wallet.publicKey) // "7xK...abc"
createDerivedWallet()
Create a wallet derived from a master mnemonic using HD derivation (BIP44).
async createDerivedWallet(
name: string,
mnemonic: string,
derivationIndex: number,
tags?: string[]
): Promise<WalletInfo>
BIP39 mnemonic (12 or 24 words)
Derivation path index (uses m/44’/501’/N’/0’)
const mnemonic = WalletManager.generateMnemonic()
const wallet = await walletManager.createDerivedWallet(
'agent-1',
mnemonic,
0,
['agent']
)
importWallet()
Import an existing wallet from a secret key.
async importWallet(
name: string,
secretKey: Uint8Array,
tags?: string[]
): Promise<WalletInfo>
64-byte Solana secret key
import bs58 from 'bs58'
const secretKey = bs58.decode('your-secret-key-here')
const wallet = await walletManager.importWallet('imported-wallet', secretKey)
generateMnemonic()
Generate a new 24-word BIP39 mnemonic for HD derivation.
static generateMnemonic(): string
const mnemonic = WalletManager.generateMnemonic()
console.log(mnemonic) // "abandon ability able about above absent absorb..."
Wallet Access
getKeypair()
Get the decrypted keypair for a wallet. Keep private keys in memory only.
async getKeypair(walletId: string): Promise<Keypair>
const keypair = await walletManager.getKeypair('abc-123')
const signature = await keypair.signTransaction(transaction)
listWallets()
List all wallets (metadata only, no private keys).
listWallets(): WalletInfo[]
const wallets = walletManager.listWallets()
wallets.forEach(w => console.log(`${w.name}: ${w.publicKey}`))
getWallet()
Get a single wallet’s info.
getWallet(walletId: string): WalletInfo | null
const wallet = walletManager.getWallet('abc-123')
if (wallet) {
console.log(wallet.publicKey)
}
findWalletByName()
Find a wallet by name.
findWalletByName(name: string): WalletInfo | null
const wallet = walletManager.findWalletByName('my-trading-wallet')
deleteWallet()
Permanently delete a wallet from the keystore.
deleteWallet(walletId: string): boolean
true if deleted, false if wallet not found
Balance Tracking
getSolBalance()
Get SOL balance for a wallet.
async getSolBalance(walletId: string): Promise<number>
const balance = await walletManager.getSolBalance('abc-123')
console.log(`Balance: ${balance} SOL`)
getBalances()
Get all balances (SOL + SPL tokens) for a wallet.
async getBalances(walletId: string): Promise<WalletBalance>
SOL balance in native units
Array of SPL token holdings
interface WalletBalance {
sol: number
tokens: TokenBalance[]
}
interface TokenBalance {
mint: string
symbol?: string
balance: number // Raw balance
decimals: number
uiBalance: number // Human-readable balance
}
const { sol, tokens } = await walletManager.getBalances('abc-123')
console.log(`SOL: ${sol}`)
tokens.forEach(t => {
console.log(`${t.mint}: ${t.uiBalance}`)
})
requestAirdrop()
Request a devnet SOL airdrop. Devnet only.
async requestAirdrop(
walletId: string,
amountSol?: number
): Promise<string>
Amount of SOL to request (default: 1, max: 2)
const signature = await walletManager.requestAirdrop('abc-123', 2)
console.log(`Airdrop confirmed: ${signature}`)
TypeScript Types
interface WalletInfo {
id: string
name: string
publicKey: string
createdAt: string
derivationIndex?: number
tags: string[]
}
interface WalletBalance {
sol: number
tokens: TokenBalance[]
}
interface TokenBalance {
mint: string
symbol?: string
balance: number
decimals: number
uiBalance: number
}
Security Notes
- All private keys are encrypted at rest using AES-256-GCM with Scrypt key derivation
- Keystores are stored in
~/.karen/keystores/ by default
- Never expose the encryption password or decrypted keypairs
- Use HD derivation for deterministic wallet generation from a single mnemonic
See Also