Spark Wallet SDK

API Reference

Constructor

Generates a new WalletSDK instance.

Parameters

network: "MAINNET" | "REGTEST" - The network to connect to.

Example Usage

const sparkWallet = new WalletSDK("REGTEST");
// Now, sparkWallet is usable and will default standard testnet default operators and SSP.
// This is highly recommended until Spark is open-sourced.

`generateMnemonic()`

Generates a new 12-word mnemonic phrase.

generateMnemonic(): string {
  return bip39.generateMnemonic();
}

Returns

string: The generated mnemonic phrase.

`createSparkWallet(mnemonic: string, options?: object)`

Creates and initializes a new wallet using a mnemonic phrase. Operators and SSP endpoint are passed in the constructor to default operators and SSP.

async createSparkWallet(
  mnemonic: string,
  options?: {
    operators?: { id: number; host: string; publicKey: string }[];
    sspEndpoint?: string;
  }
): Promise<string> { /* ... */ }

Parameters

mnemonic: string - The mnemonic phrase.
options (optional): Additional options.
- operators: Array - Custom operators.
- sspEndpoint: string - Custom Spark host URL.

Returns

Promise<string>: The public key in hexadecimal format.

`createSparkWalletWithSeedKey(seedKey: Uint8Array | string, options?: object)`

Creates and initializes a new wallet using a seed key instead of a mnemonic.

async createSparkWalletWithSeedKey(
  seedKey: Uint8Array | string,
  options?: {
    network?: 'Bitcoin' | 'Regtest',
    operators?: { id: number; host: string; publicKey: string }[];
    sspEndpoint?: string;
  }
): Promise<void> { /* ... */ }

Parameters

seedKey: Uint8Array | string - The seed key, either as a Uint8Array or a hex-encoded string.
options (optional): Additional options.
- network: 'Bitcoin' | 'Regtest' - Network selection. Defaults to 'Bitcoin'.
- operators: Array - Custom operators.
- sspEndpoint: string - Custom Spark host URL.

`getMasterPublicKey()`

Gets the master public key of the wallet.

getMasterPublicKey(): string { /* ... */ }

Returns

string: The master public key as a hexadecimal string.

`getP2trAddress()`

Gets the Pay-to-Taproot (P2TR) address for the wallet.

getP2trAddress(): string { /* ... */ }

Returns

string: The P2TR address.

`newDepositAddressRequest(token_amount?: string, token_pubkey?: string)`

Generates a new deposit address request.

newDepositAddressRequest(
  token_amount?: string,
  token_pubkey?: string
): RPCResult { /* ... */ }

Parameters

token_amount (optional): string - The amount of tokens to be deposited.
token_pubkey (optional): string - The public key of the token.

Returns

RPCResult: The result containing the deposit address.

`createNoncePair(index: number)`

Creates a nonce pair.

createNoncePair(index: number): NoncePair { /* ... */ }

Parameters

index: number - The index for the nonce pair.

Returns

NoncePair: The created nonce pair.

`deposit(utxoTxid: string, utxoVout: number, utxoAmount: bigint, token_pubkey?: string, token_amount?: string)`

Performs a deposit using a given UTXO.

async deposit(
  utxoTxid: string,
  utxoVout: number,
  utxoAmount: bigint,
  token_pubkey?: string,
  token_amount?: string
): Promise<void> { /* ... */ }

Parameters

utxoTxid: string - The transaction ID of the UTXO.
utxoVout: number - The output index of the UTXO.
utxoAmount: bigint - The amount in satoshis.
token_pubkey (optional): string - The public key of the token for LRC20 deposits.
token_amount (optional): string - The token amount for LRC20 deposits.

`transfer(amount: bigint, receiverPubkey: string, token_amount?: string, token_pubkey?: string)`

Transfers funds to another wallet.

async transfer(
  amount: bigint,
  receiverPubkey: string,
  token_amount?: string,
  token_pubkey?: string
): Promise<void> { /* ... */ }

Parameters

amount: bigint - The amount to transfer in satoshis.
receiverPubkey: string - The recipient’s public key.
token_amount (optional): string - The token amount for LRC20 transfers.
token_pubkey (optional): string - The public key of the token for LRC20 transfers.

`claimPendingPayments()`

Claims any pending payments from Spark operators.

async claimPendingPayments(): Promise<void> { /* ... */ }

`getBtcBalance()`

