API Reference

Complete API documentation for @tetherto/wdk-wallet-spark

Table of Contents

Class	Description	Methods
WalletManagerSpark	Main class for managing Spark wallets. Extends WalletManager from @tetherto/wdk-wallet.	Constructor, Methods
WalletAccountSpark	Individual Spark wallet account implementation. Implements IWalletAccount.	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<{normal: bigint, fast: bigint}>
dispose()	Disposes all wallet accounts, clearing private keys from memory	void

getAccount(index)

Returns a 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 wallet account

Example:

const account = await wallet.getAccount(0)
const account1 = await wallet.getAccount(1)

Note: Uses derivation path pattern m/44'/998'/{networkNumber}'/0/{index} where 998 is the coin type for Spark and networkNumber is 0 for MAINNET, 1 for TESTNET, 2 for SIGNET, or 3 for REGTEST.

getFeeRates()

Returns current fee rates for transactions. On Spark network, transactions have zero fees.

Returns: Promise<{normal: bigint, fast: bigint}> - Object containing fee rates (always {normal: 0n, fast: 0n})

Example:

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

dispose()

Disposes all wallet accounts and clears sensitive data from memory.

Returns: void

Example:

wallet.dispose()

Important Notes:

• getAccountByPath(path) is not supported and will throw an error

• Custom derivation paths are not available - only indexed accounts

• All Spark transactions have zero fees

• Network configuration is limited to predefined values

WalletAccountSpark

Represents an individual Spark wallet account. Implements IWalletAccount from @tetherto/wdk-wallet.

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

Methods

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>
verify(message, signature)	Verifies a message signature	Promise<boolean>
sendTransaction(tx)	Sends a Spark transaction	Promise<{hash: string, fee: bigint}>
quoteSendTransaction(tx)	Estimates transaction fee (always 0)	Promise<{fee: bigint}>
transfer(options)	Transfers tokens to another address	Promise<{hash: string, fee: bigint}>
quoteTransfer(options)	Quotes the costs of a transfer operation	Promise<{fee: bigint}>
getBalance()	Returns the native token balance in satoshis	Promise<bigint>
getTokenBalance(tokenAddress)	Returns the balance for a specific token	Promise<bigint>
getTransactionReceipt(hash)	Gets the transaction receipt for a given transaction hash	Promise<SparkTransactionReceipt | null>
getTransfers(options?)	Returns the account's transfer history	Promise<SparkTransfer[]>
getSingleUseDepositAddress()	Generates a single-use Bitcoin deposit address	Promise<string>
getUnusedDepositAddresses()	Gets all unused single-use deposit addresses	Promise<string[]>
getStaticDepositAddress()	Gets static deposit address for Bitcoin deposits	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>
getSparkInvoices(invoices)	Queries the status of Spark invoices	Promise<QuerySparkInvoicesResponse>
toReadOnlyAccount()	Creates a read-only version of this account	Promise<WalletAccountReadOnlySpark>
cleanupConnections()	Cleans up network connections and resources	Promise<void>
dispose()	Disposes the wallet account, clearing private keys	void

getAddress()

Returns the account's Spark network address.

Returns: Promise<SparkAddressFormat> - The Spark address

Example:

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

sign(message)

Signs a message using the account's identity key.

Parameters:

• message (string): The message to sign

Returns: Promise<string> - The message signature

Example:

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

verify(message, signature)

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

Parameters:

• message (string): The original message

• signature (string): The signature to verify

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

Example:

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

sendTransaction({to, value})

Sends a Spark transaction.

Parameters:

• to (string): Recipient's Spark address

• value (number): Amount in satoshis

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

Example:

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

quoteSendTransaction({to, value})

Estimates the fee for a Spark transaction (always returns 0).

Parameters:

• to (string): Recipient's Spark address

• value (number): Amount in satoshis

Returns: Promise<{fee: bigint}> - Fee estimate (always 0)

Example:

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

transfer(options)

Transfers tokens to another address.

Parameters:

• options (object): Transfer options

  • 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

Example:

const result = await account.transfer({
  token: 'btkn1...',
  amount: BigInt(1000000),
  recipient: 'spark1...'
})
console.log('Transfer hash:', result.hash)

quoteTransfer(options)

Quotes the costs of a transfer operation.

Parameters:

