wdk-wallet-spark

Official

@tetherto/wdk-wallet-spark

v1.0.0-beta.26
Apache-2.0
3,785 downloads

Spark

Spark/Lightning Bitcoin L2 wallet

wdk
wallet
bip-32
spark

Open in Playground

npm GitHub Docs

Loading README…

Recent updates

View all

v1.0.0-beta.26PatchSeptember 14, 2026

What's Changed

fix: remove seed from derivation errors by @localhost41 in https://github.com/tetherto/wdk-wallet-spark/pull/112
chore(deps-dev): bump browserslist from 4.28.2 to 4.28.9 in the security-patch-updates group across 1 directory by @dependabot[bot] in https://github.com/tetherto/wdk-wallet-spark/pull/113
Release: v1.0.0-beta.26 by @jonathunne in https://github.com/tetherto/wdk-wallet-spark/pull/114

New Contributors

@localhost41 made their first contribution in https://github.com/tetherto/wdk-wallet-spark/pull/112

Full Changelog: https://github.com/tetherto/wdk-wallet-spark/compare/v1.0.0-beta.25...v1.0.0-beta.26

Related Building Blocks

Extend WDK

Building Blocks

Discover and install building blocks to extend your WDK integration.

Back to Building Block Browser

wdk-wallet-spark

Official

@tetherto/wdk-wallet-spark

v1.0.0-beta.26
Apache-2.0
3,785 downloads

Spark

Spark/Lightning Bitcoin L2 wallet

wdk
wallet
bip-32
spark

Open in Playground

npm GitHub Docs

README

View on GitHub

@tetherto/wdk-wallet-spark

Note: This package is currently in beta. Please test thoroughly in development environments before using in production.

A simple and secure package to manage BIP-44 wallets for the Spark blockchain. This package provides a clean API for creating, managing, and interacting with Spark wallets using BIP-39 seed phrases and Liquid Bitcoin (LBTC) derivation paths.

🔍 About WDK

This module is part of the WDK (Wallet Development Kit) project, which empowers developers to build secure, non-custodial wallets with unified blockchain access, stateless architecture, and complete user control.

For detailed documentation about the complete WDK ecosystem, visit docs.wallet.tether.io.

🌟 Features

Liquid Bitcoin (LBTC) Derivation Paths: Support for BIP-44 standard derivation paths (m/44'/998')
Multi-Account Management: Create and manage multiple accounts from a single seed phrase
Transaction Management: Send transactions and get fee estimates with zero fees
Lightning Network Integration: Create invoices, pay Lightning invoices, and manage Lightning payments

⬇️ Installation

To install the @tetherto/wdk-wallet-spark package, follow these instructions:

You can install it using npm:

npm install @tetherto/wdk-wallet-spark

🚀 Quick Start

Importing from `@tetherto/wdk-wallet-spark`

WalletManagerSpark: Main class for managing wallets
WalletAccountSpark: Use this for full access accounts
WalletAccountReadOnlySpark: Use this for read-only accounts

Creating a New Wallet

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

// Use a BIP-39 seed phrase (replace with your own secure phrase)
const seedPhrase = 'test only example nut use this real life secret phrase must random'

// Create wallet manager with Spark network configuration
const wallet = new WalletManagerSpark(seedPhrase, {
  network: 'MAINNET' // 'MAINNET', 'TESTNET', or 'REGTEST'
})

// Get a full access account
const account = await wallet.getAccount(0)

// Get the account's Spark address
const address = await account.getAddress()
console.log('Account address:', address)

Note: The Spark wallet integrates with the Spark network using the @buildonspark/spark-sdk. Network configuration is limited to predefined networks, and there's no custom RPC provider option.

Managing Multiple Accounts

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

// Assume wallet is already created
// Get the first account (index 0)
const account = await wallet.getAccount(0)
const address = await account.getAddress()
console.log('Account 0 address:', address)

// Get the second account (index 1)
const account1 = await wallet.getAccount(1)
const address1 = await account1.getAddress()
console.log('Account 1 address:', address1)

// Get the third account (index 2)
const account2 = await wallet.getAccount(2)
const address2 = await account2.getAddress()
console.log('Account 2 address:', address2)

// Note: All accounts use BIP-44 derivation paths with pattern:
// m/44'/998'/{network}'/0/{index} where 998 is the coin type for Liquid Bitcoin
// and {network} is the network number (MAINNET=0, TESTNET=1, REGTEST=2)

Important Note: Custom derivation paths via getAccountByPath() are not supported on the Spark blockchain. Only indexed accounts using the standard BIP-44 pattern are available.

Checking Balances

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

// Assume wallet and account are already created
// Get native token balance (in satoshis)
const balance = await account.getBalance()
console.log('Native balance:', balance, 'satoshis')

// Get transfer history (default: 10 most recent transfers)
const transfers = await account.getTransfers()
console.log('Transfer history:', transfers)

// Get transfer history with options
const recentTransfers = await account.getTransfers({
  direction: 'all', // 'all', 'incoming', or 'outgoing'
  limit: 20,        // Number of transfers to fetch
  skip: 0           // Number of transfers to skip
})
console.log('Recent transfers:', recentTransfers)

// Get only incoming transfers
const incomingTransfers = await account.getTransfers({
  direction: 'incoming',
  limit: 5
})
console.log('Incoming transfers:', incomingTransfers)

Sending Transactions

// Send native tokens (satoshis)
const result = await account.sendTransaction({
  to: 'spark1...', // Recipient's Spark address
  value: 1000000   // Amount in satoshis
})
console.log('Transaction hash:', result.hash)
console.log('Transaction fee:', result.fee) // Always 0 for Spark transactions

// Get transaction fee estimate
const quote = await account.quoteSendTransaction({
  to: 'spark1...',
  value: 1000000
})
console.log('Estimated fee:', quote.fee) // Always returns 0

// Example with different amounts
const smallTransaction = await account.sendTransaction({
  to: 'spark1...',
  value: 100000 // 0.001 BTC in satoshis
})

const largeTransaction = await account.sendTransaction({
  to: 'spark1...',
  value: 10000000 // 0.1 BTC in satoshis
})

Important Notes:

Spark transactions have zero fees (fee: 0)
Memo/description functionality is not supported in sendTransaction
All amounts are specified in satoshis (1 BTC = 100,000,000 satoshis)
Addresses should be valid Spark network addresses

Message Signing and Verification

// Sign a message
const message = 'Hello, Spark!'
const signature = await account.sign(message)
console.log('Signature:', signature)

// Verify a signature (using read-only account)
const readOnlyAccount = await account.toReadOnlyAccount()
const isValid = await readOnlyAccount.verify(message, signature)
console.log('Signature valid:', isValid)

Memory Management

// Dispose wallet accounts to clear private keys from memory
account.dispose()

// Dispose entire wallet manager
wallet.dispose()

📚 API Reference

Class	Description	Methods
WalletManagerSpark	Main class for managing Spark wallets. Extends `WalletManager` from `@tetherto/wdk-wallet`.	Constructor, Methods
WalletAccountReadOnlySpark	Read-only Spark wallet account for querying balances, transfers, and deposit addresses without private keys.	Constructor, Methods
WalletAccountSpark	Full-access Spark wallet account. Implements `IWalletAccount`. Inherits all read-only methods.	Constructor, Methods, Properties

WalletManagerSpark

The main class for managing Spark wallets.
Extends WalletManager from @tetherto/wdk-wallet.

Constructor

new WalletManagerSpark(seed, config)

Parameters:

seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes
config (object, optional): Configuration object
- network (string, optional): 'MAINNET', 'TESTNET', or 'REGTEST' (default: 'MAINNET')

Methods

Method	Description	Returns
`getAccount(index)`	Returns a wallet account at the specified index	`Promise<WalletAccountSpark>`
`getFeeRates()`	Returns current fee rates for transactions (always zero for Spark)	`Promise<FeeRates>`
`dispose()`	Disposes all wallet accounts, clearing private keys from memory	`void`

`getAccount(index)`

Returns a Spark wallet account at the specified index using BIP-44 derivation path.

Parameters:

index (number, optional): The index of the account to get (default: 0)

Returns: Promise<WalletAccountSpark> - The Spark wallet account

Example:

const account = await wallet.getAccount(0)
const address = await account.getAddress()
console.log('Spark account address:', address)

Note: Uses derivation path pattern m/44'/998'/{network}'/0/{index} where 998 is the coin type for Liquid Bitcoin and {network} is the network number (MAINNET=0, TESTNET=1, REGTEST=2).

`getAccountByPath(path)`

Not supported on Spark blockchain. This method throws an error when called. Use getAccount(index) instead.

`getFeeRates()`

Returns current fee rates for Spark transactions from the network.

Returns: Promise<FeeRates> - Object containing fee rates in satoshis

normal: Standard fee rate for normal confirmation speed (always 0)
fast: Higher fee rate for faster confirmation (always 0)