Retrieves the BTC balance of the wallet.

async getBtcBalance(): Promise<bigint> { /* ... */ }

Returns

Promise<bigint>: The BTC balance in satoshis.

`getTokenBalances()`

Retrieves the LRC20 (stablecoin) balances.

async getTokenBalances(): Promise<{ [token_pubkey: string]: bigint }> { /* ... */ }

Returns

Promise<{ [token_pubkey: string]: bigint }>: An object mapping token public keys to balances.

`syncWallet()`

Synchronizes the wallet with the Spark servers.

async syncWallet(): Promise<void> { /* ... */ }

`createLightningInvoice(amount_sats: bigint, expiry_secs?: number)`

Creates a Lightning Network invoice.

async createLightningInvoice(
  amount_sats: bigint,
  expiry_secs?: number
): Promise<{
  id: string;
  encoded_invoice: string;
  fees_on_receive_sats: bigint;
  paid: boolean;
}> { /* ... */ }

Parameters

amount_sats: bigint - The amount in satoshis.
expiry_secs (optional): number - Seconds until invoice expires. Defaults to 86400 (24 hours).

Returns

Promise<object>:
- id: string - Unique identifier for the invoice.
- encoded_invoice: string - The encoded Lightning invoice.
- fees_on_receive_sats: bigint - The fees in satoshis for receiving the payment.
- paid: boolean - Payment status.

`queryLightningInvoice(invoice_id: string)`

Queries a Lightning invoice by its ID.

async queryLightningInvoice(
  invoice_id: string
): Promise<{
  id: string;
  encoded_invoice: string;
  fees_on_receive_sats: number;
  paid: boolean;
}> { /* ... */ }

Parameters

invoice_id: string - The unique identifier of the invoice.

Returns

Promise<object>:
- id: string - Unique identifier for the invoice.
- encoded_invoice: string - The encoded Lightning invoice.
- fees_on_receive_sats: number - The fees in satoshis for receiving the payment.
- paid: boolean - Payment status.

`payLightningInvoice(encoded_invoice: string, amount_sats?: bigint)`

Pays a Lightning Network invoice.

async payLightningInvoice(
  encoded_invoice: string,
  amount_sats?: bigint
): Promise<LightningPaymentRequest> { /* ... */ }

Parameters

encoded_invoice: string - The encoded Lightning invoice.
amount_sats: bigint (optional) - Amount in satoshis (required for zero-amount invoices).

Returns

Promise<LightningPaymentRequest>:
- request_id: string - Unique identifier for the payment request.
- encoded_invoice: string - The original encoded invoice.
- amount_sats: bigint - The payment amount in satoshis.
- fees_sats: bigint - The fees in satoshis.
- status: 'PENDING' | 'SUCCEEDED' | 'FAILED' - The payment status.

`getLightningPaymentRequest(request_id: string)`

Retrieves the status of a Lightning payment request by its request ID.

async getLightningPaymentRequest(
  request_id: string
): Promise<LightningPaymentRequest> { /* ... */ }

Parameters

request_id: string - The unique identifier of the payment request.

Returns

Promise<LightningPaymentRequest>:
- request_id: string - Unique identifier for the payment request.
- encoded_invoice: string - The original encoded invoice.
- amount_sats: bigint - The payment amount in satoshis.
- fees_sats: bigint - The fees in satoshis.
- status: 'PENDING' | 'SUCCEEDED' | 'FAILED' - The payment status.

`createSparkUserLightningInvoice(params: object)`

Creates a Lightning invoice for a Spark user.

async createSparkUserLightningInvoice(params: {
  user_pubkey: string;
  payment_hash: string;
  amount_sats: number;
  expiry_secs?: number;
}): Promise<{
  id: string;
  encoded_invoice: string;
  fees_on_receive_sats: number;
  paid: boolean;
}> { /* ... */ }

Parameters

params: object - Parameters for the invoice.
- user_pubkey: string - The user’s public key.
- payment_hash: string - The payment hash.
- amount_sats: number - The amount in satoshis.
- expiry_secs (optional): number - Seconds until invoice expires.

Returns

Promise<object>:
- id: string - Unique identifier for the invoice.
- encoded_invoice: string - The encoded Lightning invoice.
- fees_on_receive_sats: number - The fees in satoshis.
- paid: boolean - Payment status.

`umaAddressLookup(uma_address: string)`

