Bitcoin Core's RPC API call "getnewaddress" is documented here: https://bitcoincore.org/en/doc/0.18.0/rpc/wallet/getnewaddress/

It claims:

Result: "address" (string) The new bitcoin address

In other words, it is supposed to return an associative array containing only the element 'address' which is a string representing the new Bitcoin receive address.

However, it actually returns just an "untitled" string without an array/object. It's just a plain string immediately outputted, not wrapped in any array/object/container. Perhaps this is what they mean by "(string)", but it sure looks to me that the "address" part makes it an associative array with one element. This appears to be the case elsewhere in the API:

The "sendtoaddress" call does return an associative array with just a "txid" element, and it's documented just like "getnewaddress": https://bitcoincore.org/en/doc/0.18.0/rpc/wallet/sendtoaddress/

Result: "txid" (string) The transaction id.

(Or all my previous work was in vain and I have actually got that wrong. I cannot easily try sending Bitcoin.)

Should I assume that they won't change the behaviour of the program, but rather the documentation? Or will they really change the program to reflect the documentation? If they ever do, my code breaks since it expects the returned value to be a string and not an array with one element called 'address'.

This kind of thing gives me a great deal of stress, especially as money is involved and the slightest mistake could cause huge losses or (at best) a ton of nightmarish manual work to attempt to "restore the state" after something is messed up halfways.

Note: I cannot report bugs to their GitHub page because MS GitHub doesn't let me register an account. I gave up on even trying.

  • 1
    You should always test things with testnet, so that you don't lose money. Nov 24, 2019 at 17:01
  • You are incorrect about sendtoaddress. It just returns the txid as a single string just like getnewaddress.
    – Ava Chow
    Nov 25, 2019 at 22:41

1 Answer 1


In the example RPC results, it will show whether the result is a JSON array by including brackets [] or it will show if it is a JSON object (associative array) by using curly brackets {}. If the result does not come with any JSON encoding and is a single string or other data type, then you will not see that in the example.

You can see an example of a result that comes in the form of a JSON array by using listlockunspent:

    "txid" : "transactionid",     (string) The transaction id locked
    "vout" : n                      (numeric) The vout value

An example of a JSON object using createwallet:

  "name" :    <wallet_name>,        (string) The wallet name if created successfully. If the wallet was created using a full path, the wallet_name will be the full path.
  "warning" : <warning>,            (string) Warning message if wallet was not loaded cleanly.

An example of a return value that is not JSON encoded using getbalance:

amount              (numeric) The total amount in BTC received for this wallet.

I believe you may be mistaken with the assumption that sendtoaddress return a JSON object. The code clearly shows that the result is not JSON encoded:

return tx->GetHash().GetHex();

That is a transaction object, which retrieves the transaction hash (256 bit opaque blob), which is then converted to a string using the GetHex() method.

The code would use UniValue if it were to encode JSON. For example in the code of createwallet:

UniValue obj(UniValue::VOBJ);
obj.pushKV("name", wallet->GetName());
obj.pushKV("warning", warning);

return obj;

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.