API Reference

Complete API documentation for @tetherto/wdk-wallet-btc

Table of Contents

Class	Description	Methods
WalletManagerBtc	Main class for managing Bitcoin wallets. Extends WalletManager from @tetherto/wdk-wallet.	Constructor, Methods
WalletAccountBtc	Individual Bitcoin wallet account implementation. Implements IWalletAccount.	Constructor, Methods, Properties
WalletAccountReadOnlyBtc	Read-only Bitcoin wallet account. Extends WalletAccountReadOnly from @tetherto/wdk-wallet.	Constructor, Methods
WalletAccountReadOnlyBtc	Read-only Bitcoin wallet account. Extends WalletAccountReadOnly from @tetherto/wdk-wallet.	Constructor, Methods
ElectrumTcp	Standard TCP Electrum client. Implements IElectrumClient.	Constructor
ElectrumTls	TLS Electrum client. Implements IElectrumClient.	Constructor
ElectrumSsl	SSL Electrum client. Implements IElectrumClient.	Constructor
ElectrumWs	WebSocket Electrum client for browser environments. Implements IElectrumClient.	Constructor, Methods

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 bytes

• config (BtcWalletConfig, optional): Configuration object

  • client (IElectrumClient, optional): Electrum client instance. If provided, host/port/protocol are ignored.

  • host (string, optional): Electrum server hostname (default: "electrum.blockstream.info"). Ignored if client is provided.

  • port (number, optional): Electrum server port (default: 50001). Ignored if client is provided.

  • protocol (string, optional): Transport protocol - "tcp", "tls", or "ssl" (default: "tcp"). Ignored if client is provided.

  • network (string, optional): "bitcoin", "testnet", or "regtest" (default: "bitcoin")

  • bip (number, optional): BIP address type - 44 (legacy) or 84 (native SegWit) (default: 84)

Methods

Method	Description	Returns
getAccount(index)	Returns a wallet account at the specified index	Promise<WalletAccountBtc>
getAccountByPath(path)	Returns a wallet account at the specified derivation path	Promise<WalletAccountBtc>
getFeeRates()	Returns current fee rates for transactions	Promise<{normal: bigint, fast: bigint}>
dispose()	Disposes all wallet accounts, clearing private keys from memory	void

getAccount(index)

Returns a wallet account at the specified index using BIP-84 (default) or BIP-44 derivation.

Parameters:

• index (number, optional): The index of the account to get (default: 0)

Returns: Promise<WalletAccountBtc> - The wallet account

Example:

// Returns the account with derivation path:
// For mainnet (bitcoin): m/84'/0'/0'/0/1
// For testnet or regtest: m/84'/1'/0'/0/1
const account = await wallet.getAccount(1)

getAccountByPath(path)

Returns a wallet account at the specified derivation path.

Parameters:

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

Returns: Promise<WalletAccountBtc> - The wallet account

Example:

// Returns the account with derivation path:
// For mainnet (bitcoin): m/84'/0'/0'/0/1
// For testnet or regtest: m/84'/1'/0'/0/1
const account = await wallet.getAccountByPath("0'/0/1")

getFeeRates()

Returns current fee rates from mempool.space API.

Returns: Promise<{normal: bigint, fast: bigint}> - Object containing fee rates in sat/vB

• normal: Standard fee rate for confirmation within ~1 hour

• fast: 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. Extends WalletAccountReadOnlyBtc and implements IWalletAccount from @tetherto/wdk-wallet.

Constructor

new WalletAccountBtc(seed, path, config)

Parameters:

• seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes

• path (string): Derivation path suffix (e.g., "0'/0/0")

• config (BtcWalletConfig, optional): Configuration object

  • client (IElectrumClient, optional): Electrum client instance. If provided, host/port/protocol are ignored.

  • host (string, optional): Electrum server hostname (default: "electrum.blockstream.info"). Ignored if client is provided.

  • port (number, optional): Electrum server port (default: 50001). Ignored if client is provided.

  • protocol (string, optional): Transport protocol - "tcp", "tls", or "ssl" (default: "tcp"). Ignored if client is provided.

  • network (string, optional): "bitcoin", "testnet", or "regtest" (default: "bitcoin")

  • bip (number, optional): BIP address type - 44 (legacy) or 84 (native SegWit) (default: 84)

