API Reference

​

SparkWallet

​

Installation

yarn add @buildonspark/spark-sdk

npm i @buildonspark/spark-sdk

​

Methods

​

initialize({ mnemonicOrSeed, signer, options }: SparkWalletProps)

interface SparkWalletProps {
  mnemonicOrSeed?: Uint8Array | string;
  accountNumner?: number
  signer?: SparkSigner;
  options?: ConfigOptions;
}

static async initialize(props: SparkWalletProps): Promise<{
  wallet: SparkWallet;
  mnemonic?: string;
}>

• props: Object containing:
  • mnemonicOrSeed: (Optional) BIP-39 mnemonic phrase or raw seed
  • accountNumber: (Optional) number used to generate multiple identity keys from the same mnemonic
  • signer: (Optional) Custom signer implementation
  • options: (Optional) Wallet configuration options

• Object containing:
  • wallet: The initialized SparkWallet instance
  • mnemonic: The mnemonic if one was generated (undefined for raw seed)

​

getIdentityPublicKey()

async getIdentityPublicKey(): Promise<string>

• Promise<string>: The identity public key as a hex string

​

getSparkAddress()

async getSparkAddress(): Promise<SparkAddressFormat>

• Promise<SparkAddressFormat>: The Spark Address

​

getTransfers(limit?: number, offset?: number)

async getTransfers(
  limit: number = 20,
  offset: number = 0
): Promise<{
  transfers: WalletTransfer[];
  offset: number;
}>

• limit: (Optional, default: 20) Maximum number of transfers to return
• offset: (Optional, default: 0) Offset for pagination

• Promise<{ transfers: WalletTransfer[]; offset: number; }>: Response containing the list of transfers and offset

​

getBalance()

async getBalance(): Promise<{
  balance: bigint;
  tokenBalances: Map<string, { balance: bigint, bech32mTokenIdentifier: string }>;
}>

• Object containing:
  • balance: The wallet’s current balance in satoshis
  • tokenBalances: Map of token public keys to token balances with Bech32m token identifiers

​

getSingleUseDepositAddress()

async getSingleUseDepositAddress(): Promise<string>

• Promise<string>: A Bitcoin address for depositing funds

​

getUnusedDepositAddresses()

async getUnusedDepositAddresses(): Promise<string[]>

• Promise<string[]>: Array of unused deposit addresses

​

transfer(params)

async transfer({
  receiverSparkAddress,
  amountSats,
}: {
  receiverSparkAddress: string;
  amountSats: number;
}): Promise<WalletTransfer>

• params: Object containing:
  • receiverSparkAddress: The recipient’s Spark Address
  • amountSats: The amount in satoshis to transfer

• Promise<WalletTransfer>: The completed transfer details

​

payLightningInvoice(params: PayLightningInvoiceParams)

interface PayLightningInvoiceParams {
  invoice: string;
  maxFeeSats: number;
  preferSpark?: boolean;
  amountSatsToSend?: number;
}

async payLightningInvoice(params: PayLightningInvoiceParams): Promise<LightningSendRequest>

• params: Object containing:
  • invoice: The BOLT11-encoded Lightning invoice to pay.
  • maxFeeSats: Maximum fee in satoshis to pay for the invoice.
  • preferSpark: (Optional) Boolean that defaults to false. When preferSpark is set to true, Spark wallets will initiate a Spark transfer instead of a Lightning transfer if a valid Spark address is found in the invoice. If not, a regular Lightning payment will occur.
  • amountSatsToSend: (Optional) Amount in satoshis to send. This parameter is only used for zero-amount invoices. For regular invoices with a fixed amount, this parameter is ignored.

• Promise<LightningSendRequest>: The Lightning payment request details

// Pay a regular invoice
const payment_response = await wallet.payLightningInvoice({
  invoice: "lnbc100n...", // Regular Lightning invoice with amount
  maxFeeSats: 5,
});
console.log("Payment Response:", payment_response);

// Pay a zero-amount invoice
const zeroAmountPayment = await wallet.payLightningInvoice({
  invoice: "lnbc...", // Zero-amount Lightning invoice
  maxFeeSats: 5,
  amountSatsToSend: 1000, // Specify amount for zero-amount invoice
});
console.log("Zero-amount Payment Response:", zeroAmountPayment);

​

transferTokens(params)

async transferTokens({
  tokenIdentifier,
  tokenAmount,
  receiverSparkAddress,
  selectedOutputs,
}: {
  tokenIdentifier: string;
  tokenAmount: bigint;
  receiverSparkAddress: string;
  selectedOutputs?: OutputWithPreviousTransactionData[];
}): Promise<string>

• params: Object containing:
  • tokenIdentifier: The Bech32m token identifier (eg: btkn1…) of the token to transfer
  • tokenAmount: The amount of tokens to transfer
  • receiverSparkAddress: The recipient’s Spark Address
  • selectedOutputs: (Optional) Specific outputs to use for the transfer