Example:

const feeRates = await wallet.getFeeRates()
console.log('Normal fee rate:', feeRates.normal, 'satoshis')
console.log('Fast fee rate:', feeRates.fast, 'satoshis')

// Use in transaction (fees are always 0 on Spark)
const result = await account.sendTransaction({
  to: 'spark1...',
  value: 1000000 // 0.01 BTC in satoshis
})

`dispose()`

Disposes all Spark wallet accounts and clears sensitive data from memory.

Returns: void

Example:

wallet.dispose()
// All accounts and private keys are now securely wiped from memory

Important Notes:

All Spark transactions have zero fees
Network configuration is limited to predefined values
Uses BIP-44 derivation paths with coin type 998 for Liquid Bitcoin

WalletAccountReadOnlySpark

A read-only Spark wallet account for querying wallet data without needing private keys. Uses the SparkReadonlyClient from @buildonspark/spark-sdk for all queries.

Constructor

new WalletAccountReadOnlySpark(address, config)

Parameters:

address (string): The account's Spark address
config (object, optional): Configuration object
- network (string, optional): 'MAINNET', 'TESTNET', or 'REGTEST' (default: 'MAINNET')

Example:

import { WalletAccountReadOnlySpark } from '@tetherto/wdk-wallet-spark'

const readOnly = new WalletAccountReadOnlySpark('sp1pgs...', {
  network: 'MAINNET'
})

Methods

Method	Description	Returns
`getBalance()`	Returns the available (spendable) bitcoin balance in satoshis	`Promise<bigint>`
`getTokenBalance(tokenAddress)`	Returns the available-to-send balance for a specific token	`Promise<bigint>`
`getTransactionReceipt(hash)`	Gets a Spark transfer by its ID	`Promise<Object \| null>`
`getIdentityKey()`	Returns the account's identity public key	`Promise<string>`
`verify(message, signature)`	Verifies a message's signature	`Promise<boolean>`
`quoteSendTransaction(tx)`	Estimates transaction fee (always 0)	`Promise<{fee: bigint}>`
`quoteTransfer(options)`	Quotes the costs of a transfer operation	`Promise<{fee: bigint}>`
`getTransfers(options?)`	Returns the account's Spark transfer history	`Promise<SparkTransfer[]>`
`getUnusedDepositAddresses(options?)`	Returns unused single-use deposit addresses	`Promise<{depositAddresses: Array, offset: number}>`
`getStaticDepositAddresses()`	Returns all static deposit addresses	`Promise<Array>`
`getUtxosForDepositAddress(options)`	Returns confirmed UTXOs for a deposit address	`Promise<{utxos: Array<{txid: string, vout: number}>, offset: number}>`
`getSparkInvoices(params)`	Queries the status of Spark invoices	`Promise<{invoiceStatuses: Array, offset: number}>`

`getBalance()`

Returns the account's available (spendable) bitcoin balance in satoshis. This excludes sats that are locked in pending outgoing transfers.

Returns: Promise<bigint> - Available balance in satoshis

Example:

const balance = await readOnly.getBalance()
console.log('Balance:', balance, 'satoshis')

`getTokenBalance(tokenAddress)`

Returns the available-to-send balance for a specific token.

Parameters:

tokenAddress (string): Token identifier (Bech32m, e.g., btkn1...)

Returns: Promise<bigint> - Token balance (returns 0n if token not found)

Example:

const balance = await readOnly.getTokenBalance('btkn1...')
console.log('Token balance:', balance)

`getTransactionReceipt(hash)`

Gets a Spark transfer by its ID. Only returns Spark transfers, not on-chain Bitcoin transactions.

Parameters:

hash (string): The Spark transfer ID

Returns: Promise<Object | null> - The Spark transfer object, or null if not found

Example:

const transfer = await readOnly.getTransactionReceipt('transfer-id...')
if (transfer) {
  console.log('Spark transfer:', transfer)
}

`getIdentityKey()`

Returns the account's identity public key (hex-encoded), derived from the Spark address.

Returns: Promise<string> - The identity public key

Example:

const identityKey = await readOnly.getIdentityKey()
console.log('Identity key:', identityKey)

`verify(message, signature)`

Verifies a message's signature against the account's identity key.

Parameters:

message (string): The original message
signature (string): The signature to verify (hex-encoded, DER or compact)

Returns: Promise<boolean> - True if the signature is valid

Example:

const isValid = await readOnly.verify('Hello, Spark!', signatureHex)
console.log('Signature valid:', isValid)

`getTransfers(options?)`

Returns the account's Spark transfer history with filtering and pagination options. Only returns Spark transfers, not on-chain Bitcoin transactions.

Parameters:

options (object, optional): Filter options
- direction (string): 'all', 'incoming', or 'outgoing' (default: 'all')
- limit (number): Maximum transfers to return (default: 10)
- skip (number): Number of transfers to skip (default: 0)

Returns: Promise<Array> - Array of Spark transfer objects

Example:

const transfers = await readOnly.getTransfers({
  direction: 'incoming',
  limit: 5
})
console.log('Incoming transfers:', transfers)

`getUnusedDepositAddresses(options?)`

Returns unused single-use deposit addresses for the account.

Parameters:

options (object, optional): Pagination options
- limit (number): Maximum number of addresses to return (default: 100)
- offset (number): Pagination offset (default: 0)

Returns: Promise<{depositAddresses: Array, offset: number}> - Unused deposit addresses with pagination offset

Example:

const result = await readOnly.getUnusedDepositAddresses({ limit: 10 })
console.log('Unused addresses:', result.depositAddresses)

`getStaticDepositAddresses()`

Returns all static deposit addresses for the account.

Returns: Promise<Array> - Array of static deposit address objects

Example:

const addresses = await readOnly.getStaticDepositAddresses()
console.log('Static deposit addresses:', addresses)

`getUtxosForDepositAddress(options)`

Returns confirmed UTXOs for a specific deposit address.

Parameters:

options (object): Query options
- depositAddress (string): The Bitcoin deposit address to query
- limit (number, optional): Maximum number of UTXOs to return (default: 100)
- offset (number, optional): Pagination offset (default: 0)
- excludeClaimed (boolean, optional): If true, excludes already-claimed UTXOs

Returns: Promise<{utxos: Array<{txid: string, vout: number}>, offset: number}> - UTXOs with pagination offset

Example:

const result = await readOnly.getUtxosForDepositAddress({
  depositAddress: 'bc1q...',
  excludeClaimed: true
})
console.log('UTXOs:', result.utxos)

`getSparkInvoices(params)`

Queries the status of Spark invoices.

Parameters:

params (object): Query parameters
- invoices (string[]): Array of Spark invoice strings to query
- limit (number, optional): Maximum number of results to return (default: 100)
- offset (number, optional): Pagination offset (default: 0)

Returns: Promise<{invoiceStatuses: Array, offset: number}> - Invoice statuses with pagination offset

Example:

const result = await readOnly.getSparkInvoices({
  invoices: ['spark1invoice1', 'spark1invoice2']
})
console.log('Invoice statuses:', result.invoiceStatuses)

WalletAccountSpark

Represents an individual Spark wallet account with full write access. Implements IWalletAccount from @tetherto/wdk-wallet. Extends WalletAccountReadOnlySpark, inheriting all read-only methods.

Note: WalletAccountSpark instances are created internally by WalletManagerSpark.getAccount() and are not intended to be constructed directly.

Methods

All methods from WalletAccountReadOnlySpark are inherited. The following additional methods are available:

Method	Description	Returns
`getAddress()`	Returns the account's Spark address	`Promise<SparkAddressFormat>`
`sign(message)`	Signs a message using the account's identity key	`Promise<string>`
`sendTransaction(tx)`	Sends a Spark transaction	`Promise<{hash: string, fee: bigint}>`
`transfer(options)`	Transfers tokens to another address	`Promise<{hash: string, fee: bigint}>`
`getSingleUseDepositAddress()`	Generates a single-use Bitcoin deposit address	`Promise<string>`
`claimDeposit(txId)`	Claims a Bitcoin deposit to the wallet	`Promise<WalletLeaf[] \| undefined>`
`claimStaticDeposit(txId)`	Claims a static Bitcoin deposit to the wallet	`Promise<WalletLeaf[] \| undefined>`
`refundStaticDeposit(options)`	Refunds a static deposit back to a Bitcoin address	`Promise<string>`
`quoteWithdraw(options)`	Gets a fee quote for withdrawing funds	`Promise<CoopExitFeeQuote>`
`withdraw(options)`	Withdraws funds to a Bitcoin address	`Promise<CoopExitRequest \| null \| undefined>`
`createLightningInvoice(options)`	Creates a Lightning invoice	`Promise<LightningReceiveRequest>`
`getLightningReceiveRequest(invoiceId)`	Gets Lightning receive request by id	`Promise<LightningReceiveRequest \| null>`
`getLightningSendRequest(requestId)`	Gets Lightning send request by id	`Promise<LightningSendRequest \| null>`
`payLightningInvoice(options)`	Pays a Lightning invoice	`Promise<LightningSendRequest>`
`quotePayLightningInvoice(options)`	Gets fee estimate for Lightning payments	`Promise<bigint>`
`createSparkSatsInvoice(options)`	Creates a Spark invoice for receiving sats	`Promise<SparkAddressFormat>`
`createSparkTokensInvoice(options)`	Creates a Spark invoice for receiving tokens	`Promise<SparkAddressFormat>`
`paySparkInvoice(invoices)`	Pays one or more Spark invoices	`Promise<FulfillSparkInvoiceResponse>`
`toReadOnlyAccount()`	Creates a read-only version of this account	`Promise<WalletAccountReadOnlySpark>`
`dispose()`	Disposes the wallet account, clearing private keys	`void`

