Wallet methods

The wallet daemon, null-wallet-rpc, holds one wallet file, keeps it synced from a node, and serves these methods on its own listener and token. It derives deposit addresses, finds incoming notes with their memos, and builds, proves and broadcasts payments as tracked operations.

The examples assume the daemon listens on 127.0.0.1:18447 and WALLET_TOKEN holds its token; see Enable the wallet daemon. Transport, encoding and error codes are the same as the node's (overview). For a deposit and withdrawal walk-through, see Exchanges.

Methods marked Spends funds queue transactions that move money out of the wallet: sendmany and consolidate. A watch-only wallet refuses them with -2.

Wallet concepts

Notes. A wallet's money is a set of notes, each with an amount, the address it was sent to, a memo and a position in the note commitment tree. The position identifies a note in listunspent and in consolidation inputs.
Addresses. getnewaddress derives the next diversified address. All of them belong to the same key and are found by the same scan. Index 0 is the default address. It receives change and consolidated notes.
Confirmations of a note are counted from its block to the wallet's scanned height, inclusive. A reorganization rolls the wallet back on its own, and a note whose block disappears disappears from these lists. Ten confirmations (about twenty minutes) is a reasonable deposit threshold. The network refuses reorganizations deeper than 200 blocks.
Coinbase rewards appear when they mature, 100 blocks after the block that mined them.
Watch-only wallets are created from an exported full viewing key (nulld create --viewing-key nullview1…). They see every note, memo and spend, and can answer ownership challenges, but cannot spend. Run one on deposit hosts so the spending key stays elsewhere.
Operations. A send is queued, then built and proved by the sync loop, one operation at a time, then broadcast and followed until it is mined. Reads keep being served meanwhile. The operation status moves through queued, proving, submitted and confirmed, or ends as failed or cancelled.

RPCgetwalletinfo

getwalletinfo

Sync state and totals. Use synced to know when balances are current, and last_error to see why sync or broadcast is failing. No parameters.

Result

Name
network
Type
string
Description
main or test.
Name
watch_only
Type
boolean
Description
Whether the wallet holds only a viewing key.
Name
scanned_height
Type
number | null
Description
Last height the wallet has scanned.
Name
node_height
Type
number | null
Description
The node's tip at the last sync.
Name
synced
Type
boolean
Description
Whether scanned_height equals node_height.
Name
notes
Type
number
Description
Notes ever received.
Name
unspent
Type
number
Description
Notes not yet spent.
Name
balance
Type
string
Description
Value of all unspent notes, in units, regardless of confirmations or reservations.
Name
pending_operations
Type
number
Description
Operations not yet confirmed, failed or cancelled.
Name
last_error
Type
string | null
Description
The error of the last sync pass, or null if it succeeded. Broadcast errors appear here.

Request

RPC

getwalletinfo

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getwalletinfo","params":[]}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "network": "main",
    "watch_only": false,
    "scanned_height": 6206,
    "node_height": 6206,
    "synced": true,
    "notes": 42,
    "unspent": 17,
    "balance": "1284500000",
    "pending_operations": 1,
    "last_error": null
  },
  "id": 1
}

RPCgetnewaddress

getnewaddress

Derives the next diversified address and records it under a label. Give each customer their own address; deposits to any of them are found by the same scan and report the address_index and label they were sent to.

Parameters

Name
label
Type
string
Description
Optional, default "". Your reference for the address, for example a customer id.

Result

Name
index
Type
number
Description
Address index.
Name
address
Type
string
Description
The new address.
Name
label
Type
string
Description
The label as recorded.

Request

RPC

getnewaddress

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getnewaddress","params":{"label":"customer-1042"}}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "index": 2,
    "address": "null1z2fx30cyf8d93t78rradduj3mgu34ty5m4avndkglakq48t796w6nj8jh08pay403zvrwegplwl",
    "label": "customer-1042"
  },
  "id": 1
}

RPClistaddresses

listaddresses

Every address the wallet has handed out, the default address (index 0) first. No parameters.

Result

An array of {index, address, label}.

Request

RPC