• Promise<string>: The transaction ID of the token transfer

​

getTokenInfo()

async getTokenInfo(): Promise<TokenInfo[]>

• Promise<TokenInfo[]>: Array of token information objects

​

queryTokenTransactions()

async queryTokenTransactions({
  ownerPublicKeys,
  issuerPublicKeys,
  tokenTransactionHashes,
  tokenIdentifiers,
  outputIds,
}: {
  ownerPublicKeys?: string[];
  issuerPublicKeys?: string[];
  tokenTransactionHashes?: string[];
  tokenIdentifiers?: string[];
  outputIds?: string[];
}): Promise<TokenTransactionWithStatus[]>

• ownerPublicKeys: (Optional) Array of owner public keys to filter by
• issuerPublicKeys: (Optional) Array of issuer public keys to filter by
• tokenTransactionHashes: (Optional) Array of token transaction hashes to filter by
• tokenIdentifiers: (Optional) Array of Bech32m token identifiers to filter by
• outputIds: (Optional) Array of output IDs to filter by

• Promise<TokenTransactionWithStatus[]>: Array of token transactions with status

​

getTokenL1Address()

async getTokenL1Address(): Promise<string>

• Promise<string>: The Layer 1 Bitcoin address

​

createLightningInvoice(params)

interface CreateLightningInvoiceParams {
  amountSats: number;
  memo?: string;
  expirySeconds?: number;
  includeSparkAddress?: boolean;
  receiverIdentityPubkey?: string;
}

async createLightningInvoice(params: CreateLightningInvoiceParams): Promise<LightningReceiveRequest>

• params: Object containing:
  • amountSats: Amount in satoshis
  • memo: (Optional) Description for the invoice
  • expirySeconds: (Optional) Expiry time in seconds, defaults to 30 days
  • includeSparkAddress: (Optional) By passing in true, a 36-byte string consisting of a recognizable header and a receiver’s compressed identity public key SPK:identitypubkey will get embedded in the fallback address (f) field of a BOLT11 invoice
  • receiverIdentityPubkey: (Optional) To generate an invoice for another Spark user, pass in the 33-byte compressed identity pubkey as a string

• Promise<LightningReceiveRequest>: The Lightning receive request details

// Basic invoice
const invoice = await wallet.createLightningInvoice({
  amountSats: 100,
  memo: "test invoice",
});
console.log("Invoice:", invoice);

// Invoice with embedded Spark address
const invoiceWithSpark = await wallet.createLightningInvoice({
  amountSats: 100,
  memo: "Invoice with Spark integration",
  includeSparkAddress: true,
});
console.log("Invoice with Spark address:", invoiceWithSpark);

// Invoice for another Spark user
const invoiceForOther = await wallet.createLightningInvoice({
  amountSats: 100,
  memo: "Invoice for another user",
  receiverIdentityPubkey: "033b4f8cf891e45e2e3995e29b3c8b3d4d4e67f8a9b2c1d3e4f567890abcdef12",
});
console.log("Invoice for other user:", invoiceForOther);

​

getLightningReceiveRequest(id: string)

async getLightningReceiveRequest(id: string): Promise<LightningReceiveRequest | null>

• id: The ID of the invoice to check.

• Promise<LightningReceiveRequest | null>: The Lightning receive request details or null if not found.

​

getLightningSendRequest(id: string)

async getLightningSendRequest(id: string): Promise<LightningSendRequest | null>

• id: The ID of the Lightning send request to check.

• Promise<LightningSendRequest | null>: The Lightning send request details or null if not found.

​

getLightningSendFeeEstimate(params)

interface LightningSendFeeEstimateInput {
  encodedInvoice: string;
}

async getLightningSendFeeEstimate(params: LightningSendFeeEstimateInput): Promise<number>

• params: Object containing:
  • encodedInvoice: The BOLT11-encoded Lightning invoice.

• Promise<number>: The estimated fee in satoshis.

​

withdraw(params)

interface WithdrawParams {
  onchainAddress: string;
  exitSpeed: ExitSpeed;
  amountSats?: number;
  feeQuote: WithdrawalFeeQuote; // returned by getWithdrawalFeeQuote
  deductFeeFromWithdrawalAmount?: boolean; // default: true
}

async withdraw(params: WithdrawParams): Promise<CoopExitRequest | null | undefined>

• params: An object with the following properties:
  • onchainAddress: (Required) The Bitcoin address where the funds should be sent.
  • exitSpeed: (Required) The desired speed of the exit (FAST, MEDIUM, SLOW).
  • amountSats: (Optional) The amount in satoshis to withdraw. If not specified, attempts to withdraw all available funds.
  • feeQuote: (Required) The fee quote object returned by getWithdrawalFeeQuote. Must be used before it expires.
  • deductFeeFromWithdrawalAmount: (Optional, default: true) When true, fees are deducted from the withdrawal amount. When false, fees are deducted from the remaining wallet balance.

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

