Wallet Spark 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', 'SIGNET', or 'REGTEST' (default: 'MAINNET')
  • client (SparkReadonlyClient, optional): Existing read-only Spark client, reused as-is. The manager shares one read-only client across its accounts and their read-only conversions; signing wallets remain account-specific.
  • sparkscan (SparkScanConfig, optional): SparkScan configuration for balance polling. SparkScan accepts MAINNET and REGTEST; an unsupported network raises ValueError when the account is created.
  • syncAndRetry (boolean, optional): When true, native sends reconcile failures against history without resubmission; Lightning payments retry stale-leaf failures once with the same transfer ID
  • enableLogging (boolean, optional): When true, forwards logging to the underlying Spark SDK (default: false)

If HD-key derivation cannot produce the master key's private or public key, the wallet raises the Spark SDK ValidationError with field: 'hdkey'. If a derived child key is incomplete, it uses field: 'derivedKeys'. In beta.26 these derivation errors do not include seed bytes in their context; validation errors elsewhere may still contain sensitive context.

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

Throws: ValueError if sparkscan is configured for a network that SparkScan does not support.

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

getAccountByPath(path)

Spark accounts are addressed by index, so this method does not support caller-supplied BIP-44 paths and always throws.

Parameters:

• path (string): The derivation path segment (e.g. "0'/0/0")

Returns: Promise<WalletAccountSpark> - The account type in the base interface; this method always throws

Throws: UnsupportedOperationError because Spark accounts are addressed by index, not by a caller-supplied derivation path.

Example:

import { UnsupportedOperationError } from '@tetherto/wdk-wallet'

try {
  await wallet.getAccountByPath("0'/0/0")
} catch (error) {
  if (error instanceof UnsupportedOperationError) {
    console.log('Use wallet.getAccount(index) for Spark accounts')
  } else {
    throw error
  }
}

Important Notes:

• All Spark transactions have zero fees
• Accounts are addressed by index; getAccountByPath(path) is not supported
• SparkScan balance polling supports MAINNET and REGTEST

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)

signTransaction(tx)

Exposes the base IWalletAccount.signTransaction(tx) method, but standalone Spark transaction signing is not supported. Spark transfers are signed collaboratively with Spark operators through the FROST / Statechain protocol, so this method always throws. Use sendTransaction() to send Spark transactions.

Parameters:

• tx (SparkTransaction): The transaction request

Returns: Promise<never> - Always throws

Throws: UnsupportedOperationError because Spark transfers are signed collaboratively with Spark operators and cannot be signed locally.

Example:

import { UnsupportedOperationError } from '@tetherto/wdk-wallet'

try {
  await account.signTransaction({
    to: 'spark1...',
    value: 1000000
  })
} catch (error) {
  if (error instanceof UnsupportedOperationError) {
    console.error('Spark does not support standalone transaction signing')
  } else {
    throw error
  }
}

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({to, value})

Sends a Spark transaction.

When syncAndRetry is enabled, the wallet reads matching transfer history before submitting at most once. After a failed submission response, it syncs and returns a matching new transfer from history when found; otherwise it throws. An initial history-read failure prevents submission. Do not run identical recipient/amount sends concurrently from one wallet, because history matching cannot distinguish them.

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. When sparkscan is configured, this uses SparkScan's btcSoftBalanceSats value.

Returns: Promise<bigint> - Balance in satoshis

Throws: ProviderError if SparkScan is configured and returns a non-success HTTP response.

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)

Returns a Spark transfer by its ID. This method is deprecated; use getTransaction() for normalized status and keep using the returned transfer field when you need the native Spark object. Neither method looks up on-chain Bitcoin transactions.

Parameters:

• hash (string): The Spark transfer ID

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

Example:

const transfer = await account.getTransactionReceipt('transfer_id...')
console.log('Transfer details:', transfer)

getTransaction(hash)

Returns a normalized receipt for a Spark transfer ID. A transfer with status COMPLETED is final with success: true; EXPIRED and RETURNED transfers are dropped; every other Spark transfer status is pending. The receipt has fee: 0n and includes the native Spark transfer on transfer.

Parameters:

• hash (string): The Spark transfer ID returned by sendTransaction() or transfer()

Returns: Promise<TransactionReceipt & SparkTransactionDetails>

Throws: NoSuchElementError if Spark does not return a transfer for the ID.

const result = await account.sendTransaction({ to: 'spark1...', value: 1000n })
const transaction = await account.getTransaction(result.hash)

console.log(transaction.finality) // 'pending', 'final', or 'dropped'
console.log(transaction.transfer) // Native Spark transfer

waitForTransaction(hash, options?)

Polls getTransaction() until the requested target is reached, a dropped transfer is observed twice, or the wait times out. Defaults are target: 'confirmed', interval: 4000, timeout: 60000, and maxPollErrors: 3.

const transaction = await account.waitForTransaction(result.hash, {
  target: 'final',
  timeout: 120000
})

if (transaction.finality === 'dropped') {
  console.error('Spark transfer expired or was returned')
}

getTransfers(options?)

Returns the Spark transfer history of the account. Only returns Spark transfers, not on-chain Bitcoin transactions.