listaddresses

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"listaddresses","params":[]}'

Response

{
  "jsonrpc": "2.0",
  "result": [
    {
      "index": 0,
      "address": "null1drhkpmr7np84jr6ww2s8f7hf2rgddg88yrdw34kqhger9v6vc9e8hfaktdcuhnqr29usu8drf8r",
      "label": ""
    },
    {
      "index": 1,
      "address": "null1c32nxrlucj0u4vepa9swy97v2p3gwxyzgxsxya6nj26jf7nxl2tqdm2xr7pyurdaez4nj4g3cw7",
      "label": "customer-1041"
    },
    {
      "index": 2,
      "address": "null1z2fx30cyf8d93t78rradduj3mgu34ty5m4avndkglakq48t796w6nj8jh08pay403zvrwegplwl",
      "label": "customer-1042"
    }
  ],
  "id": 1
}

RPCgetaddressinfo

getaddressinfo

Whether an address belongs to this wallet, and its index and label if so.

Parameters

Name
address
Type
string
Description
Required. An address of this network.

Result

Name
is_mine
Type
boolean
Description
Whether the address is this wallet's.
Name
index
Type
number | null
Description
Its address index.
Name
label
Type
string | null
Description
Its label.

Errors

-32602 if the address does not decode for this network.

Request

RPC

getaddressinfo

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getaddressinfo","params":["null1c32nxrlucj0u4vepa9swy97v2p3gwxyzgxsxya6nj26jf7nxl2tqdm2xr7pyurdaez4nj4g3cw7"]}'

Response

{
  "jsonrpc": "2.0",
  "result": { "is_mine": true, "index": 1, "label": "customer-1041" },
  "id": 1
}

RPCvalidateaddress

validateaddress

Whether a string is a valid address for this wallet's network. Use it to check a withdrawal address before queueing a payment. A testnet address is invalid on a mainnet wallet.

Parameters

Name
address
Type
string
Description
Required. The text to check.

Result

Name
valid
Type
boolean
Description
Whether it decodes as an address of this network.
Name
network
Type
string
Description
The wallet's network.

Request

RPC

validateaddress

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"validateaddress","params":["null19crg8qy05x8gj7mz6tuq0r9c9j48njnny34ycueljywcrm7uquvyjhfkzknarmngc0yegdyfvh8"]}'

Response

{ "jsonrpc": "2.0", "result": { "valid": true, "network": "main" }, "id": 1 }

RPCexportviewingkey

exportviewingkey

The wallet's full viewing key, for creating a watch-only wallet elsewhere with nulld create --viewing-key. No parameters.

The viewing key cannot move funds, but it reveals every note, memo and spend of the wallet. Treat it as confidential.

Result

Name
viewing_key
Type
string
Description
nullview1… on mainnet, tnullview1… on testnet.
Name
watch_only
Type
boolean
Description
Whether this wallet is itself watch-only.

Request

RPC

exportviewingkey

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"exportviewingkey","params":[]}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "viewing_key": "nullview1peppc2hunfhg793c07vxa89yjue66rya4fzwe2ruvletvnh9f2hdm7uv7wz9pn3mr24r0gmsx02kjq8ez4tkryqg4v5leqe6ks5dq2x56cag3us7ppjge5ue40cr4h6nvfgwghrkkrkp0xg8m4sy0s6nqgx7x8ex",
    "watch_only": false
  },
  "id": 1
}

RPCgetbalance

getbalance

Unspent value split by what a send may use now.

Parameters

Name
min_confirmations
Type
number
Description
Optional, default 1. Notes with fewer confirmations count as pending.

Result

All values are strings in units.

Name
spendable
Type
string
Description
Has enough confirmations and is not reserved.
Name
locked
Type
string
Description
Reserved as inputs of pending operations.
Name
pending
Type
string
Description
Has fewer than min_confirmations confirmations.
Name
total
Type
string
Description
The sum of the three.

Request

RPC

getbalance

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getbalance","params":[10]}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "spendable": "1030000000",
    "locked": "250000000",
    "pending": "4500000",
    "total": "1284500000"
  },
  "id": 1
}