Looks up a UMA address to get payment information and supported currencies.

async umaAddressLookup(
  uma_address: string
): Promise<UmaLookupResponse> { /* ... */ }

Parameters

uma_address: string - The UMA address to look up (e.g., “$username@uma.me”).

Returns

Promise<UmaLookupResponse>:
- callback_id: string - Identifier used for making payments.
- min_sendable_sats: bigint - Minimum amount that can be sent in satoshis.
- max_sendable_sats: bigint - Maximum amount that can be sent in satoshis.
- currencies: Currency[] - List of supported currencies.

`umaPayRequest(callback_id: string, receiving_currency_code?: string, receiving_currency_amount: bigint)`

Creates a payment request for a UMA address using a specified currency and amount.

async umaPayRequest(
  callback_id: string,
  receiving_currency_code?: string,
  receiving_currency_amount: bigint
): Promise<UmaPayRequestResponse> { /* ... */ }

Parameters

callback_id: string - The callback ID received from umaAddressLookup.
receiving_currency_code: string (optional) - The currency code for the payment (e.g., “USD”).
receiving_currency_amount: bigint - The amount in the specified currency.

Returns

Promise<UmaPayRequestResponse>:
- encoded_invoice: string - The Lightning invoice to pay.
- invoice_amount_sats: bigint - The final amount in satoshis.
- fees_on_send_sats: bigint - The fees in satoshis for sending.

Example Usage

// Look up UMA address information
const umaInfo = await sparkWallet.umaAddressLookup("$username@uma.me");
console.log("Supported currencies:", umaInfo.currencies);
console.log("Min sendable:", umaInfo.min_sendable_sats);
console.log("Max sendable:", umaInfo.max_sendable_sats);

// Send payment using specific currency
const paymentRequest = await sparkWallet.umaPayRequest(
  umaInfo.callback_id,
  "USD",
  BigInt(1000)
);

// Pay the resulting invoice
const payment = await sparkWallet.payLightningInvoice(
  paymentRequest.encoded_invoice
);
console.log("Payment status:", payment.status);

`faucet(amountSats: bigint)`

Requests a deposit of funds to a given Regtest Bitcoin address via the faucet.

async faucet(amountSats: bigint): Promise<FaucetResponse> { /* ... */ }

Parameters

amountSats: bigint - The amount in satoshis to deposit.

Returns

Promise<FaucetResponse>:
- txid: string - The transaction ID of the deposit.
- vout: number - The output index of the deposit.

`getLightningPaymentFees(payment_type: "SEND" | "RECEIVE", encoded_invoice: string, amount_sats?: bigint)`

Estimates the fees for a Lightning payment.

async getLightningPaymentFees(
  payment_type: "SEND" | "RECEIVE",
  encoded_invoice: string,
  amount_sats?: bigint
): Promise<number> { /* ... */ }

Parameters

payment_type: "SEND" | "RECEIVE" - The type of payment.
encoded_invoice: string - The BOLT11 encoded Lightning invoice.
amount_sats: bigint (optional) - Amount in satoshis. Required for zero-amount invoices.

Returns

Promise<number>: The estimated fees in satoshis.

`cooperativeExit(transfer_amount: number, bitcoin_address?: string)`

Initiates a cooperative exit.

async cooperativeExit(
  transfer_amount: number,
  bitcoin_address?: string
): Promise<any> { /* ... */ }

Parameters

transfer_amount: number - The amount to transfer.
bitcoin_address: string (optional) - The Bitcoin address to receive the funds.

`getCooperativeExitStatus(request_id: string)`

Gets the cooperative exit status.

async getCooperativeExitStatus(request_id: string): Promise<any> { /* ... */ }

Parameters

request_id: string - The unique identifier of the exit request.

Signs in using a JWT.

async login(account_id: string, secret: string): Promise<void> { /* ... */ }

Parameters

account_id: string - The account ID.
secret: string - The secret or JWT token.

`reset()`

Resets the WalletSDK state, clearing all data.

reset(): void { /* ... */ }

Types

`LightningPaymentRequest`

Represents a Lightning Payment Request.

interface LightningPaymentRequest {
  request_id: string;
  encoded_invoice: string;
  amount_sats: bigint;
  fees_sats: bigint;
  status: PaymentStatus;
}

Properties

