Supported Devices

Support Matrix

The table below lists what devices and features are supported for each device.

  • - supported by the firmware and implemented in HWI

  • - supported by the firmware and not implemented in HWI

  • - not supported by the firmware

Feature \ Device

Ledger Nano X

Ledger Nano S

Trezor One

Trezor Model T

BitBox01

BitBox02

KeepKey

Coldcard

Blockstream Jade

Support Planned

Implemented

xpub retrieval

Message Signing

Device Setup

Device Wipe

Device Recovery

Device Backup

P2PKH Inputs

P2SH-P2WPKH Inputs

P2WPKH Inputs

P2SH Multisig Inputs

P2SH-P2WSH Multisig Inputs

P2WSH Multisig Inputs

Bare Multisig Inputs

Taproot Inputs

✓*

✓*

✓*

✓*

Arbitrary scriptPubKey Inputs

Arbitrary redeemScript Inputs

Arbitrary witnessScript Inputs

Non-wallet inputs

1

2

Mixed Segwit and Non-Segwit Inputs

Display on device screen

  • 1 - Support removed for devices with firmware 1.10.6 and greater.

  • 2 - Support removed for devices with firmware 2.4.4 and greater.

* There are some caveats. See the sign_tx for these devices.

Support Policy

For a device to be supported by HWI, it must:

  • Use open source firmware as much as possible

    • Entirely closed source devices will be rejected

    • Devices may have closed source firmware components if required to under a NDA (e.g. a secure element with NDA)

  • Publicly documented communication protocol

    • It is preferred to both document the protocol and provide a Python library for using it

    • The library, with its own documentation, can suffice as “publicly documented”

  • Either (but preferably both):

    • A simulator/emulator is available for automated tests to be run

    • A promise to maintain and support from the vendor:

Device support may be dropped:

  • If promised vendor maintenance and support disappears

    • If there are continuous issues with the device and the vendor has failed to provide support and updates

  • If the device no longer receives security updates and there are known vulnerabilities and issues

Device APIs

Ledger Devices

class hwilib.devices.ledger.LedgerClient(path, password=None, expert=False, chain=Chain.MAIN)
Parameters:
  • path (str) – Path to the device as returned by enumerate()

  • password (str | None) – A password/passphrase to use with the device. Typically a BIP 39 passphrase, but not always. See device specific documentation for further details.

  • expert (bool) – Whether to return additional information intended for experts.

  • chain (Chain) –

get_master_fingerprint()

Get the master public key fingerprint as bytes.

Retrieves the fingerprint of the master public key of a device. Typically implemented by fetching the extended public key at “m/0h” and extracting the parent fingerprint from it.

Returns:

The fingerprint as bytes

Return type:

bytes

get_pubkey_at_path(path)

Get the public key at the BIP 32 derivation path.

Parameters:
  • bip32_path – The BIP 32 derivation path

  • path (str) –

Returns:

The extended public key

Return type:

ExtendedKey

sign_tx(tx)

Sign a transaction with a Ledger device. Not all transactions can be signed by a Ledger.

The scripts supported depend on the version of the Bitcoin Application installed on the Ledger.

For application versions 1.x and 2.0.x:

  • Transactions containing both segwit and non-segwit inputs are not entirely supported; only the segwit inputs will be signed in this case.

For application versions 2.1.x and above:

  • Only keys derived with standard BIP 44, 49, 84, and 86 derivation paths are supported for single signature addresses.

Parameters:

tx (PSBT) –

Return type:

PSBT

sign_message(message, keypath)

Sign a message (bitcoin message signing).

Signs a message using the legacy Bitcoin Core signed message format. The message is signed with the key at the given path.

Parameters:
  • message (str | bytes) – The message to be signed. First encoded as bytes if not already.

  • bip32_path – The BIP 32 derivation for the key to sign the message with.

  • keypath (str) –

Returns:

The signature

Return type:

str

display_singlesig_address(keypath, addr_type)

Display and return the single sig address of specified type at the given derivation path.

Parameters:
  • bip32_path – The BIP 32 derivation path to get the address for

  • addr_type (AddressType) – The address type

  • keypath (str) –

Returns:

The retrieved address also being shown by the device

Return type:

str

display_multisig_address(addr_type, multisig)

Display and return the multisig address of specified type given the descriptor.

Parameters:
Returns:

The retrieved address also being shown by the device

Return type:

str

setup_device(label='', passphrase='')

Ledgers do not support setup via software.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:
  • label (str) –

  • passphrase (str) –

Return type:

