Skip to main content
Creates and initializes a new SparkWallet instance.

​
Method Signature

interface SparkWalletProps {
  mnemonicOrSeed?: Uint8Array | string;
  accountNumber?: number;
  signer?: SparkSigner;
  options?: ConfigOptions;
}

static async initialize(props: SparkWalletProps): Promise<{
  wallet: SparkWallet;
  mnemonic?: string;
}>

​
Parameters

​
mnemonicOrSeed
Uint8Array | string
BIP-39 mnemonic phrase or raw seed
​
accountNumber
number
Number used to generate multiple identity keys from the same mnemonic
​
signer
SparkSigner
Custom signer implementation for advanced use cases
​
options
ConfigOptions
Wallet configuration options including network selection

​
Leaf Optimization

Leaf optimization pre-arranges your wallet’s internal structure to enable faster transfers. Without optimization, transfers may require a swap with the SSP (Spark Service Provider), adding latency. With optimization, transfers complete in ~5 seconds.

​
How It Works

Spark creates power-of-2 denomination leaves (1, 2, 4, 8, 16… sats). With one leaf of each denomination, you can transfer any amount without needing an SSP swap. With multiple leaves of each denomination, you can make multiple transfers without swapping.

​
Multiplicity Levels

The multiplicity setting controls how aggressively to optimize:
LevelBehaviorUse Case
0No optimizationTesting only
11 leaf per denominationLikely 1 fast transfer before needing a swap
2-4Multiple leaves per denominationMultiple fast transfers
5Maximum optimizationLikely 5+ fast transfers without any swaps

​
The Tradeoff

Higher multiplicity = faster transfers, but smaller individual leaves. Leaves under 16,348 sats cannot be unilaterally exited (fees would exceed value). If unilateral exit capability is critical for your users, use a lower multiplicity or larger balances.
For most consumer wallets, fast transfer speeds for 100% of users outweighs unilateral exit costs for a small fraction of users.

​
Auto vs Manual Mode

Auto mode (auto: true, default):
  • Optimization runs automatically in the background after sync
  • Swaps with SSP when leaves are too far from optimal
  • Transfers wait for optimization to complete before sending
  • Best for most applications
Manual mode (auto: false):
  • You control exactly when optimization runs via optimizeLeaves()
  • More aggressive optimization (skips the “is it needed?” check)
  • Use when you want maximum optimization regardless of current state

​
Configuration Examples

// Default behavior - auto optimization with multiplicity 1
const { wallet } = await SparkWallet.initialize({
  options: { network: "MAINNET" }
});

// Fast transfers for consumer wallet
const { wallet } = await SparkWallet.initialize({
  options: {
    network: "MAINNET",
    optimizationOptions: {
      auto: true,
      multiplicity: 5
    }
  }
});

// Manual control for maximum optimization
const { wallet } = await SparkWallet.initialize({
  options: {
    network: "MAINNET",
    optimizationOptions: {
      auto: false,
      multiplicity: 5
    }
  }
});
// Then call wallet.optimizeLeaves() explicitly when needed
Safe to pass on every init. Pass optimizationOptions every time you initialize (e.g., on app reopen). The SDK only runs optimization if needed and does nothing on wallets with no balance.

​
Returns

​
wallet
SparkWallet
required
The initialized SparkWallet instance
​
mnemonic
string
The mnemonic if one was generated (undefined for raw seed)

​
Example

import { SparkWallet } from "@buildonspark/spark-sdk";

// Create a new wallet
const { wallet, mnemonic } = await SparkWallet.initialize({
  options: { network: "REGTEST" } // or "MAINNET"
});

console.log("Wallet initialized:", wallet);
console.log("Generated mnemonic:", mnemonic);

​
Multiple SDK Instances

When running multiple wallet instances (e.g., service worker + popup in a browser extension):
Multiple instances are safe but may cause temporary claim failures. The SDK handles this automatically—failed claims retry and succeed on subsequent attempts.
Best practices:
  • Avoid calling getStaticDepositAddress() concurrently—this can create duplicate addresses
  • Let one instance handle background claiming if possible
  • Failed claims due to concurrent access are automatically recoverable

​
System Time Requirements

The SDK uses your device’s system time for expiry calculations.
Your device clock must be within 2 minutes of actual time, or operations will fail with “invalid expiry_time” errors. If users report this error, ask them to sync their device clock.