hdwallet

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 13, 2026 License: MIT Imports: 4 Imported by: 1

README

go-hdwallet

Go Version License Status Go Reference

Multi-chain HD Wallet Library for Go

Overview

HDWallet is a Go library for generating hierarchical deterministic (HD) wallets across multiple cryptocurrency networks. It implements BIP32, BIP39, BIP44, BIP49, BIP84, BIP86, and SLIP-0010 standards to provide consistent wallet generation from a single mnemonic phrase.

Features

  • BIP39 Mnemonic — 12/15/18/21/24 word phrases
  • Multiple Address Types — Legacy, SegWit, Native SegWit, Taproot
  • 17 Blockchains — Bitcoin, Ethereum, Solana, TON, Polkadot, Ripple, Monero, and more
  • Test Vectors — Verified against known test vectors
  • Zero CGO — Pure Go implementation
  • Modular Design — Easy to extend with new networks
  • Custom Derivation Paths — Full support for arbitrary BIP32 paths

Supported Networks

Network Coin Type Address Types Standards
Bitcoin 0 Legacy (1...), SegWit (3...), Native SegWit (bc1q...), Taproot (bc1p...) BIP44/49/84/86
Litecoin 2 Legacy (L...), SegWit (ltc1...), SegWit-compat (M...) BIP44/49/84
Dogecoin 3 Legacy (D...) BIP44
Dash 5 Legacy (X...) BIP44
Zcash 133 Transparent (t1...) BIP44
Ripple (XRP) 144 r... (Ripple Base58) BIP44
Bitcoin Cash 145 CashAddr (bitcoincash:q...) BIP44
Stellar (XLM) 148 G... (StrKey) SLIP-0010
Monero (XMR) 128 4... (Block Base58) SLIP-0010
Ethereum 60 0x... (works on all EVM chains) BIP44
Tron 195 T... BIP44
Polkadot (DOT) 354 1... (SS58) SLIP-0010
Solana 501 Base58 SLIP-0010
TON 607 EQ.../UQ... (v3r2, v4r2, v5r1) Native / SLIP-0010
SUI 784 0x... (blake2b-256) SLIP-0010

EVM-compatible chains: Polygon, BSC, Arbitrum, Optimism, Avalanche, Fantom, Base (same address as Ethereum)

Installation

go get github.com/X-Vlad/go-hdwallet

Quick Start

package main

import (
    "fmt"
    "log"

    "github.com/X-Vlad/go-hdwallet"
    "github.com/X-Vlad/go-hdwallet/networks"
)

func main() {
    // Create wallet from mnemonic
    wallet, err := hdwallet.NewFromMnemonic(
        "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
    )
    if err != nil {
        log.Fatal(err)
    }

    // Generate Bitcoin SegWit address
    btc, _ := wallet.Generate(networks.Bitcoin(), 0)
    fmt.Printf("BTC: %s\n", btc.Address)

    // Generate Ethereum address (works on all EVM chains)
    eth, _ := wallet.Generate(networks.Ethereum(), 0)
    fmt.Printf("ETH: %s\n", eth.Address)

    // Generate Solana address
    sol, _ := wallet.Generate(networks.Solana(), 0)
    fmt.Printf("SOL: %s\n", sol.Address)

    // Generate Polkadot address
    dot, _ := wallet.Generate(networks.Polkadot(), 0)
    fmt.Printf("DOT: %s\n", dot.Address)

    // Generate Ripple address
    xrp, _ := wallet.Generate(networks.Ripple(), 0)
    fmt.Printf("XRP: %s\n", xrp.Address)
}

Detailed Usage

Creating a Wallet
// From existing mnemonic
wallet, err := hdwallet.NewFromMnemonic("your twelve word mnemonic phrase here")

// From mnemonic with passphrase (BIP39)
wallet, err := hdwallet.NewFromMnemonicWithPassword("mnemonic", "passphrase")

// Generate new random wallet
wallet, err := hdwallet.NewRandom(12)  // 12-word mnemonic
wallet, err := hdwallet.NewRandom(24)  // 24-word mnemonic

