Global Notes - Umbra Privacy

Paginated global UTXO query

curl --request GET \
  --url https://utxo-indexer.api.umbraprivacy.com/v1/utxos

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://utxo-indexer.api.umbraprivacy.com/v1/utxos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://utxo-indexer.api.umbraprivacy.com/v1/utxos"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://utxo-indexer.api.umbraprivacy.com/v1/utxos")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "error": "Not Found",
  "message": "Tree 99 not found"
}

{
  "error": "Not Found",
  "message": "Tree 99 not found"
}

{
  "error": "Not Found",
  "message": "Tree 99 not found"
}

Paginated global UTXO query

curl --request GET \
  --url https://utxo-indexer.api.umbraprivacy.com/v1/utxos

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://utxo-indexer.api.umbraprivacy.com/v1/utxos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://utxo-indexer.api.umbraprivacy.com/v1/utxos"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://utxo-indexer.api.umbraprivacy.com/v1/utxos")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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
}

{
  "error": "Not Found",
  "message": "Tree 99 not found"
}

{
  "error": "Not Found",
  "message": "Tree 99 not found"
}

{
  "error": "Not Found",
  "message": "Tree 99 not found"
}

Use this endpoint when you need to scan notes globally without knowing which tree they belong to. For tree-specific queries, prefer Tree Notes.

The path retains the legacy /v1/utxos segment. The records it serves are V18 Stealth Pool Notes.

Pagination

Use the next_cursor from each response as the start parameter for the next request. Repeat until the response contains fewer records than limit.

# First page
curl "https://utxo-indexer.api.umbraprivacy.com/v1/utxos?start=0&limit=1000"

# Next page
curl "https://utxo-indexer.api.umbraprivacy.com/v1/utxos?start=1000&limit=1000"

# Fetch a specific range (e.g. all notes in tree 1: absolute indices 1,048,576 to 2,097,151)
curl "https://utxo-indexer.api.umbraprivacy.com/v1/utxos?start=1048576&end=2097151&limit=5000"

Response Layouts

Set X-Response-Layout: columnar for columnar layout (UtxoColumnarResponse). Omit for row-oriented layout (UtxoResponse).

Headers

X-Response-Layout

enum<string>

Set to "columnar" for UtxoColumnarResponse (parallel arrays). Omit for the default row-oriented UtxoResponse.

Available options:

columnar

Query Parameters

start

integer<int64>

default:0

Inclusive lower bound of the absolute index range to fetch. Defaults to 0.

Required range: x >= 0

end

integer<int64>

Inclusive upper bound of the absolute index range. When omitted, scans from start to end of dataset, bounded by limit.

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 requested absolute index range.

Option 1
Option 2

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.

Show child attributes

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

​Pagination

​Response Layouts

Headers

Query Parameters

Response

Pagination

Response Layouts