Skip to main content
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

FlagDefaultDescription
--tree <n>0First Merkle tree index to scan
--end-tree <n>Same as --treeLast Merkle tree index to scan (inclusive)
--all-treesfalseScan all trees starting from --tree until no more are found
--start <n>0Start insertion index within the first tree (inclusive)
--end <n>End of treeEnd insertion index within each tree (inclusive)
--page-size <n>Entire rangeInsertion 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 --end-tree 3

# Scan all trees
umbra utxo scan --all-trees

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

# Paginated scan for large trees
umbra utxo scan --tree 0 --page-size 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:
CategoryDescription
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

  • umbra init with --indexer-endpoint configured.
  • umbra register must have been run.