RPClistunspent

listunspent

Unspent notes. This is the deposit feed: poll it with since_height, credit each note once it reaches your confirmation threshold, and key your records on txid plus position.

Parameters

Name
min_confirmations
Type
number
Description
Optional, default 1. Only notes with at least this many confirmations.
Name
since_height
Type
number
Description
Optional, default 0. Only notes mined at or above this height.

Result

An array of notes:

Name
position
Type
number
Description
Position in the note commitment tree. Unique per note.
Name
txid
Type
hex | null
Description
Transaction that created the note.
Name
height
Type
number
Description
Height at which the note entered the tree.
Name
confirmations
Type
number
Description
Confirmations at the wallet's scanned height.
Name
amount
Type
string
Description
Value in units.
Name
address
Type
string
Description
The address the note was sent to.
Name
address_index
Type
number | null
Description
Index of that address in this wallet.
Name
label
Type
string | null
Description
Label of that address.
Name
memo
Type
string | object | null
Description
The memo as text; {"hex": "…"} if it is not UTF-8; null if empty. Full-block scanning only; --light does not recover memos.
Name
spent
Type
boolean
Description
Whether the note is spent.
Name
spent_at
Type
number | null
Description
Height of the spending block.
Name
spent_by
Type
hex | null
Description
Spending txid, when known.
Name
locked
Type
boolean
Description
Whether a pending operation has reserved the note.

Request

RPC

listunspent

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"listunspent","params":{"min_confirmations":10,"since_height":6100}}'

Response

{
  "jsonrpc": "2.0",
  "result": [
    {
      "position": 12917,
      "txid": "8d2f6a91c04e3b7d5a1e9f08c6b2d4e7a3f5c1b9e0d8a6c4f2b7e9d1c3a5b7f9",
      "height": 6188,
      "confirmations": 19,
      "amount": "250000000",
      "address": "null1z2fx30cyf8d93t78rradduj3mgu34ty5m4avndkglakq48t796w6nj8jh08pay403zvrwegplwl",
      "address_index": 2,
      "label": "customer-1042",
      "memo": "invoice 7781",
      "spent": false,
      "spent_at": null,
      "spent_by": null,
      "locked": false
    }
  ],
  "id": 1
}

RPClistreceived

listreceived

Every note the wallet has ever received, spent ones included. Same parameters and fields as listunspent.

Request

RPC

listreceived

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"listreceived","params":[1, 6000]}'

Response

{
  "jsonrpc": "2.0",
  "result": [
    {
      "position": 12544,
      "txid": "1f4b7c2e9a0d3f6b8e1c4a7d0b3e6f9c2a5d8b1e4f7a0c3d6b9e2f5a8c1d4e7b",
      "height": 6012,
      "confirmations": 195,
      "amount": "100000000",
      "address": "null1c32nxrlucj0u4vepa9swy97v2p3gwxyzgxsxya6nj26jf7nxl2tqdm2xr7pyurdaez4nj4g3cw7",
      "address_index": 1,
      "label": "customer-1041",
      "memo": null,
      "spent": true,
      "spent_at": 6150,
      "spent_by": "c7e2a9f4b1d8e5c2a9f6b3d0e7c4a1f8b5d2e9c6a3f0b7d4e1c8a5f2b9d6e3c0",
      "locked": false
    }
  ],
  "id": 1
}

RPCgettransaction

gettransaction

This wallet's side of one transaction: the notes it gave the wallet and the wallet notes it spent.

Parameters

Name
txid
Type
hex
Description
Required. Transaction id.

Result

Name
txid
Type
hex
Description
Transaction id.
Name
height
Type
number | null
Description
Block height.
Name
confirmations
Type
number | null
Description
Confirmations at the wallet's scanned height.
Name
received
Type
array
Description
Notes received, in the listunspent format.
Name
spent
Type
array
Description
Wallet notes spent, same format.
Name
net
Type
string
Description
Received minus spent in units, signed. For a withdrawal it is negative and includes the fee.

Errors

-1 if the transaction did not touch this wallet.

Request

RPC

