HD Wallet Generator

3.6.1 · active · verified Fri Apr 17

hdwallet is a Python library that implements a Hierarchical Deterministic (HD) Wallet generator, supporting over 200 cryptocurrencies. It is currently at version 3.6.1 and sees active development with minor releases every few weeks to months, typically adding new cryptocurrencies, enhancements, and bug fixes.

Common errors

```
AttributeError: 'HDWallet' object has no attribute 'ecc'
```
cause Attempting to access the `ecc` attribute directly after the v3.5.1 refactor.

fix The attribute was renamed to `eccs`. Update your code to use `hdwallet_instance.eccs` if you need to access it, though direct access to internal attributes is generally discouraged.
```
ImportError: cannot import name 'generate_mnemonic' from 'hdwallet'
```
cause Trying to import utility functions directly from the top-level `hdwallet` package.

fix Utility functions like `generate_mnemonic` are located in `hdwallet.utils`. Correct the import to `from hdwallet.utils import generate_mnemonic`.
```
ValueError: Invalid WIF private key: checksum mismatch
```
cause Attempting to import or use a WIF (Wallet Import Format) private key that was either generated incorrectly by an older version of `hdwallet` or is simply malformed according to the updated WIF standards in v3.1.0/v3.2.0.

fix Ensure the WIF string is correctly formatted according to current standards. If it was generated by an older `hdwallet` version, verify if the new library can still process it, or re-generate/re-export from a reliable source.

Warnings

breaking The internal `ecc` attribute was renamed to `eccs` and the `const` module was refactored in v3.5.1. Direct access to these internal components might break existing code.
Fix: Review any code directly accessing `hdwallet_instance.ecc` or `hdwallet.const` and update to use `hdwallet_instance.eccs` or the new module structure/constants.
breaking The Wallet Import Format (WIF) implementations were significantly upgraded across v3.1.0 and v3.2.0. This can affect how WIF keys are generated, validated, and converted, potentially leading to incorrect keys if old logic is relied upon.
Fix: Ensure all WIF-related operations (generation, import, export) are tested with the new library version. Old WIF validation logic might fail or produce different results.
breaking The default address assignment logic was modified in v3.2.0 to align with standard HD wallet configurations. This means addresses generated by identical input (mnemonic, path) might differ from those generated by older `hdwallet` versions.
Fix: Always re-verify generated addresses against known good values or other wallet implementations when upgrading, especially if deterministic address generation is critical. Do not rely on previously generated addresses being identical.
gotcha The `raw` property of Point objects (used in ECC operations) was changed to `raw_encode` in v3.5.1. If you were accessing raw point data, this will change the method name.
Fix: Update any calls from `point_object.raw` to `point_object.raw_encode()`.

Install

pip install hdwallet Install latest version

Imports

HDWallet
```
from hdwallet import HDWallet
```
generate_mnemonic
wrong:
```
from hdwallet import generate_mnemonic
```
correct:
```
from hdwallet.utils import generate_mnemonic
```
Mnemonic utility functions are located in `hdwallet.utils`.
BIP44Derivation
wrong:
```
from hdwallet import BIP44Derivation
```
correct:
```
from hdwallet.derivations import BIP44Derivation
```
Derivation path constants are typically imported from `hdwallet.derivations`.

Quickstart

This quickstart demonstrates how to generate a new 12-word BIP-39 mnemonic, derive an Ethereum address using a standard BIP-44 path, and retrieve its associated private and public keys. It highlights the use of `generate_mnemonic`, `is_mnemonic_valid`, `HDWallet`, `from_mnemonic`, and `from_path`.

from hdwallet import HDWallet
from hdwallet.symbols import ETH as SYMBOL
from hdwallet.derivations import BIP44Derivation
from hdwallet.utils import generate_mnemonic, is_mnemonic_valid

# 1. Generate a new mnemonic phrase (12 words)
mnemonic = generate_mnemonic(language="english", strength=128)

# 2. Optionally, validate the mnemonic
if not is_mnemonic_valid(mnemonic, language="english"):
    raise ValueError("Invalid mnemonic phrase")

# 3. Create an HDWallet instance
hdwallet = HDWallet(symbol=SYMBOL)

# 4. From mnemonic, get the root key
hdwallet.from_mnemonic(mnemonic=mnemonic, language="english", passphrase=None)

# 5. Derive a child key using a BIP44 path for Ethereum
# Example: m/44'/60'/0'/0/0
hdwallet.from_path(path=BIP44Derivation.m / BIP44Derivation.coin_types.ETH / BIP44Derivation.PURPOSE.root / BIP44Derivation.ACCOUNT.root / BIP44Derivation.CHANGE.root / BIP44Derivation.ADDRESS.root)

# 6. Get wallet details
print(f"Mnemonic: {hdwallet.mnemonic()}")
print(f"Base HD path: {hdwallet.base_hd_path()}")
print(f"Address: {hdwallet.address()}")
print(f"Private Key: {hdwallet.private_key()}")
print(f"Public Key: {hdwallet.public_key()}")

view raw JSON →