API Reference

Table of Contents

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' or 'REGTEST' (default: 'MAINNET')

Methods

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, 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

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)

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')

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)

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

WalletAccountReadOnlySpark

Represents a read-only wallet account. Implements WalletAccountReadOnly from @tetherto/wdk-wallet.

Constructor

new WalletAccountReadOnlySpark(address, config)

Parameters:

• address (string): The account's Spark address
• config (SparkWalletConfig, optional): Configuration object

Methods

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)

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)

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')

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)

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

quoteTransfer(options)

Quotes the costs of a transfer operation.

Parameters:

• options (object): Transfer options
  • token (string): Token identifier
  • amount (bigint): Amount of tokens
  • recipient (string): Recipient Spark address

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

Types

SparkWalletConfig

interface SparkWalletConfig {
  network?: 'MAINNET' | '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') - default: 'MEDIUM'
  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
}

Need Help?