request_id: string - Unique identifier for the payment request.
encoded_invoice: string - The original encoded invoice.
amount_sats: bigint - The payment amount in satoshis.
fees_sats: bigint - The fees in satoshis.
status: 'PENDING' | 'SUCCEEDED' | 'FAILED' - The payment status.

`PaymentStatus`

Represents the status of a Lightning payment.

type PaymentStatus = 'PENDING' | 'SUCCEEDED' | 'FAILED';

`Currency`

Represents a currency supported by UMA.

interface Currency {
  code: string;
  name: string;
  symbol: string;
  sats_per_unit: number;
  min_sendable: bigint;
  max_sendable: bigint;
  decimals: number;
}

Properties

code: string - Currency code (e.g., “USD”).
name: string - Currency name.
symbol: string - Currency symbol.
sats_per_unit: number - Conversion rate to satoshis.
min_sendable: bigint - Minimum sendable amount in currency units.
max_sendable: bigint - Maximum sendable amount in currency units.
decimals: number - Number of decimal places for the currency.

`UmaLookupResponse`

Response from UMA address lookup.

interface UmaLookupResponse {
  callback_id: string;
  min_sendable_sats: bigint;
  max_sendable_sats: bigint;
  currencies: Currency[];
}

Properties

callback_id: string - Identifier used for making payments.
min_sendable_sats: bigint - Minimum amount that can be sent in satoshis.
max_sendable_sats: bigint - Maximum amount that can be sent in satoshis.
currencies: Currency[] - List of supported currencies.

`UmaPayRequestResponse`

Response from UMA pay request.

interface UmaPayRequestResponse {
  encoded_invoice: string;
  invoice_amount_sats: bigint;
  fees_on_send_sats: bigint;
}

Properties

encoded_invoice: string - The Lightning invoice to pay.
invoice_amount_sats: bigint - The final amount in satoshis.
fees_on_send_sats: bigint - The fees in satoshis for sending.

Please refer to the updated method signatures and types to ensure compatibility with the latest version of the Spark Wallet SDK.

Cooperative Bitcoin Exit Signing Specification

On this page

API Reference
Constructor
generateMnemonic()
createSparkWallet(mnemonic: string, options?: object)
createSparkWalletWithSeedKey(seedKey: Uint8Array | string, options?: object)
getMasterPublicKey()
getP2trAddress()
newDepositAddressRequest(token_amount?: string, token_pubkey?: string)
createNoncePair(index: number)
deposit(utxoTxid: string, utxoVout: number, utxoAmount: bigint, token_pubkey?: string, token_amount?: string)
transfer(amount: bigint, receiverPubkey: string, token_amount?: string, token_pubkey?: string)
claimPendingPayments()
getBtcBalance()
getTokenBalances()
syncWallet()
createLightningInvoice(amount_sats: bigint, expiry_secs?: number)
queryLightningInvoice(invoice_id: string)
payLightningInvoice(encoded_invoice: string, amount_sats?: bigint)
getLightningPaymentRequest(request_id: string)
createSparkUserLightningInvoice(params: object)
umaAddressLookup(uma_address: string)
umaPayRequest(callback_id: string, receiving_currency_code?: string, receiving_currency_amount: bigint)
faucet(amountSats: bigint)
getLightningPaymentFees(payment_type: "SEND" | "RECEIVE", encoded_invoice: string, amount_sats?: bigint)
cooperativeExit(transfer_amount: number, bitcoin_address?: string)
getCooperativeExitStatus(request_id: string)
login(account_id: string, secret: string)
reset()
Types
LightningPaymentRequest
PaymentStatus
Currency
UmaLookupResponse
UmaPayRequestResponse

Getting Started

Quick Start

Wallet Documentation

UX Guidelines

API Reference

Constructor

`generateMnemonic()`

`createSparkWallet(mnemonic: string, options?: object)`

`createSparkWalletWithSeedKey(seedKey: Uint8Array | string, options?: object)`

`getMasterPublicKey()`

`getP2trAddress()`

`newDepositAddressRequest(token_amount?: string, token_pubkey?: string)`

`createNoncePair(index: number)`

`deposit(utxoTxid: string, utxoVout: number, utxoAmount: bigint, token_pubkey?: string, token_amount?: string)`

`transfer(amount: bigint, receiverPubkey: string, token_amount?: string, token_pubkey?: string)`

`claimPendingPayments()`

`getBtcBalance()`

`getTokenBalances()`

`syncWallet()`

