> ## 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.

# Single Note

> Returns the single Stealth Pool Note record at the specified global absolute index.

The absolute index uniquely identifies a note across all trees:

```
absolute_index = tree_index × 1,048,576 + insertion_index
```

For example, the 5th leaf of tree 2 has absolute index `2 × 1,048,576 + 4 = 2,097,156`.

Response is a `SingleUtxoResponse` wrapper containing one `UtxoDataItem`. The `X-Response-Layout` header has no effect on this endpoint.

<Note>
  The path retains the legacy `/v1/utxos/{absolute_index}` segment. The record is a V18 Stealth Pool Note.
</Note>


## OpenAPI

````yaml GET /v1/utxos/{absolute_index}
openapi: 3.0.3
info:
  title: Umbra Indexer Read Service
  description: >
    Read-only REST API for querying Umbra mixer tree state, UTXO records,

    and Merkle inclusion proofs.


    ## Response Encoding


    **All endpoints** support `application/x-protobuf` encoding. The encoding

    strategy differs by endpoint category:


    - **Always Protobuf** (no content negotiation): stats, tree metadata, Merkle
    proofs,
      and all UTXO data endpoints. These endpoints always respond with
      `Content-Type: application/x-protobuf` regardless of the `Accept` header.
    - **Content negotiation** (health endpoints only): respond with JSON by
    default,
      or Protobuf when `Accept: application/x-protobuf` is set. Send
      `Accept: application/x-protobuf` for consistent protobuf-only clients.

    ## UTXO Response Layouts


    The three UTXO data endpoints (`GET /v1/utxos`, `GET
    /v1/utxos/{absolute_index}`,

    `GET /v1/trees/{tree_index}/utxos`) support two Protobuf response layouts

    controlled by the `X-Response-Layout` request header:


    - **Row-oriented** (default) -- `UtxoResponse` message: each UTXO is a
      self-contained `UtxoDataItem` sub-message. Easier to iterate record-by-record.
    - **Columnar** (`X-Response-Layout: columnar`) -- `UtxoColumnarResponse`
    message:
      each field across all UTXOs is packed into a parallel array inside a single
      `UtxoColumns` sub-message. Compresses significantly better over the wire and is
      preferred by vectorized consumers (e.g. data pipelines, analytics).

    ## Rate Limiting


    All endpoints are subject to rate limiting. Exceeded limits return `429 Too
    Many Requests`.


    ## Compression


    All responses are compressed. Send `Accept-Encoding: gzip, br`.


    ## Absolute Index


    The **absolute index** is a globally monotonic cursor across all Merkle
    trees:

    ```

    absolute_index = tree_index * MAX_LEAVES_PER_TREE + insertion_index

    ```

    where `MAX_LEAVES_PER_TREE = 1,048,576` (2^20).
  version: 0.1.0
  contact:
    name: Umbra Protocol
servers:
  - url: https://utxo-indexer.api.umbraprivacy.com
    description: Mainnet
  - url: https://utxo-indexer.api-devnet.umbraprivacy.com
    description: Devnet
security: []
tags:
  - name: health
    description: |
      Health and readiness probes for Kubernetes or load-balancer checks.
      Support both JSON and Protobuf via `Accept` header negotiation.
  - name: stats
    description: Aggregate statistics for the UTXO index. Always Protobuf.
  - name: trees
    description: Per-tree Merkle metadata and Merkle inclusion proofs. Always Protobuf.
  - name: utxos
    description: >
      UTXO data queries with absolute-index-based pagination. Always Protobuf.

      Supports row-oriented and columnar response layouts via
      `X-Response-Layout`.
