<p>In the example RPC results, it will show whether the result is a JSON array by including brackets <code>[]</code> or it will show if it is a JSON object (associative array) by using curly brackets <code>{}</code>. 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.</p>

<p>You can see an example of a result that comes in the form of a JSON array by using <code>listlockunspent</code>:</p>

<pre><code>Result:
[
  {
    "txid" : "transactionid",     (string) The transaction id locked
    "vout" : n                      (numeric) The vout value
  }
  ,...
]
</code></pre>

<p>An example of a JSON object using <code>createwallet</code>:</p>

<pre><code>Result:
{
  "name" :    &lt;wallet_name&gt;,        (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" : &lt;warning&gt;,            (string) Warning message if wallet was not loaded cleanly.
}
</code></pre>

<p>An example of a return value that is not JSON encoded using <code>getbalance</code>:</p>

<pre><code>Result:
amount              (numeric) The total amount in BTC received for this wallet.
</code></pre>

<p>I believe you may be mistaken with the assumption that <code>sendtoaddress</code> return a JSON object. The code <a href="https://github.com/bitcoin/bitcoin/blob/0.18/src/wallet/rpcwallet.cpp#L441" rel="nofollow noreferrer">clearly shows</a> that the result is not JSON encoded:</p>



<pre><code>return tx-&gt;GetHash().GetHex();
</code></pre>

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

<p>The code would use <code>UniValue</code> if it were to encode JSON. For example <a href="https://github.com/bitcoin/bitcoin/blob/0.18/src/wallet/rpcwallet.cpp#L2623" rel="nofollow noreferrer">in the code</a> of <code>createwallet</code>:</p>

<pre><code>UniValue obj(UniValue::VOBJ);
obj.pushKV("name", wallet-&gt;GetName());
obj.pushKV("warning", warning);

return obj;
</code></pre>

CC BY-SA 4.0
2019-11-24T22:21:21.967Z
2019-11-25T00:23:42.093Z
2019-11-25T00:23:42.093Z
presstab
<p>Bitcoin Core's RPC API call "getnewaddress" is documented here: <a href="https://bitcoincore.org/en/doc/0.18.0/rpc/wallet/getnewaddress/" rel="nofollow noreferrer">https://bitcoincore.org/en/doc/0.18.0/rpc/wallet/getnewaddress/</a></p>

<p>It claims:</p>

<blockquote>
  <p>Result: "address"    (string) The new bitcoin address</p>
</blockquote>

<p>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.</p>

<p>However, it <em>actually</em> 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:</p>

<p>The "sendtoaddress" call <em>does</em> return an associative array with just a "txid" element, and it's documented just like "getnewaddress": <a href="https://bitcoincore.org/en/doc/0.18.0/rpc/wallet/sendtoaddress/" rel="nofollow noreferrer">https://bitcoincore.org/en/doc/0.18.0/rpc/wallet/sendtoaddress/</a></p>

<blockquote>
  <p>Result: "txid"                  (string) The transaction id.</p>
</blockquote>

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

<p>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'.</p>

<p>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.</p>

<p>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.</p>

CC BY-SA 4.0
2019-11-24T17:01:08.687Z
You should always test things with testnet, so that you don't lose money.
Pieter Wuille
CC BY-SA 4.0
2019-11-25T22:41:32.697Z
You are incorrect about `sendtoaddress`. It just returns the txid as a single string just like `getnewaddress`.
Ava Chow
<bitcoin-core><api><documentation>
How should I handle cases like this where the documentation for Bitcoin Core states one thing, and the actual program does something else?
hugabug
# How should I handle cases like this where the documentation for Bitcoin Core states one thing, and the actual program does something else?

(Asked by: username_0 on 2019-11-24)

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.

**Tags:** bitcoin-core, api, documentation

> **Comments:**
> **username_1**: You should always test things with testnet, so that you don't lose money.  
> **username_2**: You are incorrect about `sendtoaddress`. It just returns the txid as a single string just like `getnewaddress`.  

---

## 1 answers

### Answer by username_3 on 2019-11-24. Score: 6

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`:

```
Result:
[
  {
    "txid" : "transactionid",     (string) The transaction id locked
    "vout" : n                      (numeric) The vout value
  }
  ,...
]

```

An example of a JSON object using `createwallet`:

```
Result:
{
  "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`:

```
Result:
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](https://github.com/bitcoin/bitcoin/blob/0.18/src/wallet/rpcwallet.cpp#L441) 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](https://github.com/bitcoin/bitcoin/blob/0.18/src/wallet/rpcwallet.cpp#L2623) of `createwallet`:

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

return obj;

```


---