// Access mnemonic and seed
mnemonic := wallet.Mnemonic()
seed := wallet.Seed()
Bitcoin Addresses
// Native SegWit (bc1q...) - BIP84, recommended
btcSegwit, _ := wallet.Generate(networks.Bitcoin(), 0)

// Legacy (1...) - BIP44
btcLegacy, _ := wallet.Generate(networks.BitcoinLegacy(), 0)

// Wrapped SegWit (3...) - BIP49
btcWrapped, _ := wallet.Generate(networks.BitcoinSegWitCompat(), 0)

// Taproot (bc1p...) - BIP86
btcTaproot, _ := wallet.Generate(networks.BitcoinTaproot(), 0)

// Testnet
gen := networks.NewBitcoinGenerator(networks.BitcoinTestnet, hdwallet.SegWit)
btcTestnet, _ := wallet.Generate(gen, 0)
Litecoin & Dogecoin
// Litecoin SegWit (ltc1...)
ltc, _ := wallet.Generate(networks.Litecoin(), 0)

// Litecoin Legacy (L...)
ltcLegacy, _ := wallet.Generate(networks.LitecoinLegacy(), 0)

// Litecoin SegWit-compat (M...)
ltcCompat, _ := wallet.Generate(networks.LitecoinSegWitCompat(), 0)

// Dogecoin (D...)
doge, _ := wallet.Generate(networks.Dogecoin(), 0)
Bitcoin Cash
// CashAddr format (bitcoincash:q...)
bch, _ := wallet.Generate(networks.BitcoinCash(), 0)

// Legacy address is stored in Version field
fmt.Printf("CashAddr: %s\n", bch.Address)
fmt.Printf("Legacy: %s\n", bch.Version)
Ethereum & EVM Chains
// Ethereum mainnet
eth, _ := wallet.Generate(networks.Ethereum(), 0)

// Same address works on all EVM chains:
// - Polygon, BSC, Arbitrum, Optimism, Avalanche, Fantom, Base, etc.

// Or explicitly specify network for metadata
polygon, _ := wallet.Generate(networks.EVM(networks.Polygon), 0)
bsc, _ := wallet.Generate(networks.EVM(networks.BSC), 0)
Solana

Important: Trust Wallet and Phantom use different derivation paths!

Wallet Path Function
Phantom, Solflare, Ledger m/44'/501'/0'/0' networks.Solana()
Trust Wallet m/44'/501'/0' networks.SolanaTrustWallet() 
// Phantom / Solflare / Ledger (4-level path)
solPhantom, _ := wallet.Generate(networks.Solana(), 0)

// Trust Wallet (3-level path - DIFFERENT ADDRESS!)
solTrust, _ := wallet.Generate(networks.SolanaTrustWallet(), 0)
TON

TON supports two different mnemonic systems:

Type Words Compatible Wallets
Native TON 24 Tonkeeper, Tonhub, MyTonWallet
BIP39 + SLIP-0010 12/24 Trust Wallet, Ledger 
// ============================================
// Option 1: Trust Wallet / Ledger (BIP39)
// Uses the SAME mnemonic as BTC, ETH, SOL, etc.
// ============================================
tonTrust, _ := wallet.Generate(networks.TONTrustWallet(), 0)
fmt.Printf("Address: %s\n", tonTrust.Address)

// With specific version
tonTrustV5, _ := wallet.Generate(networks.TONBip39(networks.TONV5R1), 0)

// ============================================
// Option 2: Tonkeeper / Native (separate mnemonic!)
// Generates its own 24-word mnemonic
// ============================================
tonGen := networks.TON()  // v4r2 by default

// Generate NEW wallet with native mnemonic
tonWallet, tonMnemonic, _ := tonGen.GenerateNew()
fmt.Printf("Address: %s\n", tonWallet.Address)
fmt.Printf("TON Mnemonic (save separately!): %s\n", tonMnemonic)

// Import existing Tonkeeper mnemonic
tonWallet, _ := tonGen.GenerateFromTONMnemonic("word1 word2 ... word24")

// Different versions
tonV5 := networks.TONV5()
tonV5Wallet, mnemonic, _ := tonV5.GenerateNew()

Important: Native TON mnemonic is NOT the same as BIP39! You need to store them separately if using Tonkeeper.