Methods

Method	Description	Returns
getAddress()	Returns the account's Bitcoin address	Promise<string>
getBalance()	Returns the confirmed account balance in satoshis	Promise<bigint>
sendTransaction(options)	Sends a Bitcoin transaction	Promise<{hash: string, fee: bigint}>
quoteSendTransaction(options)	Estimates the fee for a transaction	Promise<{fee: bigint}>
getTransfers(options?)	Returns the account's transfer history	Promise<BtcTransfer[]>
getTransactionReceipt(hash)	Returns a transaction's receipt	Promise<BtcTransactionReceipt | null>
getMaxSpendable()	Returns the maximum spendable amount	Promise<BtcMaxSpendableResult>
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 Bitcoin address (Native SegWit bech32 by default, or legacy if using BIP-44).

Returns: Promise<string> - The Bitcoin address

Example:

const address = await account.getAddress()
console.log('Address:', address) // bc1q... (BIP-84) or 1... (BIP-44)

getBalance()

Returns the account's confirmed balance in satoshis.

Returns: Promise<bigint> - 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 (BtcTransaction): Transaction options

  • to (string): Recipient's Bitcoin address

  • value (number | bigint): Amount in satoshis

  • feeRate (number | bigint, optional): Fee rate in sat/vB. If provided, overrides the fee rate estimated from the blockchain.

  • confirmationTarget (number, optional): Target blocks for confirmation (default: 1)

Returns: Promise<{hash: string, fee: bigint}>

• hash: Transaction hash

• fee: Transaction fee in satoshis

Example:

const result = await account.sendTransaction({
  to: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
  value: 50000n
})
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 (BtcTransaction): Same as sendTransaction options

  • to (string): Recipient's Bitcoin address

  • value (number | bigint): Amount in satoshis

  • feeRate (number | bigint, optional): Fee rate in sat/vB. If provided, overrides the fee rate estimated from the blockchain.

  • confirmationTarget (number, optional): Target blocks for confirmation (default: 1)

Returns: Promise<{fee: bigint}>

• fee: Estimated transaction fee in satoshis

Example:

const quote = await account.quoteSendTransaction({
  to: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
  value: 50000n
})
console.log('Estimated fee:', quote.fee, 'satoshis')

getTransfers(options?)

Returns the account's transfer history with detailed transaction information.

Parameters:

• options (object, optional): Filter options

  • direction (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 ID

• address: Account's own address

• vout: Output index in the transaction

• height: Block height (0 if unconfirmed)

• value: Transfer value in satoshis (bigint)

• direction: 'incoming' or 'outgoing'

• fee: Transaction fee in satoshis (bigint, 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)

getTransactionReceipt(hash)

Returns a transaction's receipt if it has been included in a block.

Parameters:

• hash (string): The transaction hash (64 hex characters)

Returns: Promise<BtcTransactionReceipt | null> - The receipt, or null if the transaction has not been included in a block yet.

Example:

const receipt = await account.getTransactionReceipt('abc123...')
if (receipt) {
  console.log('Transaction confirmed')
}

getMaxSpendable()

Returns the maximum spendable amount that can be sent in a single transaction. The maximum spendable amount can differ from the wallet's total balance for several reasons:

• Transaction fees: Fees are subtracted from the total balance

• Uneconomic UTXOs: Small UTXOs where the fee to spend them exceeds their value are excluded

• UTXO limit: A transaction can include at most 200 inputs. Wallets with more UTXOs cannot spend their full balance in a single transaction.

• Dust limit: Outputs below the dust threshold (294 sats for SegWit, 546 sats for legacy) cannot be created

Returns: Promise<BtcMaxSpendableResult> - Maximum spendable result

• amount: Maximum spendable amount in satoshis (bigint)

• fee: Estimated network fee in satoshis (bigint)

• changeValue: Estimated change value in satoshis (bigint)

Example:

const { amount, fee } = await account.getMaxSpendable()
console.log('Max spendable:', amount, 'satoshis')
console.log('Estimated fee:', fee, 'satoshis')

sign(message)

Signs a message using the account's private key.

Parameters:

• message (string): Message to sign

Returns: Promise<string> - Signature as base64 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 message

• signature (string): Signature as base64 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 memory

Properties

Property	Type	Description
index	number	The derivation path's index of this account
path	string	The full derivation path of this account
keyPair	KeyPair	The account's public and private key pair

WalletAccountReadOnlyBtc

Represents a read-only Bitcoin wallet account. Extends WalletAccountReadOnly from @tetherto/wdk-wallet.

Constructor

new WalletAccountReadOnlyBtc(address, config)

Parameters:

• address (string): The account's Bitcoin address

• config (object, optional): Configuration object (same as BtcWalletConfig but without bip)

  • client (IElectrumClient, optional): Electrum client instance. If provided, host/port/protocol are ignored.

  • host (string, optional): Electrum server hostname (default: "electrum.blockstream.info"). Ignored if client is provided.

  • port (number, optional): Electrum server port (default: 50001). Ignored if client is provided.

  • protocol (string, optional): Transport protocol - "tcp", "tls", or "ssl" (default: "tcp"). Ignored if client is provided.

  • network (string, optional): "bitcoin", "testnet", or "regtest" (default: "bitcoin")

Methods

Method	Description	Returns
getAddress()	Returns the account's Bitcoin address	Promise<string>
getBalance()	Returns the confirmed account balance in satoshis	Promise<bigint>
quoteSendTransaction(options)	Estimates the fee for a transaction	Promise<{fee: bigint}>
getTransactionReceipt(hash)	Returns a transaction's receipt	Promise<BtcTransactionReceipt | null>
getMaxSpendable()	Returns the maximum spendable amount	Promise<BtcMaxSpendableResult>
verify(message, signature)	Verifies a message signature	Promise<boolean>

verify(message, signature)

Verifies a message signature using the account's public key.

Parameters:

• message (string): Original message

• signature (string): Signature as base64 string

Returns: Promise<boolean> - True if signature is valid

Example:

const isValid = await readOnlyAccount.verify('Hello Bitcoin!', signature)
console.log('Signature valid:', isValid)

ElectrumTcp

Electrum client using TCP transport. Standard for command-line and server-side environments. Implements IElectrumClient.

Constructor

new ElectrumTcp(config)

Parameters:

• config (Omit<MempoolElectrumConfig, 'protocol'>): Configuration options

  • host (string): Electrum server hostname

  • port (number): Electrum server port

ElectrumTls

Electrum client using TLS transport. Implements IElectrumClient.

Constructor

new ElectrumTls(config)

Parameters:

• config (Omit<MempoolElectrumConfig, 'protocol'>): Configuration options

  • host (string): Electrum server hostname

  • port (number): Electrum server port

ElectrumSsl

Electrum client using SSL transport. Implements IElectrumClient.

Constructor

new ElectrumSsl(config)

Parameters:

• config (Omit<MempoolElectrumConfig, 'protocol'>): Configuration options

  • host (string): Electrum server hostname

  • port (number): Electrum server port

ElectrumWs

Electrum client using WebSocket transport. Compatible with browser environments where TCP sockets are not available. Implements IElectrumClient.

Constructor

new ElectrumWs(config)

Parameters:

• config (ElectrumWsConfig): Configuration options

  • url (string): The WebSocket URL (e.g., 'wss://electrum.example.com:50004')

Methods

Method	Description	Returns
connect()	Establishes connection to Electrum server	Promise<void>
close()	Closes the connection	Promise<void>
reconnect()	Recreates the underlying socket and reinitializes the session	Promise<void>
getBalance(scripthash)	Returns balance for a script hash	Promise<ElectrumBalance>
listUnspent(scripthash)	Returns UTXOs for a script hash	Promise<ElectrumUtxo[]>
getHistory(scripthash)	Returns transaction history	Promise<ElectrumHistoryItem[]>
getTransaction(txHash)	Returns raw transaction hex	Promise<string>
broadcast(rawTx)	Broadcasts raw transaction	Promise<string>
estimateFee(blocks)	Returns estimated fee rate	Promise<number>

Types

BtcTransaction

interface BtcTransaction {
  to: string                    // The transaction's recipient
  value: number | bigint        // The amount of bitcoins to send to the recipient (in satoshis)
  confirmationTarget?: number   // Optional confirmation target in blocks (default: 1)
  feeRate?: number | bigint     // Optional fee rate in satoshis per virtual byte
}

TransactionResult

interface TransactionResult {
  hash: string  // Transaction hash/ID
  fee: bigint   // Transaction fee in satoshis
}

FeeRates

interface FeeRates {
  normal: bigint  // Standard fee rate (sat/vB) for ~1 hour confirmation
  fast: bigint    // 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: bigint                       // The value of the transfer (in satoshis)
  direction: 'incoming' | 'outgoing'  // The direction of the transfer
  fee?: bigint                        // The fee paid for the full transaction (in satoshis)
  recipient?: string                  // The receiving address for outgoing transfers
}

BtcMaxSpendableResult

interface BtcMaxSpendableResult {
  amount: bigint      // The maximum spendable amount in satoshis
  fee: bigint         // The estimated network fee in satoshis
  changeValue: bigint // The estimated change value in satoshis
}

KeyPair

interface KeyPair {
  publicKey: Uint8Array   // Public key bytes
  privateKey: Uint8Array  // Private key bytes
}

BtcWalletConfig

interface BtcWalletConfig {
  client?: IElectrumClient                    // Electrum client instance. If provided, host/port/protocol are ignored.
  host?: string                               // Electrum server hostname (default: "electrum.blockstream.info")
  port?: number                               // Electrum server port (default: 50001)
  protocol?: 'tcp' | 'tls' | 'ssl'            // Transport protocol (default: "tcp")
  network?: 'bitcoin' | 'testnet' | 'regtest' // Network to use (default: "bitcoin")
  bip?: 44 | 84                               // BIP address type - 44 (legacy) or 84 (native SegWit) (default: 84)
}

IElectrumClient

Interface for implementing custom Electrum clients.

interface IElectrumClient {
  connect(): Promise<void>
  close(): Promise<void>
  reconnect(): Promise<void>
  getBalance(scripthash: string): Promise<ElectrumBalance>
  listUnspent(scripthash: string): Promise<ElectrumUtxo[]>
  getHistory(scripthash: string): Promise<ElectrumHistoryItem[]>
  getTransaction(txHash: string): Promise<string>
  broadcast(rawTx: string): Promise<string>
  estimateFee(blocks: number): Promise<number>
}

ElectrumBalance

interface ElectrumBalance {
  confirmed: number    // Confirmed balance in satoshis
  unconfirmed?: number // Unconfirmed balance in satoshis
}

ElectrumUtxo

interface ElectrumUtxo {
  tx_hash: string  // The transaction hash containing this UTXO
  tx_pos: number   // The output index within the transaction
  value: number    // The UTXO value in satoshis
  height?: number  // The block height (0 if unconfirmed)
}

ElectrumHistoryItem

interface ElectrumHistoryItem {
  tx_hash: string // The transaction hash
  height: number  // The block height (0 or negative if unconfirmed)
}

MempoolElectrumConfig

interface MempoolElectrumConfig {
  host: string              // Electrum server hostname
  port: number              // Electrum server port
  protocol?: 'tcp' | 'ssl' | 'tls' // Transport protocol (default: 'tcp')
  maxRetry?: number         // Maximum reconnection attempts (default: 2)
  retryPeriod?: number      // Delay between reconnection attempts in ms (default: 1000)
  pingPeriod?: number       // Delay between keep-alive pings in ms (default: 120000)
  callback?: (err: Error | null) => void // Called when all retries are exhausted
}

Node.js Quickstart

Get started with WDK in a Node.js environment

React Native Quickstart

Build mobile wallets with React Native Expo

WDK Bitcoin Wallet Usage

Get started with WDK's Bitcoin Wallet Usage

WDK Bitcoin Wallet Configuration

Get started with WDK's Bitcoin Wallet Configuration

---

Need Help?

Discord Community

Connect with developers, ask questions, share your projects

Join Community

GitHub Issues

Report bugs, request features, and get technical help

Open an Issue

Email Contact

For sensitive or private matters, contact our team directly

Send an email