Skip to main content
Learn how to create and initialize a Spark wallet. This guide covers wallet creation, initialization options, and essential wallet operations.
Create a Wallet

​
Initialize Wallet

The initialize method is the primary way to create or restore a Spark wallet. Leave mnemonicOrSeed blank to generate a new wallet, or provide an existing mnemonic seed phrase to import an existing wallet. 
import { SparkWallet } from "@buildonspark/spark-sdk";

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

console.log("New wallet created!");
console.log("Mnemonic:", mnemonic);
console.log("Address:", wallet.getSparkAddress());

​
Essential Wallet Operations

After creating your wallet, you can perform these essential operations getIdentityPublicKey() Gets the identity public key of the wallet 
const identityKey = await wallet.getIdentityPublicKey();
console.log("Identity Public Key:", identityKey);
getSparkAddress() Gets the Spark address of the wallet 
const sparkAddress = await wallet.getSparkAddress();
console.log("Spark Address:", sparkAddress);
getBalance() Gets the current balance of the wallet. You can use the forceRefetch option to synchronize your wallet and claim any pending incoming lightning payment, spark transfer, or bitcoin deposit before returning the balance. 
const balance = await wallet.getBalance();
console.log("Balance:", balance.balance, "sats");
console.log("Token Balances:", balance.tokenBalances);
cleanupConnections() Properly closes all network connections and cleans up resources when you’re done using the wallet. 
await wallet.cleanupConnections();
console.log("Wallet connections cleaned up");

​
Network Configuration

Spark supports both mainnet and regtest networks: 
const { wallet } = await SparkWallet.initialize({
  options: {
    network: "MAINNET"
  }
});
// Use for production applications
Always use REGTEST for development and testing. Only use MAINNET for production applications with real Bitcoin.

​
Account Derivation

You can create multiple accounts from the same mnemonic by specifying different account numbers: 
// Account 0 (default)
const wallet0 = await SparkWallet.initialize({
  mnemonicOrSeed: "your mnemonic here",
  accountNumber: 0
});

// Account 1
const wallet1 = await SparkWallet.initialize({
  mnemonicOrSeed: "your mnemonic here", 
  accountNumber: 1
});

// Each account will have different addresses
console.log("Account 0:", wallet0.getSparkAddress());
console.log("Account 1:", wallet1.getSparkAddress());

​
Security Best Practices

  • Store mnemonic securely - Never store mnemonics in plain text or commit them to version control
  • Use environment variables - Store sensitive data in environment variables
  • Test on regtest first - Always test wallet operations on regtest before mainnet
  • Clean up connections - Always call cleanupConnections() when done
  • Validate addresses - Always validate addresses before sending funds

​
API Reference

SparkWallet.initialize({
  mnemonicOrSeed?: string,     // Optional: existing mnemonic or seed
  accountNumber?: number,      // Optional: account index (default: 0)
  signer?: Signer,            // Optional: custom signer implementation
  options: {
    network: "MAINNET" | "REGTEST"
  }
})

// Returns: { wallet: SparkWallet, mnemonic: string }
Wallet Methods: 
// Initialize wallet with mnemonic or seed
initialize({ mnemonicOrSeed, signer, options })

// Get the identity public key
getIdentityPublicKey()

// Get the Spark address
getSparkAddress()

// Clean up connections
cleanupConnections()