Ripple (XRP)
xrp, _ := wallet.Generate(networks.Ripple(), 0)
fmt.Printf("Address: %s\n", xrp.Address) // r...
Dash
dash, _ := wallet.Generate(networks.Dash(), 0)
fmt.Printf("Address: %s\n", dash.Address) // X...
Zcash
zec, _ := wallet.Generate(networks.Zcash(), 0)
fmt.Printf("Address: %s\n", zec.Address) // t1...
Stellar Lumens (XLM)
xlm, _ := wallet.Generate(networks.Stellar(), 0)
fmt.Printf("Address: %s\n", xlm.Address)     // G...
fmt.Printf("Secret: %s\n", xlm.PrivateKey)   // S...
Polkadot (DOT)
dot, _ := wallet.Generate(networks.Polkadot(), 0)
fmt.Printf("Address: %s\n", dot.Address) // 1...

// Kusama
ksm, _ := wallet.Generate(networks.Kusama(), 0)
fmt.Printf("Address: %s\n", ksm.Address)
SUI
sui, _ := wallet.Generate(networks.SUI(), 0)
fmt.Printf("Address: %s\n", sui.Address) // 0x...
Monero (XMR)
xmr, _ := wallet.Generate(networks.Monero(), 0)
fmt.Printf("Address: %s\n", xmr.Address)   // 4...
fmt.Printf("View Key: %s\n", xmr.Version)  // view_key:...
Tron
tron, _ := wallet.Generate(networks.Tron(), 0)
fmt.Printf("Address: %s\n", tron.Address)  // T...
Multiple Addresses
// Generate first 10 Bitcoin addresses
wallets, err := wallet.GenerateMultiple(networks.Bitcoin(), 10)
for i, w := range wallets {
    fmt.Printf("[%d] %s\n", i, w.Address)
}

WalletInfo Structure

type WalletInfo struct {
    Coin       string `json:"coin"`            // "Bitcoin", "Ethereum", etc.
    Network    string `json:"network"`         // "btc", "eth", etc.
    Address    string `json:"address"`         // The wallet address
    PrivateKey string `json:"private_key"`     // Hex-encoded private key
    PublicKey  string `json:"public_key"`      // Hex-encoded public key
    WIF        string `json:"wif,omitempty"`   // WIF (Bitcoin-like only)
    Path       string `json:"derivation_path"` // e.g., "m/84'/0'/0'/0/0"
    Version    string `json:"version,omitempty"` // Wallet version or extra info
}

Custom Derivation Paths

You can use custom derivation paths for any supported network:

// Bitcoin with custom path (all address types auto-detected)
btcGen, _ := networks.BitcoinCustomPath("m/86'/0'/0'/0/0")  // Taproot
btcWallet, _ := wallet.Generate(btcGen, 0)

// Ethereum - access different accounts
ethGen, _ := networks.EthereumCustomPath("m/44'/60'/1'/0/0") // second account
ethWallet, _ := wallet.Generate(ethGen, 0)

// Solana - custom path (all components must be hardened!)
solGen, _ := networks.SolanaCustomPath("m/44'/501'/1'/0'") // second account
solWallet, _ := wallet.Generate(solGen, 0)

// Litecoin
ltcGen, _ := networks.LitecoinCustomPath("m/84'/2'/0'/0/0")
ltcWallet, _ := wallet.Generate(ltcGen, 0)

// Dogecoin
dogeGen, _ := networks.DogecoinCustomPath("m/44'/3'/0'/0/0")
dogeWallet, _ := wallet.Generate(dogeGen, 0)

// Tron
tronGen, _ := networks.TronCustomPath("m/44'/195'/0'/0/0")
tronWallet, _ := wallet.Generate(tronGen, 0)

// Bitcoin Cash
bchGen, _ := networks.BitcoinCashCustomPath("m/44'/145'/0'/0/0")
bchWallet, _ := wallet.Generate(bchGen, 0)

// Ripple
xrpGen, _ := networks.RippleCustomPath("m/44'/144'/0'/0/0")
xrpWallet, _ := wallet.Generate(xrpGen, 0)

