RPC reference

1. Why this chapter exists

zcash-cli help enumerates the RPC surface at runtime, but it is not searchable without a running daemon and gives no source pointers. This chapter is the flat list: every command, the file that registers it, and a one-line role. Use it as a lookup table.

The list is pinned to upstream tag v5.5.0-rc1. After NU6 the upstream tree gained a small number of additional commands; check git log src/rpc/ src/wallet/rpc*.cpp since the pin for the delta.

2. Definitions

Definition 14.1 (RPC command). A function exported via the JSON-RPC server at 127.0.0.1:8232 (mainnet) / :18232 (testnet) / :18232 (regtest). Each command is registered as a CRPCCommand record in a static array, then merged into the global tableRPC at daemon startup.

Definition 14.2 (Category). A string tag that groups related commands. The categories present in v5.5.0-rc1 are blockchain, mining, generating, util, network, rawtransactions, control, addressindex, disclosure, wallet, and hidden (commands that exist but are not listed by help).

Definition 14.3 (Safe-mode flag). Each CRPCCommand carries a boolean okSafeMode. When the node enters safe mode (alert condition), only commands marked true are callable. Most read-only commands are safe-mode OK; commands that mutate state typically are not.

Definition 14.4 (Hidden command). A command registered with category "hidden". It exists and can be invoked, but is omitted from the help output. Used for test hooks (setmocktime, invalidateblock) and seldom-used maintenance operations.

3. The code

The static registration arrays are at the bottom of each RPC file:

src/rpc/blockchain.cpp (CRPCCommand array)

loading...

View on GitHub

src/rpc/register.h (the five core Register* functions)

loading...

View on GitHub

Each function appends its commands to CRPCTable& tableRPC; the table is the single dispatch surface used by both httprpc.cpp (the HTTP front end) and rpc/client.cpp (the zcash-cli client).

Tables, by category

Conventions in the tables below:

• "Safe?" is the okSafeMode flag.
• The "Source" column links the file where the command's handler lives at v5.5.0-rc1.
• Hidden commands are marked in their own row near the bottom.
• Wallet commands are unavailable when the node is started with -disablewallet.

control (6 commands)

Daemon lifecycle, introspection, and the help dispatcher.

Command	Safe?	Source	Role
help	yes	server.cpp	List or describe RPC commands.
stop	yes	server.cpp	Shut down the daemon.
setlogfilter	yes	server.cpp	Reconfigure the tracing log filter at runtime (Rust side).
getinfo	yes	rpc/misc.cpp	Deprecated single-call summary. Prefer getblockchaininfo / getnetworkinfo / getwalletinfo.
getmemoryinfo	yes	rpc/misc.cpp	Memory allocator stats.
getexperimentalfeatures	yes	rpc/misc.cpp	List -experimentalfeatures= toggles enabled at startup.

blockchain (17 commands)

Read-only chain and mempool inspection.

Command	Safe?	Source	Role
getblockchaininfo	yes	rpc/blockchain.cpp	Chain state summary: height, NU activation, pool balances.
getbestblockhash	yes	rpc/blockchain.cpp	Hash of the current chain tip.
getblockcount	yes	rpc/blockchain.cpp	Height of the current chain tip.
getblock	yes	rpc/blockchain.cpp	Block by hash or height. Verbosity controls raw vs JSON.
getblockhash	yes	rpc/blockchain.cpp	Hash of the block at given height on the active chain.
getblockheader	yes	rpc/blockchain.cpp	Header-only view of a block.
getchaintips	yes	rpc/blockchain.cpp	All known tips (active, valid-fork, headers-only).
getdifficulty	yes	rpc/blockchain.cpp	Current PoW difficulty.
getmempoolinfo	yes	rpc/blockchain.cpp	Mempool summary (count, size, fee).
getrawmempool	yes	rpc/blockchain.cpp	Mempool txids or full mempool-entry JSON.
gettxout	yes	rpc/blockchain.cpp	UTXO lookup by outpoint (transparent only).
gettxoutsetinfo	yes	rpc/blockchain.cpp	Iterate the full UTXO set; slow on mainnet.
verifychain	yes	rpc/blockchain.cpp	Re-verify the last N blocks.
z_gettreestate	yes	rpc/blockchain.cpp	Sprout, Sapling, Orchard tree state at a given block.
getblockdeltas	no	rpc/blockchain.cpp	Insight explorer; requires -insightexplorer.
getblockhashes	yes	rpc/blockchain.cpp	Insight explorer; block hashes in a timestamp window.
gettxoutproof	yes	rpc/rawtransaction.cpp	Hex Merkle proof for a transaction.
verifytxoutproof	yes	rpc/rawtransaction.cpp	Verify a gettxoutproof blob.
getspentinfo	no	rpc/misc.cpp	Insight; which tx spent a given outpoint. Requires -spentindex.

