-
-

BDK Python API Reference

-

This document describes the Python API for the Bitcoin Development Kit (BDK).

+
+

API Reference

+
+

Core Types

+
+
+class bdkpython.Address(address: str, network: Network)[source]
+

Bases: object

+
+
+classmethod from_script(script: Script, network: Network)[source]
+
+ +
+
+is_valid_for_network(network: Network) → bool[source]
+
+ +
+
+script_pubkey() → Script[source]
+
+ +
+
+to_qr_uri() → str[source]
+
+ +
+
-
-

Bdk Module

+
+

Wallet Operations

+
+
+class bdkpython.TxBuilder[source]
+

Bases: object

+

A TxBuilder is created by calling build_tx on a wallet. After assigning it, you set options on it until finally +calling finish to consume the builder and generate the transaction.

+
+
+add_data(data: List[int]) → TxBuilder[source]
+

Add data as an output using OP_RETURN.

+
+ +
+
+add_global_xpubs() → TxBuilder[source]
+

Fill-in the PSBT_GLOBAL_XPUB field with the extended keys contained in both the external and internal +descriptors.

+

This is useful for offline signers that take part to a multisig. Some hardware wallets like BitBox and ColdCard +are known to require this.

+
+ +
+
+add_recipient(script: Script, amount: Amount) → TxBuilder[source]
+

Add a recipient to the internal list of recipients.

+
+ +
+
+add_unspendable(unspendable: OutPoint) → TxBuilder[source]
+

Add a utxo to the internal list of unspendable utxos.

+

It’s important to note that the “must-be-spent” utxos added with TxBuilder::add_utxo have priority over this.

+
+ +
+
+add_utxo(outpoint: OutPoint) → TxBuilder[source]
+

Add a utxo to the internal list of utxos that must be spent.

+

These have priority over the “unspendable” utxos, meaning that if a utxo is present both in the “utxos” and the +“unspendable” list, it will be spent.

+
+ +
+
+allow_dust(allow_dust: bool) → TxBuilder[source]
+

Set whether or not the dust limit is checked.

+

Note: by avoiding a dust limit check you may end up with a transaction that is non-standard.

+
+ +
+
+change_policy(change_policy: ChangeSpendPolicy) → TxBuilder[source]
+

Set a specific ChangeSpendPolicy. See TxBuilder::do_not_spend_change and TxBuilder::only_spend_change for +some shortcuts. This method assumes the presence of an internal keychain, otherwise it has no effect.

+
+ +
+
+current_height(height: int) → TxBuilder[source]
+

Set the current blockchain height.

+

This will be used to:

+

1. Set the nLockTime for preventing fee sniping. Note: This will be ignored if you manually specify a +nlocktime using TxBuilder::nlocktime.

+

2. Decide whether coinbase outputs are mature or not. If the coinbase outputs are not mature at current_height, +we ignore them in the coin selection. If you want to create a transaction that spends immature coinbase inputs, +manually add them using TxBuilder::add_utxos. +In both cases, if you don’t provide a current height, we use the last sync height.

+
+ +
+
+do_not_spend_change() → TxBuilder[source]
+

Do not spend change outputs.

+

This effectively adds all the change outputs to the “unspendable” list. See TxBuilder::unspendable. This method +assumes the presence of an internal keychain, otherwise it has no effect.

+
+ +
+
+drain_to(script: Script) → TxBuilder[source]
+

Sets the address to drain excess coins to.

+

Usually, when there are excess coins they are sent to a change address generated by the wallet. This option +replaces the usual change address with an arbitrary script_pubkey of your choosing. Just as with a change output, +if the drain output is not needed (the excess coins are too small) it will not be included in the resulting +transaction. The only difference is that it is valid to use drain_to without setting any ordinary recipients +with add_recipient (but it is perfectly fine to add recipients as well).

+

If you choose not to set any recipients, you should provide the utxos that the transaction should spend via +add_utxos. drain_to is very useful for draining all the coins in a wallet with drain_wallet to a single +address.

+
+ +
+
+drain_wallet() → TxBuilder[source]
+

Spend all the available inputs. This respects filters like TxBuilder::unspendable and the change policy.

+
+ +
+
+fee_absolute(fee: Amount) → TxBuilder[source]
+

Set an absolute fee The fee_absolute method refers to the absolute transaction fee in Amount. If anyone sets +both the fee_absolute method and the fee_rate method, the FeePolicy enum will be set by whichever method was +called last, as the FeeRate and FeeAmount are mutually exclusive.