• options (object): Transfer options (same as transfer)

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

Example:

const quote = await account.quoteTransfer({
  token: 'btkn1...',
  amount: BigInt(1000000),
  recipient: 'spark1...'
})
console.log('Transfer fee:', Number(quote.fee))

getBalance()

Returns the account's native token balance in satoshis.

Returns: Promise<bigint> - 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 balance for a specific token.

Parameters:

• tokenAddress (string): Token contract address

Returns: Promise<bigint> - Token balance in base unit

Example:

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

getTransactionReceipt(hash)

Gets the transaction receipt for a given transaction hash.

Parameters:

• hash (string): Transaction hash

Returns: Promise<SparkTransactionReceipt | null> - Transaction receipt details, or null if not found

Example:

const receipt = await account.getTransactionReceipt('0x...')
console.log('Transaction receipt:', receipt)

getTransfers(options?)

Returns the account's transfer history with filtering options.

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<SparkTransfer[]> - Array of transfer objects (type alias for WalletTransfer from @buildonspark/spark-sdk)

Example:

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

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)

getUnusedDepositAddresses()

Gets all unused single-use deposit addresses.

Returns: Promise<string[]> - List of unused deposit addresses

Example:

const unusedAddresses = await account.getUnusedDepositAddresses()
console.log('Unused deposit addresses:', unusedAddresses)

getStaticDepositAddress()

Gets static deposit address for Bitcoin deposits from layer 1. This address can be reused.

Returns: Promise<string> - The static deposit address

Example:

const depositAddress = await account.getStaticDepositAddress()
console.log('Static deposit address:', 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)
// Note: This transaction needs to be broadcast 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:

// First, get a fee quote
const feeQuote = await account.quoteWithdraw({
  withdrawalAddress: 'bc1q...',
  amountSats: 1000000
})

// Then withdraw with the quote
const withdrawal = await account.withdraw({
  onchainAddress: 'bc1q...',
  amountSats: 1000000,
  feeQuote: feeQuote
})
console.log('Withdrawal request:', 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<LightningReceiveRequest | 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)

getSparkInvoices(invoices)

Queries the status of Spark invoices.

Parameters:

• invoices (string[]): Array of invoice addresses to query

Returns: Promise<QuerySparkInvoicesResponse> - Response containing invoice status information

Example:

const status = await account.getSparkInvoices([
  'spark1...',
  'spark1...'
])
console.log('Invoice statuses:', status)

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 private keys from memory.

Returns: void

Example:

account.dispose()
// Private keys are now cleared 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

Types

SparkWalletConfig

interface SparkWalletConfig {
  network?: 'MAINNET' | 'TESTNET' | 'REGTEST'  // The network (default: "MAINNET")
  sparkScanApiKey?: string                      // Optional API key for SparkScan requests
}

SparkTransaction

interface SparkTransaction {
  to: string              // The transaction's recipient (Spark address)
  value: number | bigint  // The amount of bitcoins to send to the recipient (in satoshis)
}

TransactionResult

interface TransactionResult {
  hash: string  // Transaction hash/ID
  fee: bigint   // Transaction fee in satoshis (always 0n for Spark)
}

KeyPair

interface KeyPair {
  publicKey: Uint8Array   // Public key bytes
  privateKey: Uint8Array  // Private key bytes
}

LightningReceiveRequest

interface LightningReceiveRequest {
  invoice: string    // BOLT11 encoded Lightning invoice
  id: string        // Invoice ID for tracking
  amountSats: number // Amount in satoshis
  memo?: string     // Optional description
}

LightningSendRequest

interface LightningSendRequest {
  id: string           // Payment request ID
  invoice: string      // BOLT11 encoded invoice that was paid
  maxFeeSats: number   // Maximum fee that was allowed
  status: string       // Payment status
}

WalletLeaf

interface WalletLeaf {
  // Spark SDK internal structure for wallet state
  // Exact properties depend on Spark SDK implementation
}

CoopExitRequest

interface CoopExitRequest {
  id: string              // Withdrawal request ID
  onchainAddress: string  // Bitcoin address for withdrawal
  amountSats: number      // Amount in satoshis
  exitSpeed: string       // Withdrawal speed ('FAST', 'MEDIUM', 'SLOW')
  status: string          // Withdrawal status
}