network (12 commands)

Peer table, banlist, and connection control.

Command	Safe?	Source	Role
getconnectioncount	yes	rpc/net.cpp	Number of connected peers.
getdeprecationinfo	yes	rpc/net.cpp	Build's DEPRECATION_HEIGHT and -allowdeprecated state.
ping	yes	rpc/net.cpp	Send ping to every peer (round-trip times read via getpeerinfo).
getpeerinfo	yes	rpc/net.cpp	Per-peer status: addr, services, bytes, latency, subversion.
addnode	yes	rpc/net.cpp	Add/remove/onetry a manual peer (-addnode=).
disconnectnode	yes	rpc/net.cpp	Drop a peer by address or node id.
getaddednodeinfo	yes	rpc/net.cpp	Status of -addnode peers.
getnettotals	yes	rpc/net.cpp	Lifetime byte counters.
getnetworkinfo	yes	rpc/net.cpp	Protocol version, subversion, local addresses, service flags.
setban	yes	rpc/net.cpp	Add or remove a manual ban.
listbanned	yes	rpc/net.cpp	All current bans (manual + automatic).
clearbanned	yes	rpc/net.cpp	Wipe the banlist.

mining (8 commands)

Miner-facing template construction and PoW utilities.

Command	Safe?	Source	Role
getmininginfo	yes	rpc/mining.cpp	Mining-related state: difficulty, mempool, networkhashps.
getlocalsolps	yes	rpc/mining.cpp	Local Equihash solutions per second.
getnetworksolps	yes	rpc/mining.cpp	Network-wide estimated solutions per second.
getnetworkhashps	yes	rpc/mining.cpp	Alias for getnetworksolps.
getblocktemplate	yes	rpc/mining.cpp	Build a candidate block for external miners; includes coinbase template with funding streams.
submitblock	yes	rpc/mining.cpp	Submit a mined block.
getblocksubsidy	yes	rpc/mining.cpp	Block subsidy and funding-stream allocations at a height.
prioritisetransaction	yes	rpc/mining.cpp	Bias the in-memory fee on a tx for template selection.

generating (3 commands)

Built-in CPU miner; off by default.

Command	Safe?	Source	Role
getgenerate	yes	rpc/mining.cpp	Is the in-process miner running?
setgenerate	yes	rpc/mining.cpp	Start/stop the in-process miner.
generate	yes	rpc/mining.cpp	Mine N blocks immediately (regtest convenience).

util (5 commands)

Stateless helpers.

Command	Safe?	Source	Role
estimatefee	yes	rpc/mining.cpp	Fee per byte to land in N blocks (uses fee estimator).
validateaddress	yes	rpc/misc.cpp	Decode a transparent address.
z_validateaddress	yes	rpc/misc.cpp	Decode a Sprout / Sapling / unified / Orchard address.
createmultisig	yes	rpc/misc.cpp	Build a transparent multisig address.
verifymessage	yes	rpc/misc.cpp	Verify a signmessage signature against an address.

rawtransactions (7 commands)

Transparent transaction surgery and proof verification.

Command	Safe?	Source	Role
getrawtransaction	yes	rpc/rawtransaction.cpp	Transaction by id. Requires -txindex for arbitrary historical txes.
createrawtransaction	yes	rpc/rawtransaction.cpp	Build a transparent transaction skeleton.
decoderawtransaction	yes	rpc/rawtransaction.cpp	Parse a hex-serialised transaction.
decodescript	yes	rpc/rawtransaction.cpp	Disassemble a redeem-script hex blob.
sendrawtransaction	no	rpc/rawtransaction.cpp	Broadcast a serialised transaction; mempool-checks first.
signrawtransaction	no	rpc/rawtransaction.cpp	Sign a raw tx using keys from the wallet.
fundrawtransaction	no	wallet/rpcwallet.cpp	Add wallet inputs + change to balance a raw tx.