+

Note that this is really a minimum absolute fee – it’s possible to overshoot it slightly since adding a change output to drain the remaining excess might not be viable.

+
+ +
+
+fee_rate(fee_rate: FeeRate) → TxBuilder[source]
+

Set a custom fee rate.

+

This method sets the mining fee paid by the transaction as a rate on its size. This means that the total fee paid +is equal to fee_rate times the size of the transaction. Default is 1 sat/vB in accordance with Bitcoin Core’s +default relay policy.

+

Note that this is really a minimum feerate – it’s possible to overshoot it slightly since adding a change output +to drain the remaining excess might not be viable.

+
+ +
+
+finish(wallet: Wallet) → Psbt[source]
+

Finish building the transaction.

+

Uses the thread-local random number generator (rng).

+

Returns a new Psbt per BIP174.

+

WARNING: To avoid change address reuse you must persist the changes resulting from one or more calls to this +method before closing the wallet. See Wallet::reveal_next_address.

+
+ +
+
+manually_selected_only() → TxBuilder[source]
+

Only spend utxos added by TxBuilder::add_utxo.

+

The wallet will not add additional utxos to the transaction even if they are needed to make the transaction valid.

+
+ +
+
+nlocktime(locktime: LockTime) → TxBuilder[source]
+

Use a specific nLockTime while creating the transaction.

+

This can cause conflicts if the wallet’s descriptors contain an “after” (OP_CLTV) operator.

+
+ +
+
+only_spend_change() → TxBuilder[source]
+

Only spend change outputs.

+

This effectively adds all the non-change outputs to the “unspendable” list. See TxBuilder::unspendable. This +method assumes the presence of an internal keychain, otherwise it has no effect.

+
+ +
+
+policy_path(policy_path: dict[str, List[int]], keychain: KeychainKind) → TxBuilder[source]
+

The TxBuilder::policy_path is a complex API. See the Rust docs for complete information: https://docs.rs/bdk_wallet/latest/bdk_wallet/struct.TxBuilder.html#method.policy_path

+
+ +
+
+set_exact_sequence(nsequence: int) → TxBuilder[source]
+

Set an exact nSequence value.

+

This can cause conflicts if the wallet’s descriptors contain an “older” (OP_CSV) operator and the given +nsequence is lower than the CSV value.

+
+ +
+
+set_recipients(recipients: List[ScriptAmount]) → TxBuilder[source]
+

Replace the recipients already added with a new list of recipients.

+
+ +
+
+unspendable(unspendable: List[OutPoint]) → TxBuilder[source]
+

Replace the internal list of unspendable utxos with a new list.

+

It’s important to note that the “must-be-spent” utxos added with TxBuilder::add_utxo have priority over these.

+
+ +
+
+version(version: int) → TxBuilder[source]
+

Build a transaction with a specific version.

+

The version should always be greater than 0 and greater than 1 if the wallet’s descriptors contain an “older” +(OP_CSV) operator.

+
+ +
+ +
+
+class bdkpython.BumpFeeTxBuilder(txid: str, fee_rate: FeeRate)[source]
+

Bases: object

+

A BumpFeeTxBuilder is created by calling build_fee_bump on a wallet. After assigning it, you set options on it +until finally calling finish to consume the builder and generate the transaction.

+
+
+allow_dust(allow_dust: bool) → BumpFeeTxBuilder[source]
+

Set whether or not the dust limit is checked.

+

Note: by avoiding a dust limit check you may end up with a transaction that is non-standard.

+
+ +
+
+current_height(height: int) → BumpFeeTxBuilder[source]
+

Set the current blockchain height.

+

This will be used to:

+

1. Set the nLockTime for preventing fee sniping. Note: This will be ignored if you manually specify a +nlocktime using TxBuilder::nlocktime.

+

2. Decide whether coinbase outputs are mature or not. If the coinbase outputs are not mature at current_height, +we ignore them in the coin selection. If you want to create a transaction that spends immature coinbase inputs, +manually add them using TxBuilder::add_utxos. +In both cases, if you don’t provide a current height, we use the last sync height.

+
+ +
+
+finish(wallet: Wallet) → Psbt[source]
+

Finish building the transaction.

+

Uses the thread-local random number generator (rng).

+

Returns a new Psbt per BIP174.