// 1) Fetch a fee quote
const feeQuote = await wallet.getWithdrawalFeeQuote({
  amountSats: 17000,
  withdrawalAddress:
    "bcrt1pf8hed85p94emupfpfhq2g0p5c40cgzqs4agvvfmeuy32nxeh549syu2lwf",
});

// 2) Use the quote before it expires to create the withdrawal
const withdraw_result = await wallet.withdraw({
  onchainAddress:
    "bcrt1pf8hed85p94emupfpfhq2g0p5c40cgzqs4agvvfmeuy32nxeh549syu2lwf",
  amountSats: 17000,
  exitSpeed: ExitSpeed.MEDIUM, // Or ExitSpeed.FAST, ExitSpeed.SLOW
  feeQuote,
  deductFeeFromWithdrawalAmount: true,
});
console.log("Withdraw Result:", withdraw_result);

​

getWithdrawalFeeQuote(params)

async getWithdrawalFeeQuote({
  amountSats,
  withdrawalAddress,
}: {
  amountSats: number;
  withdrawalAddress: string;
}): Promise<WithdrawalFeeQuote | null>

• params: Object containing:
  • amountSats: The amount in satoshis to withdraw.
  • withdrawalAddress: The Bitcoin address where the funds should be sent.

• Promise<WithdrawalFeeQuote | null>: A fee quote for the withdrawal, or null if not available.

​

getCoopExitRequest(id: string)

async getCoopExitRequest(id: string): Promise<CoopExitRequest | null>

• id: The ID of the cooperative exit request.

• Promise<CoopExitRequest | null>: The cooperative exit request details or null if not found.

​

claimDeposit(txId: string)

async claimDeposit(txId: string): Promise<WalletLeaf[]>

• txId: The transaction ID of the Bitcoin deposit.

• Promise<WalletLeaf[]>: The wallet leaves resulting from the claim operation.

​

getStaticDepositAddress()

async getStaticDepositAddress(): Promise<string>

• Promise<string>: A reusable Bitcoin address for depositing funds

​

getClaimStaticDepositQuote(txId: string, outputIndex?: number)

async getClaimStaticDepositQuote(
  txId: string,
  outputIndex?: number
): Promise<{
  txId: string;
  outputIndex: number;
  creditAmountSats: number;
  sspSignature: string;
}>

• txId: The Bitcoin transaction ID of the deposit transaction.
• outputIndex: (Optional) The index of the output

• Promise<object>: Object containing transaction details and claiming information

​

claimStaticDeposit(params)

async claimStaticDeposit({
  transactionId,
  creditAmountSats,
  sspSignature,
  outputIndex,
}: {
  transactionId: string;
  creditAmountSats: number;
  sspSignature: string;
  outputIndex?: number;
}): Promise<ClaimStaticDepositOutput | null>

• params: Object containing:
  • transactionId: The Bitcoin transaction ID from the quote
  • creditAmountSats: The amount of sats from the quote
  • sspSignature: The SSP signature from the quote
  • outputIndex: (Optional) The index of the output

• Promise<ClaimStaticDepositOutput | null>: The claim result or null if the operation fails

​

refundStaticDeposit(depositTxId: string, destinationAddress: string, feeSats: number)

async refundStaticDeposit(
  depositTxId: string, 
  destinationAddress: string, 
  feeSats: number
): Promise<string>

• depositTxId: The transaction ID of the original deposit
• destinationAddress: The Bitcoin address to send the refund to
• feeSats: The fee to pay for the refund transaction (minimum 300 sats)

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

​

advancedDeposit(txHex: string)

async advancedDeposit(txHex: string): Promise<TreeNode[]>

• txHex: The hex string of the transaction to deposit.

• Promise<TreeNode[]>: The nodes resulting from the deposit.

​

getSwapFeeEstimate(amountSats: number)

async getSwapFeeEstimate(amountSats: number): Promise<LeavesSwapFeeEstimateOutput>

• amountSats: The amount of sats to swap.

• Promise<LeavesSwapFeeEstimateOutput>: The estimated fee for the swap.

​

cleanupConnections()

async cleanupConnections(): Promise<void>

• Promise<void>

​

Inherited Methods from EventEmitter

​

on(event: string, listener: Function)

on(event: keyof SparkWalletEvents, listener: Function): this

• event: The event name to listen for
• listener: The callback function to execute when the event is emitted

• this: The SparkWallet instance for chaining

wallet.on("transfer:claimed", (transferId, updatedBalance) => {
  console.log(`Transfer ${transferId} claimed. New balance: ${updatedBalance}`);
});

​

once(event: string, listener: Function)

once(event: keyof SparkWalletEvents, listener: Function): this

• event: The event name to listen for
• listener: The callback function to execute when the event is emitted

• this: The SparkWallet instance for chaining

​

off(event: string, listener: Function)

off(event: keyof SparkWalletEvents, listener: Function): this

• event: The event name
• **`