Configuration

Wallet Configuration

const config = {
  network: 'MAINNET', // 'MAINNET', 'SIGNET', or 'REGTEST'
  sparkscan: {
    apiKey: 'your-api-key-here'
  },
  syncAndRetry: true,
  enableLogging: false
}

const wallet = new WalletManagerSpark(seedPhrase, config)

Account Creation

// WalletAccountSpark is created by the WalletManagerSpark
// It does not take configuration parameters directly
const account = await wallet.getAccount(0) // Get account at index 0

Configuration Options

Network

The network option specifies which Spark network to use.

Type: string

Values:

• "MAINNET" - Spark mainnet (production)
• "SIGNET" - Spark signet (testing)
• "REGTEST" - Spark regtest (local development) - Get test funds

Default: "MAINNET"

Example:

const config = {
  network: 'REGTEST' // Use REGTEST for development
}

Read-Only Client

client optionally accepts an existing SparkReadonlyClient. Without it, the manager creates one from network and enableLogging and shares it across derived accounts and their read-only conversions. This shares the client used for reads; each owned account still creates its own Spark signing wallet.

A supplied client is reused as-is. Match its network to the wallet's network; those network and logging options do not reconfigure it. SparkScan remains a separate, optional balance source.

To construct the client yourself, install the Spark SDK version used by beta.28:

npm install @tetherto/wdk-wallet-spark@1.0.0-beta.28 @buildonspark/spark-sdk@0.10.0

Pass the client through the wallet configuration:

import WalletManagerSpark from '@tetherto/wdk-wallet-spark'
import { SparkReadonlyClient } from '@buildonspark/spark-sdk'

const network = 'REGTEST'
const client = SparkReadonlyClient.createPublic({ network, log: false })
const wallet = new WalletManagerSpark(seedPhrase, { network, client })

SparkScan Balance Polling

The sparkscan option configures SparkScan-backed balance polling for getBalance().

Type: SparkScanConfig (optional)

Fields:

• baseUrl - Optional SparkScan URL, default: https://api.sparkscan.io
• network - Optional Spark network. SparkScan supports MAINNET and REGTEST
• apiKey - Optional SparkScan API key

Example:

const config = {
  network: 'MAINNET',
  sparkscan: {
    apiKey: 'your-api-key-here'
  }
}

When sparkscan is configured, getBalance() returns SparkScan's soft balance from btcSoftBalanceSats.

Automatic Retry

The syncAndRetry option controls two different recovery flows:

• sendTransaction() reads transfer history before submitting once. If submission fails, it syncs wallet state and returns a matching new transfer when one appears in history. It never resubmits the native send. If the initial history read fails, it does not submit.
• payLightningInvoice() syncs after a payment failure and retries once only for a stale-leaf error. Both attempts use the same transfer ID. Other payment failures raise LightningPaymentError with that ID.

Do not run native sends with the same recipient and amount concurrently from one wallet: history matching cannot distinguish them. These recovery flows do not apply to token transfer() calls.

Type: boolean (optional)

Default: false

Example:

const config = {
  network: 'MAINNET',
  syncAndRetry: true
}

You can also call syncWalletBalance() directly to reconcile wallet state. A failed response alone does not prove a payment was not submitted; inspect its status before deciding whether to pay again.

Spark SDK Logging

The enableLogging option forwards logging to the underlying Spark SDK.

Type: boolean (optional)

Default: false

Example:

const config = {
  network: 'REGTEST',
  enableLogging: true
}

Network Configuration

The wallet can be configured for different Spark networks:

// Mainnet configuration
const mainnetConfig = {
  network: 'MAINNET'
}



// Regtest configuration
const regtestConfig = {
  network: 'REGTEST'
}

BIP-44 Derivation Path

Spark uses the BIP-44 coin type 998, resulting in derivation paths like:

• m/44'/998'/0'/0/0 for MAINNET account index 0
• m/44'/998'/0'/0/1 for MAINNET account index 1
• m/44'/998'/2'/0/0 for SIGNET account index 0
• m/44'/998'/3'/0/0 for REGTEST account index 0

The path follows the pattern m/44'/998'/{networkNumber}'/0/{index} where:

• 998 is the coin type for Spark
• networkNumber is 0 for MAINNET, 2 for SIGNET, or 3 for REGTEST
• index is the account index

This ensures compatibility with standard BIP-44 wallets while using Spark's unique coin type identifier.

Complete Configuration Example

import WalletManagerSpark from '@tetherto/wdk-wallet-spark'

// Create wallet manager with configuration
const seedPhrase = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
const wallet = new WalletManagerSpark(seedPhrase, {
  network: 'MAINNET',
  sparkscan: {
    apiKey: 'your-api-key-here'
  },
  syncAndRetry: true,
  enableLogging: false
})

// Get accounts (no additional configuration needed)
const account0 = await wallet.getAccount(0)
const account1 = await wallet.getAccount(1)

// Clean up when done
wallet.dispose()

Need Help?