bool

wipe_device()

Ledgers do not support wiping via software.

Raises:

UnavailableActionError – Always, this function is unavailable

Return type:

bool

restore_device(label='', word_count=24)

Ledgers do not support restoring via software.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:
  • label (str) –

  • word_count (int) –

Return type:

bool

backup_device(label='', passphrase='')

Ledgers do not support backing up via software.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:
  • label (str) –

  • passphrase (str) –

Return type:

bool

close()

Close the HID device.

Return type:

None

prompt_pin()

Ledgers do not need a PIN sent from the host.

Raises:

UnavailableActionError – Always, this function is unavailable

Return type:

bool

send_pin(pin)

Ledgers do not need a PIN sent from the host.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:

pin (str) –

Return type:

bool

toggle_passphrase()

Ledgers do not support toggling passphrase from the host.

Raises:

UnavailableActionError – Always, this function is unavailable

Return type:

bool

can_sign_taproot()

Ledgers support Taproot if the Bitcoin App version greater than 2.0.0; support here is for versions 2.1.0 and above.

Returns:

True if Bitcoin App version is greater than or equal to 2.1.0, and not the “Legacy” release. False otherwise.

Return type:

bool

get_master_xpub(addrtype=AddressType.WIT, account=0)

Retrieves a BIP 44 master public key

Get the extended public key used to derive receiving and change addresses with the BIP 44 derivation path scheme. The returned xpub will be dependent on the address type requested, the chain type, and the BIP 44 account number.

Returns:

The extended public key

Parameters:
Return type:

ExtendedKey

Trezor Devices

class hwilib.devices.trezor.TrezorClient(path, password=None, expert=False, chain=Chain.MAIN, hid_ids={(21324, 1)}, webusb_ids={(4617, 21440), (4617, 21441), (21324, 1)}, sim_path='127.0.0.1:21324', model=None)
Parameters:
  • path (str) – Path to the device as returned by enumerate()

  • password (str | None) – A password/passphrase to use with the device. Typically a BIP 39 passphrase, but not always. See device specific documentation for further details.

  • expert (bool) – Whether to return additional information intended for experts.

  • chain (Chain) –

  • hid_ids (Set[Tuple[int, int]]) –

  • webusb_ids (Set[Tuple[int, int]]) –

  • sim_path (str) –

  • model (TrezorModel | None) –

get_pubkey_at_path(path)

Get the public key at the BIP 32 derivation path.

Parameters:
  • bip32_path – The BIP 32 derivation path

  • path (str) –

Returns:

The extended public key

Return type:

ExtendedKey

sign_tx(tx)

Sign a transaction with the Trezor. There are some limitations to what transactions can be signed.

  • Multisig inputs are limited to at most n-of-15 multisigs. This is a firmware limitation.

  • Transactions with arbitrary input scripts (scriptPubKey, redeemScript, or witnessScript) and arbitrary output scripts cannot be signed. This is a firmware limitation.

  • Send-to-self transactions will result in no prompt for outputs as all outputs will be detected as change.

  • Transactions containing Taproot inputs cannot have external inputs.

Parameters:

tx (PSBT) –

Return type:

PSBT

sign_message(message, keypath)

Sign a message (bitcoin message signing).

Signs a message using the legacy Bitcoin Core signed message format. The message is signed with the key at the given path.

Parameters:
  • message (str | bytes) – The message to be signed. First encoded as bytes if not already.

  • bip32_path – The BIP 32 derivation for the key to sign the message with.

  • keypath (str) –

Returns:

The signature

Return type:

str

display_singlesig_address(keypath, addr_type)

Display and return the single sig address of specified type at the given derivation path.

Parameters:
  • bip32_path – The BIP 32 derivation path to get the address for

  • addr_type (AddressType) – The address type

  • keypath (str) –

Returns:

The retrieved address also being shown by the device

Return type:

str

display_multisig_address(addr_type, multisig)

Display and return the multisig address of specified type given the descriptor.

Parameters:
Returns:

The retrieved address also being shown by the device

Return type:

str

setup_device(label='', passphrase='')

Setup the device.

Parameters:
  • label (str) – A label to apply to the device. See device specific documentation for details as to what this actually does.

  • passphrase (str) – A passphrase to apply to the device. Typically a BIP 39 passphrase. See device specific documentation for details as to what this actually does.

Returns:

Whether the setup was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

wipe_device()

Wipe the device.

Returns:

Whether the wipe was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

restore_device(label='', word_count=24)

Restore the device.

