HWI (Hardware Wallet Interface)

What Is HWI?

HWI (Hardware Wallet Interface) is an open-source Python library and command-line tool, maintained under the bitcoin-core GitHub organization, that gives software a single way to communicate with hardware signing devices. Instead of writing custom integration code for each vendor, developers call HWI's commands and let the tool handle device-specific protocols behind a consistent JSON-based interface.

The project was created by Andrew Chow, a Bitcoin Core contributor, to solve a practical problem: Bitcoin Core had no built-in way to talk to hardware wallets. Users who wanted the privacy and verification benefits of running their own full node had to rely on vendor software that often used third-party servers. HWI bridges that gap by connecting Bitcoin Core's PSBT workflow directly to hardware devices. The tool is MIT-licensed and supports Ledger, Trezor, Coldcard, BitBox, KeepKey, and Blockstream Jade, among others.

How It Works

HWI operates as a middleware layer between wallet software and hardware devices. The core workflow revolves around BIP-174 Partially Signed Bitcoin Transactions (PSBTs): wallet software constructs an unsigned or partially signed transaction, HWI sends it to the hardware device for signing, and the device returns the signed result.

1. The user connects a hardware wallet via USB (or in some cases, SD card for air-gapped devices like Coldcard)
2. HWI's enumerate command discovers connected devices and reports their type, path, fingerprint, and readiness
3. Wallet software creates a PSBT containing the unsigned transaction and all required metadata (UTXOs, derivation paths, scripts)
4. HWI's signtx command sends the PSBT to the device, which displays the transaction details for user confirmation
5. The user verifies and approves on the device screen, the device signs with its private keys, and HWI returns the signed PSBT
6. Wallet software finalizes the PSBT and broadcasts the completed transaction

Key Commands

HWI exposes a set of commands that cover the full lifecycle of hardware wallet interactions. All output is returned as JSON on stdout:

# Discover connected hardware wallets
hwi enumerate

# Get the master extended public key
hwi -t <device_type> -d <device_path> getmasterxpub

# Get an xpub at a specific BIP32 derivation path
hwi -t <device_type> -d <device_path> getxpub m/84h/0h/0h

# Get output descriptors for importing into Bitcoin Core
hwi -t <device_type> -d <device_path> getdescriptors

# Sign a PSBT
hwi -t <device_type> -d <device_path> signtx <base64_psbt>

# Display and verify an address on the device screen
hwi -t <device_type> -d <device_path> displayaddress --desc "wpkh([fingerprint/84h/0h/0h]xpub.../0/0)"

The getdescriptors command is particularly useful: it retrieves output descriptors from the device, which can be imported directly into Bitcoin Core's descriptor wallet. This allows Bitcoin Core to track addresses and construct transactions without ever needing access to private keys.

Bitcoin Core Integration

Since Bitcoin Core 0.21.0, the node software supports an external signer interface via the -signer startup flag. When launched with -signer=hwi, Bitcoin Core can automatically call HWI to enumerate devices, import public keys, and request transaction signatures:

# Launch Bitcoin Core with HWI as external signer
bitcoind -signer=hwi

# Inside Bitcoin Core, list connected signers
bitcoin-cli enumeratesigners

# Create a descriptor wallet linked to the device
bitcoin-cli createwallet "hardware_wallet" true true "" false true

# Verify a receive address on the device screen
bitcoin-cli -rpcwallet=hardware_wallet walletdisplayaddress <address>

This integration means users can build, sign, and broadcast transactions entirely through Bitcoin Core's interface while keeping private keys secured on the hardware device. For a deeper look at self-custody workflows, see the self-custodial vs. custodial wallets comparison.

Supported Devices

HWI supports a range of hardware wallets with varying feature coverage. The project maintains a compatibility matrix that tracks which commands each device supports:

The project has an inclusion policy requiring that devices have a publicly documented communication protocol. Entirely closed-source devices are rejected. This encourages transparency and allows security researchers to audit the communication layer between HWI and each device.

Use Cases

Full Node with Hardware Signing

The primary use case for HWI is pairing a personal Bitcoin Core full node with a hardware wallet. This combination gives users the strongest self-custody setup: the full node validates transactions independently (no third-party server trust), while the hardware wallet keeps private keys in a secure element, isolated from internet-connected computers. Without HWI, achieving this setup required manual PSBT file transfers or vendor-specific workarounds.

Multi-Vendor Multisig

HWI's device-agnostic design is especially valuable for multisig wallets. A 2-of-3 multisig setup can use a Coldcard, a Trezor, and a Ledger as the three signers, with HWI handling communication to all three through the same interface. This eliminates single-vendor dependency: if one manufacturer discontinues a product line or introduces a vulnerability, the remaining devices still function. For more on multisig architecture, see the multisig wallets explained research article.

Automated Signing Infrastructure

Because HWI exposes a programmatic interface, it can be integrated into scripts and applications that manage signing workflows. Businesses running cold storage operations can build tooling that constructs PSBTs, routes them through HWI to the appropriate device, and handles the signed output: all without custom driver code for each hardware vendor. The JSON-based output makes it straightforward to parse results in any programming language.

Wallet Software Development

Wallet developers who want to support hardware wallets can use HWI (or its Python library, hwilib) as a dependency rather than implementing each vendor's proprietary USB protocol. Software written in languages other than Python can shell out to the hwi command-line tool and parse its JSON output. A Rust reimplementation also exists for native integration in Rust-based wallet projects.

Risks and Considerations

Software Supply Chain

HWI runs on a general-purpose computer that sits between the user and their hardware device. If the machine running HWI is compromised, an attacker could substitute a malicious PSBT (displaying a different destination address) before it reaches the device. Users must always verify transaction details on the hardware wallet's own screen before approving. The displayaddress command helps with address verification, but it requires the user to actually compare the displayed address. For a broader discussion of attack surfaces, see the hardware wallet attack vectors research.

Device Compatibility Gaps

Not every device supports every HWI feature. Some devices lack Taproot signing support, others have limited multisig capabilities, and air-gapped workflows (via SD card rather than USB) may require additional steps outside HWI's standard flow. The compatibility matrix in the project documentation should be consulted before relying on a specific device-command combination.

Experimental Status

The Bitcoin Core documentation notes that the external signer integration is experimental and has received less review than Bitcoin Core itself. While HWI has been in active development since 2018 and is widely used in the Bitcoin community, users handling significant funds should test their workflow thoroughly on testnet or signet before using it in production.

USB and Host Dependencies

HWI requires Python 3, libusb, and (on Linux) udev rules configured for each device vendor. Setting up these dependencies can be nontrivial, especially on restricted systems. Users comfortable with air-gapped workflows may prefer transferring PSBTs via SD card or QR code, bypassing HWI entirely for the signing step while still using it for key export and descriptor generation.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.