gettransaction

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"gettransaction","params":["c7e2a9f4b1d8e5c2a9f6b3d0e7c4a1f8b5d2e9c6a3f0b7d4e1c8a5f2b9d6e3c0"]}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "txid": "c7e2a9f4b1d8e5c2a9f6b3d0e7c4a1f8b5d2e9c6a3f0b7d4e1c8a5f2b9d6e3c0",
    "height": 6150,
    "confirmations": 57,
    "received": [
      {
        "position": 12801,
        "txid": "c7e2a9f4b1d8e5c2a9f6b3d0e7c4a1f8b5d2e9c6a3f0b7d4e1c8a5f2b9d6e3c0",
        "height": 6150,
        "confirmations": 57,
        "amount": "49980000",
        "address": "null1drhkpmr7np84jr6ww2s8f7hf2rgddg88yrdw34kqhger9v6vc9e8hfaktdcuhnqr29usu8drf8r",
        "address_index": 0,
        "label": "",
        "memo": null,
        "spent": false,
        "spent_at": null,
        "spent_by": null,
        "locked": false
      }
    ],
    "spent": [
      {
        "position": 12544,
        "txid": "1f4b7c2e9a0d3f6b8e1c4a7d0b3e6f9c2a5d8b1e4f7a0c3d6b9e2f5a8c1d4e7b",
        "height": 6012,
        "confirmations": 195,
        "amount": "100000000",
        "address": "null1c32nxrlucj0u4vepa9swy97v2p3gwxyzgxsxya6nj26jf7nxl2tqdm2xr7pyurdaez4nj4g3cw7",
        "address_index": 1,
        "label": "customer-1041",
        "memo": null,
        "spent": true,
        "spent_at": 6150,
        "spent_by": "c7e2a9f4b1d8e5c2a9f6b3d0e7c4a1f8b5d2e9c6a3f0b7d4e1c8a5f2b9d6e3c0",
        "locked": false
      }
    ],
    "net": "-50020000"
  },
  "id": 1
}

RPCrescan

rescan

Rolls the wallet back to just below from_height and lets the sync loop scan forward again. Use it after restoring a wallet or if you suspect missed notes. The call waits for an active sync or proof to finish first. It returns at once with the rolled-back height; watch getwalletinfo until synced is true again.

Parameters

Name
from_height
Type
number
Description
Optional, default 0. First height to scan again.

Result

Name
scanned_height
Type
number | null
Description
The wallet's scanned height after the rollback.

Request

RPC

rescan

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"rescan","params":{"from_height":6100}}'

Response

{ "jsonrpc": "2.0", "result": { "scanned_height": 6099 }, "id": 1 }

RPCestimatefee

estimatefee

The fee for paying a number of recipients plus change. Transactions are padded to 2, 4, 8 or 16 actions, and the fee is 10,000 units per action. This is a lower bound: spending many small notes can need a larger class. Use quotepayment for the exact figure.

Parameters

Name
recipients
Type
number
Description
Optional, default 1. From 1 to 15.

Result

Name
fee
Type
string
Description
Fee in units.
Name
actions
Type
number
Description
Action class of the transaction.

Errors

-32602 if recipients is 0 or more than 15.

Request

RPC

estimatefee

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"estimatefee","params":[15]}'

Response

{ "jsonrpc": "2.0", "result": { "fee": "160000", "actions": 16 }, "id": 1 }

RPCquotepayment

quotepayment

The exact fee and total for a payment, selecting notes as sendmany would right now. Notes reserved by pending operations are excluded. A queued payment is built later and may select differently if the wallet's notes change in between.

Parameters

Name
recipients
Type
array
Description
Required. 1 to 15 recipients, in the sendmany format.
Name
min_confirmations
Type
number
Description
Optional, default 1. Only spend notes with at least this many confirmations.

Result

Name
fee
Type
string
Description
Fee in units.
Name
total
Type
string
Description
Sum of the recipient amounts plus the fee.
Name
spends
Type
number
Description
Notes the payment would spend.
Name
actions
Type
number
Description
Actions in the transaction after padding.

Errors