Parameters:
  • label (str) – A label to apply to the device. See device specific documentation for details as to what this actually does.

  • word_count (int) – The number of BIP 39 mnemonic words.

Returns:

Whether the restore was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

backup_device(label='', passphrase='')

Trezor devices do not support backing up via software.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:
  • label (str) –

  • passphrase (str) –

Return type:

bool

close()

Close the HID device.

Return type:

None

prompt_pin()

Prompt for PIN.

Returns:

Whether the PIN prompt was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

send_pin(pin)

Send PIN.

Parameters:

pin (str) – The PIN

Returns:

Whether the PIN successfully unlocked the device

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

toggle_passphrase()

Toggle passphrase.

Returns:

Whether the passphrase was successfully toggled

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

can_sign_taproot()

Trezor T supports Taproot since firmware version 2.4.3. Trezor One supports Taproot since firmware version 1.10.4.

Returns:

False, always.

Return type:

bool

get_master_fingerprint()

Get the master public key fingerprint as bytes.

Retrieves the fingerprint of the master public key of a device. Typically implemented by fetching the extended public key at “m/0h” and extracting the parent fingerprint from it.

Returns:

The fingerprint as bytes

Return type:

bytes

get_master_xpub(addrtype=AddressType.WIT, account=0)

Retrieves a BIP 44 master public key

Get the extended public key used to derive receiving and change addresses with the BIP 44 derivation path scheme. The returned xpub will be dependent on the address type requested, the chain type, and the BIP 44 account number.

Returns:

The extended public key

Parameters:
Return type:

ExtendedKey

BitBox01

exception hwilib.devices.digitalbitbox.DBBError(error)
Parameters:

error (Dict[str, Dict[str, str | int]]) –

Return type:

None

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class hwilib.devices.digitalbitbox.DigitalbitboxClient(path, password, expert=False, chain=Chain.MAIN)

The DigitalbitboxClient is a HardwareWalletClient for interacting with BitBox01 devices (previously known as the Digital BitBox).

Parameters:
  • path (str) – Path to the device as given by enumerate

  • password (str | None) – The password required to communicate with the device. Must be provided.

  • expert (bool) – Whether to be in expert mode and return additional information.

  • chain (Chain) –

get_pubkey_at_path(path)

Retrieve the public key at the path. The BitBox01 requires that at least one of the levels in the path is hardened.

Parameters:

path (str) – Path to retrieve the public key at.

Return type:

ExtendedKey

sign_tx(tx)

Sign a partially signed bitcoin transaction (PSBT).

Parameters:
  • psbt – The PSBT to sign

  • tx (PSBT) –

Returns:

The PSBT after being processed by the hardware wallet

Return type:

PSBT

sign_message(message, keypath)

Sign a message (bitcoin message signing).

Signs a message using the legacy Bitcoin Core signed message format. The message is signed with the key at the given path.

Parameters:
  • message (str | bytes) – The message to be signed. First encoded as bytes if not already.

  • bip32_path – The BIP 32 derivation for the key to sign the message with.

  • keypath (str) –

Returns:

The signature

Return type:

str

display_singlesig_address(keypath, addr_type)

The BitBox01 does not have a screen to display addresses on.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:
Return type:

str

display_multisig_address(addr_type, multisig)

The BitBox01 does not have a screen to display addresses on.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:
Return type:

str

setup_device(label='', passphrase='')

Setup the device.

Parameters:
  • label (str) – A label to apply to the device. See device specific documentation for details as to what this actually does.

  • passphrase (str) – A passphrase to apply to the device. Typically a BIP 39 passphrase. See device specific documentation for details as to what this actually does.

Returns:

Whether the setup was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

wipe_device()

Wipe the device.

Returns:

Whether the wipe was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

restore_device(label='', word_count=24)

The BitBox01 does not support restoring via software.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:
  • label (str) –

  • word_count (int) –

Return type:

bool

backup_device(label='', passphrase='')

Backup the device.

Parameters:
  • label (str) – A label to apply to the backup. See device specific documentation for details as to what this actually does.

  • passphrase (str) – A passphrase to apply to the backup. See device specific documentation for details as to what this actually does.

Returns:

Whether the backup was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

close()

Close the HID device.

Return type:

None

prompt_pin()

The BitBox01 does not need a PIN sent from the host.

Raises:

UnavailableActionError – Always, this function is unavailable

Return type:

bool

send_pin(pin)

The BitBox01 does not need a PIN sent from the host.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:

pin (str) –

Return type:

bool

toggle_passphrase()