`getAddress()`

Returns the account's Spark network address.

Returns: Promise<SparkAddressFormat> - The account's Spark address

Example:

const address = await account.getAddress()
console.log('Spark address:', address) // spark1...

`sign(message)`

Signs a message using the account's identity key.

Parameters:

message (string): Message to sign

Returns: Promise<string> - Signature as hex string

Example:

const signature = await account.sign('Hello Spark!')
console.log('Signature:', signature)

`getIdentityKey()`

Returns the account's identity public key (hex-encoded).

Returns: Promise<string> - The identity public key

Example:

const identityKey = await account.getIdentityKey()
console.log('Identity key:', identityKey) // 02eda8...

`sendTransaction(tx)`

Sends a Spark transaction and broadcasts it to the network.

Parameters:

tx (object): The transaction object
- to (string): Recipient's Spark address
- value (number): Amount in satoshis

Returns: Promise<{hash: string, fee: bigint}> - Object containing hash and fee (fee is always 0)

Example:

const result = await account.sendTransaction({
  to: 'spark1...',
  value: 1000000 // 0.01 BTC in satoshis
})
console.log('Transaction hash:', result.hash)
console.log('Fee paid:', Number(result.fee), 'satoshis') // Always 0

`quoteSendTransaction(tx)`

Estimates the fee for a Spark transaction without broadcasting it.

Parameters:

tx (object): Same as sendTransaction parameters
- to (string): Recipient's Spark address
- value (number): Amount in satoshis

Returns: Promise<{fee: bigint}> - Object containing estimated fee (always 0)

Example:

const quote = await account.quoteSendTransaction({
  to: 'spark1...',
  value: 1000000 // 0.01 BTC in satoshis
})
console.log('Estimated fee:', Number(quote.fee), 'satoshis') // Always 0
console.log('Estimated fee in BTC:', Number(quote.fee) / 1e8)

`transfer(options)`

Transfers tokens to another address.

Parameters:

options (TransferOptions): Transfer options object
- token (string): Token identifier (Bech32m token identifier, e.g., btkn1...)
- amount (bigint): Amount of tokens to transfer
- recipient (string): Recipient Spark address

Returns: Promise<{hash: string, fee: bigint}> - Transfer result containing transaction details

Example:

const result = await account.transfer({
  token: 'btkn1...', // Token identifier
  amount: BigInt(1000000), // Amount of tokens
  recipient: 'spark1...' // Recipient address
})
console.log('Transfer hash:', result.hash)

`quoteTransfer(options)`

Quotes the costs of a transfer operation without executing it.

Parameters:

options (TransferOptions): Transfer options object

Returns: Promise<{fee: bigint}> - Transfer quote without transaction hash

Example:

const quote = await account.quoteTransfer({
  to: 'spark1...',
  value: 1000000
})
console.log('Transfer fee estimate:', Number(quote.fee))

`getBalance()`

Returns the account's total owned bitcoin balance in satoshis. This includes both available (spendable) sats and sats locked in pending outgoing transfers. This differs from WalletAccountReadOnlySpark.getBalance(), which only returns the available balance.

Returns: Promise<bigint> - Total owned balance in satoshis

Example:

const balance = await account.getBalance()
console.log('Balance:', balance, 'satoshis')
console.log('Balance in BTC:', Number(balance) / 1e8)

`getTokenBalance(tokenAddress)`

Returns the available-to-send balance for a specific token. Inherited from WalletAccountReadOnlySpark; both classes return the same available-to-send value.

Parameters:

tokenAddress (string): Token identifier (Bech32m token identifier, e.g., btkn1...)

Returns: Promise<bigint> - Token balance in base unit (available to send)

Example:

const tokenBalance = await account.getTokenBalance('btkn1...')
console.log('Token balance:', tokenBalance)

`getTransactionReceipt(hash)`

Gets a Spark transfer by its ID. Inherited from WalletAccountReadOnlySpark. Only returns Spark transfers, not on-chain Bitcoin transactions.

Parameters:

hash (string): The Spark transfer ID

Returns: Promise<Object | null> - The Spark transfer object, or null if not found

Example:

const transfer = await account.getTransactionReceipt('transfer-id...')
if (transfer) {
  console.log('Spark transfer:', transfer)
}

`getSingleUseDepositAddress()`

Generates a single-use Bitcoin deposit address for funding the Spark wallet.

Returns: Promise<string> - Bitcoin deposit address

Example:

const depositAddress = await account.getSingleUseDepositAddress()
console.log('Send Bitcoin to:', depositAddress)

`claimDeposit(txId)`

Claims a Bitcoin deposit to add funds to the Spark wallet.

Parameters:

txId (string): Bitcoin transaction ID of the deposit

Returns: Promise<WalletLeaf[] | undefined> - Wallet leaves created from the deposit

Example:

const leaves = await account.claimDeposit('bitcoin_tx_id...')
console.log('Claimed deposit:', leaves)

`claimStaticDeposit(txId)`

Claims a static Bitcoin deposit to add funds to the Spark wallet.

Parameters:

txId (string): Bitcoin transaction ID of the deposit

Returns: Promise<WalletLeaf[] | undefined> - Wallet leaves created from the deposit

Example:

const leaves = await account.claimStaticDeposit('bitcoin_tx_id...')
console.log('Claimed static deposit:', leaves)

`refundStaticDeposit(options)`

Refunds a deposit made to a static deposit address back to a specified Bitcoin address. The minimum fee is 300 satoshis.

Parameters:

options (object): Refund options
- depositTransactionId (string): The transaction ID of the original deposit
- outputIndex (number): The output index of the deposit
- destinationAddress (string): The Bitcoin address to send the refund to
- satsPerVbyteFee (number): The fee rate in sats per vbyte for the refund transaction

Returns: Promise<string> - The refund transaction as a hex string that needs to be broadcast

Example:

const refundTx = await account.refundStaticDeposit({
  depositTransactionId: 'txid...',
  outputIndex: 0,
  destinationAddress: 'bc1q...',
  satsPerVbyteFee: 10
})
console.log('Refund transaction (hex):', refundTx)
// Broadcast this transaction to the Bitcoin network

`quoteWithdraw(options)`

Gets a fee quote for withdrawing funds from Spark cooperatively to an on-chain Bitcoin address.

Parameters:

options (object): Withdrawal quote options
- withdrawalAddress (string): The Bitcoin address where the funds should be sent
- amountSats (number): The amount in satoshis to withdraw

Returns: Promise<CoopExitFeeQuote> - The withdrawal fee quote

Example:

const feeQuote = await account.quoteWithdraw({
  withdrawalAddress: 'bc1q...',
  amountSats: 1000000
})
console.log('Withdrawal fee quote:', feeQuote)

`withdraw(options)`

Withdraws funds from the Spark network to an on-chain Bitcoin address.

Parameters:

options (WithdrawOptions): Withdrawal options object
- onchainAddress (string): Bitcoin address to withdraw to
- amountSats (number): Amount in satoshis to withdraw
- Additional options from WithdrawParams may be supported

Returns: Promise<CoopExitRequest | null | undefined> - Withdrawal request details

Example:

// Withdraw funds to a Bitcoin address (fee quote is fetched internally)
const withdrawal = await account.withdraw({
  onchainAddress: 'bc1q...',
  amountSats: 1000000
})
console.log('Withdrawal request:', withdrawal)

Note: The fee quote is automatically fetched internally by the withdraw() method. Use quoteWithdraw() if you want to preview the fees before initiating a withdrawal.

`createLightningInvoice(options)`

Creates a Lightning invoice for receiving payments.

Parameters:

options (CreateLightningInvoiceParams): Invoice options object
- amountSats (number, optional): Amount in satoshis
- memo (string, optional): Invoice description
- Additional options from CreateLightningInvoiceParams may be supported

Returns: Promise<LightningReceiveRequest> - Lightning invoice details

Example:

const invoice = await account.createLightningInvoice({
  amountSats: 100000,
  memo: 'Payment for services'
})
console.log('Invoice:', invoice.invoice)

