Skip to main content
Paginated global UTXO query
curl --request GET \
  --url http://localhost:3001/v1/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 need to scan UTXOs globally without knowing which tree they belong to. For tree-specific queries, prefer Tree UTXOs.

​
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://acqzie0a1h.execute-api.eu-central-1.amazonaws.com/v1/utxos?start=0&limit=1000"

# Next page
curl "https://acqzie0a1h.execute-api.eu-central-1.amazonaws.com/v1/utxos?start=1000&limit=1000"

# Fetch a specific range (e.g. all UTXOs in tree 1: absolute indices 1,048,576 to 2,097,151)
curl "https://acqzie0a1h.execute-api.eu-central-1.amazonaws.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.

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