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

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

Arbitrary scriptPubKey Inputs

Arbitrary redeemScript Inputs

Arbitrary witnessScript Inputs

Non-wallet inputs

Mixed Segwit and Non-Segwit Inputs

Display on device screen

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='', expert=False)
Parameters
  • path (str) – Path to the device as returned by enumerate()

  • password (str) – 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.

Return type

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

hwilib.key.ExtendedKey

sign_tx(tx)

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

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

Parameters

tx (hwilib.psbt.PSBT) –

Return type

hwilib.psbt.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 (Union[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 (hwilib.common.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='')

The Coldcard does 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()

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

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

hwilib.key.ExtendedKey

Trezor Devices

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

  • password (str) – 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.

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

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

  • sim_path (str) –

Return type

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

hwilib.key.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.

Parameters

tx (hwilib.psbt.PSBT) –

Return type

hwilib.psbt.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 (Union[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 (hwilib.common.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

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

hwilib.key.ExtendedKey

toggle_passphrase()

Toggle passphrase.

Returns

Whether the passphrase was successfully toggled

Raises

UnavailableActionError – if appropriate for the device.

Return type

bool

BitBox01

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

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

Return type

None

with_traceback()

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

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

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) – The password required to communicate with the device. Must be provided.

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

Return type

None

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

hwilib.key.ExtendedKey

sign_tx(tx)

Sign a partially signed bitcoin transaction (PSBT).

Parameters
Returns

The PSBT after being processed by the hardware wallet

Return type

hwilib.psbt.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 (Union[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

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

hwilib.key.ExtendedKey

Keepkey

class hwilib.devices.keepkey.KeepkeyClient(path, password='', expert=False)

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) –

  • expert (bool) –

Return type

None

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 (hwilib.common.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

hwilib.key.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

hwilib.key.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 (Union[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.

Parameters

tx (hwilib.psbt.PSBT) –

Return type

hwilib.psbt.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='', expert=False)
Parameters
  • path (str) – Path to the device as returned by enumerate()

  • password (str) – 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.

Return type

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

hwilib.key.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 (hwilib.psbt.PSBT) –

Return type

hwilib.psbt.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 (Union[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 (hwilib.common.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

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

hwilib.key.ExtendedKey