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

> 检索与查看标签或特定环匹配的加密 UTXO 输出。

## 加密输出

使用此方法获取加密 UTXO，以便在客户端解密。你的钱包会解密这些输出，并汇总每种资产的未花费金额，以确定其隐私余额。

这类似于 Solana 的 [`getTokenAccountsByOwner`](https://solana.com/docs/rpc/http/gettokenaccountsbyowner)，后者返回某个地址拥有的 SPL 代币账户。隐私余额存储在 UTXO 中，而不是 Solana 账户中，因此需要专用的 RPC 方法。详细了解[隐私状态和 UTXO](https://www.helius.dev/docs/zh/privacy/concepts/utxo.md)。

此方法在 `result.data` 中返回匹配的输出，并按 Solana 交易分组。每个条目都包含交易的 `slot` 和 `signature`。输出包含其密文、查看标签、承诺、树 ID 和叶索引。

响应包含可能已被花费的历史输出。你的钱包必须跟踪作废标识符，以确定其可花费余额。请参阅[隐私余额指南](https://www.helius.dev/docs/zh/privacy/guides/read-balance.md)。

空的 `tags` 数组需要提供 `ringProgramId`，并选择该环中的输出。同时提供两者时，输出必须同时匹配标签和环。

有关页面限制、续传代币和增量读取的信息，请参阅[分页和新鲜度](https://www.helius.dev/docs/zh/api-reference/privacy.md#分页)。

## 请求参数

**filters** `object`

Slot 范围。要恢复已追赶至最新状态且无上限的读取，请将 `slot.gt` 设置为最后一页的 `context.slot`。

**filters.slot** `object`

读取的 Slot 范围。提供的范围条件使用 AND 组合。

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

仅包含此 Slot 之后的交易。

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

仅包含此 Slot 或之后的交易。

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

仅包含此 Slot 之前的交易。

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

仅包含此 Slot 或之前的交易。

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

每页最多包含的 Solana 交易数，取值范围为 1 到 1,000。

**minContextSlot** `number`

此次读取所需的索引器最小持久化 Slot。如果索引器落后，则返回 JSON-RPC 错误 -32016。

**paginationToken** `string`

上一个响应中的续传代币。使用相同的标签、环和 Slot 过滤条件，将其原样传回。

**ringProgramId** `string`

将结果限制为由此程序 ID 授权的环。当 tags 为空时，此参数为必填项。

**tags** `array` *required*

经过 Base58 编码的 32 字节查看标签，最多可提供 1,000 个。空数组需要提供 ringProgramId，并选择该环。


## OpenAPI

````yaml zh/openapi/privacy/getEncryptedUtxosByTags.yaml POST /v1/spr/getEncryptedUtxosByTags
openapi: 3.0.3
info:
  title: Solana 隐私环 API
  version: 0.51.2
  description: 用于加密状态、历史记录、证明和公共注册表记录的隐私索引器 JSON-RPC API。
servers:
  - url: https://devnet.helius-rpc.com
    description: 开发网 Solana 隐私环 API
security: []
paths:
  /v1/spr/getEncryptedUtxosByTags:
    post:
      summary: getEncryptedUtxosByTags
      description: 检索与查看标签或特定环匹配的加密 UTXO 输出。
      operationId: getEncryptedUtxosByTags
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - jsonrpc
                - id
                - method
                - params
              properties:
                id:
                  type: string
                  description: 用于标识请求的 ID。
                  default: '1'
                jsonrpc:
                  type: string
                  description: JSON-RPC 协议版本。
                  enum:
                    - '2.0'
                  default: '2.0'
                method:
                  type: string
                  description: 要调用的方法。必须与 URL 的最后一个路径段匹配。
                  enum:
                    - getEncryptedUtxosByTags
                  default: getEncryptedUtxosByTags
                params:
                  type: object
                  required:
                    - tags
                  properties:
                    filters:
                      allOf:
                        - $ref: '#/components/schemas/HistoryFilters'
                      description: >-
                        槽位边界。若要恢复已追上进度且未设置上限的读取，请将 `slot.gt` 设置为上一页的
                        `context.slot`。
                    limit:
                      type: integer
                      format: uint64
                      maximum: 1000
                      minimum: 1
                      nullable: true
                      default: 1000
                      description: 每页最多包含的 Solana 交易数，范围为 1 到 1,000。
                    minContextSlot:
                      type: integer
                      format: uint64
                      minimum: 0
                      nullable: true
                      description: 此次读取所需的最小已持久化索引器槽位。如果索引器落后，则返回 JSON-RPC 错误 -32016。
                    paginationToken:
                      type: string
                      description: 上一响应中的续传令牌。请将其原样传回，并使用相同的标签、环和槽位过滤器。
                      nullable: true
                    ringProgramId:
                      type: string
                      description: 将结果限制为由此程序 ID 授权的环。标签为空时必填。
                      nullable: true
                    tags:
                      type: array
                      items:
                        $ref: '#/components/schemas/Hash'
                      description: >-
                        以 Base58 编码的 32 字节查看标签。最多 1,000 个。空数组需要提供
                        ringProgramId，并选择对应的环。
                      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 响应。读取结果前请先检查错误。
          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: 请求 ID。
                  jsonrpc:
                    type: string
                    description: JSON-RPC 协议的版本。
                    enum:
                      - '2.0'
                  result:
                    type: object
                    description: 采用 gTFA 风格分页的单个有界历史读取页面。
                    required:
                      - context
                      - data
                      - paginationToken
                    properties:
                      context:
                        $ref: '#/components/schemas/Context'
                      data:
                        type: array
                        items:
                          type: object
                          description: 一笔 Solana 交易的所有匹配输出。
                          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: 最新的未暂停状态树 ID。不可用时省略。
                        minimum: 0
                      paginationToken:
                        type: string
                        description: |-
                          下一页的令牌；没有更多匹配结果时为 null。对于未设置 `lt` 或 `lte` 边界且已追上进度的
                          读取，稍后恢复时应将 `filters.slot.gt` 设置为本页的 `context.slot`；
                          设置了上限的读取仅涵盖不超过
                          该上限的槽位。
                        nullable: true
              example:
                jsonrpc: '2.0'
                id: '1'
                result:
                  context:
                    slot: 4242
                    blockTime: 1730000000
                  data: []
                  paginationToken: null
        '400':
          description: 执行前被拒绝。方法与路径不匹配、方法字段重复或批量请求会返回 -32601。无法读取或过大的请求正文会返回 -32600。
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonrpc
                  - id
                  - error
                properties:
                  jsonrpc:
                    type: string
                    enum:
                      - '2.0'
                  id:
                    type: string
                    nullable: true
                    description: 请求 ID；当正文不是单个 JSON-RPC 调用时为 null。
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                      data:
                        type: object
                        additionalProperties: true
        '429':
          description: 超出速率限制。
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonrpc
                  - id
                  - error
                properties:
                  jsonrpc:
                    type: string
                    enum:
                      - '2.0'
                  id:
                    type: string
                    nullable: true
                    description: 请求 ID；当正文不是单个 JSON-RPC 调用时为 null。
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                      data:
                        type: object
                        additionalProperties: true
        '500':
          description: 内部服务器错误。
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonrpc
                  - id
                  - error
                properties:
                  jsonrpc:
                    type: string
                    enum:
                      - '2.0'
                  id:
                    type: string
                    nullable: true
                    description: 请求 ID；当正文不是单个 JSON-RPC 调用时为 null。
                  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: 历史查询的可选槽位边界。
      properties:
        slot:
          $ref: '#/components/schemas/SlotFilter'
      additionalProperties: false
    Hash:
      type: string
      description: 以 Base58 编码的 32 字节哈希。
    Context:
      type: object
      required:
        - blockTime
        - slot
      properties:
        blockTime:
          type: integer
          format: int64
        slot:
          type: integer
          format: uint64
          description: 索引器已持久化的最高槽位，用于基于槽位的新鲜度检查。
          minimum: 0
    EncryptedUtxoMatch:
      type: object
      required:
        - slot
        - txSignature
        - txViewingPk
        - salt
        - outputSlot
      properties:
        outputSlot:
          $ref: '#/components/schemas/RingsOutputSlot'
        salt:
          type: string
          description: 由每个输出密文共享的交易级 AES 盐值。
          nullable: true
        slot:
          type: integer
          format: uint64
          minimum: 0
        txSignature:
          $ref: '#/components/schemas/SerializableSignature'
        txViewingPk:
          type: string
          description: 以 Base64 编码的字节字符串。
          nullable: true
    SerializableSignature:
      type: string
      description: 以 Base58 编码的 64 字节 Solana 交易签名。
    SlotFilter:
      type: object
      description: 读取的槽位边界。提供的边界使用 AND 组合。
      properties:
        gt:
          type: integer
          format: uint64
          minimum: 0
          nullable: true
          description: 仅包含此槽位之后的交易。
        gte:
          type: integer
          format: uint64
          minimum: 0
          nullable: true
          description: 仅包含此槽位或之后的交易。
        lt:
          type: integer
          format: uint64
          minimum: 0
          nullable: true
          description: 仅包含此槽位之前的交易。
        lte:
          type: integer
          format: uint64
          minimum: 0
          nullable: true
          description: 仅包含此槽位或之前的交易。
      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: 状态树账户。优先使用 treeId；树账户由其派生。
          deprecated: true
        treeId:
          type: integer
          format: uint16
          description: 输出承诺在其下进行哈希计算的原始树 ID。
          minimum: 0
    Base64String:
      type: string
      description: 以 Base64 编码的字节字符串。
    SerializablePubkey:
      type: string
      description: 以 Base58 编码的 Solana 公钥。
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api-key
      description: 你的 Helius API 密钥。

````

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