paths:
  /v1/utxos/{absolute_index}:
    get:
      tags:
        - utxos
      summary: Single UTXO by absolute index
      description: >
        Returns the UTXO record at the specified global absolute index.


        **Always Protobuf** -- responds with `application/x-protobuf` regardless

        of the `Accept` header.


        The response is a `SingleUtxoResponse` wrapper containing one

        `UtxoDataItem`. The `X-Response-Layout` header has no effect on this

        endpoint (columnar layout is not applicable for single-record
        responses).
      operationId: getUtxoSingle
      parameters:
        - name: absolute_index
          in: path
          required: true
          description: >
            Global absolute index of the UTXO to fetch.

            `absolute_index = tree_index * MAX_LEAVES_PER_TREE +
            insertion_index`.
          schema:
            type: integer
            format: int64
            minimum: 0
          example: 1048620
      responses:
        '200':
          description: UTXO record found.
          content:
            application/x-protobuf:
              schema:
                $ref: '#/components/schemas/SingleUtxoResponse'
        '404':
          description: No UTXO record exists at the given absolute index.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Storage backend error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SingleUtxoResponse:
      type: object
      description: >
        Protobuf `SingleUtxoResponse` message returned by

        `GET /v1/utxos/{absolute_index}`.


        Contains a single `UtxoDataItem` when the requested absolute index
        exists.

        On `404 Not Found` the entire response is an `ErrorResponse` JSON body.
      required:
        - utxo
      properties:
        utxo:
          $ref: '#/components/schemas/UtxoDataItem'
    ErrorResponse:
      type: object
      description: Standard JSON error body returned on 4xx and 5xx responses.
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: |
            Short error category, e.g. `"Bad Request"`, `"Not Found"`,
            `"Too Many Requests"`, `"Internal Server Error"`.
          example: Not Found
        message:
          type: string
          description: Human-readable explanation of what went wrong.
          example: Tree 99 not found
    UtxoDataItem:
      type: object
      description: >
        Protobuf `UtxoDataItem` message -- a single UTXO record as it appears in

        `UtxoResponse.items` and `SingleUtxoResponse.utxo`.


        All binary fields (`final_commitment`, `h1_sender_address`,
        `h1_mint_address`,

        `h1_circuit_provable_hash`, `h1_smart_program_provable_hash`, `h1_hash`,

        `h2_hash`, `aes_encrypted_data`, `depositor_x25519_public_key`) are
        Protobuf

        `bytes` fields carrying the raw little-endian bytes (no base64 or hex
        encoding

        at the wire level).


        The 128-bit integer fields `h1_version` and `h1_commitment_index` are
        encoded

        as Protobuf `bytes` fields containing their **16-byte little-endian**
        binary

        representation.
      required:
        - absolute_index
        - tree_index
        - insertion_index
        - final_commitment
        - h1_version
        - h1_commitment_index
        - h1_sender_address
        - h1_mint_address
        - h1_relayer_fixed_sol_fees
        - h1_year
        - h1_month
        - h1_day
        - h1_hour
        - h1_minute
        - h1_second
        - h1_purpose
        - h1_circuit_provable_hash
        - h1_smart_program_provable_hash
        - h1_hash
        - h2_hash
        - aes_encrypted_data
        - depositor_x25519_public_key
        - timestamp
        - slot
        - event_type
      properties:
        absolute_index:
          type: integer
          format: int64
          description: |
            `tree_index * MAX_LEAVES_PER_TREE + insertion_index`. Monotonically
            increasing pagination cursor. `MAX_LEAVES_PER_TREE = 1,048,576`.
          example: 1048620
        tree_index:
          type: integer
          format: int64
          description: Zero-based Merkle tree index this UTXO belongs to.
          example: 1
        insertion_index:
          type: integer
          format: int64
          description: Zero-based leaf position within `tree_index` (0 to 1,048,575).
          example: 44
        final_commitment:
          type: string
          format: byte
          description: >
            Raw 32-byte `Poseidon(h1_hash, h2_hash)` -- the leaf value inserted
            into

            the Merkle tree (little-endian byte order, Protobuf `bytes`).
        h1_version:
          type: string
          format: byte
          description: >
            16-byte little-endian encoding of the `u128` protocol version used
            as a

            domain separator in the H1 hash circuit (Protobuf `bytes`).
        h1_commitment_index:
          type: string
          format: byte
          description: >
            16-byte little-endian encoding of the `u128` on-chain commitment
            counter

            fed into the H1 circuit (Protobuf `bytes`).
        h1_sender_address:
          type: string
          format: byte
          description: Raw 32-byte sender public key, little-endian (Protobuf `bytes`).
        h1_mint_address:
          type: string
          format: byte
          description: >-
            Raw 32-byte SPL token mint public key, little-endian (Protobuf
            `bytes`).
        h1_relayer_fixed_sol_fees:
          type: integer
          format: int64
          description: Relayer fixed fee in lamports (1 SOL = 1,000,000,000 lamports).
          example: 5000000
        h1_year:
          type: integer
          description: UTC year of the insertion block timestamp.
          example: 2026
        h1_month:
          type: integer
          minimum: 1
          maximum: 12
          description: UTC month (1-12).
          example: 2
        h1_day:
          type: integer
          minimum: 1
          maximum: 31
          description: UTC day (1-31).
          example: 25
        h1_hour:
          type: integer
          minimum: 0
          maximum: 23
          description: UTC hour (0-23).
          example: 12
        h1_minute:
          type: integer
          minimum: 0
          maximum: 59
          description: UTC minute (0-59).
          example: 0
        h1_second:
          type: integer
          minimum: 0
          maximum: 59
          description: UTC second (0-59).
          example: 0
        h1_purpose:
          type: integer
          description: Smart-program-provable domain tag (`u32`).
          example: 1
        h1_circuit_provable_hash:
          type: string
          format: byte
          description: >-
            Raw 32-byte `Poseidon(circuit_provable_inputs)`, little-endian
            (Protobuf `bytes`).
        h1_smart_program_provable_hash:
          type: string
          format: byte
          description: >-
            Raw 32-byte `Poseidon([h1_purpose])`, little-endian (Protobuf
            `bytes`).
        h1_hash:
          type: string
          format: byte
          description: >
            Raw 32-byte `Poseidon([h1_circuit_provable_hash,
            h1_smart_program_provable_hash])`,

            little-endian (Protobuf `bytes`).
        h2_hash:
          type: string
          format: byte
          description: >-
            Raw 32-byte private commitment hash, little-endian (Protobuf
            `bytes`).
        aes_encrypted_data:
          type: string
          format: byte
          description: |
            Raw 96-byte AES-256-GCM encrypted UTXO payload (Protobuf `bytes`):
            - Bytes 0-11: 12-byte random nonce
            - Bytes 12-79: 68-byte ciphertext
            - Bytes 80-95: 16-byte authentication tag
        depositor_x25519_public_key:
          type: string
          format: byte
          description: |
            Raw 32-byte ephemeral X25519 public key. Used to derive the shared
            AES-256-GCM key for decrypting `aes_encrypted_data` via X25519 DH
            with the network's static private key (Protobuf `bytes`).
        timestamp:
          type: integer
          format: int64
          description: Unix block timestamp in seconds (`0` when unavailable).
          example: 1735689600
        slot:
          type: integer
          format: int64
          description: Solana slot number of the confirming block.
          example: 350000000
        event_type:
          type: string
          description: '`"deposit"` or `"callback"` (see `EventType`).'
          example: deposit

````