Skip to main content

Manage derivation paths

A derivation path specifies how addresses and keys are generated from a seed or mnemonic phrase. This allows you to manage multiple addresses (or “accounts”) under the same wallet.

For example, Ethereum commonly uses m/44'/60'/0'/0/0 for the first address. If you want the second address, you’d use m/44'/60'/0'/0/1, and so on.

Wallet type required

Derivation paths are relevant only for wallets initialized from a seed or mnemonic phrase.
If your wallet is from a private key (or a keystore containing a private key), you cannot derive multiple addresses.

What is a derivation path?​

A derivation path is essentially instructions telling your wallet how to "walk" through a hierarchical key tree. Each segment in the path (e.g., 85', 0', 0', etc.) corresponds to a level of derivation in your wallet. By changing one or more segments (often the final index), you can create new sub-accounts or addresses — all while using the same root seed.

For example, a Bitcoin wallet using the BIP84 standard (which generates native SegWit addresses starting with bc1) might use the derivation path:

m/84'/0'/0'/0/0

Here's what each segment means:

  • 84' — specifies BIP84, for native SegWit (bech32) addresses
  • 0' — indicates Bitcoin as the coin type (as per SLIP-44)
  • 0' — the first account
  • 0 — the external chain (used for receiving addresses)
  • 0 — the first receiving address in that chain

By incrementing the final index (e.g., m/84'/0'/0'/0/1, m/84'/0'/0'/0/2, etc.), the wallet can deterministically generate new SegWit addresses — all derived from the same root seed.

This structure allows for organized key management, multiple accounts, and improved privacy, without ever needing to back up more than your original seed.

Getting and setting the derivation path​

Each currency instance in your wallet supports two methods:

  • currency.getDerivationPath(): Returns the current derivation path.
  • currency.setDerivationPath(path: string): Sets a new derivation path.
Derived address

The address derived from the current path is used for all address-based operations, such as getAddress(), addressHistory(), getBalance(), and sending transactions.

Example usage​

import { initializeWallet } from 'chaingate'

async function managePaths() {
  // Example with a phrase-based wallet
  const wallet = await initializeWallet.fromPhrase({
    phrase: 'some bip39 phrase ...'
  })

  // Get the Bitcoin currency instance
  const bitcoin = wallet.currency('bitcoin')

  // Check the default derivation path
  const defaultPath = bitcoin.getDerivationPath()
  console.log('Default path:', defaultPath)
  // e.g., "m/84'/0'/0'/0/0"

  // Retrieve the default address
  const address0 = await bitcoin.getAddress()
  console.log('Address #0:', address0)

  // Set a new derivation path for the next address
  bitcoin.setDerivationPath("m/84'/0'/0'/0/1")
  const address1 = await bitcoin.getAddress()
  console.log('Address #1:', address1)
}

Why use different paths?​

  • Multiple addresses: Assign different addresses for receiving payments, accounting separation, or organizational purposes.
  • Multi-account support: Some protocols or dApps expect multiple derivation paths for advanced features.

Key points​

  • Phrase or Seed Required: Only wallets derived from mnemonic phrases or seeds can utilize multiple derivation paths.
  • Address-based operations use the current path: Methods like getAddress(), addressHistory(), and transaction signing will reflect the latest path set with setDerivationPath(...).
  • Default path: By default, ChainGate uses each currency’s standard path (e.g., m/44'/60'/0'/0/0 for Ethereum).
  • Private key wallets: Do not support derivation paths, since each private key represents exactly one address.