API Reference
Complete API documentation for @tetherto/wdk-wallet-btc
Table of Contents
Main class for managing Bitcoin wallets. Extends WalletManager from @tetherto/wdk-wallet.
Individual Bitcoin wallet account implementation. Implements IWalletAccount.
WalletManagerBtc
The main class for managing Bitcoin wallets.
Extends WalletManager from @tetherto/wdk-wallet.
Constructor
new WalletManagerBtc(seed, config)Parameters:
seed(string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytesconfig(object, optional): Configuration objecthost(string, optional): Electrum server hostname (default: "electrum.blockstream.info")port(number, optional): Electrum server port (default: 50001)network(string, optional): "bitcoin", "testnet", or "regtest" (default: "bitcoin")
Methods
getAccount(index)
Returns a wallet account at the specified index
Promise<WalletAccountBtc>
getAccountByPath(path)
Returns a wallet account at the specified BIP-84 derivation path
Promise<WalletAccountBtc>
getFeeRates()
Returns current fee rates for transactions
Promise<{normal: number, fast: number}>
dispose()
Disposes all wallet accounts, clearing private keys from memory
void
getAccount(index)
Returns a wallet account at the specified index using BIP-84 derivation.
Parameters:
index(number, optional): The index of the account to get (default: 0)
Returns: Promise<WalletAccountBtc> - The wallet account
Example:
const account = await wallet.getAccount(0)getAccountByPath(path)
Returns a wallet account at the specified BIP-84 derivation path.
Parameters:
path(string): The derivation path (e.g., "0'/0/0")
Returns: Promise<WalletAccountBtc> - The wallet account
Example:
const account = await wallet.getAccountByPath("0'/0/1")getFeeRates()
Returns current fee rates from mempool.space API.
Returns: Promise<{normal: number, fast: number}> - Object containing fee rates in sat/vB
normal: Standard fee rate for confirmation within ~1 hourfast: Higher fee rate for faster confirmation
Example:
const feeRates = await wallet.getFeeRates()
console.log('Normal fee rate:', feeRates.normal, 'sat/vB')
console.log('Fast fee rate:', feeRates.fast, 'sat/vB')dispose()
Disposes all wallet accounts and clears sensitive data from memory.
Returns: void
Example:
wallet.dispose()WalletAccountBtc
Represents an individual Bitcoin wallet account. Implements IWalletAccount from @tetherto/wdk-wallet.
Constructor
new WalletAccountBtc(seed, path, config)Parameters:
seed(string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytespath(string): BIP-84 derivation path (e.g., "0'/0/0")config(object, optional): Configuration objecthost(string, optional): Electrum server hostname (default: "electrum.blockstream.info")port(number, optional): Electrum server port (default: 50001)network(string, optional): "bitcoin", "testnet", or "regtest" (default: "bitcoin")
Methods
getAddress()
Returns the account's Native SegWit address
Promise<string>
getBalance()
Returns the confirmed account balance in satoshis
Promise<number>
sendTransaction(options)
Sends a Bitcoin transaction
Promise<{hash: string, fee: number}>
quoteSendTransaction(options)
Estimates the fee for a transaction
Promise<{fee: number}>
getTransfers(options?)
Returns the account's transfer history
Promise<BtcTransfer[]>
sign(message)
Signs a message with the account's private key
Promise<string>
verify(message, signature)
Verifies a message signature
Promise<boolean>
toReadOnlyAccount()
Creates a read-only version of this account
Promise<WalletAccountReadOnlyBtc>
dispose()
Disposes the wallet account, clearing private keys from memory
void
getAddress()
Returns the account's Native SegWit (bech32) address.
Returns: Promise<string> - The Bitcoin address
Example:
const address = await account.getAddress()
console.log('Address:', address) // bc1q...getBalance()
Returns the account's confirmed balance in satoshis.
Returns: Promise<number> - Balance in satoshis
Example:
const balance = await account.getBalance()
console.log('Balance:', balance, 'satoshis')sendTransaction(options)
Sends a Bitcoin transaction to a single recipient.
Parameters:
options(object): Transaction optionsto(string): Recipient's Bitcoin addressvalue(number): Amount in satoshis
Returns: Promise<{hash: string, fee: number}>
hash: Transaction hashfee: Transaction fee in satoshis
Example:
const result = await account.sendTransaction({
to: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
value: 50000
})
console.log('Transaction hash:', result.hash)
console.log('Fee:', result.fee, 'satoshis')quoteSendTransaction(options)
Estimates the fee for a transaction without broadcasting it.
Parameters:
options(object): Same as sendTransaction optionsto(string): Recipient's Bitcoin addressvalue(number): Amount in satoshis
Returns: Promise<{fee: number}>
fee: Estimated transaction fee in satoshis
Example:
const quote = await account.quoteSendTransaction({
to: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
value: 50000
})
console.log('Estimated fee:', quote.fee, 'satoshis')getTransfers(options?)
Returns the account's transfer history with detailed transaction information.
Parameters:
options(object, optional): Filter optionsdirection(string, optional): 'incoming', 'outgoing', or 'all' (default: 'all')limit(number, optional): Maximum number of transfers (default: 10)skip(number, optional): Number of transfers to skip (default: 0)
Returns: Promise<BtcTransfer[]> - Array of transfer objects
txid: Transaction IDaddress: Account's own addressvout: Output index in the transactionheight: Block height (0 if unconfirmed)value: Transfer value in satoshisdirection: 'incoming' or 'outgoing'fee: Transaction fee in satoshis (for outgoing transfers)recipient: Receiving address (for outgoing transfers)
Example:
const transfers = await account.getTransfers({
direction: 'incoming',
limit: 5
})
console.log('Recent incoming transfers:', transfers)sign(message)
Signs a message using the account's private key.
Parameters:
message(string): Message to sign
Returns: Promise<string> - Signature as hex string
Example:
const signature = await account.sign('Hello Bitcoin!')
console.log('Signature:', signature)verify(message, signature)
Verifies a message signature using the account's public key.
Parameters:
message(string): Original messagesignature(string): Signature as hex string
Returns: Promise<boolean> - True if signature is valid
Example:
const isValid = await account.verify('Hello Bitcoin!', signature)
console.log('Signature valid:', isValid)getTokenBalance(tokenAddress)
Not supported on the Bitcoin blockchain. Always throws an error.
Parameters:
tokenAddress(string): Token contract address
Throws: Error - "The 'getTokenBalance' method is not supported on the bitcoin blockchain."
Example:
// This will throw an error
try {
await account.getTokenBalance('some-address')
} catch (error) {
console.log(error.message) // Not supported on bitcoin blockchain
}transfer(options)
Not supported on the Bitcoin blockchain. Always throws an error.
Parameters:
options(object): Transfer options
Throws: Error - "The 'transfer' method is not supported on the bitcoin blockchain."
quoteTransfer(options)
Not supported on the Bitcoin blockchain. Always throws an error.
Parameters:
options(object): Transfer options
Throws: Error - "The 'quoteTransfer' method is not supported on the bitcoin blockchain."
toReadOnlyAccount()
Creates a read-only version of this account that can query balances and transactions but cannot sign or send transactions.
Returns: Promise<WalletAccountReadOnlyBtc> - Read-only account instance
Example:
const readOnlyAccount = await account.toReadOnlyAccount()
const balance = await readOnlyAccount.getBalance()dispose()
Disposes the wallet account, securely erasing the private key from memory and closing the Electrum connection.
Returns: void
Example:
account.dispose()
// Private key is now securely wiped from memoryProperties
index
number
The derivation path's index of this account
path
string
The full BIP-84 derivation path of this account
keyPair
KeyPair
The account's public and private key pair
Types
BtcTransaction
interface BtcTransaction {
to: string // The transaction's recipient
value: number // The amount of bitcoins to send to the recipient (in satoshis)
}TransactionResult
interface TransactionResult {
hash: string // Transaction hash/ID
fee: number // Transaction fee in satoshis
}FeeRates
interface FeeRates {
normal: number // Standard fee rate (sat/vB) for ~1 hour confirmation
fast: number // Higher fee rate (sat/vB) for faster confirmation
}BtcTransfer
interface BtcTransfer {
txid: string // The transaction's ID
address: string // The user's own address
vout: number // The index of the output in the transaction
height: number // The block height (if unconfirmed, 0)
value: number // The value of the transfer (in satoshis)
direction: 'incoming' | 'outgoing' // The direction of the transfer
fee?: number // The fee paid for the full transaction (in satoshis)
recipient?: string // The receiving address for outgoing transfers
}KeyPair
interface KeyPair {
publicKey: Uint8Array // Public key bytes
privateKey: Uint8Array // Private key bytes
}BtcWalletConfig
interface BtcWalletConfig {
host?: string // Electrum server hostname (default: "electrum.blockstream.info")
port?: number // Electrum server port (default: 50001)
network?: 'bitcoin' | 'testnet' | 'regtest' // Network to use (default: "bitcoin")
}