`createLightningInvoice(amount_sats: bigint, expiry_secs?: number)`

`queryLightningInvoice(invoice_id: string)`

`payLightningInvoice(encoded_invoice: string, amount_sats?: bigint)`

`getLightningPaymentRequest(request_id: string)`

`createSparkUserLightningInvoice(params: object)`

`umaAddressLookup(uma_address: string)`

`umaPayRequest(callback_id: string, receiving_currency_code?: string, receiving_currency_amount: bigint)`

`faucet(amountSats: bigint)`

`getLightningPaymentFees(payment_type: "SEND" | "RECEIVE", encoded_invoice: string, amount_sats?: bigint)`

`cooperativeExit(transfer_amount: number, bitcoin_address?: string)`

`getCooperativeExitStatus(request_id: string)`

`reset()`

Types

`LightningPaymentRequest`

`PaymentStatus`

`Currency`

`UmaLookupResponse`

`UmaPayRequestResponse`

Getting Started

Quick Start

Wallet Documentation

UX Guidelines

​API Reference

​Constructor

​generateMnemonic()

​createSparkWallet(mnemonic: string, options?: object)

​createSparkWalletWithSeedKey(seedKey: Uint8Array | string, options?: object)

​getMasterPublicKey()

​getP2trAddress()

​newDepositAddressRequest(token_amount?: string, token_pubkey?: string)

​createNoncePair(index: number)

​deposit(utxoTxid: string, utxoVout: number, utxoAmount: bigint, token_pubkey?: string, token_amount?: string)

​transfer(amount: bigint, receiverPubkey: string, token_amount?: string, token_pubkey?: string)

​claimPendingPayments()

​getBtcBalance()

​getTokenBalances()

​syncWallet()

​createLightningInvoice(amount_sats: bigint, expiry_secs?: number)

​queryLightningInvoice(invoice_id: string)

​payLightningInvoice(encoded_invoice: string, amount_sats?: bigint)

​getLightningPaymentRequest(request_id: string)

​createSparkUserLightningInvoice(params: object)

​umaAddressLookup(uma_address: string)

​umaPayRequest(callback_id: string, receiving_currency_code?: string, receiving_currency_amount: bigint)

​faucet(amountSats: bigint)

​getLightningPaymentFees(payment_type: "SEND" | "RECEIVE", encoded_invoice: string, amount_sats?: bigint)

​cooperativeExit(transfer_amount: number, bitcoin_address?: string)

​getCooperativeExitStatus(request_id: string)

​login(account_id: string, secret: string)

​reset()

​Types

​LightningPaymentRequest

​PaymentStatus

​Currency

​UmaLookupResponse

​UmaPayRequestResponse

API Reference

Constructor

`generateMnemonic()`

`createSparkWallet(mnemonic: string, options?: object)`

`createSparkWalletWithSeedKey(seedKey: Uint8Array | string, options?: object)`

`getMasterPublicKey()`

`getP2trAddress()`

`newDepositAddressRequest(token_amount?: string, token_pubkey?: string)`

`createNoncePair(index: number)`

`deposit(utxoTxid: string, utxoVout: number, utxoAmount: bigint, token_pubkey?: string, token_amount?: string)`

`transfer(amount: bigint, receiverPubkey: string, token_amount?: string, token_pubkey?: string)`

`claimPendingPayments()`

`getBtcBalance()`

`getTokenBalances()`

`syncWallet()`

`createLightningInvoice(amount_sats: bigint, expiry_secs?: number)`

`queryLightningInvoice(invoice_id: string)`

`payLightningInvoice(encoded_invoice: string, amount_sats?: bigint)`

`getLightningPaymentRequest(request_id: string)`

`createSparkUserLightningInvoice(params: object)`

`umaAddressLookup(uma_address: string)`

`umaPayRequest(callback_id: string, receiving_currency_code?: string, receiving_currency_amount: bigint)`

`faucet(amountSats: bigint)`

`getLightningPaymentFees(payment_type: "SEND" | "RECEIVE", encoded_invoice: string, amount_sats?: bigint)`

`cooperativeExit(transfer_amount: number, bitcoin_address?: string)`

`getCooperativeExitStatus(request_id: string)`

`login(account_id: string, secret: string)`

`reset()`

Types

`LightningPaymentRequest`

`PaymentStatus`

`Currency`

`UmaLookupResponse`

`UmaPayRequestResponse`