> ## 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를 가져옵니다. 지갑은 출력을 복호화하고 각 자산의 미사용 금액을 합산하여 비공개 잔액을 확인합니다.

이 메서드는 주소가 소유한 SPL Token 계정을 반환하는 Solana의 [`getTokenAccountsByOwner`](https://solana.com/docs/rpc/http/gettokenaccountsbyowner)에 대응합니다. 비공개 잔액은 Solana 계정이 아닌 UTXO에 저장되므로 전용 RPC 메서드가 필요합니다. 자세한 내용은 [비공개 상태 및 UTXO](https://www.helius.dev/docs/ko/privacy/concepts/utxo.md)를 참조하세요.

이 메서드는 일치하는 출력을 `result.data`에 Solana 트랜잭션별로 그룹화하여 반환합니다. 각 항목에는 트랜잭션의 `slot` 및 `signature`가 포함됩니다. 출력에는 암호문, 뷰 태그, 커밋먼트, 트리 ID, 리프 인덱스가 포함됩니다.

응답에는 이미 사용되었을 수 있는 과거 출력도 포함됩니다. 지갑은 사용 가능한 잔액을 확인하기 위해 널리파이어를 추적해야 합니다. [비공개 잔액 가이드](https://www.helius.dev/docs/ko/privacy/guides/read-balance.md)를 참조하세요.

빈 `tags` 배열을 사용하려면 `ringProgramId`가 필요하며, 해당 링의 출력을 선택합니다. 둘 다 제공하면 출력은 태그와 링에 모두 일치해야 합니다.

페이지 제한, 연속 토큰 및 증분 읽기에 관한 내용은 [페이지네이션 및 최신성](https://www.helius.dev/docs/ko/api-reference/privacy.md#페이지네이션)을 참조하세요.

## 요청 매개변수

**filters** `object`

슬롯 범위입니다. 범위 제한 없이 최신 상태까지 읽은 작업을 재개하려면 `slot.gt`를 마지막 페이지의 `context.slot`로 설정하세요.

**filters.slot** `object`

읽기에 적용할 슬롯 범위입니다. 제공된 범위 조건은 AND로 결합됩니다.

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

이 슬롯 이후의 트랜잭션만 포함합니다.

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

이 슬롯 또는 그 이후의 트랜잭션만 포함합니다.

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

이 슬롯 이전의 트랜잭션만 포함합니다.

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

이 슬롯 또는 그 이전의 트랜잭션만 포함합니다.

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

페이지당 Solana 트랜잭션의 최대 개수입니다. 1\~1,000개를 지정할 수 있습니다.

**minContextSlot** `number`

이 읽기에 필요한 인덱서의 최소 영구 저장 슬롯입니다. 인덱서가 이 슬롯에 도달하지 못한 경우 JSON-RPC 오류 -32016을 반환합니다.

**paginationToken** `string`

이전 응답의 연속 토큰입니다. 동일한 태그, 링 및 슬롯 필터와 함께 변경하지 않고 다시 전달하세요.

**ringProgramId** `string`

이 프로그램 ID가 승인한 링으로 결과를 제한합니다. tags가 비어 있으면 필수입니다.

**tags** `array` *required*

Base58로 인코딩된 32바이트 뷰 태그입니다. 최대 1,000개까지 지정할 수 있습니다. 빈 배열을 사용하려면 ringProgramId가 필요하며, 해당 링을 선택합니다.


## OpenAPI

````yaml ko/openapi/privacy/getEncryptedUtxosByTags.yaml POST /v1/spr/getEncryptedUtxosByTags
openapi: 3.0.3
info:
  title: Solana Privacy Rings API
  version: 0.51.2
  description: 암호화된 상태, 기록, 증명 및 공개 레지스트리 레코드를 위한 개인정보 보호 인덱서 JSON-RPC API입니다.
servers:
  - url: https://devnet.helius-rpc.com
    description: Devnet Solana Privacy Rings 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가 승인한 링으로 제한합니다. tags가 비어 있으면 필수입니다.
                      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`
                          경계가 없는 따라잡기 완료 읽기는 이 페이지의 `context.slot`을
                          `filters.slot.gt`로 설정하여 나중에 재개합니다. 상한이 있는 읽기는 해당 상한까지의
                          슬롯만 포함합니다.
                        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를 사용하는 것이 좋습니다. 트리 계정은 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.