API Reference
Complete API documentation for @tetherto/wdk-wallet-spark
API Reference
Table of Contents
| Class | Description | Methods |
|---|---|---|
| WalletManagerSpark | Extends @tetherto/wdk-wallet. | Constructor, Methods, Properties |
| WalletAccountReadOnlySpark | Extends @tetherto/wdk-wallet. | Constructor, Methods, Properties |
| WalletAccountSpark | Extends @tetherto/wdk-wallet-spark. | Constructor, Methods, Properties |
WalletManagerSpark
Extends @tetherto/wdk-wallet
Constructor
new WalletManagerSpark(seed, config?)Parameters
seed(string | Uint8Array<ArrayBufferLike>): The wallet's BIP-39 seed phrase.config(SparkWalletConfig, optional): The configuration object.
Source
src/wallet-manager-spark.js#L30
Methods
| Method | Description | Returns | Throws |
|---|---|---|---|
dispose() | Disposes all the wallet accounts, erasing their private keys from the memory. | void | - |
getAccount(index) | Returns the wallet account at a specific index (see BIP-44). | Promise<WalletAccountSpark> | - |
getAccountByPath(path) | Returns the wallet account at a specific BIP-44 derivation path. | Promise<WalletAccountSpark> | - |
getFeeRates() | Returns the current fee rates. | Promise<FeeRates> | - |
(static) getRandomSeedPhrase(wordCount) | Returns a random BIP-39 seed phrase. | string | - |
(static) isValidSeedPhrase(seedPhrase) | Checks if a seed phrase is valid. | boolean | - |
dispose()
Disposes all the wallet accounts, erasing their private keys from the memory.
Returns
void
getAccount(index)
Returns the wallet account at a specific index (see BIP-44).
Parameters
index(number): The index of the account to get (default: 0).
Returns
Promise<WalletAccountSpark> - The account.
Example
// Returns the account with derivation path m/44'/998'/0'/0/1
const account = await wallet.getAccount(1);Source
src/wallet-manager-spark.js#L43
getAccountByPath(path)
Returns the wallet account at a specific BIP-44 derivation path.
Parameters
path(string): The derivation path (e.g. "0'/0/0").
Returns
Promise<WalletAccountSpark> - The account.
Source
src/wallet-manager-spark.js#L59
getFeeRates()
Returns the current fee rates.
Returns
Promise<FeeRates> - The fee rates (in satoshis).
Source
src/wallet-manager-spark.js#L68
getRandomSeedPhrase(wordCount) (static)
Returns a random BIP-39 seed phrase.
Parameters
wordCount(12 | unknown, optional): The number of words in the seed phrase.
Returns
string - The seed phrase.
isValidSeedPhrase(seedPhrase) (static)
Checks if a seed phrase is valid.
Parameters
seedPhrase(string): The seed phrase.
Returns
boolean - True if the seed phrase is valid.
Properties
| Property | Type | Description |
|---|---|---|
seed | Uint8Array | The seed phrase of the wallet. |
WalletAccountReadOnlySpark
Extends @tetherto/wdk-wallet
Constructor
new WalletAccountReadOnlySpark(address, config?)Parameters
address(string): The account's address.config(SparkWalletConfig, optional): The configuration object.
Source
src/wallet-account-read-only-spark.js#L70
Methods
| Method | Description | Returns | Throws |
|---|---|---|---|
getAddress() | Returns the account's address. | Promise<string> | - |
getBalance() | Returns the account's available (non-pending) bitcoin balance. | Promise<bigint> | - |
getIdentityKey() | Returns the account's identity public key. | Promise<string> | - |
getSparkInvoices(params) | Queries the status of Spark invoices. | Promise<object> | - |
getStaticDepositAddresses() | Returns all existing static deposit addresses for the account. | Promise<DepositAddressQueryResult[]> | - |
getTokenBalance(tokenAddress) | Returns the account balance for a specific token. | Promise<bigint> | - |
getTransactionReceipt(hash) | Returns a Spark transfer by its ID. Only returns Spark transfers, not on-chain Bitcoin transactions. | Promise<Transfer> | - |
getTransfers(options) | Returns the Spark transfer history of the account. Only returns Spark transfers, not on-chain Bitcoin transactions. | Promise<Transfer[]> | - |
getUnusedDepositAddresses(options) | Returns unused single-use deposit addresses for the account. | Promise<object> | - |
getUtxosForDepositAddress(options) | Returns confirmed UTXOs for a specific deposit address. | Promise<object> | - |
quoteSendTransaction(tx) | Quotes the costs of a send transaction operation. | Promise<Omit<TransactionResult, "hash">> | - |
quoteTransfer(options) | Quotes the costs of a transfer operation. | Promise<Omit<TransferResult, "hash">> | - |
verify(message, signature) | Verifies a message's signature. | Promise<boolean> | - |
getAddress()
Returns the account's address.
Returns
Promise<string> - The account's address.
getBalance()
Returns the account's available (non-pending) bitcoin balance.
Returns
Promise<bigint> - The bitcoin balance (in satoshis).
Source
src/wallet-account-read-only-spark.js#L111
getIdentityKey()
Returns the account's identity public key.
Returns
Promise<string> - The identity public key (hex-encoded).
Source
src/wallet-account-read-only-spark.js#L170
getSparkInvoices(params)
Queries the status of Spark invoices.
Parameters
params(QuerySparkInvoicesParams): The query parameters.
Returns
Promise<object> - The invoice statuses.
Source
src/wallet-account-read-only-spark.js#L274
getStaticDepositAddresses()
Returns all existing static deposit addresses for the account.
Returns
Promise<DepositAddressQueryResult[]> - The static deposit addresses.
Source
src/wallet-account-read-only-spark.js#L253
getTokenBalance(tokenAddress)
Returns the account balance for a specific token.
Parameters
tokenAddress(string): The token identifier (Bech32m token identifier, e.g.,btkn1...).
Returns
Promise<bigint> - The token balance (in base unit).
Source
src/wallet-account-read-only-spark.js#L126
getTransactionReceipt(hash)
Returns a Spark transfer by its ID. Only returns Spark transfers, not on-chain Bitcoin transactions.
Parameters
hash(string): The Spark transfer's ID.
Returns
Promise<Transfer> - The Spark transfer, or null if not found.
Source
src/wallet-account-read-only-spark.js#L160
getTransfers(options)
Returns the Spark transfer history of the account. Only returns Spark transfers, not on-chain Bitcoin transactions.
Parameters
options(GetTransfersOptions, optional): The options.
Returns
Promise<Transfer[]> - The Spark transfers.
Source
src/wallet-account-read-only-spark.js#L200
getUnusedDepositAddresses(options)
Returns unused single-use deposit addresses for the account.
Parameters
options(Omit<QueryDepositAddressesParams, "sparkAddress">, optional): The options.
Returns
Promise<object> - The unused deposit addresses.
Source
src/wallet-account-read-only-spark.js#L240
getUtxosForDepositAddress(options)
Returns confirmed UTXOs for a specific deposit address.
Parameters
options(GetUtxosParams): The options.
Returns
Promise<object> - The UTXOs.
Source
src/wallet-account-read-only-spark.js#L264
quoteSendTransaction(tx)
Quotes the costs of a send transaction operation.
Parameters
tx(SparkTransaction): The transaction.
Returns
Promise<Omit<TransactionResult, "hash">> - The transaction's quotes.
Source
src/wallet-account-read-only-spark.js#L140
quoteTransfer(options)
Quotes the costs of a transfer operation.
Parameters
options(TransferOptions): The transfer's options.
Returns
Promise<Omit<TransferResult, "hash">> - The transfer's quotes.
Source
src/wallet-account-read-only-spark.js#L150
verify(message, signature)
Verifies a message's signature.
Parameters
message(string): The original message.signature(string): The signature to verify (hex-encoded, DER or compact).
Returns
Promise<boolean> - True if the signature is valid.
Source
src/wallet-account-read-only-spark.js#L184
Properties
| Property | Type | Description |
|---|---|---|
_address | string | The account's address. |
WalletAccountSpark
Extends @tetherto/wdk-wallet-spark
Constructor
new WalletAccountSpark(wallet, config?)Parameters
wallet(SparkWalletNodeJS): The underlying Spark wallet instance.config(SparkWalletConfig, optional): The configuration object.
Source
src/wallet-account-spark.js#L93
Methods
| Method | Description | Returns | Throws |
|---|---|---|---|
claimDeposit(txId) | Claims a deposit to the wallet. | Promise<WalletLeaf[]> | - |
claimStaticDeposit(txId) | Claims a static deposit to the wallet. | Promise<WalletLeaf[]> | - |
cleanupConnections() | Cleans up and closes the connections with the spark blockchain. | Promise<void> | - |
createLightningInvoice(options) | Creates a Lightning invoice for receiving payments. | Promise<LightningReceiveRequest> | - |
createSparkSatsInvoice(options) | Creates a Spark invoice for receiving a sats payment. | Promise<unknown> | - |
createSparkTokensInvoice(options) | Creates a Spark invoice for receiving a token payment. | Promise<unknown> | - |
dispose() | Disposes the wallet account, erasing its private keys from the memory. | void | - |
getAddress() | Returns the account's Spark address. | Promise<unknown> | - |
getBalance() | Returns the account's total (available + locked in outgoing transfer) bitcoin balance. | Promise<bigint> | - |
getIdentityKey() | Returns the account's identity public key. | Promise<string> | - |
getLightningReceiveRequest(invoiceId) | Gets a Lightning receive request by id. | Promise<LightningReceiveRequest> | - |
getLightningSendRequest(requestId) | Gets a Lightning send request by id. | Promise<LightningSendRequest> | - |
getSingleUseDepositAddress() | Generates a single-use deposit address for bitcoin deposits from layer 1. Once you deposit funds to this address, it cannot be used again. | Promise<string> | - |
getSparkInvoices(params) | Queries the status of Spark invoices. | Promise<object> | - |
getStaticDepositAddress() | Returns a static deposit address for Bitcoin deposits from layer 1, generating one if it does not already exist. The address is reusable. | Promise<string> | - |
getStaticDepositAddresses() | Returns all existing static deposit addresses for the account. | Promise<DepositAddressQueryResult[]> | - |
getTokenBalance(tokenAddress) | Returns the account balance for a specific token. | Promise<bigint> | - |
getTransactionReceipt(hash) | Returns a Spark transfer by its ID. Only returns Spark transfers, not on-chain Bitcoin transactions. | Promise<Transfer> | - |
getTransfers(options) | Returns the Spark transfer history of the account. Only returns Spark transfers, not on-chain Bitcoin transactions. | Promise<Transfer[]> | - |
getUnusedDepositAddresses(options) | Returns unused single-use deposit addresses for the account. | Promise<object> | - |
getUtxosForDepositAddress(options) | Returns confirmed UTXOs for a specific deposit address. | Promise<object> | - |
payLightningInvoice(options) | Pays a Lightning invoice. | Promise<LightningSendRequest> | - |
paySparkInvoice(invoices) | Fulfills one or more Spark invoices by paying them. | Promise<FulfillSparkInvoiceResponse> | - |
quotePayLightningInvoice(options) | Gets fee estimate for sending Lightning payments. | Promise<bigint> | - |
quoteSendTransaction(tx) | Quotes the costs of a send transaction operation. | Promise<Omit<TransactionResult, "hash">> | - |
quoteTransfer(options) | Quotes the costs of a transfer operation. | Promise<Omit<TransferResult, "hash">> | - |
quoteWithdraw(options) | Gets a fee quote for withdrawing funds from Spark cooperatively to an on-chain Bitcoin address. | Promise<CoopExitFeeQuote> | - |
refundStaticDeposit(options) | Refunds a deposit made to a static deposit address back to a specified Bitcoin address. The minimum fee is 300 satoshis. | Promise<string> | - |
sendTransaction(tx) | Sends a transaction. | Promise<TransactionResult> | - |
sign(message) | Signs a message. | Promise<string> | - |
signTransaction(tx) | Signs a transaction. Not supported on spark: transfers are signed collaboratively with the spark operators via a FROST / Statechain protocol, so a signed payload cannot be produced locally and broadcast independently. Use sendTransaction instead. | Promise<never> | - |
syncWalletBalance() | Reconciles the wallet's internal state with the server and waits for any triggered optimisation to complete. | Promise<void> | - |
toReadOnlyAccount() | Returns a read-only copy of the account. | Promise<WalletAccountReadOnlySpark> | - |
transfer(options) | Transfers a token to another address. | Promise<TransferResult> | - |
verify(message, signature) | Verifies a message's signature. | Promise<boolean> | - |
withdraw(options) | Initiates a withdrawal to move funds from the Spark network to an on-chain Bitcoin address. | Promise<CoopExitRequest> | - |
(static) at(seed, index, config) | Creates a new spark wallet account. | Promise<WalletAccountSpark> | - |
claimDeposit(txId)
Claims a deposit to the wallet.
Parameters
txId(string): The transaction id of the deposit.
Returns
Promise<WalletLeaf[]> - The nodes resulting from the deposit.
Source
src/wallet-account-spark.js#L271
claimStaticDeposit(txId)
Claims a static deposit to the wallet.
Parameters
txId(string): The transaction id of the deposit.
Returns
Promise<WalletLeaf[]> - The nodes resulting from the deposit.
Source
src/wallet-account-spark.js#L281
cleanupConnections()
Cleans up and closes the connections with the spark blockchain.
Returns
Promise<void>
Source
src/wallet-account-spark.js#L456
createLightningInvoice(options)
Creates a Lightning invoice for receiving payments.
Parameters
options(CreateLightningInvoiceParams): The invoice options.
Returns
Promise<LightningReceiveRequest> - BOLT11 encoded invoice.
Source
src/wallet-account-spark.js#L337
createSparkSatsInvoice(options)
Creates a Spark invoice for receiving a sats payment.
Parameters
options(CreateSatsInvoiceOptions): The invoice options.
Returns
Promise<unknown> - A Spark invoice that can be paid by another Spark wallet.
Source
src/wallet-account-spark.js#L397
createSparkTokensInvoice(options)
Creates a Spark invoice for receiving a token payment.
Parameters
options(CreateTokensInvoiceOptions): The invoice options.
Returns
Promise<unknown> - A Spark invoice that can be paid by another Spark wallet.
Source
src/wallet-account-spark.js#L407
dispose()
Disposes the wallet account, erasing its private keys from the memory.
Returns
void
Source
src/wallet-account-spark.js#L465
getAddress()
Returns the account's Spark address.
Returns
Promise<unknown> - The account's Spark address.
Source
src/wallet-account-spark.js#L162
getBalance()
Returns the account's total (available + locked in outgoing transfer) bitcoin balance.
Returns
Promise<bigint> - The bitcoin balance (in satoshis).
Source
src/wallet-account-spark.js#L171
getIdentityKey()
Returns the account's identity public key.
Returns
Promise<string> - The identity public key (hex-encoded).
Source
src/wallet-account-read-only-spark.js#L170
getLightningReceiveRequest(invoiceId)
Gets a Lightning receive request by id.
Parameters
invoiceId(string): The id of the Lightning receive request.
Returns
Promise<LightningReceiveRequest> - The Lightning receive request.
Source
src/wallet-account-spark.js#L347
getLightningSendRequest(requestId)
Gets a Lightning send request by id.
Parameters
requestId(string): The id of the Lightning send request.
Returns
Promise<LightningSendRequest> - The Lightning send request.
Source
src/wallet-account-spark.js#L357
getSingleUseDepositAddress()
Generates a single-use deposit address for bitcoin deposits from layer 1. Once you deposit funds to this address, it cannot be used again.
Returns
Promise<string> - The single-use deposit address.
Source
src/wallet-account-spark.js#L251
getSparkInvoices(params)
Queries the status of Spark invoices.
Parameters
params(QuerySparkInvoicesParams): The query parameters.
Returns
Promise<object> - The invoice statuses.
Source
src/wallet-account-read-only-spark.js#L274
getStaticDepositAddress()
Returns a static deposit address for Bitcoin deposits from layer 1, generating one if it does not already exist. The address is reusable.
Returns
Promise<string> - The static deposit address.
Source
src/wallet-account-spark.js#L261
getStaticDepositAddresses()
Returns all existing static deposit addresses for the account.
Returns
Promise<DepositAddressQueryResult[]> - The static deposit addresses.
Source
src/wallet-account-read-only-spark.js#L253
getTokenBalance(tokenAddress)
Returns the account balance for a specific token.
Parameters
tokenAddress(string): The token identifier (Bech32m token identifier, e.g.,btkn1...).
Returns
Promise<bigint> - The token balance (in base unit).
Source
src/wallet-account-read-only-spark.js#L126
getTransactionReceipt(hash)
Returns a Spark transfer by its ID. Only returns Spark transfers, not on-chain Bitcoin transactions.
Parameters
hash(string): The Spark transfer's ID.
Returns
Promise<Transfer> - The Spark transfer, or null if not found.
Source
src/wallet-account-read-only-spark.js#L160
getTransfers(options)
Returns the Spark transfer history of the account. Only returns Spark transfers, not on-chain Bitcoin transactions.
Parameters
options(GetTransfersOptions, optional): The options.
Returns
Promise<Transfer[]> - The Spark transfers.
Source
src/wallet-account-read-only-spark.js#L200
getUnusedDepositAddresses(options)
Returns unused single-use deposit addresses for the account.
Parameters
options(Omit<QueryDepositAddressesParams, "sparkAddress">, optional): The options.
Returns
Promise<object> - The unused deposit addresses.
Source
src/wallet-account-read-only-spark.js#L240
getUtxosForDepositAddress(options)
Returns confirmed UTXOs for a specific deposit address.
Parameters
options(GetUtxosParams): The options.
Returns
Promise<object> - The UTXOs.
Source
src/wallet-account-read-only-spark.js#L264
payLightningInvoice(options)
Pays a Lightning invoice.
Parameters
options(PayLightningInvoiceParams): The payment options.
Returns
Promise<LightningSendRequest> - The Lightning payment request details.
Source
src/wallet-account-spark.js#L367
paySparkInvoice(invoices)
Fulfills one or more Spark invoices by paying them.
Parameters
invoices(SparkInvoice[]): Array of invoices to fulfill.
Returns
Promise<FulfillSparkInvoiceResponse> - Response containing transaction results and errors.
Source
src/wallet-account-spark.js#L417
quotePayLightningInvoice(options)
Gets fee estimate for sending Lightning payments.
Parameters
options(LightningSendFeeEstimateInput): The fee estimation options.
Returns
Promise<bigint> - Fee estimate for sending Lightning payments.
Source
src/wallet-account-spark.js#L386
quoteSendTransaction(tx)
Quotes the costs of a send transaction operation.
Parameters
tx(SparkTransaction): The transaction.
Returns
Promise<Omit<TransactionResult, "hash">> - The transaction's quotes.
Source
src/wallet-account-read-only-spark.js#L140
quoteTransfer(options)
Quotes the costs of a transfer operation.
Parameters
options(TransferOptions): The transfer's options.
Returns
Promise<Omit<TransferResult, "hash">> - The transfer's quotes.
Source
src/wallet-account-read-only-spark.js#L150
quoteWithdraw(options)
Gets a fee quote for withdrawing funds from Spark cooperatively to an on-chain Bitcoin address.
Parameters
options(QuoteWithdrawOptions): The withdrawal's options.
Returns
Promise<CoopExitFeeQuote> - The withdrawal fee quote.
Source
src/wallet-account-spark.js#L308
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(RefundStaticDepositOptions): The refund options.
Returns
Promise<string> - The refund transaction as a hex string that needs to be broadcast.
Source
src/wallet-account-spark.js#L298
sendTransaction(tx)
Sends a transaction.
Parameters
tx(SparkTransaction): The transaction.
Returns
Promise<TransactionResult> - The transaction's result.
Source
src/wallet-account-spark.js#L211
sign(message)
Signs a message.
Parameters
message(string): The message to sign.
Returns
Promise<string> - The message's signature.
Source
src/wallet-account-spark.js#L187
signTransaction(tx)
Signs a transaction.
Not supported on spark: transfers are signed collaboratively with the spark operators
via a FROST / Statechain protocol, so a signed payload cannot be produced locally and
broadcast independently. Use sendTransaction instead.
Parameters
tx(SparkTransaction): The transaction.
Returns
Promise<never> - Never resolves; always throws.
Source
src/wallet-account-spark.js#L201
syncWalletBalance()
Reconciles the wallet's internal state with the server and waits for any triggered optimisation to complete.
Returns
Promise<void>
Source
src/wallet-account-spark.js#L427
toReadOnlyAccount()
Returns a read-only copy of the account.
Returns
Promise<WalletAccountReadOnlySpark> - The read-only account.
Source
src/wallet-account-spark.js#L442
transfer(options)
Transfers a token to another address.
Parameters
options(TransferOptions): The transfer's options.
Returns
Promise<TransferResult> - The transfer's result.
Source
src/wallet-account-spark.js#L235
verify(message, signature)
Verifies a message's signature.
Parameters
message(string): The original message.signature(string): The signature to verify (hex-encoded, DER or compact).
Returns
Promise<boolean> - True if the signature is valid.
Source
src/wallet-account-read-only-spark.js#L184
withdraw(options)
Initiates a withdrawal to move funds from the Spark network to an on-chain Bitcoin address.
Parameters
options(WithdrawOptions): The withdrawal's options.
Returns
Promise<CoopExitRequest> - The withdrawal request details, or null/undefined if the request cannot be completed.
Source
src/wallet-account-spark.js#L318
at(seed, index, config) (static)
Creates a new spark wallet account.
Parameters
seed(string | Uint8Array<ArrayBufferLike>): The wallet's BIP-39 seed phrase.index(number): The index of the account.config(SparkWalletConfig, optional): The configuration object.
Returns
Promise<WalletAccountSpark> - The wallet account.
Source
src/wallet-account-spark.js#L111
Properties
| Property | Type | Description |
|---|---|---|
_address | string | The account's address. |
index | number | The derivation path's index of this account. |
keyPair | KeyPair | The account's key pair. |
path | string | The derivation path of this account (see BIP-44). |
Types
CreateSatsInvoiceOptions
| Property | Type | Description |
|---|---|---|
amount? | number | The amount of sats to receive (optional for open invoices). |
expiryTime? | Date | Optional expiry time for the invoice. |
memo? | string | Optional memo/description for the payment. |
senderSparkAddress? | unknown | Optional Spark address of the expected sender. |
Source
src/wallet-account-spark.js#L63
CreateTokensInvoiceOptions
| Property | Type | Description |
|---|---|---|
amount? | bigint | The amount of tokens to receive. |
expiryTime? | Date | Optional expiry time for the invoice. |
memo? | string | Optional memo/description for the payment. |
senderSparkAddress? | unknown | Optional Spark address of the expected sender. |
tokenIdentifier? | string | The Bech32m token identifier (e.g., btkn1...). |
Source
src/wallet-account-spark.js#L71
GetTransfersOptions
| Property | Type | Description |
|---|---|---|
direction? | `"incoming" | unknown |
limit? | number | The number of transfers to return (default: 10). |
skip? | number | The number of transfers to skip (default: 0). |
Source
src/wallet-account-read-only-spark.js#L55
QuoteWithdrawOptions
| Property | Type | Description |
|---|---|---|
amountSats | number | The amount in satoshis to withdraw. |
withdrawalAddress | string | The Bitcoin address where the funds should be sent. |
Source
src/wallet-account-spark.js#L49
RefundStaticDepositOptions
| Property | Type | Description |
|---|---|---|
depositTransactionId | string | The transaction ID of the original deposit. |
destinationAddress | string | The Bitcoin address to send the refund to. |
outputIndex | number | The output index of the deposit. |
satsPerVbyteFee | number | The fee rate in sats per vbyte for the refund transaction. |
Source
src/wallet-account-spark.js#L55
SparkInvoice
| Property | Type | Description |
|---|---|---|
amount? | bigint | Amount to pay (required for invoices without encoded amount). |
invoice | unknown | The Spark invoice to pay. |
Source
src/wallet-account-spark.js#L80
SparkTransaction
| Property | Type | Description |
|---|---|---|
to | string | The transaction's recipient. |
value | `number | bigint` |
Source
src/wallet-account-read-only-spark.js#L42
SparkWalletConfig
| Property | Type | Description |
|---|---|---|
network? | `"MAINNET" | unknown |
sparkscan? | SparkScanConfig | Optional sparkscan client config |
syncAndRetry? | boolean | When true, failed sends and Lightning payments will automatically sync wallet state and retry once (default: false). |