-2 with insufficient funds: have …, need …. -32602 for an invalid recipient.

Request

RPC

quotepayment

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"quotepayment","params":{"recipients":[
        {"address":"null19crg8qy05x8gj7mz6tuq0r9c9j48njnny34ycueljywcrm7uquvyjhfkzknarmngc0yegdyfvh8","amount":"150000000"},
        {"address":"null17a976zkntq09pvvtusamynsmpzmlnq6u787qkqh5qu7rfhl5zqrrf7yxyq8cc2qe0fps2kq6t0t","amount":"75000000"}]}}'

Response

{
  "jsonrpc": "2.0",
  "result": { "fee": "40000", "total": "225040000", "spends": 1, "actions": 4 },
  "id": 1
}

RPCsendmany

sendmany

Spends funds. Queues a payment to 1 to 15 recipients in one transaction and returns an operation id at once. The sync loop then selects notes, builds and proves the transaction, records it, and broadcasts it. Change goes to the default address. Follow the operation with getoperationstatus.

Funds are checked when the operation is built, not when it is queued. A payment the wallet cannot cover ends as failed. Call quotepayment first.

Parameters

Name
recipients
Type
array
Description
Required. 1 to 15 objects: address (string, required), amount (decimal string or whole number in units, required), memo (UTF-8 text up to 512 bytes, optional; the recipient sees it).
Name
min_confirmations
Type
number
Description
Optional, default 1. Only spend notes with at least this many confirmations.

Result

Name
operation_id
Type
number
Description
Id of the new operation.
Name
status
Type
string
Description
queued.

Errors

-2 on a watch-only wallet. -32602 for an empty or oversized recipient list, an invalid address, amount or memo.

Request

RPC

sendmany

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"sendmany","params":{"recipients":[
        {"address":"null19crg8qy05x8gj7mz6tuq0r9c9j48njnny34ycueljywcrm7uquvyjhfkzknarmngc0yegdyfvh8","amount":"150000000","memo":"withdrawal 5521"},
        {"address":"null17a976zkntq09pvvtusamynsmpzmlnq6u787qkqh5qu7rfhl5zqrrf7yxyq8cc2qe0fps2kq6t0t","amount":"75000000","memo":"withdrawal 5522"}],
        "min_confirmations":10}}'

Response

{
  "jsonrpc": "2.0",
  "result": { "operation_id": 18, "status": "queued" },
  "id": 1
}

RPCgetoperationstatus

getoperationstatus

The state of one send operation.

queued: waiting for the sync loop to build it.
proving: being built and proved.
submitted: the exact transaction is recorded and has been, or is being, broadcast. This does not guarantee the node accepted it. Until it is mined, the wallet rebroadcasts the same bytes on every pass and keeps its inputs reserved. Submission errors show in getwalletinfo last_error.
confirmed: mined. txid, height and confirmations are set. A reorganization can move it back to submitted.
failed: the transaction could not be built (for example insufficient funds), or the retry budget was used up before anything was broadcast. error says why. Inputs are released.
cancelled: cancelled before it was ever broadcast.

If the anchor of a broadcast transaction ages past 100 blocks unmined, the operation goes back to queued and is rebuilt, up to five build attempts in total. A replacement spends only the inputs of the earlier attempt, so at most one of them can be mined. Every attempt stays recorded and is checked for confirmation. A failed replacement leaves the operation submitted with the earlier transaction pending; it is not a failed payment.

Parameters

Name
operation_id
Type
number
Description
Required.

Result

Name
operation_id
Type
number
Description
Operation id.
Name
status
Type
string
Description
See above.
Name
created_at
Type
number
Description
Unix time the operation was queued.
Name
recipients
Type
array
Description
{address, amount, memo} per recipient.
Name
total
Type
string
Description
Sum of the recipient amounts, without the fee.
Name
min_confirmations
Type
number
Description
As requested.
Name
txid
Type
hex | null
Description
Set once submitted.
Name
height
Type
number | null
Description
Set once confirmed.
Name
confirmations
Type
number | null
Description
Set once confirmed.
Name
attempts
Type
number
Description
Build attempts so far.
Name
cancellable
Type
boolean
Description
Whether canceloperation would succeed.
Name
error
Type
string | null
Description
The reason, when failed.