`getLightningReceiveRequest(invoiceId)`

Gets details of a previously created Lightning receive request.

Parameters:

invoiceId (string): Invoice ID

Returns: Promise<{id: string, invoice: string, status: string, value: number, memo?: string} | null> - Invoice details, or null if not found

Example:

const request = await account.getLightningReceiveRequest(invoiceId)
if (request) {
  console.log('Invoice status:', request.status)
}

`getLightningSendRequest(requestId)`

Gets a Lightning send request by id.

Parameters:

requestId (string): The id of the Lightning send request

Returns: Promise<LightningSendRequest | null> - The Lightning send request

Example:

const request = await account.getLightningSendRequest(requestId)
if (request) {
  console.log('Lightning send request:', request)
}

`payLightningInvoice(options)`

Pays a Lightning invoice.

Parameters:

options (PayLightningInvoiceParams): Payment options object
- encodedInvoice (string): BOLT11 Lightning invoice
- maxFeeSats (number, optional): Maximum fee willing to pay in satoshis
- Additional options from PayLightningInvoiceParams may be supported

Returns: Promise<LightningSendRequest> - Payment details

Example:

const payment = await account.payLightningInvoice({
  encodedInvoice: 'lnbc...',
  maxFeeSats: 1000
})
console.log('Payment result:', payment)

`quotePayLightningInvoice(options)`

Estimates the fee for paying a Lightning invoice.

Parameters:

options (LightningSendFeeEstimateInput): Fee estimation options
- encodedInvoice (string): BOLT11 Lightning invoice
- Additional options may be supported

Returns: Promise<bigint> - Estimated fee in satoshis

Example:

const feeEstimate = await account.quotePayLightningInvoice({
  encodedInvoice: 'lnbc...'
})
console.log('Estimated Lightning fee:', Number(feeEstimate), 'satoshis')

`createSparkSatsInvoice(options)`

Creates a Spark invoice for receiving a sats payment.

Parameters:

options (object): Invoice options
- amount (number, optional): The amount of sats to receive (optional for open invoices)
- memo (string, optional): Optional memo/description for the payment
- senderSparkAddress (SparkAddressFormat, optional): Optional Spark address of the expected sender
- expiryTime (Date, optional): Optional expiry time for the invoice

Returns: Promise<SparkAddressFormat> - A Spark invoice that can be paid by another Spark wallet

Example:

const invoice = await account.createSparkSatsInvoice({
  amount: 100000,
  memo: 'Payment for services'
})
console.log('Spark invoice:', invoice)

`createSparkTokensInvoice(options)`

Creates a Spark invoice for receiving a token payment.

Parameters:

options (object): Invoice options
- tokenIdentifier (string, optional): The Bech32m token identifier (e.g., btkn1...)
- amount (bigint, optional): The amount of tokens to receive
- memo (string, optional): Optional memo/description for the payment
- senderSparkAddress (SparkAddressFormat, optional): Optional Spark address of the expected sender
- expiryTime (Date, optional): Optional expiry time for the invoice

Returns: Promise<SparkAddressFormat> - A Spark invoice that can be paid by another Spark wallet

Example:

const invoice = await account.createSparkTokensInvoice({
  tokenIdentifier: 'btkn1...',
  amount: BigInt(1000),
  memo: 'Token payment'
})
console.log('Spark token invoice:', invoice)

`paySparkInvoice(invoices)`

Fulfills one or more Spark invoices by paying them.

Parameters:

invoices (SparkInvoice[]): Array of invoices to fulfill
- Each invoice has:
  - invoice (SparkAddressFormat): The Spark invoice to pay
  - amount (bigint, optional): Amount to pay (required for invoices without encoded amount)

Returns: Promise<FulfillSparkInvoiceResponse> - Response containing transaction results and errors

Example:

const result = await account.paySparkInvoice([
  {
    invoice: 'spark1...',
    amount: BigInt(100000)
  }
])
console.log('Payment result:', result)

`toReadOnlyAccount()`

Creates a read-only version of this account that can query data but not sign transactions.

Returns: Promise<WalletAccountReadOnlySpark> - Read-only account instance

Example:

const readOnlyAccount = await account.toReadOnlyAccount()
const balance = await readOnlyAccount.getBalance()

`cleanupConnections()`

Cleans up network connections and resources.

Returns: Promise<void>

Example:

await account.cleanupConnections()

`dispose()`

Disposes the wallet account, securely erasing the private key from memory.

Returns: void

Example:

account.dispose()
// Private key is now securely wiped from memory

Properties

Property	Type	Description
`index`	`number`	The derivation path index of this account
`path`	`string`	The full BIP-44 derivation path
`keyPair`	`KeyPair`	The account's public and private key pair

🌐 Supported Networks

This package works with the Spark blockchain through the @buildonspark/spark-sdk. The following networks are supported:

MAINNET - Spark production network
TESTNET - Spark test network
REGTEST - Spark regression test network (for development)

Network Configuration

Networks are configured using the network parameter in the wallet configuration:

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

// Mainnet (default)
const mainnetWallet = new WalletManagerSpark(seedPhrase, {
  network: 'MAINNET' // This is the default
})

// Testnet
const testnetWallet = new WalletManagerSpark(seedPhrase, {
  network: 'TESTNET'
})

// Regtest (for development)
const regtestWallet = new WalletManagerSpark(seedPhrase, {
  network: 'REGTEST'
})

Important Notes:

Network connections are handled internally by the Spark SDK
No custom RPC endpoints are supported - the SDK manages all network communication
Network selection affects derivation paths and transaction routing
Default network is 'MAINNET' if not specified

🔒 Security Considerations

Seed Phrase Security:
- Always store your seed phrase securely and never share it
- Use strong entropy for seed generation
- Keep backups in secure, offline locations
Private Key Management:
- The package handles private keys internally with memory safety features
- Identity keys are managed securely by the underlying Spark signer
- Keys are never stored on disk
- Keys are cleared from memory when dispose() is called
Network Security:
- The Spark SDK handles all network communication internally
- Network connections are managed by the @buildonspark/spark-sdk
- No custom RPC configuration is needed or supported
- Trust the Spark network's built-in security mechanisms
Transaction Validation:
- Always verify recipient Spark addresses before sending
- Double-check transaction amounts (in satoshis)
- Spark transactions have zero fees, so no fee validation is needed
- Transactions are final once broadcast to the Spark network
Lightning Network Security:
- Verify Lightning invoice details before payment
- Set appropriate maximum fee limits for Lightning payments
- Be aware that Lightning payments are typically instant and irreversible
- Store Lightning invoices securely if needed for record-keeping
Deposit/Withdrawal Security:
- Verify Bitcoin addresses when withdrawing to on-chain
- Understand withdrawal timing and confirmation requirements
- Only claim deposits from trusted Bitcoin transactions
- Monitor deposit addresses for expected transactions only
Memory Management:
- Always call dispose() on accounts and wallets when finished
- The Spark signer automatically clears sensitive data
- Avoid keeping references to disposed wallet instances
- Use proper error handling to ensure cleanup even on failures

🛠️ Development

Building

# Install dependencies
npm install

# Build TypeScript definitions
npm run build:types

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🆘 Support

For support, please open an issue on the GitHub repository.

Loading README…

Recent updates

View all

v1.0.0-beta.26PatchSeptember 14, 2026

What's Changed

fix: remove seed from derivation errors by @localhost41 in https://github.com/tetherto/wdk-wallet-spark/pull/112
chore(deps-dev): bump browserslist from 4.28.2 to 4.28.9 in the security-patch-updates group across 1 directory by @dependabot[bot] in https://github.com/tetherto/wdk-wallet-spark/pull/113
Release: v1.0.0-beta.26 by @jonathunne in https://github.com/tetherto/wdk-wallet-spark/pull/114

New Contributors

@localhost41 made their first contribution in https://github.com/tetherto/wdk-wallet-spark/pull/112

Full Changelog: https://github.com/tetherto/wdk-wallet-spark/compare/v1.0.0-beta.25...v1.0.0-beta.26

Related Building Blocks

README

View on GitHub

@tetherto/wdk-wallet-spark

Note: This package is currently in beta. Please test thoroughly in development environments before using in production.

🔍 About WDK

For detailed documentation about the complete WDK ecosystem, visit docs.wallet.tether.io.

🌟 Features

Liquid Bitcoin (LBTC) Derivation Paths: Support for BIP-44 standard derivation paths (m/44'/998')
Multi-Account Management: Create and manage multiple accounts from a single seed phrase
Transaction Management: Send transactions and get fee estimates with zero fees
Lightning Network Integration: Create invoices, pay Lightning invoices, and manage Lightning payments

⬇️ Installation

To install the @tetherto/wdk-wallet-spark package, follow these instructions:

You can install it using npm:

npm install @tetherto/wdk-wallet-spark