+

WARNING: To avoid change address reuse you must persist the changes resulting from one or more calls to this +method before closing the wallet. See Wallet::reveal_next_address.

+
+ +
+
+nlocktime(locktime: LockTime) → BumpFeeTxBuilder[source]
+

Use a specific nLockTime while creating the transaction.

+

This can cause conflicts if the wallet’s descriptors contain an “after” (OP_CLTV) operator.

+
+ +
+
+set_exact_sequence(nsequence: int) → BumpFeeTxBuilder[source]
+

Set an exact nSequence value.

+

This can cause conflicts if the wallet’s descriptors contain an “older” (OP_CSV) operator and the given +nsequence is lower than the CSV value.

+
+ +
+
+version(version: int) → BumpFeeTxBuilder[source]
+

Build a transaction with a specific version.

+

The version should always be greater than 0 and greater than 1 if the wallet’s descriptors contain an “older” +(OP_CSV) operator.

+
+ +
+ +
+
+class bdkpython.Psbt(psbt_base64: str)[source]
+

Bases: object

+
+
+combine(other: Psbt) → Psbt[source]
+
+ +
+
+extract_tx() → Transaction[source]
+
+ +
+
+fee() → int[source]
+
+ +
+
+finalize() → FinalizedPsbtResult[source]
+
+ +
+
+json_serialize() → str[source]
+
+ +
+
+serialize() → str[source]
+
+ +
+ +
+
+class bdkpython.ElectrumClient(url: str)[source]
+

Bases: object

+
+
+broadcast(transaction: Transaction) → str[source]
+
+ +
+
+full_scan(full_scan_request: FullScanRequest, stop_gap: int, batch_size: int, fetch_prev_txouts: bool) → Update[source]
+
+ +
+
+sync(sync_request: SyncRequest, batch_size: int, fetch_prev_txouts: bool) → Update[source]
+
+ +
+ +
+
+class bdkpython.EsploraClient(url: str)[source]
+

Bases: object

+
+
+broadcast(transaction: Transaction) → None[source]
+
+ +
+
+full_scan(full_scan_request: FullScanRequest, stop_gap: int, parallel_requests: int) → Update[source]
+
+ +
+
+get_height() → int[source]
+
+ +
+
+get_tx(txid: str) → Transaction | None[source]
+
+ +
+
+sync(sync_request: SyncRequest, parallel_requests: int) → Update[source]
+
+ +
+ +
+
+class bdkpython.Wallet(descriptor: Descriptor, change_descriptor: Descriptor, network: Network, connection: Connection)[source]
+

Bases: object

+
+
+apply_update(update: Update) → None[source]
+

Applies an update to the wallet and stages the changes (but does not persist them).

+

Usually you create an update by interacting with some blockchain data source and inserting +transactions related to your wallet into it.

+

After applying updates you should persist the staged wallet changes. For an example of how +to persist staged wallet changes see [Wallet::reveal_next_address].

+
+ +
+
+balance() → Balance[source]
+

Return the balance, separated into available, trusted-pending, untrusted-pending and immature +values.

+
+ +
+
+calculate_fee(tx: Transaction) → Amount[source]
+

Calculates the fee of a given transaction. Returns [Amount::ZERO] if tx is a coinbase transaction.

+

To calculate the fee for a [Transaction] with inputs not owned by this wallet you must +manually insert the TxOut(s) into the tx graph using the [insert_txout] function.

+

Note tx does not have to be in the graph for this to work.

+
+ +
+
+calculate_fee_rate(tx: Transaction) → FeeRate[source]
+

Calculate the [FeeRate] for a given transaction.

+

To calculate the fee rate for a [Transaction] with inputs not owned by this wallet you must +manually insert the TxOut(s) into the tx graph using the [insert_txout] function.

+

Note tx does not have to be in the graph for this to work.

+
+ +
+
+cancel_tx(tx: Transaction) → None[source]
+

Informs the wallet that you no longer intend to broadcast a tx that was built from it.

+

This frees up the change address used when creating the tx for use in future transactions.

+
+ +
+
+derivation_index(keychain: KeychainKind) → int | None[source]
+

The derivation index of this wallet. It will return None if it has not derived any addresses. +Otherwise, it will return the index of the highest address it has derived.

+
+ +
+
+derivation_of_spk(spk: Script) → KeychainAndIndex | None[source]
+

