utxo scan - Umbra CLI

umbra utxo scan [options]

Queries the Umbra indexer for stealth UTXOs that belong to your wallet. UTXOs are organized into Merkle trees — the scanner tries to decrypt each one using your keys and reports those it owns. Use this to check what’s available before running utxo claim. The scan does not submit any transactions.

Options

Flag	Default	Description
`--tree <n>`	`0`	First Merkle tree index to scan
`--endTree <n>`	Same as `--tree`	Last Merkle tree index to scan (inclusive)
`--allTrees`	`false`	Scan all trees starting from `--tree` until no more are found
`--start <n>`	`0`	Start insertion index within the first tree (inclusive)
`--end <n>`	End of tree	End insertion index within each tree (inclusive)
`--pageSize <n>`	Entire range	Insertion indices to cover per indexer request

Examples

# Scan tree 0 from the beginning (most common)
umbra utxo scan

# Scan trees 0 through 3
umbra utxo scan --tree 0 --endTree 3

# Scan all trees
umbra utxo scan --allTrees

# Continue from a previous scan
umbra utxo scan --tree 2 --start 1500

# Paginated scan for large trees
umbra utxo scan --tree 0 --pageSize 500

Output

✓ Scan complete
  Self-claimable (encrypted)    2 UTXOs  [1000000, 500000]
  Received (encrypted)          1 UTXO   [250000]

  Next scan start: tree 0, index 3240

UTXO categories:

Category	Description
Self-claimable (encrypted)	You created these UTXOs from your encrypted balance
Self-claimable (public)	You created these UTXOs from your public ATA
Received (encrypted)	Another user sent these to you (encrypted)
Received (public)	Another user sent these to you (public)

The Next scan start values tell you where to resume the next scan to avoid re-scanning already-covered indices.

Prerequisites

A user must be added and active (umbra user add), and indexerApiEndpoint must be set (umbra config set indexerApiEndpoint <url>).
umbra register must have been run.