I'm using bitcoin-core v23.0.

It seems to support watch-only wallets by setting disable_private_keys=true during wallet creation.

$ bitcoin-cli -regtest createwallet "test" true
  "name": "test",
  "warning": ""

But when I try to import an address into it, the command fails:

$ bitcoin-cli -regtest -rpcwallet=test importaddress "bcrt1qpsw3ts4v3srzxqk7f797sxhn22xhwcc3cdq0xe"
error code: -4
error message:
This type of wallet does not support this command

The importpubkey command fails, too

$ bitcoin-cli -regtest -rpcwallet=test importpubkey "035310a2af27b41544204c544b6df18a3a7cc217498d740fb9d1212c3af9fd8010"
error code: -4
error message:
This type of wallet does not support this command

So how to add a watch-only address to bitcoin-core?

And is it possible to derive HD addresses using a watch-only wallet? (I know it's possible because Coinkite can do it)

2 Answers 2


If you're using Bitcoin Core 23.0, and created a new wallet using that, it is by default a descriptor wallet. These are a new generation of wallets which use Output Descriptors to determine which keys/scripts/addresses "belong" to the wallet, as opposed to legacy wallets which use a much less well-defined process to determine this.

Several RPCs, like the importaddress, importpubkey, and importmulti are disabled for descriptor wallets, for the simple reason that the behavior they have for legacy wallets cannot be exactly replicated for descriptor wallets. This is a good thing - it was extremely complicated to reason about what that behavior is.

If you want to import something into a descriptor wallet, you need the importdescriptors RPC instead. This single RPC subsumes the functionality of all legacy import commands in a single RPC, by using the Output Descriptor language to specify what to import. That includes the ability to import single addresses (using addr([ADDR]) descriptors), or ranges of HD key-derived scripts (e.g. wpkh([XPUB]/0/1/2/*) would import all P2WPKH addresses derived from xpub [XPUB], with derivation path m/0/1/2/0, m/0/1/2/1, m/0/1/2/2, ...).

The documentation on developer.bitcoin.org seems outdated. The Bitcoin Core 23.0 RPC documentation (accessible through the help RPC command) does say:

Note: This command is only compatible with legacy wallets. Use "importdescriptors" with "addr(X)" for descriptor wallets.

  • getdescriptorinfo( wpkh(zpub...) ) says the key is invalid. Could you please explain why?
    – Meglio
    Commented Mar 21, 2023 at 16:29
  • You need to use BIP32 xpubs/xprvs in descriptors. All these zpubs/ypubs/vpubs/... are not supported (as they're redundant, they try to convey the same information about how the key is to be used as the descriptor itself) Commented Mar 21, 2023 at 17:02
  • If I'm given an zpub, is there a path to convert it to xpub?
    – Meglio
    Commented Mar 21, 2023 at 17:07
  • You really shouldn't. Whatever gave you a zpub probably did so for a reason. Converting it to something else may well be incompatible with that. Commented Mar 21, 2023 at 17:08
  • I see. I have read here - github.com/satoshilabs/slips/blob/master/slip-0132.md - and it made an impression that zpub is just a more advanced and self-contained version. What we're trying to achieve is have one person (e.g. a vendor) give me an extended public key, and me (e.g. a market) generate one-per-order receiving addresses for them with using bitcoin core rpc and that extended public key. Is that doable with relying on bitcoin core rpc solely? P.S. I feel like it's related ot the topic of "watch-only" wallet, since I'm not given private keys by the vendor.
    – Meglio
    Commented Mar 21, 2023 at 17:10

The complete answer can be found at:

The following steps takes a more practical approach. It's hoped that future interface updates will simplify this process further (today: January 2024):

  1. On Bitcoin-Qt, first create a Wallet with "disabled private keys".
  2. go to Window -> Console.
    • Obs.: The next steps could also be done directly from bitcoin-cli.
  3. getdescriptorinfo "addr(bc1qc7slrfxkknqcq2jevvvkdgvrt8080852dfjewde450xdlk4ugp7szw5tk9)"
  4. Get the "descriptor" result field to be used later. (something like: addr(bc1qc7slrfxkknqcq2jevvvkdgvrt8080852dfjewde450xdlk4ugp7szw)#6rmdcqux)
  5. importdescriptors '[{"desc": "addr(bc1qc7slrfxkknqcq2jevvvkdgvrt8080852dfjewde450xdlk4ugp7szw)#6rmdcqux", "timestamp": "now", "watchonly": true}]' (replacing the "desc" field by the output of "getdescriptorinfo" field "descriptor").
  6. The output should be: [{"success": true}]
  7. (Optional) Consider going to Window -> Receiving Address and add labels to your watch-only addresses.
  8. (Optional) Consider editing the config file and add the walletnotify=<script> %s if you want to be notified. For example: walletnotify=xmessage "Funds had been moved: %s" -center (where %s will be replaced by the txid).

Please note that by setting "timestamp": "now" the blockchain won't be rescanned. Meaning that the you won't see old transactions and therefore a wrong balance had some bitcoins transferred in the past to the address specified. You can specify "timestamp": 0 to have the client rescan the chain and add all transactions or provide a specific timecode at which to start rescanning.

Now an extra tip (perhaps not so related), but a piece of advice:

This kind of thing can be useful for you to know if a system has been breached. You place a private key (or seed) completely open, without a password, in the exact location where you want it to be "monitored". Set a reasonable prize value. Monitor this address using the steps above.

If the balance of the address changes, you know that system has been breached and you can try to take measures to minimize further damage.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.