Wallet: addresses & keys

Reference for the address-generation, address-inspection, wallet-metadata, and lock/unlock methods. For the wire format, auth, and multiwallet /wallet/<name> routing, see Conventions & wire format; for background on Unified Addresses, diversified addresses, and pool configuration, see Addresses & shielded pools.

getnewaddress

getnewaddress ( "" address_type )

Returns a fresh receiving address for the wallet's account: a new diversified Unified Address (new diversifier, same account key), or a bare transparent address when requested. Works on watch-only wallets and on locked encrypted wallets (addresses derive from the viewing key, not the seed).

Parameters

With no address_type, the wallet's [pools] configuration decides: the default (Orchard-only) config returns an Orchard-only UA; a wallet with transparent_default = true returns a bare transparent address. Every requested shielded receiver must be a pool enabled on the wallet. "transparent" requires [pools] transparent = true and cannot be combined with shielded pool names (zecd hands out one receiver type at a time; ZIP-316 forbids a transparent-only UA, so the transparent receiver is bare-encoded as t1.../tm...).

Transparent addresses come from the gap-limited external chain. Once the recovery window is full of unfunded addresses, zecd by default issues past it with a loud log warning (such an address may be unrecoverable from seed); with [pools] transparent_allow_beyond_recovery_window = false it returns -4 instead. See Transparent support.

Result: the address as a JSON string.

"u1v0qh8pw9qm4h2v0negtfzrwhtjzfhgh0jcs9tzkjxg7xkpxkfhz5c4tj0nzqyjrmzgcqnyu7q6cx"

Errors

The address_type syntax is validated before the wallet is resolved, so an unknown token is -5 regardless of which wallet is targeted; pool enablement is checked per wallet.

vs Bitcoin Core: same signature (label, address_type) and the same -5 Unknown address type '...' for a bad type, but zecd rejects a non-empty label with -8 where Core records it in the address book. The type values differ: pool names instead of legacy/p2sh-segwit/bech32/bech32m.

vs zcashd: zcashd's getnewaddress is deprecated and only produces transparent addresses; its shielded flow is z_getnewaccount + z_getaddressforaccount. zecd's getnewaddress is the primary shielded path.

z_getaddressforaccount

z_getaddressforaccount account ( ["receiver_type",...] diversifier_index )

Derives a Unified Address for the wallet's account in zcashd's syntax, optionally at an exact diversifier index. Unlike getnewaddress, the returned object includes the diversifier index, so a client can re-derive the same address deterministically later.

Parameters