The BitBox01 does not support toggling passphrase from the host.

Raises:

UnavailableActionError – Always, this function is unavailable

Return type:

bool

can_sign_taproot()

The BitBox01 does not support Taproot as it is no longer supported by the manufacturer

Returns:

False, always

Return type:

bool

get_master_fingerprint()

Get the master public key fingerprint as bytes.

Retrieves the fingerprint of the master public key of a device. Typically implemented by fetching the extended public key at “m/0h” and extracting the parent fingerprint from it.

Returns:

The fingerprint as bytes

Return type:

bytes

get_master_xpub(addrtype=AddressType.WIT, account=0)

Retrieves a BIP 44 master public key

Get the extended public key used to derive receiving and change addresses with the BIP 44 derivation path scheme. The returned xpub will be dependent on the address type requested, the chain type, and the BIP 44 account number.

Returns:

The extended public key

Parameters:
Return type:

ExtendedKey

Keepkey

class hwilib.devices.keepkey.KeepkeyClient(path, password=None, expert=False, chain=Chain.MAIN)

The KeepkeyClient is a HardwareWalletClient for interacting with the Keepkey.

As Keepkeys are clones of the Trezor 1, please refer to TrezorClient for documentation.

Parameters:
  • path (str) –

  • password (str | None) –

  • expert (bool) –

  • chain (Chain) –

can_sign_taproot()

The KeepKey does not support Taproot yet.

Returns:

False, always

Return type:

bool

backup_device(label='', passphrase='')

Trezor devices do not support backing up via software.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:
  • label (str) –

  • passphrase (str) –

Return type:

bool

close()

Close the HID device.

Return type:

None

display_multisig_address(addr_type, multisig)

Display and return the multisig address of specified type given the descriptor.

Parameters:
Returns:

The retrieved address also being shown by the device

Return type:

str

display_singlesig_address(keypath, addr_type)

Display and return the single sig address of specified type at the given derivation path.

Parameters:
  • bip32_path – The BIP 32 derivation path to get the address for

  • addr_type (AddressType) – The address type

  • keypath (str) –

Returns:

The retrieved address also being shown by the device

Return type:

str

get_master_fingerprint()

Get the master public key fingerprint as bytes.

Retrieves the fingerprint of the master public key of a device. Typically implemented by fetching the extended public key at “m/0h” and extracting the parent fingerprint from it.

Returns:

The fingerprint as bytes

Return type:

bytes

get_master_xpub(addrtype=AddressType.WIT, account=0)

Retrieves a BIP 44 master public key

Get the extended public key used to derive receiving and change addresses with the BIP 44 derivation path scheme. The returned xpub will be dependent on the address type requested, the chain type, and the BIP 44 account number.

Returns:

The extended public key

Parameters:
Return type:

ExtendedKey

get_pubkey_at_path(path)

Get the public key at the BIP 32 derivation path.

Parameters:
  • bip32_path – The BIP 32 derivation path

  • path (str) –

Returns:

The extended public key

Return type:

ExtendedKey

prompt_pin()

Prompt for PIN.

Returns:

Whether the PIN prompt was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

restore_device(label='', word_count=24)

Restore the device.

Parameters:
  • label (str) – A label to apply to the device. See device specific documentation for details as to what this actually does.

  • word_count (int) – The number of BIP 39 mnemonic words.

Returns:

Whether the restore was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

send_pin(pin)

Send PIN.

Parameters:

pin (str) – The PIN

Returns:

Whether the PIN successfully unlocked the device

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

setup_device(label='', passphrase='')

Setup the device.

Parameters:
  • label (str) – A label to apply to the device. See device specific documentation for details as to what this actually does.

  • passphrase (str) – A passphrase to apply to the device. Typically a BIP 39 passphrase. See device specific documentation for details as to what this actually does.

Returns:

Whether the setup was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

sign_message(message, keypath)

Sign a message (bitcoin message signing).

Signs a message using the legacy Bitcoin Core signed message format. The message is signed with the key at the given path.

Parameters:
  • message (str | bytes) – The message to be signed. First encoded as bytes if not already.

  • bip32_path – The BIP 32 derivation for the key to sign the message with.

  • keypath (str) –

Returns:

The signature

Return type:

str

sign_tx(tx)

Sign a transaction with the Trezor. There are some limitations to what transactions can be signed.

  • Multisig inputs are limited to at most n-of-15 multisigs. This is a firmware limitation.

  • Transactions with arbitrary input scripts (scriptPubKey, redeemScript, or witnessScript) and arbitrary output scripts cannot be signed. This is a firmware limitation.

  • Send-to-self transactions will result in no prompt for outputs as all outputs will be detected as change.

  • Transactions containing Taproot inputs cannot have external inputs.