SparkTransactionReceipt

Type alias for TxV1Response from @sparkscan/api-node-sdk-client. Key properties include:

interface SparkTransactionReceipt {
  id: string                // Transaction ID
  type: string              // Transaction type
  status: 'confirmed' | 'pending' | 'sent' | 'failed' | 'expired'
  amountSats: number        // Transfer amount in satoshis
  txid?: string | null      // Bitcoin transaction ID (if applicable)
  createdAt?: string | null // When the transaction was initiated
  updatedAt?: string | null // Last update timestamp
}

TransferOptions

interface TransferOptions {
  direction?: 'incoming' | 'outgoing' | 'all'  // Filter by direction (default: 'all')
  limit?: number                               // Number of transfers to return (default: 10)
  skip?: number                                // Number of transfers to skip (default: 0)
}

SparkTransfer

Type alias for WalletTransfer from @buildonspark/spark-sdk. Key properties include:

interface SparkTransfer {
  id: string                    // Transfer ID
  status: string                // Transfer status
  totalValue: number            // Total value in satoshis
  transferDirection: string     // 'INCOMING' or 'OUTGOING'
  type: string                  // Transfer type
  createdTime?: Date            // When the transfer was created
  updatedTime?: Date            // Last update timestamp
}

Lightning Invoice Options

// Use CreateLightningInvoiceParams from @buildonspark/spark-sdk
// Basic options include:
interface CreateLightningInvoiceParams {
  amountSats?: number  // Amount in satoshis
  memo?: string         // Optional description for the invoice
  // Additional options may be available
}

Lightning Payment Options

// Use PayLightningInvoiceParams from @buildonspark/spark-sdk
// Basic options include:
interface PayLightningInvoiceParams {
  encodedInvoice: string  // BOLT11-encoded Lightning invoice to pay
  maxFeeSats?: number     // Maximum fee in satoshis to pay
  // Additional options may be available
}

Lightning Fee Estimate Options

// Use LightningSendFeeEstimateInput from @buildonspark/spark-sdk/types
// Basic options include:
interface LightningSendFeeEstimateInput {
  encodedInvoice: string  // BOLT11-encoded Lightning invoice to estimate fees for
  // Additional options may be available
}

Withdrawal Options

interface WithdrawOptions {
  onchainAddress: string  // Bitcoin address where the funds should be sent
  amountSats: number      // Amount in satoshis to withdraw
  // Additional options from WithdrawParams may be supported
}

interface QuoteWithdrawOptions {
  withdrawalAddress: string  // Bitcoin address where the funds should be sent
  amountSats: number        // Amount in satoshis to withdraw
}

Spark Invoice Options

interface CreateSatsInvoiceOptions {
  amount?: number              // Amount of sats to receive (optional for open invoices)
  memo?: string                // Optional memo/description
  senderSparkAddress?: string  // Optional Spark address of expected sender
  expiryTime?: Date           // Optional expiry time
}

interface CreateTokensInvoiceOptions {
  tokenIdentifier?: string     // Bech32m token identifier (e.g., btkn1...)
  amount?: bigint             // Amount of tokens to receive
  memo?: string                // Optional memo/description
  senderSparkAddress?: string  // Optional Spark address of expected sender
  expiryTime?: Date           // Optional expiry time
}

interface SparkInvoice {
  invoice: string   // The Spark invoice to pay
  amount?: bigint   // Amount to pay (required for invoices without encoded amount)
}

Refund Options

interface RefundStaticDepositOptions {
  depositTransactionId: string  // Transaction ID of the original deposit
  outputIndex: number            // Output index of the deposit
  destinationAddress: string     // Bitcoin address to send refund to
  satsPerVbyteFee: number        // Fee rate in sats per vbyte
}

Node.js Quickstart

Get started with WDK in a Node.js environment

React Native Quickstart

Build mobile wallets with React Native Expo

WDK Spark Wallet Usage

Get started with WDK's Spark Wallet Usage

WDK Spark Wallet Configuration

Get started with WDK's Spark Wallet Configuration

---

Need Help?

Discord Community

Connect with developers, ask questions, share your projects

Join Community

GitHub Issues

Report bugs, request features, and get technical help

Open an Issue

Email Contact

For sensitive or private matters, contact our team directly

Send an email