HD Wallet Management with Crypto APIs

HD Wallet Management with Crypto APIs

Blockchain xPub yPub zPub Use Cases

Crypto APIs Team

Nov 25, 2022 • 7 min

Cryptocurrency wallets are used to secure and manage digital assets, but they don’t actually store coins. Instead, they protect funds by securing the cryptographic keys used for verifying ownership. These keys are also used to prepare, sign and broadcast transactions to the blockchain. 

DIfferent wallet types are defined based on how their keys are generated and stored. They can be non-deterministic or deterministic wallets, also known as hierarchical deterministic or HD wallets. 

In this article, we will explore the specifics of hierarchical deterministic (HD) wallets and how they are managed. 

Crypto Wallets and Key Management

Crypto wallets contain addresses that are derived from the holder’s public key, while the private key acts as a secret PIN code that is used to make transactions from an account. It should be kept private and in a secure place, so that only the account owner has access to it. This is where the popular expression “not your keys, not your coins” comes from.

In non-deterministic or random wallets, the keys are randomly generated values which means a user has to keep a copy of all these keys.

In hierarchical deterministic wallets, also known as seeded wallets, the keys are mathematically generated from a seed, which consists of both letters and numerals. This seed usually also comes with a custom seed phrase or mnemonic, represented by a particular combination of words. The seed phrase acts as a backup for the private key.

HD crypto wallets offer stronger privacy than non-deterministic wallets because key pairs are derived automatically for every transaction. They generate keys from the master key in a hierarchical manner, following a tree-like pattern.

In this type of wallets, only the seed needs to be backed up once and this provides access to all of the keys as they are related. This means users don’t need to have several accounts and backup multiple keys. 

Understanding Hierarchical Deterministic Wallets 

In 2012, the publication of BIP 32, a Bitcoin Improvement Proposal (BIP) introduced the creation of a hierarchical tree-like wallet structure, making hierarchical deterministic wallets possible. These wallets can be shared with different systems, each with or without the ability to spend coins.

Several other improvement proposals later introduced different features and functionalities that made HD wallets more flexible and secure.

HD wallets provide a convenient solution for account management and privacy preserving, as the key tree can be deterministically regenerated from the master seed phrase and users can increase their account index on a per-transaction basis to anonymize identity via unique signing keys.

Generally, HD wallets consist of a master key pair which includes an extended public key (xPub) and an extended private key (xPriv). The xPriv generates all the private keys, while the xPub can show the balances of all the public keys within the wallet. All public addresses are generated from an xPub, and that’s why it needs to be handled carefully.

These characteristics of HD wallets make them applicable to multiple use cases, such as:

- Sharing wallet between different systems that need access to perform transactions

- Accounting reports for incoming and outgoing payments and transactions 

- Multi-location offices that operate with assets from a single place  

- Recurrent business-to-business transactions

- Unsecured money receiver 

The Challenges of Accessing HD Wallet Data

In general, each xPub can consist of billions of addresses that are related to a particular seed. Based on the different BIP schemes, the logical structure may vary depending on the path level. For example, the BIP 44 lays out the hierarchy for handling of different coins, multiple accounts, external and internal chains per account and millions of addresses per chain.

What makes it challenging to get all data for a specific xPub is the synchronization for all addresses that already exist or could be created (derived) from the xPub in the future. 

For example, if you’re a crypto exchange that operates with the accounts of millions of users, you own millions of addresses. With an non-detremniscic wallets, storing and protecting all these millions of private keys would be a headache and a serious security vulnerability. 

Thanks to HD wallets, customers can share only their xPub and this will allow monitoring, syncing and collecting information for all activities, including addresses and transactions. 

This provides additional security as some of the addresses that a part of an xPub may have never been exposed to the blockchain and used for transactions. 

APIs for HD Wallet Management 

Crypto APIs’ suite includes a collection of API endpoints that facilitate the management of hierarchical deterministic wallets. Our solutions are trusted and used by hundreds of businesses, including crypto exchanges, hardware wallets, taxes and accounting companies, portfolio trackers, payment service providers and more. 