Parameters:

tx (PSBT) –

Return type:

PSBT

toggle_passphrase()

Toggle passphrase.

Returns:

Whether the passphrase was successfully toggled

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

wipe_device()

Wipe the device.

Returns:

Whether the wipe was successful

Raises:

UnavailableActionError – if appropriate for the device.

Return type:

bool

Coldcard

class hwilib.devices.coldcard.ColdcardClient(path, password=None, expert=False, chain=Chain.MAIN)
Parameters:
  • path (str) – Path to the device as returned by enumerate()

  • password (str | None) – A password/passphrase to use with the device. Typically a BIP 39 passphrase, but not always. See device specific documentation for further details.

  • expert (bool) – Whether to return additional information intended for experts.

  • chain (Chain) –

get_pubkey_at_path(path)

Get the public key at the BIP 32 derivation path.

Parameters:
  • bip32_path – The BIP 32 derivation path

  • path (str) –

Returns:

The extended public key

Return type:

ExtendedKey

get_master_fingerprint()

Get the master public key fingerprint as bytes.

Retrieves the fingerprint of the master public key of a device. Typically implemented by fetching the extended public key at “m/0h” and extracting the parent fingerprint from it.

Returns:

The fingerprint as bytes

Return type:

bytes

sign_tx(tx)

Sign a transaction with the Coldcard.

  • The Coldcard firmware only supports signing single key and multisig transactions. It cannot sign arbitrary scripts.

  • Multisigs need to be registered on the device before a transaction spending that multisig will be signed by the device.

  • Multisigs must use BIP 67. This can be accomplished in Bitcoin Core using the sortedmulti() descriptor, available in Bitcoin Core 0.20.

Parameters:

tx (PSBT) –

Return type:

PSBT

sign_message(message, keypath)

Sign a message (bitcoin message signing).

Signs a message using the legacy Bitcoin Core signed message format. The message is signed with the key at the given path.

Parameters:
  • message (str | bytes) – The message to be signed. First encoded as bytes if not already.

  • bip32_path – The BIP 32 derivation for the key to sign the message with.

  • keypath (str) –

Returns:

The signature

Return type:

str

display_singlesig_address(keypath, addr_type)

Display and return the single sig address of specified type at the given derivation path.

Parameters:
  • bip32_path – The BIP 32 derivation path to get the address for

  • addr_type (AddressType) – The address type

  • keypath (str) –

Returns:

The retrieved address also being shown by the device

Return type:

str

display_multisig_address(addr_type, multisig)

Display and return the multisig address of specified type given the descriptor.

Parameters:
Returns:

The retrieved address also being shown by the device

Return type:

str

setup_device(label='', passphrase='')

The Coldcard does not support setup via software.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:
  • label (str) –

  • passphrase (str) –

Return type:

bool

wipe_device()

The Coldcard does not support wiping via software.

Raises:

UnavailableActionError – Always, this function is unavailable

Return type:

bool

restore_device(label='', word_count=24)

The Coldcard does not support restoring via software.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:
  • label (str) –

  • word_count (int) –

Return type:

bool

backup_device(label='', passphrase='')

Creates a backup file in the current working directory. This file is protected by the passphrase shown on the Coldcard.

Parameters:
  • label (str) – Value is ignored

  • passphrase (str) – Value is ignored

Return type:

bool

close()

Close the HID device.

Return type:

None

prompt_pin()

The Coldcard does not need a PIN sent from the host.

Raises:

UnavailableActionError – Always, this function is unavailable

Return type:

bool

send_pin(pin)

The Coldcard does not need a PIN sent from the host.

Raises:

UnavailableActionError – Always, this function is unavailable

Parameters:

pin (str) –

Return type:

bool

toggle_passphrase()

The Coldcard does not support toggling passphrase from the host.

Raises:

UnavailableActionError – Always, this function is unavailable

Return type:

bool

can_sign_taproot()

The Coldard does not support Taproot yet.

Returns:

False, always

Return type:

bool

get_master_xpub(addrtype=AddressType.WIT, account=0)

Retrieves a BIP 44 master public key

Get the extended public key used to derive receiving and change addresses with the BIP 44 derivation path scheme. The returned xpub will be dependent on the address type requested, the chain type, and the BIP 44 account number.

Returns:

The extended public key

Parameters:
Return type:

ExtendedKey