Skip to main content

Wallets

The SDK provides simple methods to create, import, and manage wallets. All wallet operations are handled through SDK methods.

Get or Create Wallet

The SDK automatically creates a wallet if the user doesn’t have one:
// Get existing wallet or create new one
const wallet = await axonVault.getOrCreateWallet({
  walletName: 'My Wallet',
  walletType: 'cloud-hd', // default
  isDefault: true
});

console.log('Wallet ID:', wallet.walletId);
console.log('Wallet Type:', wallet.walletType);

Create Cloud HD Wallet

Create a new cloud-hosted HD wallet (default for new users):
const wallet = await axonVault.createWallet({
  walletName: 'My Wallet',
  walletType: 'cloud-hd',
  isDefault: true
});

Create Self-Custody HD Wallet

Create a wallet where the user provides their own mnemonic:
const wallet = await axonVault.createWallet({
  walletName: 'My Self-Custody Wallet',
  walletType: 'self-hd',
  mnemonic: userProvidedMnemonic,
  isDefault: false
});

Import HD Wallet

Import an existing HD wallet by mnemonic:
const wallet = await axonVault.importWallet({
  walletName: 'Imported Wallet',
  walletType: 'hd',
  mnemonic: existingMnemonic,
  isDefault: false
});

Import Private Key Wallet

Import a wallet from a private key:
const wallet = await axonVault.importWallet({
  walletName: 'Imported Key Wallet',
  walletType: 'private-key',
  privateKey: '0x...',
  isDefault: false
});

Import External Wallet

Connect an external wallet via WalletConnect:
const wallet = await axonVault.importWallet({
  walletName: 'MetaMask',
  walletType: 'external',
  walletConnectUri: wcUri,
  isDefault: false
});

Import Observer Wallet

Add watch-only addresses:
const wallet = await axonVault.importWallet({
  walletName: 'Portfolio Tracker',
  walletType: 'observer',
  addresses: [
    { address: '0x1234...', chainId: 'eip155:1' },
    { address: '0x5678...', chainId: 'eip155:8453' }
  ],
  isDefault: false
});

List Wallets

Get all wallets for the authenticated user:
const wallets = await axonVault.listWallets();

wallets.forEach(wallet => {
  console.log(`${wallet.walletName} (${wallet.walletType})`);
});

Get Wallet

Get a specific wallet by ID:
const wallet = await axonVault.getWallet('wal_abc123');

console.log('Wallet:', wallet.walletName);
console.log('Type:', wallet.walletType);
console.log('Default:', wallet.isDefault);

Get Default Wallet

Get the user’s default wallet:
const wallet = await axonVault.getDefaultWallet();

if (wallet) {
  console.log('Default wallet:', wallet.walletName);
} else {
  console.log('No default wallet found');
}

Set Default Wallet

Set a wallet as the default:
await wallet.setAsDefault();

Get Wallet Addresses

Get all addresses for a wallet across all chains:
const addresses = await wallet.getAddresses();

addresses.forEach(addr => {
  console.log(`${addr.chainId}: ${addr.address}`);
});

Derive Address for Chain

Derive a new address for a specific chain:
const address = await wallet.deriveAddress({
  chainId: 'eip155:8453',
  accountIndex: 0,
  addressIndex: 0
});

console.log('New address:', address.address);
console.log('Derivation path:', address.derivationPath);

Wallet Events

Listen for wallet events:
// Wallet created
axonVault.on('wallet:created', (wallet) => {
  console.log('New wallet:', wallet.walletId);
});

// Wallet updated
wallet.on('wallet:updated', (wallet) => {
  console.log('Wallet updated:', wallet);
});

// Address derived
wallet.on('address:derived', (address) => {
  console.log('New address:', address.address);
});

Error Handling

import { WalletError } from '@axonvault/embedded-wallet-sdk';

try {
  const wallet = await axonVault.createWallet({ ... });
} catch (error) {
  if (error instanceof WalletError) {
    switch (error.code) {
      case 'WALLET_ALREADY_EXISTS':
        console.error('Wallet already exists');
        break;
      case 'INVALID_MNEMONIC':
        console.error('Invalid mnemonic phrase');
        break;
      case 'INVALID_PRIVATE_KEY':
        console.error('Invalid private key');
        break;
      default:
        console.error('Wallet error:', error.message);
    }
  }
}

Wallet Types Reference

TypeKey StorageUse Case
cloud-hdTEE-protectedDefault for new users
self-hdUser-managedPower users with their own mnemonic
hdTEE-protectedImport existing HD wallet
private-keyTEE-protectedImport single private key
externalExternal walletWalletConnect integration
observerN/AWatch-only addresses