Errors

-1 if there is no such operation.

Request

RPC

getoperationstatus

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getoperationstatus","params":[18]}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "operation_id": 18,
    "status": "confirmed",
    "created_at": 1793000310,
    "recipients": [
      {
        "address": "null19crg8qy05x8gj7mz6tuq0r9c9j48njnny34ycueljywcrm7uquvyjhfkzknarmngc0yegdyfvh8",
        "amount": "150000000",
        "memo": "withdrawal 5521"
      },
      {
        "address": "null17a976zkntq09pvvtusamynsmpzmlnq6u787qkqh5qu7rfhl5zqrrf7yxyq8cc2qe0fps2kq6t0t",
        "amount": "75000000",
        "memo": "withdrawal 5522"
      }
    ],
    "total": "225000000",
    "min_confirmations": 10,
    "txid": "5a9e3c1f7b2d8e4a6c0f9b3d5e7a1c8f2b4d6e0a9c3f5b7d1e8a2c4f6b0d9e3a",
    "height": 6203,
    "confirmations": 4,
    "attempts": 1,
    "cancellable": false,
    "error": null
  },
  "id": 1
}

RPClistoperations

listoperations

Every operation, oldest first, in the getoperationstatus format.

Parameters

Name
status
Type
string
Description
Optional. Only operations in this status: queued, proving, submitted, confirmed, failed or cancelled.

Request

RPC

listoperations

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"listoperations","params":["failed"]}'

Response

{
  "jsonrpc": "2.0",
  "result": [
    {
      "operation_id": 15,
      "status": "failed",
      "created_at": 1792998120,
      "recipients": [
        {
          "address": "null19crg8qy05x8gj7mz6tuq0r9c9j48njnny34ycueljywcrm7uquvyjhfkzknarmngc0yegdyfvh8",
          "amount": "90000000000",
          "memo": null
        }
      ],
      "total": "90000000000",
      "min_confirmations": 1,
      "txid": null,
      "height": null,
      "confirmations": null,
      "attempts": 1,
      "cancellable": false,
      "error": "insufficient funds: have 1030000000, need 90000020000"
    }
  ],
  "id": 1
}

RPCcanceloperation

canceloperation

Cancels a queued operation that has never been broadcast. Once a transaction has been recorded for broadcast it can still be mined, so it can no longer be cancelled. cancellable in the operation tells you which case applies.

Parameters

Name
operation_id
Type
number
Description
Required.

Result

The operation in the getoperationstatus format, now cancelled.

Errors

-1 if there is no such operation. -2 if it is not cancellable (operation is submitted; only queued, never-broadcast ones can be cancelled) or changed during the call.

Request

RPC

canceloperation

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"canceloperation","params":[19]}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "operation_id": 19,
    "status": "cancelled",
    "created_at": 1793000902,
    "recipients": [
      {
        "address": "null19crg8qy05x8gj7mz6tuq0r9c9j48njnny34ycueljywcrm7uquvyjhfkzknarmngc0yegdyfvh8",
        "amount": "50000000",
        "memo": null
      }
    ],
    "total": "50000000",
    "min_confirmations": 1,
    "txid": null,
    "height": null,
    "confirmations": null,
    "attempts": 0,
    "cancellable": false,
    "error": null
  },
  "id": 1
}

RPCquoteconsolidation

quoteconsolidation

A preview of merging the wallet's notes into fewer, larger notes at the default (index 0) address. Useful for a pool or miner whose wallet holds many small coinbase rewards, which make later payments need more actions. Nothing is queued or broadcast.

The plan takes the eligible notes from any of the wallet's addresses, largest first, in batches of up to 16. Each batch becomes one transaction with one output at the default address, worth the batch's value minus its fee. Excluded: notes reserved by other operations, notes below min_confirmations, zero-value notes, and batches whose value does not cover their fee. A single leftover note is left alone. A watch-only wallet can preview.

Parameters