Parameters:

• options (GetTransfersOptions, 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 Spark transfers

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(options?)

Returns unused single-use deposit addresses for the account.

Parameters:

• options (Omit<QueryDepositAddressesParams, 'sparkAddress'>, optional): Query options

Returns: Promise<{depositAddresses: DepositAddressQueryResult[], offset: number}> - The unused deposit addresses with pagination offset

Example:

const result = await account.getUnusedDepositAddresses()
console.log('Unused addresses:', result.depositAddresses)
console.log('Offset:', result.offset)

getStaticDepositAddress()

Returns a static deposit address for Bitcoin deposits from layer 1, generating one if it does not already exist. This address can be reused.

Returns: Promise<string> - The static deposit address

Example:

const depositAddress = await account.getStaticDepositAddress()
console.log('Static deposit address:', depositAddress)

getStaticDepositAddresses()

Returns all existing static deposit addresses for the account.

Returns: Promise<DepositAddressQueryResult[]> - The static deposit addresses

Example:

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

getUtxosForDepositAddress(options)

Returns confirmed UTXOs for a specific deposit address.

Parameters:

• options (GetUtxosParams): Query options

Returns: Promise<{utxos: {txid: string, vout: number}[], offset: number}> - The confirmed UTXOs with pagination offset

Example:

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

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)

Initiates a withdrawal to move funds from the Spark network to an on-chain Bitcoin address.

Parameters:

• options (WithdrawOptions): Withdrawal options object (Omit<WithdrawParams, 'feeQuote'>)
  • onchainAddress (string): Bitcoin address to withdraw to
  • amountSats (number): Amount in satoshis to withdraw

Returns: Promise<CoopExitRequest | null | undefined> - The withdrawal request details, or null/undefined if the request cannot be completed

Example:

const withdrawal = await account.withdraw({
  onchainAddress: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
  amountSats: 100000
})
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.

When syncAndRetry is enabled, the wallet syncs after a payment failure and retries once only for a stale-leaf error. It reuses options.transferId, or generates an ID when omitted, for both attempts. An unrecovered payment failure raises LightningPaymentError carrying that transfer ID and the original cause. Setup or sync failures may use other error types. Reuse the ID with the same invoice and options if you later choose to retry.

Parameters:

• options (PayLightningInvoiceParams): Payment options object
  • invoice (string): BOLT11 Lightning invoice
  • maxFeeSats (number): Maximum fee willing to pay in satoshis
  • transferId (UUID, optional): Spark transfer ID to reuse for another attempt of the same payment
  • Additional options from PayLightningInvoiceParams may be supported

Returns: Promise<LightningSendRequest> - Payment details

Example:

const payment = await account.payLightningInvoice({
  invoice: '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)

syncWalletBalance()

Reconciles the wallet's internal state with the server and waits for any triggered optimization to complete.

Returns: Promise<void>

Example:

await account.syncWalletBalance()

getSparkInvoices(params)

Queries the status of Spark invoices.

Parameters:

• params (QuerySparkInvoicesParams): The query parameters

Returns: Promise<{invoiceStatuses: InvoiceResponse[], offset: number}> - The invoice statuses with pagination offset

Example:

const result = await account.getSparkInvoices({
  sparkAddress: await account.getAddress()
})
console.log('Invoice statuses:', result.invoiceStatuses)

toReadOnlyAccount()

Returns a read-only version of this account that can query data but not sign transactions. After the first call, subsequent calls reuse the same read-only account instance.

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

Throws: ValueError if sparkscan is configured for a network that SparkScan does not support.

Methods

getAddress()

Returns the account's Spark network address.

Returns: Promise<SparkAddressFormat> - The Spark address

Example:

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

getIdentityKey()

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

Returns: Promise<string> - The identity public key

Example:

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

getBalance()

Returns the account's native token balance in satoshis. When sparkscan is configured, this uses SparkScan's btcSoftBalanceSats value.

Returns: Promise<bigint> - Balance in satoshis

Throws: ProviderError if SparkScan is configured and returns a non-success HTTP response.

Example:

const balance = await readOnlyAccount.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 readOnlyAccount.getTokenBalance('token_address...')
console.log('Token balance:', tokenBalance)

getTransactionReceipt(hash)

Returns a Spark transfer by its ID. This method is deprecated in favor of getTransaction(). The read-only account's getTransaction() and waitForTransaction() use the same Spark transfer-ID, finality, timeout, and raw transfer semantics documented above. These methods do not look up on-chain Bitcoin transactions.

Parameters:

• hash (string): The Spark transfer ID

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

Example:

const transfer = await readOnlyAccount.getTransactionReceipt('transfer_id...')
console.log('Transfer details:', transfer)

getTransfers(options?)

Returns the Spark transfer history of the account. Only returns Spark transfers, not on-chain Bitcoin transactions.

Parameters:

• options (GetTransfersOptions, 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 Spark transfers

Example:

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

getUnusedDepositAddresses(options?)

Returns unused single-use deposit addresses for the account.

Parameters:

• options (Omit<QueryDepositAddressesParams, 'sparkAddress'>, optional): Query options

Returns: Promise<{depositAddresses: DepositAddressQueryResult[], offset: number}> - The unused deposit addresses with pagination offset

Example:

const result = await readOnlyAccount.getUnusedDepositAddresses()
console.log('Unused addresses:', result.depositAddresses)

getStaticDepositAddresses()

Returns all existing static deposit addresses for the account.

Returns: Promise<DepositAddressQueryResult[]> - The static deposit addresses

Example:

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

getUtxosForDepositAddress(options)

Returns confirmed UTXOs for a specific deposit address.

Parameters:

• options (GetUtxosParams): Query options

Returns: Promise<{utxos: {txid: string, vout: number}[], offset: number}> - The confirmed UTXOs with pagination offset

Example:

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

getSparkInvoices(params)

Queries the status of Spark invoices.

Parameters:

• params (QuerySparkInvoicesParams): The query parameters

Returns: Promise<{invoiceStatuses: InvoiceResponse[], offset: number}> - The invoice statuses with pagination offset

Example:

const result = await readOnlyAccount.getSparkInvoices({
  sparkAddress: await readOnlyAccount.getAddress()
})
console.log('Invoice statuses:', result.invoiceStatuses)

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 readOnlyAccount.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 readOnlyAccount.quoteTransfer({
  token: 'btkn1...',
  amount: BigInt(1000000),
  recipient: 'spark1...'
})
console.log('Transfer fee:', Number(quote.fee))

Types

SparkScanConfig

interface SparkScanConfig {
  baseUrl?: string  // Optional SparkScan URL (default: "https://api.sparkscan.io")
  network?: 'MAINNET' | 'SIGNET' | 'REGTEST'  // Spark network, SparkScan only accepts MAINNET and REGTEST at runtime
  apiKey?: string  // Optional API key for SparkScan requests
}

When SparkScan is used by getBalance(), a non-success HTTP response throws ProviderError. Inspect error.reason (ProviderErrorReason) for the response category: UNAUTHORIZED for HTTP 401, FORBIDDEN for 403, REQUEST_TIMEOUT for 408 or 504, INTERNAL_SERVER_ERROR for other 5xx responses, and NETWORK_ERROR for other non-2xx responses.

LightningPaymentError

Exported from @tetherto/wdk-wallet-spark; extends WdkError. Its transferId is the Spark transfer ID used for the failed Lightning payment, and cause preserves the underlying error. It is distinct from the Lightning request ID accepted by getLightningSendRequest().

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

SparkWalletConfig

interface SparkWalletConfig {
  network?: 'MAINNET' | 'SIGNET' | 'REGTEST'  // The network (default: "MAINNET")
  client?: SparkReadonlyClient // Existing read-only client; match the configured network
  sparkscan?: SparkScanConfig  // Optional SparkScan configuration for balance polling
  syncAndRetry?: boolean       // Native send recovery and stale-leaf Lightning retry
  enableLogging?: boolean     // Logging for newly constructed SDK clients/wallets
}

SparkReadonlyClient is a type exported by this WDK package. Import the runtime class from @buildonspark/spark-sdk; see the client configuration example. A supplied client keeps its existing network and logging settings.

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 | null  // Private key bytes; null after dispose() is called
}

The arrays returned by keyPair are bound to the wallet account. Treat them as a read-only view — do not modify their contents. privateKey is null after dispose() is called.

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
}

TransferOptions

interface TransferOptions {
  token: string      // Token identifier (Bech32m, e.g. btkn1...)
  amount: bigint     // Amount of tokens to transfer
  recipient: string  // Recipient Spark address
}

GetTransfersOptions

interface GetTransfersOptions {
  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 Transfer from @buildonspark/spark-sdk/proto/spark. 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
}

DepositAddressQueryResult

From @buildonspark/spark-sdk/proto/spark:

interface DepositAddressQueryResult {
  address: string       // The deposit address
  confirmationStatus: string  // Confirmation status
}

InvoiceResponse

From @buildonspark/spark-sdk/proto/spark:

interface InvoiceResponse {
  invoiceId: string     // The invoice identifier
  status: string        // The invoice status
}

QueryDepositAddressesParams

interface QueryDepositAddressesParams {
  sparkAddress: string  // The Spark address to query deposit addresses for
  offset?: number       // Pagination offset
  limit?: number        // Maximum results to return
}

GetUtxosParams

interface GetUtxosParams {
  depositAddress: string  // The deposit address to query UTXOs for
  offset?: number         // Pagination offset
  limit?: number          // Maximum results to return
}

QuerySparkInvoicesParams

interface QuerySparkInvoicesParams {
  sparkAddress: string  // The Spark address to query invoices for
  offset?: number       // Pagination offset
  limit?: number        // Maximum results to return
}

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

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

const paymentOptions: PayLightningInvoiceParams = {
  invoice: 'lnbc...',
  maxFeeSats: 1000
}

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

// WithdrawOptions = Omit<WithdrawParams, 'feeQuote'>
interface WithdrawOptions {
  onchainAddress: string  // Bitcoin address where the funds should be sent
  amountSats: number      // Amount in satoshis to withdraw
}

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?