// Dash
dashGen, _ := networks.DashCustomPath("m/44'/5'/0'/0/0")
dashWallet, _ := wallet.Generate(dashGen, 0)

// Zcash
zecGen, _ := networks.ZcashCustomPath("m/44'/133'/0'/0/0")
zecWallet, _ := wallet.Generate(zecGen, 0)

// Stellar (all hardened)
xlmGen, _ := networks.StellarCustomPath("m/44'/148'/0'")
xlmWallet, _ := wallet.Generate(xlmGen, 0)

// Polkadot (all hardened)
dotGen, _ := networks.PolkadotCustomPath("m/44'/354'/0'/0'/0'")
dotWallet, _ := wallet.Generate(dotGen, 0)

// SUI (all hardened)
suiGen, _ := networks.SUICustomPath("m/44'/784'/0'/0'/0'")
suiWallet, _ := wallet.Generate(suiGen, 0)

Note: For Ed25519 chains (Solana, Stellar, Polkadot, SUI), all path components must be hardened (end with ').

Derivation Paths

Network Address Type Path
Bitcoin Legacy m/44'/0'/0'/0/index
Bitcoin SegWit (wrapped) m/49'/0'/0'/0/index
Bitcoin SegWit (native) m/84'/0'/0'/0/index
Bitcoin Taproot m/86'/0'/0'/0/index
Litecoin Legacy m/44'/2'/0'/0/index
Litecoin SegWit (wrapped) m/49'/2'/0'/0/index
Litecoin SegWit m/84'/2'/0'/0/index
Dogecoin Legacy m/44'/3'/0'/0/index
Dash Legacy m/44'/5'/0'/0/index
Monero Standard m/44'/128'/index'
Zcash Transparent m/44'/133'/0'/0/index
Ripple Standard m/44'/144'/0'/0/index
Bitcoin Cash CashAddr m/44'/145'/0'/0/index
Stellar Standard m/44'/148'/index'
Ethereum Standard m/44'/60'/0'/0/index
Tron Standard m/44'/195'/0'/0/index
Polkadot Standard m/44'/354'/index'/0'/0'
Solana Phantom/Solflare m/44'/501'/index'/0'
Solana Trust Wallet m/44'/501'/index'
TON Trust Wallet (BIP39) m/44'/607'/index'
TON Native (Tonkeeper) ton-native
SUI Standard m/44'/784'/index'/0'/0'

Testing

go test ./...

# With coverage
go test -cover ./...

# Verbose output
go test -v ./...

Security

Important security notes:

  1. Never share your mnemonic — anyone who sees it can steal your funds
  2. Use secure generation — NewRandom() uses crypto/rand
  3. Clear sensitive data — zero out private keys and seed after use
  4. Test with small amounts first — always verify addresses before sending large amounts
  5. Use hardware wallets for large amounts — this library is for development and testing

Dependencies

  • github.com/btcsuite/btcd — Bitcoin primitives
  • github.com/ethereum/go-ethereum — Ethereum crypto
  • github.com/X-Vlad/go-bip32 — BIP32 implementation
  • github.com/X-Vlad/go-bip39 — BIP39 mnemonic
  • github.com/xssnick/tonutils-go — TON wallet support
  • golang.org/x/crypto — Cryptographic primitives (blake2b, etc.)

License

MIT License. See LICENSE for details.

Credits

  • go-bip32 — BIP32 implementation (based on tyler-smith/go-bip32)
  • go-bip39 — BIP39 mnemonic (based on tyler-smith/go-bip39)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Donate

If this project was helpful, you can support development:

Network Address
BTC bc1q3l4jcnplvcmvqh26pfh3qdkrw4flqevemsfed8
ETH, BSC, ... (EVM) 0x49999CD2B8F7Bc9309e5929a79799eA55a17e6Ce
Tron TDxyjiittx9zzkHd25wmM12mvutTKBhZKS
Solana ahiiQWz9eRLpFRpEFSPf7See7J46YBFhMgsADNmGRgt
TON UQCfsCHBWq3_kD0D_mkfetuwIgACoSJ8YsYTZPKKkMprDlLD

Disclaimer

This software is provided "as is", without warranty of any kind. Use at your own risk. Always verify generated addresses before sending real funds.

Documentation

Overview

Package hdwallet provides hierarchical deterministic wallet generation for multiple cryptocurrency networks including Bitcoin, Ethereum, Solana, TON, and more.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func PathToIndexes 

func PathToIndexes(components []PathComponent) []uint32

PathToIndexes converts path components to uint32 indexes (without hardened offset)

func PathToString 

func PathToString(components []PathComponent) string

PathToString converts path components back to string

func PathToValues 

func PathToValues(components []PathComponent) []uint32

PathToValues converts path components to uint32 values (with hardened offset)

Types

type AddressType 

type AddressType int

AddressType defines the type of address to generate 

const (
	// Legacy - BIP44 P2PKH addresses (1... for BTC)
	Legacy AddressType = iota
	// SegWit - BIP84 P2WPKH native segwit addresses (bc1q... for BTC)
	SegWit
	// SegWitCompat - BIP49 P2SH-P2WPKH wrapped segwit addresses (3... for BTC)
	SegWitCompat
	// Taproot - BIP86 P2TR taproot addresses (bc1p... for BTC)
	Taproot
)

type Generator 

type Generator interface {
	// Generate creates a wallet at the specified index
	Generate(seed []byte, index uint32) (*WalletInfo, error)
	// Network returns the network identifier (e.g., "btc", "eth")
	Network() string
	// CoinType returns the BIP44 coin type number
	CoinType() uint32
}

Generator is the interface that all network generators must implement

type HDWallet 

type HDWallet struct {
	// contains filtered or unexported fields
}

HDWallet is the main wallet manager

func NewFromMnemonic 

func NewFromMnemonic(mnemonic string) (*HDWallet, error)

NewFromMnemonic creates a new HDWallet from an existing mnemonic phrase

func NewFromMnemonicWithPassword 

func NewFromMnemonicWithPassword(mnemonic, password string) (*HDWallet, error)

NewFromMnemonicWithPassword creates a new HDWallet with a passphrase

func NewRandom 

func NewRandom(wordCount int) (*HDWallet, error)

NewRandom generates a new random HDWallet with the specified word count wordCount should be 12, 15, 18, 21, or 24

func (*HDWallet) Generate 

func (w *HDWallet) Generate(gen Generator, index uint32) (*WalletInfo, error)

Generate creates a wallet using the provided generator

func (*HDWallet) GenerateMultiple 

func (w *HDWallet) GenerateMultiple(gen Generator, count uint32) ([]*WalletInfo, error)

GenerateMultiple creates multiple wallets for a given generator

func (*HDWallet) Mnemonic 

func (w *HDWallet) Mnemonic() string

Mnemonic returns the mnemonic phrase

func (*HDWallet) Seed 

func (w *HDWallet) Seed() []byte

Seed returns the seed bytes

type PathComponent 

type PathComponent struct {
	Index    uint32
	Hardened bool
}

PathComponent represents a single component in a derivation path

func ParseDerivationPath 

func ParseDerivationPath(path string) ([]PathComponent, error)

ParseDerivationPath parses a BIP44-style derivation path string Examples: "m/44'/60'/0'/0/0", "m/84'/0'/0'/0/0", "m/44'/501'/0'" Returns slice of path components and whether each is hardened

func (PathComponent) String 

func (p PathComponent) String() string

String returns the string representation of the component

func (PathComponent) Value 

func (p PathComponent) Value() uint32

Value returns the actual index value (with hardened offset if applicable)

type WalletInfo 

type WalletInfo struct {
	Coin       string `json:"coin"`
	Network    string `json:"network"`
	Address    string `json:"address"`
	PrivateKey string `json:"private_key"`
	PublicKey  string `json:"public_key"`
	WIF        string `json:"wif,omitempty"`
	Path       string `json:"derivation_path"`
	Version    string `json:"version,omitempty"`
}

WalletInfo contains all information about a generated wallet

Source Files

View all Source files

Directories

Path Synopsis
Package encoding provides various encoding utilities for cryptocurrency addresses
 Package encoding provides various encoding utilities for cryptocurrency addresses
Package networks provides wallet generators for different cryptocurrency networks
 Package networks provides wallet generators for different cryptocurrency networks

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.