Re-deriving at the same index with the same receiver set is idempotent (byte-identical response, zcashd's invariant). Requesting a different receiver set at an already-exposed index is a -4 reuse error. Auto-selected shielded indices are not sequential (the next-unused selection is clock-seeded; see Addresses & shielded pools), so record the returned diversifier_index if you need to re-derive.

Result

{
  "account": 0,
  "diversifier_index": 1000000,
  "receiver_types": ["orchard"],
  "address": "u1v0qh8pw9qm4h2v0negtfzrwhtjzfhgh0jcs9tzkjxg7xkpxkfhz5c4tj0nzqyjrmzgcqnyu7q6cx"
}

Errors

vs Bitcoin Core: no equivalent.

vs zcashd: same syntax and result shape, and the reuse/no-address error strings match zcashd's wording under the same -4. Two deliberate divergences: zcashd accepts any previously generated account number, zecd only account 0; and zcashd's default (and accepted) receiver set includes p2pkh, while zecd is shielded-only here and rejects it with -8. Use getnewaddress "" "transparent" for a t-address.

getaddressinfo

getaddressinfo "address"

Returns ownership and validity details for an address. ismine is cryptographic, not just a lookup: after the recorded-address fast path, zecd attributes the address to the account's incoming viewing key by decrypting its diversifier, so an address the account can derive but never recorded (for example one handed out before a from-seed restore and never funded) still reports ismine: true. Bare transparent addresses are recognized via recorded addresses only.

Parameters

Result

{
  "address": "u1v0qh8pw9qm4h2v0negtfzrwhtjzfhgh0jcs9tzkjxg7xkpxkfhz5c4tj0nzqyjrmzgcqnyu7q6cx",
  "scriptPubKey": "",
  "ismine": true,
  "solvable": true,
  "iswatchonly": false,
  "isscript": false,
  "iswitness": false,
  "isvalid_orchard": true,
  "receiver_types": ["orchard"],
  "labels": []
}

• scriptPubKey: the real hex script for transparent addresses; empty for shielded addresses, which have no script form.
• solvable: equals ismine, including on watch-only wallets (Core's definition ignores the lack of private keys; the wallet-level signal is getwalletinfo.private_keys_enabled).
• iswatchonly: always false, matching Core master where the field is deprecated.
• isvalid_orchard, receiver_types: zecd extensions mirroring validateaddress: whether the address carries an Orchard receiver, and the full list of pools it can receive into (transparent/sapling/orchard).
• labels: always [] (zecd is stateless; the field is kept for shape conformance).
• receivers_consistent (optional, extension): present only for a multi-receiver UA whose consistency against this wallet's keys is computable. false flags a hand-spliced UA (receivers from different diversifier indices, or one of ours mixed with a stranger's) that this wallet can never have issued.

Errors

vs Bitcoin Core: same core fields and the same -5 on an undecodable address, but zecd emits a fixed subset: no desc/parent_desc, no HD key path or pubkey fields, no ischange/timestamp. isvalid_orchard/receiver_types/receivers_consistent are additions.

vs zcashd: no equivalent; zcashd has only validateaddress/z_validateaddress, with no ownership attribution for Unified Addresses in this shape.

getwalletinfo

getwalletinfo

Wallet metadata and balances. scanning reports sync progress and stays truthy while the transaction-enhancement backlog drains (the wallet is at the tip but still backfilling memos and full transaction data), not just during the block scan.

Result

{
  "walletname": "default",
  "walletversion": 169900,
  "format": "sqlite",
  "balance": 1.25000000,
  "unconfirmed_balance": 0.10000000,
  "immature_balance": 0.00000000,
  "txcount": 12,
  "keypoolsize": 1,
  "keypoolsize_hd_internal": 0,
  "paytxfee": 0.00000000,
  "private_keys_enabled": true,
  "avoid_reuse": false,
  "scanning": { "duration": 0, "progress": 0.9731 },
  "descriptors": false,
  "unlocked_until": 1751629200
}

• balance/unconfirmed_balance/immature_balance: decimal ZEC, 8 places, under the wallet's confirmations policy.
• keypoolsize is always 1 and keypoolsize_hd_internal always 0: addresses are diversified on demand from the account key; there is no key pool.
• paytxfee is always 0 (fees are ZIP-317, never client-settable).
• private_keys_enabled: false for a watch-only (imported UFVK) wallet; the wallet-level cannot-sign signal, as with Core's disable_private_keys wallets.
• scanning: an object (duration always 0, progress the block-scan ratio in [0,1]) while scanning or while the enhancement backlog is nonzero; false when idle.
• descriptors: always false.
• unlocked_until: present only for passphrase-encrypted wallets; the unix time the wallet auto-relocks, or 0 while locked. Absent on unencrypted and watch-only wallets.
• transparent (extension): present only when [pools] transparent = true, so a shielded-only wallet's shape is unchanged. {"enabled": true, "default": <bool>, "gap_limit": <n>}, plus, when transparent_initial_scan is set, an initial_sync object {"exposed": <n>, "total": <n>, "complete": <bool>} for polling the address pre-exposure. See Transparent support.

vs Bitcoin Core: walletversion 169900 and format: "sqlite" match Core's values. Core master has dropped the balance/unconfirmed_balance/immature_balance/paytxfee fields from this method (balances live on getbalances); zecd still emits them, in the older Core shape. zecd omits Core's external_signer, blank, birthtime, flags, and lastprocessedblock (the latter appears on zecd's getbalances). The transparent block is an addition.

vs zcashd: zcashd's getwalletinfo keeps the old pre-0.19 Core shape plus its own split (balance is transparent-only, with a separate shielded_balance), a real key pool (keypoololdest), and a settable paytxfee; zecd follows modern Core instead.

listwallets

listwallets

Returns the names of all loaded wallets: every [wallets.<name>] in the config (plus the default wallet). Target a specific wallet with the /wallet/<name> URL path, as in Bitcoin Core; see Conventions & wire format.

Result

["default", "watch1"]

vs Bitcoin Core: identical shape. zecd has no createwallet/loadwallet/ unloadwallet: the wallet set is fixed by configuration at startup, and at most one loaded wallet may hold spending keys.

vs zcashd: no equivalent (zcashd is single-wallet).

walletpassphrase

walletpassphrase "passphrase" timeout

Decrypts the seed of a passphrase-encrypted wallet into (mlocked) memory for timeout seconds, after which it auto-relocks. Re-running it resets the timer; a timeout of 0 relocks almost immediately. Only wallets created with zecd init --encrypt are passphrase-encrypted; there is no passphrase-setting or passphrase-changing RPC, so the passphrase is chosen at init and never crosses the network in any other call. See Key custody.

Before holding the seed unlocked, zecd verifies it derives the account's pinned UFVK; a mismatch (a replaced keys.toml or wallet database) fails with -4 and the wallet stays locked.

Parameters

Result: null.

Errors

Argument validation runs before the encryption-state check, so a negative timeout is -8 even on an unencrypted wallet.

Example

curl -u user:pass -d '{"jsonrpc":"1.0","id":1,"method":"walletpassphrase","params":["correct horse battery staple",600]}' http://127.0.0.1:8232/

vs Bitcoin Core: same semantics, the same 100,000,000-second clamp, and the same -14/-15 messages. zecd unlocks a seed (scrypt-derived key over an age-encrypted mnemonic) rather than a wallet.dat master key.

vs zcashd: same method and error codes, but zcashd has no timeout clamp, and its wallet encryption (encryptwallet/walletpassphrasechange) is an experimental feature disabled by default; zecd sets encryption once at init --encrypt.

walletlock

walletlock

Drops the decrypted seed immediately and cancels the pending relock. Subsequent sends fail with -13 ("unlock needed") until the next walletpassphrase.

The zeroization takes a fast path: wallet commands normally serialize through the per-wallet actor, so a lock queued behind a send that is mid-proof would wait out the whole proving window. walletlock instead zeroizes the shared in-memory seed immediately, bypassing the queue. The in-flight send already derived its spending key before proving, so it completes; any queued send then fails -13 at key derivation, which is the correct post-lock behavior. The actor still processes the lock command afterward as the authoritative writer of the relock deadline and published status.

Result: null.

Errors

vs Bitcoin Core: same semantics and the same -15 on an unencrypted wallet.

vs zcashd: same method; zcashd locks its wallet.dat master key, zecd zeroizes the in-memory seed.