addressindex (5 commands, Insight Explorer)

Off by default. Require -addressindex=1 (and sometimes -spentindex=1). Originated in the Bitcore / Insight explorer fork.

Command	Safe?	Source	Role
getaddresstxids	no	rpc/misc.cpp	All txids touching one or more addresses.
getaddressbalance	no	rpc/misc.cpp	Net balance across an address set.
getaddressdeltas	no	rpc/misc.cpp	Per-transaction balance deltas per address.
getaddressutxos	no	rpc/misc.cpp	Unspent outputs paying to an address set.
getaddressmempool	yes	rpc/misc.cpp	Mempool entries touching an address.

wallet, transparent (33 commands)

Require the wallet (-disablewallet=0). Most match Bitcoin Core's legacy wallet.

Command	Safe?	Source	Role
addmultisigaddress	yes	wallet/rpcwallet.cpp	Register a transparent multisig address.
backupwallet	yes	wallet/rpcwallet.cpp	Transactional copy of wallet.dat.
dumpprivkey	yes	wallet/rpcdump.cpp	WIF private key for a transparent address.
encryptwallet	yes	wallet/rpcwallet.cpp	First-time passphrase encryption.
getbalance	no	wallet/rpcwallet.cpp	Confirmed wallet balance, transparent.
getnewaddress	yes	wallet/rpcwallet.cpp	Derive a new transparent receive address.
getrawchangeaddress	yes	wallet/rpcwallet.cpp	Internal change address (transparent).
getreceivedbyaddress	no	wallet/rpcwallet.cpp	Sum received at one address.
gettransaction	no	wallet/rpcwallet.cpp	Wallet-side view of a tx by id.
getunconfirmedbalance	no	wallet/rpcwallet.cpp	Mempool-only balance.
getwalletinfo	no	wallet/rpcwallet.cpp	Wallet state summary.
importprivkey	yes	wallet/rpcdump.cpp	Import a WIF transparent key.
importwallet	yes	wallet/rpcdump.cpp	Replay a dumpwallet text export.
importaddress	yes	wallet/rpcdump.cpp	Watch-only transparent address.
importpubkey	yes	wallet/rpcdump.cpp	Watch-only public key.
keypoolrefill	yes	wallet/rpcwallet.cpp	Pre-derive transparent keys.
listaddresses	yes	wallet/rpcwallet.cpp	Every address (all pools) the wallet knows.
listaddressgroupings	no	wallet/rpcwallet.cpp	Heuristic clustering of transparent addresses.
listlockunspent	no	wallet/rpcwallet.cpp	Outpoints temporarily locked from spending.
listreceivedbyaddress	no	wallet/rpcwallet.cpp	Per-address received totals.
listsinceblock	no	wallet/rpcwallet.cpp	All wallet txes since a given block.
listtransactions	no	wallet/rpcwallet.cpp	Recent wallet transactions.
listunspent	no	wallet/rpcwallet.cpp	Transparent UTXOs available to the wallet.
lockunspent	yes	wallet/rpcwallet.cpp	Lock/unlock specific outpoints.
sendmany	no	wallet/rpcwallet.cpp	Transparent multi-output send.
sendtoaddress	no	wallet/rpcwallet.cpp	Transparent single-output send.
settxfee	yes	wallet/rpcwallet.cpp	Default fee per kB for legacy commands.
signmessage	yes	wallet/rpcwallet.cpp	Sign a message with a transparent address's key.
walletlock	yes	wallet/rpcwallet.cpp	Forget the unlocked passphrase.
walletpassphrase	yes	wallet/rpcwallet.cpp	Decrypt the wallet for a timeout.
walletpassphrasechange	yes	wallet/rpcwallet.cpp	Change the passphrase.
walletconfirmbackup	yes	wallet/rpcwallet.cpp	Acknowledge that a wallet backup has been taken.
zcbenchmark	yes	wallet/rpcwallet.cpp	Run a built-in cryptographic microbenchmark.
zcsamplejoinsplit	yes	wallet/rpcwallet.cpp	Construct one Sprout JoinSplit; sample / debug only.

