Wallet

The Wallet class is the primary interface for all Bitcoin operations.

Creating a Wallet


from bitpilot import Wallet

wallet, mnemonic = Wallet.create(network="testnet", word_count=24)

Restoring from Mnemonic


wallet = Wallet.from_mnemonic(mnemonic="abandon ability ...", network="testnet")

Balance


balance = wallet.get_balance()

Returns a Balance model with:

confirmed_sats — satoshis in confirmed UTXOs
unconfirmed_sats — satoshis in unconfirmed UTXOs
total_sats — sum of both (computed)
confirmed_btc / total_btc — BTC equivalents (computed)
utxo_count, address_count

Syncing from Network


await wallet.sync()

Refreshes the UTXO set from the configured backend (mempool.space by default). Raises WalletSyncError if the backend is unreachable.

Addresses


addr = wallet.get_address()        # next fresh address
addr = wallet.get_address(index=5) # specific index

UTXOs


utxos = wallet.get_utxos()

Returns a list of UTXO models with txid, vout, amount_sats, confirmations, address, outpoint (computed), is_confirmed (computed).

Proposals

The wallet uses a propose-then-approve flow. No funds move without explicit approval.


proposal = wallet.propose_payment(
    to_address="tb1q...",
    amount_sats=10_000,
    fee_rate_sat_vb=5.0,
    memo="test",
)

txid = wallet.approve_proposal(proposal.id)
wallet.reject_proposal(proposal.id)
proposals = wallet.list_proposals()

Policy Integration


from bitpilot import Policy
wallet.set_policy(Policy(max_per_tx_sats=100_000))

See Policy for full configuration options.

Constructor Parameters

Parameter	Default	Description
`network`	`"testnet"`	`mainnet`, `testnet`, or `signet`
`storage_path`	`~/.bitpilot/wallet.dat`	Encrypted wallet file location
`provider_url`	`None`	Custom mempool.space or Electrum URL
`backend_timeout`	`15.0`	HTTP timeout in seconds
`scan_gap_limit`	`20`	BIP-44 address gap limit for scanning

Exceptions

WalletError — base class for all wallet errors
WalletSyncError — network sync failure
InsufficientConfirmedFundsError — not enough confirmed UTXOs
ProposalNotFoundError — invalid proposal ID