🚀 Quick Start

Importing from `@tetherto/wdk-wallet-spark`

WalletManagerSpark: Main class for managing wallets
WalletAccountSpark: Use this for full access accounts
WalletAccountReadOnlySpark: Use this for read-only accounts

Creating a New Wallet

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

// Use a BIP-39 seed phrase (replace with your own secure phrase)
const seedPhrase = 'test only example nut use this real life secret phrase must random'

// Create wallet manager with Spark network configuration
const wallet = new WalletManagerSpark(seedPhrase, {
  network: 'MAINNET' // 'MAINNET', 'TESTNET', or 'REGTEST'
})

// Get a full access account
const account = await wallet.getAccount(0)

// Get the account's Spark address
const address = await account.getAddress()
console.log('Account address:', address)

Note: The Spark wallet integrates with the Spark network using the @buildonspark/spark-sdk. Network configuration is limited to predefined networks, and there's no custom RPC provider option.

Managing Multiple Accounts

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

// Assume wallet is already created
// Get the first account (index 0)
const account = await wallet.getAccount(0)
const address = await account.getAddress()
console.log('Account 0 address:', address)

// Get the second account (index 1)
const account1 = await wallet.getAccount(1)
const address1 = await account1.getAddress()
console.log('Account 1 address:', address1)

// Get the third account (index 2)
const account2 = await wallet.getAccount(2)
const address2 = await account2.getAddress()
console.log('Account 2 address:', address2)

// Note: All accounts use BIP-44 derivation paths with pattern:
// m/44'/998'/{network}'/0/{index} where 998 is the coin type for Liquid Bitcoin
// and {network} is the network number (MAINNET=0, TESTNET=1, REGTEST=2)

Important Note: Custom derivation paths via getAccountByPath() are not supported on the Spark blockchain. Only indexed accounts using the standard BIP-44 pattern are available.

Checking Balances

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

// Assume wallet and account are already created
// Get native token balance (in satoshis)
const balance = await account.getBalance()
console.log('Native balance:', balance, 'satoshis')

// Get transfer history (default: 10 most recent transfers)
const transfers = await account.getTransfers()
console.log('Transfer history:', transfers)

// Get transfer history with options
const recentTransfers = await account.getTransfers({
  direction: 'all', // 'all', 'incoming', or 'outgoing'
  limit: 20,        // Number of transfers to fetch
  skip: 0           // Number of transfers to skip
})
console.log('Recent transfers:', recentTransfers)

// Get only incoming transfers
const incomingTransfers = await account.getTransfers({
  direction: 'incoming',
  limit: 5
})
console.log('Incoming transfers:', incomingTransfers)

Sending Transactions

// Send native tokens (satoshis)
const result = await account.sendTransaction({
  to: 'spark1...', // Recipient's Spark address
  value: 1000000   // Amount in satoshis
})
console.log('Transaction hash:', result.hash)
console.log('Transaction fee:', result.fee) // Always 0 for Spark transactions

// Get transaction fee estimate
const quote = await account.quoteSendTransaction({
  to: 'spark1...',
  value: 1000000
})
console.log('Estimated fee:', quote.fee) // Always returns 0

// Example with different amounts
const smallTransaction = await account.sendTransaction({
  to: 'spark1...',
  value: 100000 // 0.001 BTC in satoshis
})

const largeTransaction = await account.sendTransaction({
  to: 'spark1...',
  value: 10000000 // 0.1 BTC in satoshis
})

Important Notes:

Spark transactions have zero fees (fee: 0)
Memo/description functionality is not supported in sendTransaction
All amounts are specified in satoshis (1 BTC = 100,000,000 satoshis)
Addresses should be valid Spark network addresses

Message Signing and Verification

// Sign a message
const message = 'Hello, Spark!'
const signature = await account.sign(message)
console.log('Signature:', signature)

// Verify a signature (using read-only account)
const readOnlyAccount = await account.toReadOnlyAccount()
const isValid = await readOnlyAccount.verify(message, signature)
console.log('Signature valid:', isValid)

Memory Management

// Dispose wallet accounts to clear private keys from memory
account.dispose()

// Dispose entire wallet manager
wallet.dispose()

📚 API Reference

Class	Description	Methods
WalletManagerSpark	Main class for managing Spark wallets. Extends `WalletManager` from `@tetherto/wdk-wallet`.	Constructor, Methods
WalletAccountReadOnlySpark	Read-only Spark wallet account for querying balances, transfers, and deposit addresses without private keys.	Constructor, Methods
WalletAccountSpark	Full-access Spark wallet account. Implements `IWalletAccount`. Inherits all read-only methods.	Constructor, Methods, Properties

WalletManagerSpark

The main class for managing Spark wallets.
Extends WalletManager from @tetherto/wdk-wallet.

Constructor

new WalletManagerSpark(seed, config)

Parameters:

seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes
config (object, optional): Configuration object
- network (string, optional): 'MAINNET', 'TESTNET', or 'REGTEST' (default: 'MAINNET')

Methods

Method	Description	Returns
`getAccount(index)`	Returns a wallet account at the specified index	`Promise<WalletAccountSpark>`
`getFeeRates()`	Returns current fee rates for transactions (always zero for Spark)	`Promise<FeeRates>`
`dispose()`	Disposes all wallet accounts, clearing private keys from memory	`void`

`getAccount(index)`

Returns a Spark wallet account at the specified index using BIP-44 derivation path.

Parameters:

index (number, optional): The index of the account to get (default: 0)

Returns: Promise<WalletAccountSpark> - The Spark wallet account

Example:

const account = await wallet.getAccount(0)
const address = await account.getAddress()
console.log('Spark account address:', address)

Note: Uses derivation path pattern m/44'/998'/{network}'/0/{index} where 998 is the coin type for Liquid Bitcoin and {network} is the network number (MAINNET=0, TESTNET=1, REGTEST=2).

`getAccountByPath(path)`

Not supported on Spark blockchain. This method throws an error when called. Use getAccount(index) instead.

`getFeeRates()`

Returns current fee rates for Spark transactions from the network.

Returns: Promise<FeeRates> - Object containing fee rates in satoshis

normal: Standard fee rate for normal confirmation speed (always 0)
fast: Higher fee rate for faster confirmation (always 0)

Example:

const feeRates = await wallet.getFeeRates()
console.log('Normal fee rate:', feeRates.normal, 'satoshis')
console.log('Fast fee rate:', feeRates.fast, 'satoshis')

// Use in transaction (fees are always 0 on Spark)
const result = await account.sendTransaction({
  to: 'spark1...',
  value: 1000000 // 0.01 BTC in satoshis
})

`dispose()`

Disposes all Spark wallet accounts and clears sensitive data from memory.

Returns: void

Example:

wallet.dispose()
// All accounts and private keys are now securely wiped from memory

Important Notes:

All Spark transactions have zero fees
Network configuration is limited to predefined values
Uses BIP-44 derivation paths with coin type 998 for Liquid Bitcoin

WalletAccountReadOnlySpark

A read-only Spark wallet account for querying wallet data without needing private keys. Uses the SparkReadonlyClient from @buildonspark/spark-sdk for all queries.

Constructor

new WalletAccountReadOnlySpark(address, config)

Parameters:

address (string): The account's Spark address
config (object, optional): Configuration object
- network (string, optional): 'MAINNET', 'TESTNET', or 'REGTEST' (default: 'MAINNET')

Example:

import { WalletAccountReadOnlySpark } from '@tetherto/wdk-wallet-spark'

const readOnly = new WalletAccountReadOnlySpark('sp1pgs...', {
  network: 'MAINNET'
})

Methods

Method	Description	Returns
`getBalance()`	Returns the available (spendable) bitcoin balance in satoshis	`Promise<bigint>`
`getTokenBalance(tokenAddress)`	Returns the available-to-send balance for a specific token	`Promise<bigint>`
`getTransactionReceipt(hash)`	Gets a Spark transfer by its ID	`Promise<Object \| null>`
`getIdentityKey()`	Returns the account's identity public key	`Promise<string>`
`verify(message, signature)`	Verifies a message's signature	`Promise<boolean>`
`quoteSendTransaction(tx)`	Estimates transaction fee (always 0)	`Promise<{fee: bigint}>`
`quoteTransfer(options)`	Quotes the costs of a transfer operation	`Promise<{fee: bigint}>`
`getTransfers(options?)`	Returns the account's Spark transfer history	`Promise<SparkTransfer[]>`
`getUnusedDepositAddresses(options?)`	Returns unused single-use deposit addresses	`Promise<{depositAddresses: Array, offset: number}>`
`getStaticDepositAddresses()`	Returns all static deposit addresses	`Promise<Array>`
`getUtxosForDepositAddress(options)`	Returns confirmed UTXOs for a deposit address	`Promise<{utxos: Array<{txid: string, vout: number}>, offset: number}>`
`getSparkInvoices(params)`	Queries the status of Spark invoices	`Promise<{invoiceStatuses: Array, offset: number}>`