Through our HD wallet endpoints customers can sync HD wallets, obtain details, list wallet transactions, and more. They are a great solution for:

- Getting information directly from the blockchain 

- Keeping track record of user activities

- Generating reports for taxes and accounting

- Creating and managing secure hardware wallets 

- Creating and operating decentralized exchanges 

- Preserving privacy and security of users

Here are the endpoints that can help you manage your crypto and blockchain projects: 

Sync HD Wallet (xPub, yPub, zPub) - This endpoint is a great helper in obtaining HD wallet details or information for transactions. After initial syncing an xPub, yPub or zPub, we will provide all available information related to it and we will continue updating the sync with new data. We will look into all addresses and sync all the data regardless of the type.

Sync New HD Wallet (xPub, yPub, zPub) - With this API customers can add a brand new xPub to the Crypto APIs system to be ready for deriving. Unlike the endpoint above, this one does not create new addresses nor syncs old data.  

Derive And Sync New Receiving Addresses - Through this endpoint users can derive up to 100 receiving addresses, starting from the last index we have data for. The addresses are then added to the xPub, subscribed for syncing, and start recording data. If no data is available, it will start from index 0.

Derive And Sync New Change Addresses  - Through this endpoint users can derive 100 change addresses, starting from the last index we have data for, which are then added to the xPub, subscribed for syncing, and start recording data. If no data is available, it will start from index 0.

Informative Endpoints for HD Wallet Data

List Synced Addresses - Through this endpoint users can list all addresses that Crypto APIs have synced for a specific xPub. This includes previous and current/new xPubs, what addresses we’ve synced for them, etc.

List HD Wallet (xPub, yPub, zPub) Transactions - This endpoint will list HD Wallet transactions.

List HD Wallet (xPub, yPub, zPub) UTXOs - Through this endpoint you can list HD wallet's UTXOs (Unspent Transaction Outputs) by providing extended public key of an already synced HD wallet.

Get HD Wallet (xPub, yPub, zPub) Assets - This endpoint will return details on assets we support for a predefined extended public key (xPub). These could be cryptocurrencies, fungible or non-fungible (NFT) tokens. Each asset has a unique identifier - assetId, and a unique symbol in the form of a string, e.g. "USDT".

Get HD Wallet (xPub, yPub, zPub) Details - HD wallet details is useful endpoint to get the most important data about HD wallet without the need to do a lot of calculations, once the HD Wallet is synced using Sync endpoint we keep it up to date and we calculate these details in advance.

APIs for Preparing and Broadcasting Transactions

Prepare A UTXO-Based Transaction From HD Wallet (xPub, yPub, zPub)Through this endpoint users can prepare a transaction for signing from all synced with Crypto APIs addresses for the specific xPub. This is based on the selectionStrategy and the addresses’ balances. In the case a user has an address not synced with Crypto APIs, it will not be included. This endpoint applies to all supported UTXO-based blockchain protocols, e.g. Bitcoin, Litecoin, etc.

Prepare An Account-Based Transaction From HD Wallet (xPub, yPub, zPub) -Through this API customers can prepare a transaction for signing from a synced with Crypto APIs address from the specific xPub. This endpoint applies to all supported account-based blockchain protocols, e.g. Ethereum, BSC, etc

Broadcast Locally Signed Transaction - Customers can use this endpoint to broadcast transactions that have been already signed locally, instead of using a node. We then keep the user posted about the status by sending a callback with a success or failure status.

Overcome the Challenges with Crypto APIs

The complexity of hierarchical deterministic wallets makes them great for security and privacy, but also could pose challenges for obtaining the necessary information.

Thanks to Crypto APIs blockchain data, crypto and blockchain companies can facilitate the management of their users’ wallets and ensure accurate information. If you'd like to learn more on how our products can help your project, contact out team.

Related articles