wallet: add `gethdkey` RPC for BIP 32 key derivation #34438

w0xlt commented at 2:21 AM on January 29, 2026: contributor

Revives #22341 (marked "up for grabs").

Add gethdkey RPC to derive an extended key at any BIP 32 path from the wallet's active HD key. This enables exporting xpubs/xprvs for external setups (e.g., BIP 87 multisig) without modifying the wallet's keypool.

$ bitcoin-cli gethdkey "m/87'/0'/0'"
{
    "xpub": "xpub6...",
    "fingerprint": "1a2b3c4d",
    "origin": "[1a2b3c4d/87'/0'/0']" 
}                                                                                                                                     
                                                                                                                                        
$ bitcoin-cli gethdkey "m/87'/0'/0'" '{"private": true}' 
{
    "xpub": "xpub6...",
    "xprv": "xprv9...",
    .. 
}

Use case: Users setting up multisig (e.g., with hardware wallets or other software) need xpubs at specific derivation paths. Currently this there is no way to extract a specific path from wallets in Bitcoin Core.

Design: Intentionally simple, only exports key info. To sign with derived keys, users import the returned xprv via importdescriptors. This keeps all signing through the normal keypool mechanism.

util: support 'h' as hardened marker in ParseHDKeypath

Allow paths like "m/84h/0h/0h" in addition to "m/84'/0'/0'".
This aligns with descriptor notation where both markers are valid.

Co-Authored-By: Sjors Provoost <sjors@sprovoost.nl>

16d2695a8e

wallet: add gethdkey RPC for BIP 32 key derivation

Add a new RPC that derives an extended key at any BIP 32 path from the
wallet's active HD key. This enables exporting xpubs for use in external
setups (e.g., BIP 87 multisig) without modifying the wallet's keypool.

The RPC returns the xpub, master fingerprint, and origin info in
descriptor format. With the "private" option, it also returns the xprv.
Hardened derivation requires the wallet to be unlocked.

This RPC is intentionally simple: it only exports key information.
Users who want to sign with keys at custom derivation paths
should use the returned xprv with importdescriptors to add the
descriptor to their wallet's keypool. This ensures all signing goes
through the normal keypool mechanism.

Co-Authored-By: Sjors Provoost <sjors@sprovoost.nl>

d2ba62fa90

test: add functional tests for gethdkey RPC

Cover BIP 32 derivation correctness, basic functionality, path format
validation, error cases, and a 2-of-3 multisig workflow using keys
derived at the BIP 87 path.

Co-Authored-By: Sjors Provoost <sjors@sprovoost.nl>

bb657f9d96

doc: update multisig tutorial to use gethdkey RPC

Replace the listdescriptors-based xpub extraction with gethdkey,
enabling proper BIP 87 multisig derivation path (m/87'/1'/0').

Changes:
- Use gethdkey to derive keys at the standard multisig path
- Add section 1.4 explaining how to import the multisig descriptor
  with private keys into participant wallets for signing
- Simplify xpub extraction (no more jq/grep/sed pipeline)
- Update section numbering (1.4 Fund -> 1.5, etc.)

Co-Authored-By: Sjors Provoost <sjors@sprovoost.nl>

b4dbab25bf

DrahtBot renamed this:
~~wallet: add `gethdkey` RPC for BIP 32 key derivation~~
wallet: add `gethdkey` RPC for BIP 32 key derivation
on Jan 29, 2026

DrahtBot added the label Wallet on Jan 29, 2026

DrahtBot commented at 2:22 AM on January 29, 2026: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Reviews

See the guideline for information on the review process. A summary of reviews will appear here.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#34049 (rpc: Disallow captures in RPCMethodImpl by ajtowns)
#32784 (wallet: derivehdkey RPC to get xpub at arbitrary path by Sjors)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

LLM Linter (✨ experimental)

Possible typos and grammar issues:

One signed by participant_1 wallet and other, by the participant_2 wallet. -> One signed by the participant_1 wallet and the other by the participant_2 wallet. [Fixes missing articles and word order to make the sentence grammatical and clear]

rkrux commented at 2:19 PM on February 6, 2026: contributor

This seems quite similar to #32784, possibly a subset of the functionality provided by it.

Like in the other PR, the name derivehdkey seems more appropriate to me - gethdkey gives the impression that something is being gotten from the wallet storage (read database).

w0xlt commented at 2:51 PM on February 6, 2026: contributor

I wasn't aware of #32784. Thanks for letting me know. Closing this in favor of that PR.

w0xlt closed this on Feb 6, 2026

w0xlt deleted the branch on Feb 6, 2026