`getBalance()`

Returns the account's available (spendable) bitcoin balance in satoshis. This excludes sats that are locked in pending outgoing transfers.

Returns: Promise<bigint> - Available balance in satoshis

Example:

const balance = await readOnly.getBalance()
console.log('Balance:', balance, 'satoshis')

`getTokenBalance(tokenAddress)`

Returns the available-to-send balance for a specific token.

Parameters:

tokenAddress (string): Token identifier (Bech32m, e.g., btkn1...)

Returns: Promise<bigint> - Token balance (returns 0n if token not found)

Example:

const balance = await readOnly.getTokenBalance('btkn1...')
console.log('Token balance:', balance)

`getTransactionReceipt(hash)`

Gets a Spark transfer by its ID. Only returns Spark transfers, not on-chain Bitcoin transactions.

Parameters:

hash (string): The Spark transfer ID

Returns: Promise<Object | null> - The Spark transfer object, or null if not found

Example:

const transfer = await readOnly.getTransactionReceipt('transfer-id...')
if (transfer) {
  console.log('Spark transfer:', transfer)
}

`getIdentityKey()`

Returns the account's identity public key (hex-encoded), derived from the Spark address.

Returns: Promise<string> - The identity public key

Example:

const identityKey = await readOnly.getIdentityKey()
console.log('Identity key:', identityKey)

`verify(message, signature)`

Verifies a message's signature against the account's identity key.

Parameters:

message (string): The original message
signature (string): The signature to verify (hex-encoded, DER or compact)

Returns: Promise<boolean> - True if the signature is valid

Example:

const isValid = await readOnly.verify('Hello, Spark!', signatureHex)
console.log('Signature valid:', isValid)

`getTransfers(options?)`

Returns the account's Spark transfer history with filtering and pagination options. Only returns Spark transfers, not on-chain Bitcoin transactions.

Parameters:

options (object, optional): Filter options
- direction (string): 'all', 'incoming', or 'outgoing' (default: 'all')
- limit (number): Maximum transfers to return (default: 10)
- skip (number): Number of transfers to skip (default: 0)

Returns: Promise<Array> - Array of Spark transfer objects

Example:

const transfers = await readOnly.getTransfers({
  direction: 'incoming',
  limit: 5
})
console.log('Incoming transfers:', transfers)

`getUnusedDepositAddresses(options?)`

Returns unused single-use deposit addresses for the account.

Parameters:

options (object, optional): Pagination options
- limit (number): Maximum number of addresses to return (default: 100)
- offset (number): Pagination offset (default: 0)

Returns: Promise<{depositAddresses: Array, offset: number}> - Unused deposit addresses with pagination offset

Example:

const result = await readOnly.getUnusedDepositAddresses({ limit: 10 })
console.log('Unused addresses:', result.depositAddresses)

`getStaticDepositAddresses()`

Returns all static deposit addresses for the account.

Returns: Promise<Array> - Array of static deposit address objects

Example:

const addresses = await readOnly.getStaticDepositAddresses()
console.log('Static deposit addresses:', addresses)

`getUtxosForDepositAddress(options)`

Returns confirmed UTXOs for a specific deposit address.

Parameters:

options (object): Query options
- depositAddress (string): The Bitcoin deposit address to query
- limit (number, optional): Maximum number of UTXOs to return (default: 100)
- offset (number, optional): Pagination offset (default: 0)
- excludeClaimed (boolean, optional): If true, excludes already-claimed UTXOs

Returns: Promise<{utxos: Array<{txid: string, vout: number}>, offset: number}> - UTXOs with pagination offset

Example:

const result = await readOnly.getUtxosForDepositAddress({
  depositAddress: 'bc1q...',
  excludeClaimed: true
})
console.log('UTXOs:', result.utxos)

`getSparkInvoices(params)`

Queries the status of Spark invoices.

Parameters:

params (object): Query parameters
- invoices (string[]): Array of Spark invoice strings to query
- limit (number, optional): Maximum number of results to return (default: 100)
- offset (number, optional): Pagination offset (default: 0)

Returns: Promise<{invoiceStatuses: Array, offset: number}> - Invoice statuses with pagination offset

Example:

const result = await readOnly.getSparkInvoices({
  invoices: ['spark1invoice1', 'spark1invoice2']
})
console.log('Invoice statuses:', result.invoiceStatuses)

WalletAccountSpark

Represents an individual Spark wallet account with full write access. Implements IWalletAccount from @tetherto/wdk-wallet. Extends WalletAccountReadOnlySpark, inheriting all read-only methods.

Note: WalletAccountSpark instances are created internally by WalletManagerSpark.getAccount() and are not intended to be constructed directly.

Methods

All methods from WalletAccountReadOnlySpark are inherited. The following additional methods are available:

Method	Description	Returns
`getAddress()`	Returns the account's Spark address	`Promise<SparkAddressFormat>`
`sign(message)`	Signs a message using the account's identity key	`Promise<string>`
`sendTransaction(tx)`	Sends a Spark transaction	`Promise<{hash: string, fee: bigint}>`
`transfer(options)`	Transfers tokens to another address	`Promise<{hash: string, fee: bigint}>`
`getSingleUseDepositAddress()`	Generates a single-use Bitcoin deposit address	`Promise<string>`
`claimDeposit(txId)`	Claims a Bitcoin deposit to the wallet	`Promise<WalletLeaf[] \| undefined>`
`claimStaticDeposit(txId)`	Claims a static Bitcoin deposit to the wallet	`Promise<WalletLeaf[] \| undefined>`
`refundStaticDeposit(options)`	Refunds a static deposit back to a Bitcoin address	`Promise<string>`
`quoteWithdraw(options)`	Gets a fee quote for withdrawing funds	`Promise<CoopExitFeeQuote>`
`withdraw(options)`	Withdraws funds to a Bitcoin address	`Promise<CoopExitRequest \| null \| undefined>`
`createLightningInvoice(options)`	Creates a Lightning invoice	`Promise<LightningReceiveRequest>`
`getLightningReceiveRequest(invoiceId)`	Gets Lightning receive request by id	`Promise<LightningReceiveRequest \| null>`
`getLightningSendRequest(requestId)`	Gets Lightning send request by id	`Promise<LightningSendRequest \| null>`
`payLightningInvoice(options)`	Pays a Lightning invoice	`Promise<LightningSendRequest>`
`quotePayLightningInvoice(options)`	Gets fee estimate for Lightning payments	`Promise<bigint>`
`createSparkSatsInvoice(options)`	Creates a Spark invoice for receiving sats	`Promise<SparkAddressFormat>`
`createSparkTokensInvoice(options)`	Creates a Spark invoice for receiving tokens	`Promise<SparkAddressFormat>`
`paySparkInvoice(invoices)`	Pays one or more Spark invoices	`Promise<FulfillSparkInvoiceResponse>`
`toReadOnlyAccount()`	Creates a read-only version of this account	`Promise<WalletAccountReadOnlySpark>`
`dispose()`	Disposes the wallet account, clearing private keys	`void`

`getAddress()`

Returns the account's Spark network address.

Returns: Promise<SparkAddressFormat> - The account's Spark address

Example:

const address = await account.getAddress()
console.log('Spark address:', address) // spark1...

`sign(message)`

Signs a message using the account's identity key.

Parameters:

message (string): Message to sign

Returns: Promise<string> - Signature as hex string

Example:

const signature = await account.sign('Hello Spark!')
console.log('Signature:', signature)

`getIdentityKey()`

Returns the account's identity public key (hex-encoded).

Returns: Promise<string> - The identity public key

Example:

const identityKey = await account.getIdentityKey()
console.log('Identity key:', identityKey) // 02eda8...

`sendTransaction(tx)`

Sends a Spark transaction and broadcasts it to the network.

Parameters:

tx (object): The transaction object
- to (string): Recipient's Spark address
- value (number): Amount in satoshis

Returns: Promise<{hash: string, fee: bigint}> - Object containing hash and fee (fee is always 0)

Example:

const result = await account.sendTransaction({
  to: 'spark1...',
  value: 1000000 // 0.01 BTC in satoshis
})
console.log('Transaction hash:', result.hash)
console.log('Fee paid:', Number(result.fee), 'satoshis') // Always 0

`quoteSendTransaction(tx)`

Estimates the fee for a Spark transaction without broadcasting it.

Parameters:

tx (object): Same as sendTransaction parameters
- to (string): Recipient's Spark address
- value (number): Amount in satoshis

Returns: Promise<{fee: bigint}> - Object containing estimated fee (always 0)

Example:

const quote = await account.quoteSendTransaction({
  to: 'spark1...',
  value: 1000000 // 0.01 BTC in satoshis
})
console.log('Estimated fee:', Number(quote.fee), 'satoshis') // Always 0
console.log('Estimated fee in BTC:', Number(quote.fee) / 1e8)