wallet, shielded z_* (28 commands)

Zcash-specific shielded operations. All wallet RPC; most are async (return an opid from z_getoperationstatus).

Command	Safe?	Source	Role
z_getbalance	no	wallet/rpcwallet.cpp	Balance for a transparent or shielded address.
z_getbalanceforaccount	no	wallet/rpcwallet.cpp	Balance for a unified-account number.
z_getbalanceforviewingkey	no	wallet/rpcwallet.cpp	Watch-only balance for a UFVK / extended viewing key.
z_gettotalbalance	no	wallet/rpcwallet.cpp	Sum across pools.
z_listunspent	no	wallet/rpcwallet.cpp	Unspent notes per shielded address.
z_listreceivedbyaddress	no	wallet/rpcwallet.cpp	Received notes for one address.
z_sendmany	no	wallet/rpcwallet.cpp	Async build + send a shielded transaction.
z_mergetoaddress	no	wallet/rpcwallet.cpp	Async consolidate notes into one output.
z_shieldcoinbase	no	wallet/rpcwallet.cpp	Async shield coinbase outputs.
z_setmigration	no	wallet/rpcwallet.cpp	Toggle Sprout-to-Sapling migration.
z_getmigrationstatus	no	wallet/rpcwallet.cpp	Read migration progress.
z_getoperationstatus	yes	wallet/rpcwallet.cpp	Poll one or more async operation IDs.
z_getoperationresult	yes	wallet/rpcwallet.cpp	Drain finished async operation results.
z_listoperationids	yes	wallet/rpcwallet.cpp	Enumerate async operation IDs.
z_getnewaddress	yes	wallet/rpcwallet.cpp	Sapling / Sprout new address (legacy path).
z_getnewaccount	yes	wallet/rpcwallet.cpp	Create a ZIP-316 unified account.
z_listaccounts	yes	wallet/rpcwallet.cpp	Enumerate unified accounts.
z_listaddresses	yes	wallet/rpcwallet.cpp	Enumerate shielded / unified addresses.
z_listunifiedreceivers	yes	wallet/rpcwallet.cpp	Decompose a unified address.
z_getaddressforaccount	yes	wallet/rpcwallet.cpp	Derive a unified address for an account.
z_exportkey	yes	wallet/rpcdump.cpp	Export the spending key for a shielded address.
z_importkey	yes	wallet/rpcdump.cpp	Import a spending key.
z_exportviewingkey	yes	wallet/rpcdump.cpp	Export a viewing key.
z_importviewingkey	yes	wallet/rpcdump.cpp	Import a viewing key (watch-only).
z_exportwallet	yes	wallet/rpcdump.cpp	Text export including shielded keys.
z_importwallet	yes	wallet/rpcdump.cpp	Text import of a z_exportwallet blob.
z_viewtransaction	no	wallet/rpcwallet.cpp	Decrypt the wallet's view of every shielded item in a tx.
z_getnotescount	no	wallet/rpcwallet.cpp	Count of Sprout / Sapling / Orchard notes.

disclosure (2 commands)

ZIP-308: selective payment disclosure. Off by default; require -experimentalfeatures -paymentdisclosure.

Command	Safe?	Source	Role
z_getpaymentdisclosure	yes	wallet/rpcdisclosure.cpp	Produce a ZIP-308 disclosure for one output.
z_validatepaymentdisclosure	yes	wallet/rpcdisclosure.cpp	Verify a ZIP-308 disclosure blob.

hidden (6 commands)

Not listed by help. Useful for tests and incident response.

Command	Safe?	Source	Role
invalidateblock	yes	rpc/blockchain.cpp	Mark a block invalid; forces reorg to the next-best tip.
reconsiderblock	yes	rpc/blockchain.cpp	Undo invalidateblock.
setmocktime	yes	rpc/misc.cpp	Override GetTime(); regtest only.
resendwallettransactions	yes	wallet/rpcwallet.cpp	Re-broadcast wallet txes that are still in the mempool.
dumpwallet	yes	wallet/rpcdump.cpp	Text export, transparent half only. Hidden because z_exportwallet is preferred.