Name
min_confirmations
Type
number
Description
Optional, default 1. Only notes with at least this many confirmations.
Name
inputs
Type
array
Description
Optional. Note positions to consolidate, instead of every eligible note.

Result

Name
address
Type
string
Description
The default address that receives the merged notes.
Name
input_count
Type
number
Description
Notes that would be spent.
Name
inputs
Type
array
Description
Their positions. Pass this list to consolidate.
Name
transactions
Type
number
Description
Transactions (batches) that would be built.
Name
fee
Type
string
Description
Total fee in units. Pass it to consolidate as max_fee.
Name
amount
Type
string
Description
Total value of the new notes, in units.

Errors

All -2:

wallet is busy; try consolidation again shortly: a scan or proof is running. Retry.
wait for the wallet to finish scanning: the wallet is behind the node.
cannot consolidate: need at least two available notes whose value covers the fee.
cannot consolidate: inputs changed or are unavailable; request a new quote: some inputs are unknown, spent, reserved, unconfirmed or duplicated.

Request

RPC

quoteconsolidation

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"quoteconsolidation","params":{"min_confirmations":10}}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "address": "null1drhkpmr7np84jr6ww2s8f7hf2rgddg88yrdw34kqhger9v6vc9e8hfaktdcuhnqr29usu8drf8r",
    "input_count": 5,
    "inputs": [12210, 12348, 12517, 12690, 12873],
    "transactions": 1,
    "fee": "80000",
    "amount": "4849920000"
  },
  "id": 1
}

RPCconsolidate

consolidate

Spends funds. Queues the consolidation that quoteconsolidation previews: one operation per batch, with every batch's inputs reserved together in one step. The funds stay in the wallet, but each transaction pays a fee.

To confirm exactly what you reviewed, pass the quote's inputs and its fee as max_fee. If any input is no longer available or the fee would be higher, nothing is queued. Track or cancel each operation with the operation methods. After they confirm, another consolidation can merge the resulting notes further. Consolidation never spends future rewards on its own.

Parameters

Name
min_confirmations
Type
number
Description
Optional, default 1.
Name
inputs
Type
array
Description
Optional. Note positions from the quote.
Name
max_fee
Type
string
Description
Optional. Highest total fee you accept, in units.

Result

The quote fields, plus:

Name
operation_ids
Type
array
Description
One operation id per transaction.
Name
status
Type
string
Description
queued.

Errors

All errors of quoteconsolidation, plus -2 with watch-only wallet cannot spend and consolidation fee exceeds max_fee; request a new quote.

Request

RPC

consolidate

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"consolidate","params":{
        "min_confirmations":10,
        "inputs":[12210, 12348, 12517, 12690, 12873],
        "max_fee":"80000"}}'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "address": "null1drhkpmr7np84jr6ww2s8f7hf2rgddg88yrdw34kqhger9v6vc9e8hfaktdcuhnqr29usu8drf8r",
    "input_count": 5,
    "inputs": [12210, 12348, 12517, 12690, 12873],
    "transactions": 1,
    "fee": "80000",
    "amount": "4849920000",
    "operation_ids": [20],
    "status": "queued"
  },
  "id": 1
}

The same planner is available on the command line against a node's control socket: nulld consolidate --wallet <file> --dry-run previews and nulld consolidate --wallet <file> queues and records the transactions. Close any other program that has the wallet file open first. See Command line.

RPChelp

help

The names of every wallet daemon method. No parameters.

Request

RPC

help

curl -s http://127.0.0.1:18447/ \
  -H "Authorization: Bearer $WALLET_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"help","params":[]}'

Response

{
  "jsonrpc": "2.0",
  "result": [
    "getwalletinfo", "getnewaddress", "listaddresses", "getaddressinfo",
    "validateaddress", "exportviewingkey", "getbalance", "listunspent",
    "listreceived", "gettransaction", "sendmany", "getoperationstatus",
    "listoperations", "canceloperation", "estimatefee", "quotepayment",
    "quoteconsolidation", "consolidate", "rescan", "getpaymentdisclosure",
    "answerchallenge", "help"
  ],
  "id": 1
}