> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# getEncryptedUtxosByTags

> Retrieve encrypted UTXO outputs matching view tags or a specific ring.

## Encrypted Outputs

Use this method to get encrypted UTXOs for client-side decryption. Your wallet decrypts the outputs and sums the unspent amounts for each asset to determine its private balance.

This compares to Solana’s [`getTokenAccountsByOwner`](https://solana.com/docs/rpc/http/gettokenaccountsbyowner), which returns SPL Token accounts owned by an address. A private balance is stored in UTXOs, not Solana accounts, wherefore it requires a dedicated RPC method. Learn more about [Private State and UTXOs](https://www.helius.dev/docs/privacy/concepts/utxo.md).

The method returns matching outputs in `result.data`, grouped by Solana transaction. Each entry includes the transaction’s `slot` and `signature`. An output includes its ciphertext, view tag, commitment, tree ID, and leaf index.

The response includes historical outputs that may already have been spent. Your wallet must track nullifiers to determine its spendable balance. See the [private balance guide](https://www.helius.dev/docs/privacy/guides/read-balance.md).

An empty `tags` array requires `ringProgramId` and selects outputs from that ring. When both are supplied, outputs must match the tags and the ring.

See [pagination and freshness](https://www.helius.dev/docs/api-reference/privacy.md#pagination) for page limits, continuation tokens, and incremental reads.

## Request Parameters

**filters** `object`

Slot bounds. Resume a caught-up, uncapped read with `slot.gt` set to the last page's `context.slot`.

**filters.slot** `object`

Slot bounds for the read. Supplied bounds combine with AND.

**filters.slot.gt** `number`

Only include transactions after this slot.

**filters.slot.gte** `number`

Only include transactions at or after this slot.

**filters.slot.lt** `number`

Only include transactions before this slot.

**filters.slot.lte** `number`

Only include transactions at or before this slot.

**limit** `number` (default: 1000)

Maximum number of Solana transactions per page, from 1 to 1,000.

**minContextSlot** `number`

Minimum persisted indexer slot required for this read. Returns JSON-RPC error -32016 if the indexer is behind.

**paginationToken** `string`

Continuation token from the previous response. Pass it back unchanged with the same tags, ring, and slot filters.

**ringProgramId** `string`

Restrict results to the ring authorized by this program ID. Required when tags is empty.

**tags** `array` *required*

Base58-encoded 32-byte view tags. At most 1,000. An empty array requires ringProgramId and selects that ring.


## OpenAPI

````yaml openapi/privacy/getEncryptedUtxosByTags.yaml POST /v1/spr/getEncryptedUtxosByTags
openapi: 3.0.3
info:
  title: Solana Privacy Rings API
  version: 0.51.2
  description: >-
    Privacy indexer JSON-RPC API for encrypted state, history, proofs, and
    public registry records.
servers:
  - url: https://devnet.helius-rpc.com
    description: Devnet Solana Privacy Rings API
security: []
paths:
  /v1/spr/getEncryptedUtxosByTags:
    post:
      summary: getEncryptedUtxosByTags
      description: Retrieve encrypted UTXO outputs matching view tags or a specific ring.
      operationId: getEncryptedUtxosByTags
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - jsonrpc
                - id
                - method
                - params
              properties:
                id:
                  type: string
                  description: An ID to identify the request.
                  default: '1'
                jsonrpc:
                  type: string
                  description: The JSON-RPC protocol version.
                  enum:
                    - '2.0'
                  default: '2.0'
                method:
                  type: string
                  description: The method to invoke. Must match the final URL path segment.
                  enum:
                    - getEncryptedUtxosByTags
                  default: getEncryptedUtxosByTags
                params:
                  type: object
                  required:
                    - tags
                  properties:
                    filters:
                      allOf:
                        - $ref: '#/components/schemas/HistoryFilters'
                      description: >-
                        Slot bounds. Resume a caught-up, uncapped read with
                        `slot.gt` set to the last page's `context.slot`.
                    limit:
                      type: integer
                      format: uint64
                      maximum: 1000
                      minimum: 1
                      nullable: true
                      default: 1000
                      description: >-
                        Maximum number of Solana transactions per page, from 1
                        to 1,000.
                    minContextSlot:
                      type: integer
                      format: uint64
                      minimum: 0
                      nullable: true
                      description: >-
                        Minimum persisted indexer slot required for this read.
                        Returns JSON-RPC error -32016 if the indexer is behind.
                    paginationToken:
                      type: string
                      description: >-
                        Continuation token from the previous response. Pass it
                        back unchanged with the same tags, ring, and slot
                        filters.
                      nullable: true
                    ringProgramId:
                      type: string
                      description: >-
                        Restrict results to the ring authorized by this program
                        ID. Required when tags is empty.
                      nullable: true
                    tags:
                      type: array
                      items:
                        $ref: '#/components/schemas/Hash'
                      description: >-
                        Base58-encoded 32-byte view tags. At most 1,000. An
                        empty array requires ringProgramId and selects that
                        ring.
                      maxItems: 1000
                  additionalProperties: false
                  example:
                    tags:
                      - '11111111111111111111111111111112'
                    limit: 100
            example:
              jsonrpc: '2.0'
              id: '1'
              method: getEncryptedUtxosByTags
              params:
                tags:
                  - '11111111111111111111111111111112'
                limit: 100
        required: true
      responses:
        '200':
          description: JSON-RPC response. Inspect error before reading result.
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonrpc
                  - id
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                      data:
                        type: object
                        additionalProperties: true
                  id:
                    type: string
                    description: The request ID.
                  jsonrpc:
                    type: string
                    description: The version of the JSON-RPC protocol.
                    enum:
                      - '2.0'
                  result:
                    type: object
                    description: >-
                      One bounded page of a history read, in gTFA-style
                      pagination.
                    required:
                      - context
                      - data
                      - paginationToken
                    properties:
                      context:
                        $ref: '#/components/schemas/Context'
                      data:
                        type: array
                        items:
                          type: object
                          description: All matching outputs of one Solana transaction.
                          required:
                            - slot
                            - signature
                            - outputs
                          properties:
                            outputs:
                              type: array
                              items:
                                $ref: '#/components/schemas/EncryptedUtxoMatch'
                            signature:
                              $ref: '#/components/schemas/SerializableSignature'
                            slot:
                              type: integer
                              format: uint64
                              minimum: 0
                          additionalProperties: false
                      outputTreeId:
                        type: integer
                        format: uint16
                        description: >-
                          The newest unpaused state tree ID. Omitted when
                          unavailable.
                        minimum: 0
                      paginationToken:
                        type: string
                        description: >-
                          Token for the next page, null when no more results
                          match. A caught-up

                          read without an `lt` or `lte` bound resumes later with
                          `filters.slot.gt`

                          set to this page's `context.slot`; a capped read
                          covers only slots up to

                          its cap.
                        nullable: true
              example:
                jsonrpc: '2.0'
                id: '1'
                result:
                  context:
                    slot: 4242
                    blockTime: 1730000000
                  data: []
                  paginationToken: null
        '400':
          description: >-
            Rejected before execution. A method/path mismatch, duplicate method
            fields, or a batch request returns -32601. An unreadable or
            oversized body returns -32600.
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonrpc
                  - id
                  - error
                properties:
                  jsonrpc:
                    type: string
                    enum:
                      - '2.0'
                  id:
                    type: string
                    nullable: true
                    description: >-
                      The request id, or null when the body is not a single
                      JSON-RPC call.
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                      data:
                        type: object
                        additionalProperties: true
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonrpc
                  - id
                  - error
                properties:
                  jsonrpc:
                    type: string
                    enum:
                      - '2.0'
                  id:
                    type: string
                    nullable: true
                    description: >-
                      The request id, or null when the body is not a single
                      JSON-RPC call.
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                      data:
                        type: object
                        additionalProperties: true
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonrpc
                  - id
                  - error
                properties:
                  jsonrpc:
                    type: string
                    enum:
                      - '2.0'
                  id:
                    type: string
                    nullable: true
                    description: >-
                      The request id, or null when the body is not a single
                      JSON-RPC call.
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                      data:
                        type: object
                        additionalProperties: true
      security:
        - ApiKeyQuery: []
components:
  schemas:
    HistoryFilters:
      type: object
      description: Optional slot bounds for the history query.
      properties:
        slot:
          $ref: '#/components/schemas/SlotFilter'
      additionalProperties: false
    Hash:
      type: string
      description: A base58-encoded 32-byte hash.
    Context:
      type: object
      required:
        - blockTime
        - slot
      properties:
        blockTime:
          type: integer
          format: int64
        slot:
          type: integer
          format: uint64
          description: >-
            Highest slot the indexer has persisted, for slot-based freshness
            checks.
          minimum: 0
    EncryptedUtxoMatch:
      type: object
      required:
        - slot
        - txSignature
        - txViewingPk
        - salt
        - outputSlot
      properties:
        outputSlot:
          $ref: '#/components/schemas/RingsOutputSlot'
        salt:
          type: string
          description: Transaction-level AES salt shared by every output ciphertext.
          nullable: true
        slot:
          type: integer
          format: uint64
          minimum: 0
        txSignature:
          $ref: '#/components/schemas/SerializableSignature'
        txViewingPk:
          type: string
          description: A base64-encoded byte string.
          nullable: true
    SerializableSignature:
      type: string
      description: A base58-encoded 64-byte Solana transaction signature.
    SlotFilter:
      type: object
      description: Slot bounds for the read. Supplied bounds combine with AND.
      properties:
        gt:
          type: integer
          format: uint64
          minimum: 0
          nullable: true
          description: Only include transactions after this slot.
        gte:
          type: integer
          format: uint64
          minimum: 0
          nullable: true
          description: Only include transactions at or after this slot.
        lt:
          type: integer
          format: uint64
          minimum: 0
          nullable: true
          description: Only include transactions before this slot.
        lte:
          type: integer
          format: uint64
          minimum: 0
          nullable: true
          description: Only include transactions at or before this slot.
      additionalProperties: false
    RingsOutputSlot:
      type: object
      required:
        - viewTag
        - outputContext
        - payload
      properties:
        outputContext:
          $ref: '#/components/schemas/RingsOutputContext'
        payload:
          $ref: '#/components/schemas/Base64String'
        viewTag:
          $ref: '#/components/schemas/Hash'
    RingsOutputContext:
      type: object
      required:
        - hash
        - tree
        - treeId
        - leafIndex
      properties:
        hash:
          $ref: '#/components/schemas/Hash'
        leafIndex:
          type: integer
          format: uint64
          minimum: 0
        tree:
          allOf:
            - $ref: '#/components/schemas/SerializablePubkey'
          description: >-
            State tree account. Prefer treeId; the tree account is derived from
            it.
          deprecated: true
        treeId:
          type: integer
          format: uint16
          description: The raw tree id the output's commitment is hashed under.
          minimum: 0
    Base64String:
      type: string
      description: A base64-encoded byte string.
    SerializablePubkey:
      type: string
      description: A base58-encoded Solana public key.
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api-key
      description: Your Helius API key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.