Counts at v5.5.0-rc1: 123 commands in 11 categories.

How a call is served

HTTP POST / -> httprpc.cpp::HTTPReq_JSONRPC
  -> JSONRPCRequest
  -> tableRPC.execute(jreq)
    -> CRPCCommand::actor(params)
    -> handler function in the category file
    -> wallet lock / cs_main lock as needed
    -> returns UniValue
  -> serialised back to the HTTP body

Authentication is HTTP Basic, either via the auto-generated ~/.zcash/.cookie file (default) or via -rpcuser= / -rpcpassword= / -rpcauth=. The server is bound to 127.0.0.1 by default; binding to a public interface requires -rpcbind= AND a password, or a TLS-terminating reverse proxy.

Deprecation

A small set of commands and behaviours are gated by -allowdeprecated=<feature>. The list of allowable features is in src/deprecation.cpp; the names match the strings used in getdeprecationinfo.

Adding a new RPC

Pattern (in any of the per-category files):

UniValue mycommand(const UniValue& params, bool fHelp) {
    if (fHelp || params.size() != N) {
        throw runtime_error(R"(usage and docstring)");
    }
    LOCK(cs_main);  // or whatever locks apply
    // ... do work
    return result;
}

static const CRPCCommand commands[] = {
    { "mycategory", "mycommand", &mycommand, true, {"arg1", "arg2"} },
};

void RegisterMyRPCCommands(CRPCTable& t) {
    for (auto& cmd : commands) t.appendCommand(cmd.name, &cmd);
}

Then hook RegisterMyRPCCommands into src/rpc/register.h or, for wallet RPCs, into wallet/wallet.cpp::RegisterWalletRPCCommands.

4. Failure modes

• Calling a wallet RPC under -disablewallet. Returns "Method not found" because the wallet's registration was skipped. Caught at first call.
• Calling getrawtransaction for a historical tx without -txindex. Returns an error; the index does not exist. Caught by the RPC returning -5.
• Insight RPCs without -addressindex / -spentindex. The command exists but returns an error. Caught by the RPC layer.
• Async RPC without polling. z_sendmany returns an operation ID, not the result. Forgetting to call z_getoperationresult strands the work; the operation completes but its result is held until drained. Drained on shutdown.
• Using the getinfo legacy summary. Deprecated; some fields are misleading once shielded pools dominate. Use getblockchaininfo / getnetworkinfo / getwalletinfo instead. Caught by the deprecation warning in the result.
• Binding RPC to a public IP without TLS. The protocol is HTTP Basic; credentials cross the wire in clear. Caught by audit only.

5. Spec pointers

RPC is implementation-specific and not consensus. Authoritative references:

• doc/payment-api.md: the authoritative description of the wallet-payment RPC surface (z_* commands).
• Bitcoin Core JSON-RPC reference: most non-z_* commands inherit Bitcoin Core semantics.
• ZIP-308 for payment disclosure.
• ZIP-317 for fee policy as it affects z_sendmany.

6. Exercises

1. Count, by category. Run zcash-cli help | grep -c '^==' || zcash-cli help to enumerate commands by category and compare to the totals above. A delta here often signals a hidden command, or a feature gated behind -experimentalfeatures.

2. Trace a call. Run zcash-cli getinfo against a regtest node. Inspect debug.log with -debug=rpc and identify each step of the dispatch: HTTP receive, JSON parse, table lookup, handler invocation, lock acquisition, return.

3. Find an undocumented response field. Pick one command (e.g. getblockchaininfo) and find a field of the response that is not documented in its help string. The fix is a one-line docstring update in the handler.

4. Modification exercise. Add a getrpcstats RPC that returns per-command invocation counts since startup. The pattern lives in src/rpc/server.cpp; the count can be added to CRPCCommand or kept in a separate std::map.

5. Audit safe-mode flags. Sort the table above by Safe?. Are there commands marked true that mutate state? Treat any you find as findings; safe-mode is intended for read-only commands.

7. Further reading

• Bitcoin Core's RPC reference for commands inherited from upstream.
• ECC wallet payment API docs for the z_* family.
• The chapter 09 RPC overview for the dispatch model from a wallet-and-RPC perspective.