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

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

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

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

Show Returns

bigint

required

The wallet’s current balance in satoshis

Map<string, { balance: bigint, tokenMetadata: UserTokenMetadata }>

required

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

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");

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

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