Finds how the wallet derived the script pubkey spk.

+

Will only return Some(_) if the wallet has given out the spk.

+
+ +
+
+descriptor_checksum(keychain: KeychainKind) → str[source]
+

Return the checksum of the public descriptor associated to keychain

+

Internally calls [Self::public_descriptor] to fetch the right descriptor

+
+ +
+
+finalize_psbt(psbt: Psbt) → bool[source]
+

Finalize a PSBT, i.e., for each input determine if sufficient data is available to pass +validation and construct the respective scriptSig or scriptWitness. Please refer to +[BIP174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#Input_Finalizer), +and [BIP371](https://github.com/bitcoin/bips/blob/master/bip-0371.mediawiki) +for further information.

+

Returns true if the PSBT could be finalized, and false otherwise.

+

The [SignOptions] can be used to tweak the behavior of the finalizer.

+
+ +
+
+get_tx(txid: str) → CanonicalTx | None[source]
+

Get a single transaction from the wallet as a [WalletTx] (if the transaction exists).

+

WalletTx contains the full transaction alongside meta-data such as: +* Blocks that the transaction is [Anchor]ed in. These may or may not be blocks that exist

+
+

in the best chain.

+
+
    +

  • The [ChainPosition] of the transaction in the best chain - whether the transaction is +confirmed or unconfirmed. If the transaction is confirmed, the anchor which proves the +confirmation is provided. If the transaction is unconfirmed, the unix timestamp of when +the transaction was last seen in the mempool is provided.

    • +
+
+ +
+
+get_utxo(op: OutPoint) → LocalOutput | None[source]
+

Returns the utxo owned by this wallet corresponding to outpoint if it exists in the +wallet’s database.

+
+ +
+
+is_mine(script: Script) → bool[source]
+

Return whether or not a script is part of this wallet (either internal or external)

+
+ +
+
+list_output() → List[LocalOutput][source]
+

List all relevant outputs (includes both spent and unspent, confirmed and unconfirmed).

+

To list only unspent outputs (UTXOs), use [Wallet::list_unspent] instead.

+
+ +
+
+list_unspent() → List[LocalOutput][source]
+

Return the list of unspent outputs of this wallet

+
+ +
+
+list_unused_addresses(keychain: KeychainKind) → List[AddressInfo][source]
+

List addresses that are revealed but unused.

+

Note if the returned iterator is empty you can reveal more addresses +by using [reveal_next_address](Self::reveal_next_address) or +[reveal_addresses_to](Self::reveal_addresses_to).

+
+ +
+
+classmethod load(descriptor: Descriptor, change_descriptor: Descriptor, connection: Connection)[source]
+
+ +
+
+mark_used(keychain: KeychainKind, index: int) → bool[source]
+

Marks an address used of the given keychain at index.

+

Returns whether the given index was present and then removed from the unused set.

+
+ +
+
+network() → Network[source]
+

Get the Bitcoin network the wallet is using.

+
+ +
+
+next_derivation_index(keychain: KeychainKind) → int[source]
+

The index of the next address that you would get if you were to ask the wallet for a new address

+
+ +
+
+next_unused_address(keychain: KeychainKind) → AddressInfo[source]
+

Get the next unused address for the given keychain, i.e. the address with the lowest +derivation index that hasn’t been used.

+

This will attempt to derive and reveal a new address if no newly revealed addresses +are available. See also [reveal_next_address](Self::reveal_next_address).

+

WARNING: To avoid address reuse you must persist the changes resulting from one or more +calls to this method before closing the wallet. See [Wallet::reveal_next_address].

+
+ +
+
+peek_address(keychain: KeychainKind, index: int) → AddressInfo[source]
+

Peek an address of the given keychain at index without revealing it.

+

For non-wildcard descriptors this returns the same address at every provided index.

+

# Panics

+

This panics when the caller requests for an address of derivation index greater than the +[BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) max index.

+
+ +
+
+persist(connection: Connection) → bool[source]
+
+ +
+
+policies(keychain: KeychainKind) → Policy | None[source]
+
+ +
+
+reveal_addresses_to(keychain: KeychainKind, index: int) → List[AddressInfo][source]
+

Reveal addresses up to and including the target index and return an iterator +of newly revealed addresses.

+

If the target index is unreachable, we make a best effort to reveal up to the last +possible index. If all addresses up to the given index are already revealed, then +no new addresses are returned.

+

WARNING: To avoid address reuse you must persist the changes resulting from one or more +calls to this method before closing the wallet. See [Wallet::reveal_next_address].

+
+ +
+
+reveal_next_address(keychain: KeychainKind) → AddressInfo[source]
+

Attempt to reveal the next address of the given keychain.

+

This will increment the keychain’s derivation index. If the keychain’s descriptor doesn’t +contain a wildcard or every address is already revealed up to the maximum derivation +index defined in [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), +then the last revealed address will be returned.

+
+ +
+
+sent_and_received(tx: Transaction) → SentAndReceivedValues[source]
+

Compute the tx’s sent and received [Amount]s.

+

This method returns a tuple (sent, received). Sent is the sum of the txin amounts +that spend from previous txouts tracked by this wallet. Received is the summation +of this tx’s outputs that send to script pubkeys tracked by this wallet.

+
+ +
+
+sign(psbt: Psbt) → bool[source]
+

Sign a transaction with all the wallet’s signers, in the order specified by every signer’s +[SignerOrdering]. This function returns the Result type with an encapsulated bool that has the value true if the PSBT was finalized, or false otherwise.

+

The [SignOptions] can be used to tweak the behavior of the software signers, and the way +the transaction is finalized at the end. Note that it can’t be guaranteed that every +signers will follow the options, but the “software signers” (WIF keys and xprv) defined +in this library will.

+
+ +
+
+start_full_scan() → FullScanRequestBuilder[source]
+

Create a [`FullScanRequest] for this wallet.

+

This is the first step when performing a spk-based wallet full scan, the returned +[`FullScanRequest] collects iterators for the wallet’s keychain script pub keys needed to +start a blockchain full scan with a spk based blockchain client.

+

This operation is generally only used when importing or restoring a previously used wallet +in which the list of used scripts is not known.

+
+ +
+
+start_sync_with_revealed_spks() → SyncRequestBuilder[source]
+

Create a partial [SyncRequest] for this wallet for all revealed spks.

+

This is the first step when performing a spk-based wallet partial sync, the returned +[SyncRequest] collects all revealed script pubkeys from the wallet keychain needed to +start a blockchain sync with a spk based blockchain client.

+
+ +
+
+transactions() → List[CanonicalTx][source]
+

Iterate over the transactions in the wallet.

+
+ +
+
-
-

Bitcoin Module

-
-

Examples

-
-

Basic Wallet Usage

-
from bdkpython import *
-             # Create a new wallet
-             descriptor = "wpkh(...)"  # Your descriptor here
-             wallet = Wallet(descriptor, network=Network.TESTNET)
-
-             # Sync wallet
-             blockchain = Blockchain("https://blockstream.info/testnet/api")
-             wallet.sync(blockchain)
-
-             # Get balance
-             balance = wallet.get_balance()
-             print(f"Confirmed balance: {balance.confirmed}")
-
-
+
+

Utilities

+
+
+class bdkpython.Mnemonic(word_count: WordCount)[source]
+

Bases: object

+
+
+classmethod from_entropy(entropy: List[int])[source]
+
+ +
+
+classmethod from_string(mnemonic: str)[source]
+
+ +
+
+
+

Exceptions

+
+
+class bdkpython.InternalError[source]
+

Bases: Exception

+
+
diff --git a/bdk-python/docs/_build/html/genindex.html b/bdk-python/docs/_build/html/genindex.html index a7de5bf9..3d79e0e2 100644 --- a/bdk-python/docs/_build/html/genindex.html +++ b/bdk-python/docs/_build/html/genindex.html @@ -41,9 +41,7 @@
@@ -73,8 +71,372 @@

Index

+ A + | B + | C + | D + | E + | F + | G + | I + | J + | L + | M + | N + | O + | P + | R + | S + | T + | U + | V + | W
+

A

+ + + +
+ +

B

+ + + +
+ +

C

+ + + +
+ +

D

+ + + +
+ +

E

+ + + +
+ +

F

+ + + +
+ +

G

+ + + +
+ +

I

+ + + +
+ +

J

+ + +
+ +

L

+ + + +
+ +

M

+ + + +
+ +

N

+ + + +
+ +

O

+ + +
+ +

P

+ + + +
+ +

R

+ + + +
+ +

S

+ + + +
+ +

T

+ + + +
+ +

U

+ + +
+ +

V

+ + +
+ +

W

+ + +
+