Skip to main content
Paginated UTXO records for a specific tree
Use this endpoint when you know which tree you want to scan. For global scans across all trees, use Global Notes.
The path retains the legacy /v1/trees/{tree_index}/utxos segment. The records are V18 Stealth Pool Notes.

Response Layouts

The X-Response-Layout header controls how records are packed in the protobuf response:
  • Row-oriented (default, omit header): each note is a self-contained UtxoDataItem. Easy to iterate record by record.
  • Columnar (set header to "columnar"): all fields across notes are packed into parallel arrays. Significantly smaller on the wire — preferred for data pipelines and bulk processing.
The Umbra SDK uses row-oriented layout internally. Use columnar layout only if you are building a custom bulk processing pipeline.

Pagination

Initialise with cursor = tree_index × 1,048,576. Each response includes a next_cursor field. Repeat requests using cursor = next_cursor until the response contains fewer records than limit.

Headers

X-Response-Layout
enum<string>

Set to "columnar" to receive a UtxoColumnarResponse (struct-of-arrays). Omit or use any other value for the default row-oriented UtxoResponse.

Available options:
columnar

Path Parameters

tree_index
integer<int64>
required

Zero-based index of the Merkle tree whose UTXOs to fetch.

Required range: x >= 0

Query Parameters

cursor
integer<int64>

Absolute index at which to start the current page (inclusive). Defaults to tree_index * MAX_LEAVES_PER_TREE (first slot of the tree). Values below the tree's start boundary are clamped up.

Required range: x >= 0
limit
integer<int64>
default:1000

Maximum records per page. Default: 1000. Maximum: 5000. Passing 0 uses the default.

Required range: 0 <= x <= 5000

Response

UTXO records for the specified tree.

Protobuf UtxoResponse message -- row-oriented paginated UTXO response.

Returned by GET /v1/utxos and GET /v1/trees/{tree_index}/utxos when X-Response-Layout is absent or set to any value other than "columnar".

Each UTXO is encoded as a self-contained UtxoDataItem sub-message. Use next_cursor as the start (or cursor) parameter of the next request to retrieve the following page.

items
object[]
required

Up to limit UTXO records in ascending absolute_index order.

has_more
boolean
required

true if additional records exist beyond this page.

Example:

true

total_count
integer<int64>
required

Total number of matching records in the requested range across all pages.

Example:

5000

start_index
integer<int64>
required

Inclusive lower bound of the absolute index range that was queried.

Example:

0

next_cursor
integer<int64> | null

Absolute index to pass as start (or cursor) for the next page. Absent when has_more is false.

Example:

1001

end_index
integer<int64> | null

Inclusive upper bound of the absolute index range that was queried. Absent when no explicit end (or tree boundary) was provided.

Example:

4999