`transfer(options)`

Transfers tokens to another address.

Parameters:

options (TransferOptions): Transfer options object
- token (string): Token identifier (Bech32m token identifier, e.g., btkn1...)
- amount (bigint): Amount of tokens to transfer
- recipient (string): Recipient Spark address

Returns: Promise<{hash: string, fee: bigint}> - Transfer result containing transaction details

Example:

const result = await account.transfer({
  token: 'btkn1...', // Token identifier
  amount: BigInt(1000000), // Amount of tokens
  recipient: 'spark1...' // Recipient address
})
console.log('Transfer hash:', result.hash)

`quoteTransfer(options)`

Quotes the costs of a transfer operation without executing it.

Parameters:

options (TransferOptions): Transfer options object

Returns: Promise<{fee: bigint}> - Transfer quote without transaction hash

Example:

const quote = await account.quoteTransfer({
  to: 'spark1...',
  value: 1000000
})
console.log('Transfer fee estimate:', Number(quote.fee))

`getBalance()`

Returns: Promise<bigint> - Total owned balance in satoshis

Example:

const balance = await account.getBalance()
console.log('Balance:', balance, 'satoshis')
console.log('Balance in BTC:', Number(balance) / 1e8)

`getTokenBalance(tokenAddress)`

Returns the available-to-send balance for a specific token. Inherited from WalletAccountReadOnlySpark; both classes return the same available-to-send value.

Parameters:

tokenAddress (string): Token identifier (Bech32m token identifier, e.g., btkn1...)

Returns: Promise<bigint> - Token balance in base unit (available to send)

Example:

const tokenBalance = await account.getTokenBalance('btkn1...')
console.log('Token balance:', tokenBalance)

`getTransactionReceipt(hash)`

Gets a Spark transfer by its ID. Inherited from WalletAccountReadOnlySpark. Only returns Spark transfers, not on-chain Bitcoin transactions.

Parameters:

hash (string): The Spark transfer ID

Returns: Promise<Object | null> - The Spark transfer object, or null if not found

Example:

const transfer = await account.getTransactionReceipt('transfer-id...')
if (transfer) {
  console.log('Spark transfer:', transfer)
}

`getSingleUseDepositAddress()`

Generates a single-use Bitcoin deposit address for funding the Spark wallet.

Returns: Promise<string> - Bitcoin deposit address

Example:

const depositAddress = await account.getSingleUseDepositAddress()
console.log('Send Bitcoin to:', depositAddress)

`claimDeposit(txId)`

Claims a Bitcoin deposit to add funds to the Spark wallet.

Parameters:

txId (string): Bitcoin transaction ID of the deposit

Returns: Promise<WalletLeaf[] | undefined> - Wallet leaves created from the deposit

Example:

const leaves = await account.claimDeposit('bitcoin_tx_id...')
console.log('Claimed deposit:', leaves)

`claimStaticDeposit(txId)`

Claims a static Bitcoin deposit to add funds to the Spark wallet.

Parameters:

txId (string): Bitcoin transaction ID of the deposit

Returns: Promise<WalletLeaf[] | undefined> - Wallet leaves created from the deposit

Example:

const leaves = await account.claimStaticDeposit('bitcoin_tx_id...')
console.log('Claimed static deposit:', leaves)

`refundStaticDeposit(options)`

Refunds a deposit made to a static deposit address back to a specified Bitcoin address. The minimum fee is 300 satoshis.

Parameters:

options (object): Refund options
- depositTransactionId (string): The transaction ID of the original deposit
- outputIndex (number): The output index of the deposit
- destinationAddress (string): The Bitcoin address to send the refund to
- satsPerVbyteFee (number): The fee rate in sats per vbyte for the refund transaction

Returns: Promise<string> - The refund transaction as a hex string that needs to be broadcast

Example:

const refundTx = await account.refundStaticDeposit({
  depositTransactionId: 'txid...',
  outputIndex: 0,
  destinationAddress: 'bc1q...',
  satsPerVbyteFee: 10
})
console.log('Refund transaction (hex):', refundTx)
// Broadcast this transaction to the Bitcoin network

`quoteWithdraw(options)`

Gets a fee quote for withdrawing funds from Spark cooperatively to an on-chain Bitcoin address.

Parameters:

options (object): Withdrawal quote options
- withdrawalAddress (string): The Bitcoin address where the funds should be sent
- amountSats (number): The amount in satoshis to withdraw

Returns: Promise<CoopExitFeeQuote> - The withdrawal fee quote

Example:

const feeQuote = await account.quoteWithdraw({
  withdrawalAddress: 'bc1q...',
  amountSats: 1000000
})
console.log('Withdrawal fee quote:', feeQuote)

`withdraw(options)`

Withdraws funds from the Spark network to an on-chain Bitcoin address.

Parameters:

options (WithdrawOptions): Withdrawal options object
- onchainAddress (string): Bitcoin address to withdraw to
- amountSats (number): Amount in satoshis to withdraw
- Additional options from WithdrawParams may be supported

Returns: Promise<CoopExitRequest | null | undefined> - Withdrawal request details

Example:

// Withdraw funds to a Bitcoin address (fee quote is fetched internally)
const withdrawal = await account.withdraw({
  onchainAddress: 'bc1q...',
  amountSats: 1000000
})
console.log('Withdrawal request:', withdrawal)

Note: The fee quote is automatically fetched internally by the withdraw() method. Use quoteWithdraw() if you want to preview the fees before initiating a withdrawal.

`createLightningInvoice(options)`

Creates a Lightning invoice for receiving payments.

Parameters:

options (CreateLightningInvoiceParams): Invoice options object
- amountSats (number, optional): Amount in satoshis
- memo (string, optional): Invoice description
- Additional options from CreateLightningInvoiceParams may be supported

Returns: Promise<LightningReceiveRequest> - Lightning invoice details

Example:

const invoice = await account.createLightningInvoice({
  amountSats: 100000,
  memo: 'Payment for services'
})
console.log('Invoice:', invoice.invoice)

`getLightningReceiveRequest(invoiceId)`

Gets details of a previously created Lightning receive request.

Parameters:

invoiceId (string): Invoice ID

Returns: Promise<{id: string, invoice: string, status: string, value: number, memo?: string} | null> - Invoice details, or null if not found

Example:

const request = await account.getLightningReceiveRequest(invoiceId)
if (request) {
  console.log('Invoice status:', request.status)
}

`getLightningSendRequest(requestId)`

Gets a Lightning send request by id.

Parameters:

requestId (string): The id of the Lightning send request

Returns: Promise<LightningSendRequest | null> - The Lightning send request

Example:

const request = await account.getLightningSendRequest(requestId)
if (request) {
  console.log('Lightning send request:', request)
}

`payLightningInvoice(options)`

Pays a Lightning invoice.

Parameters:

options (PayLightningInvoiceParams): Payment options object
- encodedInvoice (string): BOLT11 Lightning invoice
- maxFeeSats (number, optional): Maximum fee willing to pay in satoshis
- Additional options from PayLightningInvoiceParams may be supported

Returns: Promise<LightningSendRequest> - Payment details

Example:

const payment = await account.payLightningInvoice({
  encodedInvoice: 'lnbc...',
  maxFeeSats: 1000
})
console.log('Payment result:', payment)

`quotePayLightningInvoice(options)`

Estimates the fee for paying a Lightning invoice.

Parameters:

options (LightningSendFeeEstimateInput): Fee estimation options
- encodedInvoice (string): BOLT11 Lightning invoice
- Additional options may be supported

Returns: Promise<bigint> - Estimated fee in satoshis

Example:

const feeEstimate = await account.quotePayLightningInvoice({
  encodedInvoice: 'lnbc...'
})
console.log('Estimated Lightning fee:', Number(feeEstimate), 'satoshis')

`createSparkSatsInvoice(options)`

Creates a Spark invoice for receiving a sats payment.

Parameters:

options (object): Invoice options
- amount (number, optional): The amount of sats to receive (optional for open invoices)
- memo (string, optional): Optional memo/description for the payment
- senderSparkAddress (SparkAddressFormat, optional): Optional Spark address of the expected sender
- expiryTime (Date, optional): Optional expiry time for the invoice

Returns: Promise<SparkAddressFormat> - A Spark invoice that can be paid by another Spark wallet

Example:

const invoice = await account.createSparkSatsInvoice({
  amount: 100000,
  memo: 'Payment for services'
})
console.log('Spark invoice:', invoice)

`createSparkTokensInvoice(options)`

Creates a Spark invoice for receiving a token payment.

Parameters:

options (object): Invoice options
- tokenIdentifier (string, optional): The Bech32m token identifier (e.g., btkn1...)
- amount (bigint, optional): The amount of tokens to receive
- memo (string, optional): Optional memo/description for the payment
- senderSparkAddress (SparkAddressFormat, optional): Optional Spark address of the expected sender
- expiryTime (Date, optional): Optional expiry time for the invoice

