Skip to main content
Paginated UTXO records for a specific tree
curl --request GET \
  --url https://utxo-indexer.api.umbraprivacy.com/v1/trees/{tree_index}/utxos
{
  "items": [
    {
      "absolute_index": 1048620,
      "tree_index": 1,
      "insertion_index": 44,
      "final_commitment": "aSDinaTvuI8gbWludGxpZnk=",
      "h1_version": "aSDinaTvuI8gbWludGxpZnk=",
      "h1_commitment_index": "aSDinaTvuI8gbWludGxpZnk=",
      "h1_sender_address": "aSDinaTvuI8gbWludGxpZnk=",
      "h1_mint_address": "aSDinaTvuI8gbWludGxpZnk=",
      "h1_relayer_fixed_sol_fees": 5000000,
      "h1_year": 2026,
      "h1_month": 2,
      "h1_day": 25,
      "h1_hour": 12,
      "h1_minute": 0,
      "h1_second": 0,
      "h1_purpose": 1,
      "h1_circuit_provable_hash": "aSDinaTvuI8gbWludGxpZnk=",
      "h1_smart_program_provable_hash": "aSDinaTvuI8gbWludGxpZnk=",
      "h1_hash": "aSDinaTvuI8gbWludGxpZnk=",
      "h2_hash": "aSDinaTvuI8gbWludGxpZnk=",
      "aes_encrypted_data": "aSDinaTvuI8gbWludGxpZnk=",
      "depositor_x25519_public_key": "aSDinaTvuI8gbWludGxpZnk=",
      "timestamp": 1735689600,
      "slot": 350000000,
      "event_type": "deposit"
    }
  ],
  "has_more": true,
  "total_count": 5000,
  "start_index": 0,
  "next_cursor": 1001,
  "end_index": 4999
}

Documentation Index

Fetch the complete documentation index at: https://sdk.umbraprivacy.com/llms.txt

Use this file to discover all available pages before exploring further.

Use this endpoint when you know which tree you want to scan. For global scans across all trees, use Global UTXOs.

​
Response Layouts

The X-Response-Layout header controls how records are packed in the protobuf response:
  • Row-oriented (default, omit header): Each UTXO is a self-contained UtxoDataItem. Easy to iterate record by record.
  • Columnar (set header to "columnar"): All fields across UTXOs 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

Initialize with cursor = tree_index x 1,048,576. Each response includes a next_cursor field. Repeat requests using cursor = next_cursor until the response contains fewer records than limit. 
# First page of tree 0
curl "https://utxo-indexer.api.umbraprivacy.com/v1/trees/0/utxos?cursor=0&limit=1000"

# Next page (using next_cursor from previous response)
curl "https://utxo-indexer.api.umbraprivacy.com/v1/trees/0/utxos?cursor=1000&limit=1000"

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