Create a Wallet

Create and initialize Spark wallets with full key control.

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:", await wallet.getSparkAddress());

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

// Restore wallet from existing mnemonic
const { wallet } = await SparkWallet.initialize({
  mnemonicOrSeed: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
  accountNumber: 0, // Optional: specify account index
  options: {
    network: "REGTEST" // or "MAINNET"
  }
});

console.log("Wallet restored from mnemonic!");
console.log("Address:", await wallet.getSparkAddress());

Show Parameters

Uint8Array | string

BIP-39 mnemonic phrase or raw seed. Leave blank to generate a new wallet.

number

Account index for generating multiple identity keys from the same mnemonic (default: 0 on REGTEST, 1 on MAINNET). Important: Always specify this explicitly if you use the same mnemonic across networks.

SparkSigner

Custom signer implementation for advanced use cases

ConfigOptions

Wallet configuration options including network selection

Show Returns

SparkWallet

required

The initialized SparkWallet instance

string

The 12-word mnemonic seed phrase for wallet recovery (undefined for raw seed)

Essential Wallet Operations

After creating your wallet, you can perform these essential operations Gets the identity public key of the wallet

const identityKey = await wallet.getIdentityPublicKey();
console.log("Identity Public Key:", identityKey);

Show Returns

string

required

The identity public key as a hex string

Gets the Spark address of the wallet

const sparkAddress = await wallet.getSparkAddress();
console.log("Spark Address:", sparkAddress);

Show Returns

SparkAddressFormat

required

The Spark address for receiving Bitcoin and tokens

Gets the current balance of the wallet, including Bitcoin and token balances.

const balance = await wallet.getBalance();
console.log("Balance:", balance.satsBalance.available, "sats");
console.log("Token Balances:", balance.tokenBalances);

Show Returns

object

required

Bitcoin balances in satoshis: available, owned, and incoming. Use available for spendable funds.

Map<string, { ownedBalance: bigint, availableToSendBalance: bigint, tokenMetadata: UserTokenMetadata }>

required

Map of Bech32m token identifiers to token balance and metadata. UserTokenMetadata includes extraMetadata?: Uint8Array for arbitrary issuer-defined bytes.

Initialization starts an active wallet: it subscribes to events, claims incoming transfers, and runs periodic maintenance such as token-output optimization. This also applies to a wallet used only to create invoices for other users. For queries alone, use SparkReadonlyClient. Automatic token-output optimization is enabled by default. To disable that task, pass tokenOptimizationOptions: { enabled: false } inside the initialization options. The wallet still subscribes to events and claims incoming transfers; this is not a read-only mode. Call cleanup() when the wallet is no longer needed. It clears background intervals, aborts streams, removes listeners, and closes connections. Open resources can keep a Node.js script alive after its main function finishes.

try {
  console.log(await wallet.getSparkAddress());
  // Perform this script’s wallet work here.
} finally {
  await wallet.cleanup();
}

Show Returns

Promise<void>

required

No return value - cleans up connections and aborts active streams

Network Configuration

Spark supports both mainnet and regtest networks:

const { wallet } = await SparkWallet.initialize({
  options: {
    network: "MAINNET"
  }
});
// Use for production applications

const { wallet } = await SparkWallet.initialize({
  options: {
    network: "REGTEST"
  }
});
// Use for development and testing

Always use REGTEST for development and testing. Only use MAINNET for production applications with real Bitcoin.

Account number defaults differ by network. REGTEST defaults to account 0, MAINNET defaults to account 1. If you test on REGTEST without specifying accountNumber, then deploy to MAINNET with the same mnemonic, your wallet will be empty because funds are on a different account. Always explicitly set accountNumber for consistent behavior.

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:", await wallet0.getSparkAddress());
console.log("Account 1:", await wallet1.getSparkAddress());

API Reference

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

// Returns: { wallet: SparkWallet, mnemonic: string | undefined }

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
cleanup()

Introduction

Installation

Wallet

Transfers

Deposits

Withdrawals

Fees

Spark Signer Interface

Tools

Create a Wallet

Initialize Wallet

Essential Wallet Operations

Network Configuration

Account Derivation

API Reference

​Initialize Wallet

​Essential Wallet Operations

​Network Configuration

​Account Derivation

​API Reference

Initialize Wallet

Essential Wallet Operations

Network Configuration

Account Derivation

API Reference