Returns: Promise<SparkAddressFormat> - A Spark invoice that can be paid by another Spark wallet

Example:

const invoice = await account.createSparkTokensInvoice({
  tokenIdentifier: 'btkn1...',
  amount: BigInt(1000),
  memo: 'Token payment'
})
console.log('Spark token invoice:', invoice)

`paySparkInvoice(invoices)`

Fulfills one or more Spark invoices by paying them.

Parameters:

invoices (SparkInvoice[]): Array of invoices to fulfill
- Each invoice has:
  - invoice (SparkAddressFormat): The Spark invoice to pay
  - amount (bigint, optional): Amount to pay (required for invoices without encoded amount)

Returns: Promise<FulfillSparkInvoiceResponse> - Response containing transaction results and errors

Example:

const result = await account.paySparkInvoice([
  {
    invoice: 'spark1...',
    amount: BigInt(100000)
  }
])
console.log('Payment result:', result)

`toReadOnlyAccount()`

Creates a read-only version of this account that can query data but not sign transactions.

Returns: Promise<WalletAccountReadOnlySpark> - Read-only account instance

Example:

const readOnlyAccount = await account.toReadOnlyAccount()
const balance = await readOnlyAccount.getBalance()

`cleanupConnections()`

Cleans up network connections and resources.

Returns: Promise<void>

Example:

await account.cleanupConnections()

`dispose()`

Disposes the wallet account, securely erasing the private key from memory.

Returns: void

Example:

account.dispose()
// Private key is now securely wiped from memory

Properties

Property	Type	Description
`index`	`number`	The derivation path index of this account
`path`	`string`	The full BIP-44 derivation path
`keyPair`	`KeyPair`	The account's public and private key pair

🌐 Supported Networks

This package works with the Spark blockchain through the @buildonspark/spark-sdk. The following networks are supported:

MAINNET - Spark production network
TESTNET - Spark test network
REGTEST - Spark regression test network (for development)

Network Configuration

Networks are configured using the network parameter in the wallet configuration:

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

// Mainnet (default)
const mainnetWallet = new WalletManagerSpark(seedPhrase, {
  network: 'MAINNET' // This is the default
})

// Testnet
const testnetWallet = new WalletManagerSpark(seedPhrase, {
  network: 'TESTNET'
})

// Regtest (for development)
const regtestWallet = new WalletManagerSpark(seedPhrase, {
  network: 'REGTEST'
})

Important Notes:

Network connections are handled internally by the Spark SDK
No custom RPC endpoints are supported - the SDK manages all network communication
Network selection affects derivation paths and transaction routing
Default network is 'MAINNET' if not specified

🔒 Security Considerations

Seed Phrase Security:
- Always store your seed phrase securely and never share it
- Use strong entropy for seed generation
- Keep backups in secure, offline locations
Private Key Management:
- The package handles private keys internally with memory safety features
- Identity keys are managed securely by the underlying Spark signer
- Keys are never stored on disk
- Keys are cleared from memory when dispose() is called
Network Security:
- The Spark SDK handles all network communication internally
- Network connections are managed by the @buildonspark/spark-sdk
- No custom RPC configuration is needed or supported
- Trust the Spark network's built-in security mechanisms
Transaction Validation:
- Always verify recipient Spark addresses before sending
- Double-check transaction amounts (in satoshis)
- Spark transactions have zero fees, so no fee validation is needed
- Transactions are final once broadcast to the Spark network
Lightning Network Security:
- Verify Lightning invoice details before payment
- Set appropriate maximum fee limits for Lightning payments
- Be aware that Lightning payments are typically instant and irreversible
- Store Lightning invoices securely if needed for record-keeping
Deposit/Withdrawal Security:
- Verify Bitcoin addresses when withdrawing to on-chain
- Understand withdrawal timing and confirmation requirements
- Only claim deposits from trusted Bitcoin transactions
- Monitor deposit addresses for expected transactions only
Memory Management:
- Always call dispose() on accounts and wallets when finished
- The Spark signer automatically clears sensitive data
- Avoid keeping references to disposed wallet instances
- Use proper error handling to ensure cleanup even on failures

🛠️ Development

Building

# Install dependencies
npm install

# Build TypeScript definitions
npm run build:types

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🆘 Support

For support, please open an issue on the GitHub repository.

wdk-wallet-spark

Recent updates

What's Changed

New Contributors

Related Building Blocks

wdk-wallet-btc

wdk-wallet-evm

wdk-wallet-evm-erc4337

Building Blocks

wdk-wallet-spark

README

@tetherto/wdk-wallet-spark

🔍 About WDK

🌟 Features

⬇️ Installation

🚀 Quick Start

Importing from @tetherto/wdk-wallet-spark

Creating a New Wallet

Managing Multiple Accounts

Checking Balances

Sending Transactions

Message Signing and Verification

Memory Management

📚 API Reference

Table of Contents

WalletManagerSpark

Constructor

Methods

getAccount(index)

getAccountByPath(path)

getFeeRates()

dispose()

WalletAccountReadOnlySpark

Constructor

Methods

getBalance()

getTokenBalance(tokenAddress)

getTransactionReceipt(hash)

getIdentityKey()

verify(message, signature)

getTransfers(options?)

getUnusedDepositAddresses(options?)

getStaticDepositAddresses()

getUtxosForDepositAddress(options)

getSparkInvoices(params)

WalletAccountSpark

Methods

getAddress()

sign(message)

getIdentityKey()

sendTransaction(tx)

quoteSendTransaction(tx)

transfer(options)

quoteTransfer(options)

getBalance()

getTokenBalance(tokenAddress)

getTransactionReceipt(hash)

getSingleUseDepositAddress()

claimDeposit(txId)

claimStaticDeposit(txId)

refundStaticDeposit(options)

quoteWithdraw(options)

withdraw(options)

createLightningInvoice(options)

getLightningReceiveRequest(invoiceId)

getLightningSendRequest(requestId)

payLightningInvoice(options)

quotePayLightningInvoice(options)

createSparkSatsInvoice(options)

createSparkTokensInvoice(options)

paySparkInvoice(invoices)

toReadOnlyAccount()

cleanupConnections()

dispose()

Properties

🌐 Supported Networks

Network Configuration

🔒 Security Considerations

🛠️ Development

Building

Importing from `@tetherto/wdk-wallet-spark`

`getAccount(index)`

`getAccountByPath(path)`

`getFeeRates()`

`dispose()`

`getBalance()`

`getTokenBalance(tokenAddress)`

`getTransactionReceipt(hash)`

`getIdentityKey()`

`verify(message, signature)`

`getTransfers(options?)`

`getUnusedDepositAddresses(options?)`

`getStaticDepositAddresses()`

`getUtxosForDepositAddress(options)`

`getSparkInvoices(params)`

`getAddress()`

`sign(message)`

`getIdentityKey()`

`sendTransaction(tx)`

`quoteSendTransaction(tx)`

`transfer(options)`

`quoteTransfer(options)`

`getBalance()`

`getTokenBalance(tokenAddress)`

`getTransactionReceipt(hash)`

`getSingleUseDepositAddress()`

`claimDeposit(txId)`

`claimStaticDeposit(txId)`

`refundStaticDeposit(options)`

`quoteWithdraw(options)`

`withdraw(options)`

`createLightningInvoice(options)`

`getLightningReceiveRequest(invoiceId)`

`getLightningSendRequest(requestId)`

`payLightningInvoice(options)`

`quotePayLightningInvoice(options)`

`createSparkSatsInvoice(options)`

`createSparkTokensInvoice(options)`

`paySparkInvoice(invoices)`

`toReadOnlyAccount()`

`cleanupConnections()`

`dispose()`

Importing from `@tetherto/wdk-wallet-spark`

`getAccount(index)`

`getAccountByPath(path)`

`getFeeRates()`

`dispose()`

`getBalance()`

`getTokenBalance(tokenAddress)`

`getTransactionReceipt(hash)`

`getIdentityKey()`

`verify(message, signature)`

`getTransfers(options?)`

`getUnusedDepositAddresses(options?)`

`getStaticDepositAddresses()`

`getUtxosForDepositAddress(options)`

`getSparkInvoices(params)`

`getAddress()`

`sign(message)`

`getIdentityKey()`

`sendTransaction(tx)`

`quoteSendTransaction(tx)`

`transfer(options)`

`quoteTransfer(options)`

`getBalance()`

`getTokenBalance(tokenAddress)`

`getTransactionReceipt(hash)`

`getSingleUseDepositAddress()`

`claimDeposit(txId)`

`claimStaticDeposit(txId)`

`refundStaticDeposit(options)`

`quoteWithdraw(options)`

`withdraw(options)`

`createLightningInvoice(options)`

`getLightningReceiveRequest(invoiceId)`