Skip to main content
Paginated UTXO records for a specific tree
curl --request GET \
  --url http://localhost:3001/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
}
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://acqzie0a1h.execute-api.eu-central-1.amazonaws.com/v1/trees/0/utxos?cursor=0&limit=1000"

# Next page (using next_cursor from previous response)
curl "https://acqzie0a1h.execute-api.eu-central-1.amazonaws.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