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

# Solana 프라이버시 링 API

> Solana 프라이버시 링의 암호화된 UTXO, 차폐된 트랜잭션 기록, Merkle 증명, 공개 사용자 레지스트리 레코드를 조회합니다.

Solana 프라이버시 링 API는 프라이버시 인덱서를 조회합니다. 암호화된 상태와 공개 트랜잭션 메타데이터를 반환합니다. 지갑은 페이로드를 복호화하여 비공개 잔액과 기록을 읽습니다. 개념은 [프라이버시 개요](https://www.helius.dev/docs/ko/privacy.md)를, 입금, 전송, 출금 흐름은 [SDK](https://www.helius.dev/docs/ko/privacy/sdk.md)를 참조하세요.

## 공개 잔액과 비공개 잔액

비공개 잔액은 UTXO(미사용 트랜잭션 출력)에 저장됩니다. UTXO는 Solana 계정이 아닙니다.

| | 공개 잔액 | 비공개 잔액 |
| - | - | - |
| 잔액 | Solana 계정의 Lamport 또는 SPL Token 계정의 `amount` | 한 자산에 대한 미사용 UTXO의 합계 |
| 공개 여부 | 온체인에서 공개됨 | 온체인에서 암호화됨 |
| 토큰 계정 또는 출력 검색 | [`getTokenAccountsByOwner`](https://solana.com/docs/rpc/http/gettokenaccountsbyowner)는 주소가 소유한 SPL Token 계정을 반환합니다 | `getEncryptedUtxosByTags`는 보기 태그 또는 링과 일치하는 암호화된 출력을 반환합니다 |
| 잔액 조회 | SOL에는 [`getBalance`](https://solana.com/docs/rpc/http/getbalance), SPL Token 계정에는 [`getTokenAccountBalance`](https://solana.com/docs/rpc/http/gettokenaccountbalance)를 사용합니다 | 지갑이 출력을 복호화하고 미사용 상태인지 확인한 후 자산별 금액을 합산합니다 |

비공개 잔액의 저장 및 사용 방식은 [비공개 상태와 UTXO](https://www.helius.dev/docs/ko/privacy/concepts/utxo.md)를 참조하세요.

## 엔드포인트 및 인증

Helius API 키를 사용하여 메서드 경로로 JSON-RPC 2.0 요청을 보내세요.

```bash theme={"system"}
curl --request POST \
  --url "https://devnet.helius-rpc.com/v1/spr/getUserRecords?api-key=YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "getUserRecords",
    "params": {
      "owners": ["11111111111111111111111111111111"]
    }
  }'
```

`method`는 최종 URL 경로 세그먼트와 일치해야 합니다. 메서드 경로는 단일 요청만 허용합니다. 배치, 중복된 `method` 필드, 경로와 본문의 불일치는 실행 전에 HTTP 400을 반환합니다.

로컬 개발에서는 [로컬 스택](https://www.helius.dev/docs/ko/privacy/endpoints.md)을 시작한 후 `http://127.0.0.1:8784/{method}`를 사용하세요.

## 메서드

> [card] [getEncryptedUtxosByTags](https://www.helius.dev/docs/ko/api-reference/privacy/getencryptedutxosbytags.md)
>
> 보기 태그 또는 링으로 암호화된 출력을 검색합니다.

> [card] [getShieldedTransactionsByTags](https://www.helius.dev/docs/ko/api-reference/privacy/getshieldedtransactionsbytags.md)
>
> 보기 태그 또는 링으로 차폐된 트랜잭션 기록을 조회합니다.

> [card] [getShieldedTransactionsBySignature](https://www.helius.dev/docs/ko/api-reference/privacy/getshieldedtransactionsbysignature.md)
>
> 하나의 Solana 트랜잭션에 대한 차폐된 이벤트를 가져옵니다.

> [card] [getShieldedTransactionsByNullifiers](https://www.helius.dev/docs/ko/api-reference/privacy/getshieldedtransactionsbynullifiers.md)
>
> 제공된 무효화자를 사용한 트랜잭션을 찾습니다.

> [card] [getMerkleProofs](https://www.helius.dev/docs/ko/api-reference/privacy/getmerkleproofs.md)
>
> 상태 트리 커밋먼트의 포함 증명을 가져옵니다.

> [card] [getNonInclusionProofs](https://www.helius.dev/docs/ko/api-reference/privacy/getnoninclusionproofs.md)
>
> 무효화자 값의 비포함 증명을 가져옵니다.

> [card] [getNullifierQueueElements](https://www.helius.dev/docs/ko/api-reference/privacy/getnullifierqueueelements.md)
>
> 대기열에 있는 무효화자를 시퀀스 순서로 읽습니다.

> [card] [getUserRecords](https://www.helius.dev/docs/ko/api-reference/privacy/getuserrecords.md)
>
> 공개 차폐 주소 등록을 조회합니다.

## 페이지네이션

`getEncryptedUtxosByTags`, `getShieldedTransactionsByTags`, `getShieldedTransactionsByNullifiers`는 `result`에 페이지를 반환합니다.

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "context": { "slot": 4242, "blockTime": 1730000000 },
    "data": [],
    "paginationToken": null
  }
}
```

* `data`는 결과를 Solana 트랜잭션별로 그룹화하며 슬롯과 서명의 오름차순으로 정렬합니다. 암호화된 UTXO 메서드는 각 그룹에서 `outputs` 배열을 사용하고, 트랜잭션 기록 메서드는 `events` 배열을 사용합니다.
* `limit`는 Solana 트랜잭션 수를 나타내며 범위는 1\~1,000이고 기본값은 1,000입니다. 한 트랜잭션에서 일치하는 출력 또는 이벤트는 하나의 페이지에 함께 유지됩니다.
* null이 아닌 `paginationToken`를 동일한 태그 또는 무효화자, 링, 슬롯 필터와 함께 변경하지 않고 다시 전달하세요. 응답 토큰이 `null`가 될 때까지 계속하세요.
* `filters.slot`는 `gt`, `gte`, `lt`, `lte` 경계를 허용합니다. 제공된 경계는 AND 조건으로 결합됩니다. 상한이 없는 읽기가 null 토큰에 도달하면 해당 페이지의 `context.slot`를 저장하고, 나중에 `filters.slot.gt`를 해당 값으로 설정하여 재개하세요. `lt` 또는 `lte`로 제한된 읽기는 해당 상한까지의 슬롯만 포함합니다. `context.slot`가 아니라 해당 상한부터 재개하세요.
* 최소 영구 저장 인덱서 슬롯을 요구하려면 `minContextSlot`를 설정하세요. 인덱서는 `paginationToken`의 슬롯과 모든 `gt` 또는 `gte` 필터의 슬롯도 충족해야 합니다. 인덱서가 이 중 하나라도 따라잡지 못한 경우 `error.data.contextSlot`와 함께 오류 `-32016`를 반환합니다. 인덱서가 따라잡은 후 다시 시도하세요.

기록 응답에는 일시 중지되지 않은 최신 상태 트리 ID인 `outputTreeId`가 포함될 수도 있습니다. 사용할 수 없으면 생략됩니다. 개별 출력은 `outputContext.treeId`로 자체 트리를 식별합니다.

`getNullifierQueueElements`는 시퀀스 기반 페이지네이션을 사용합니다. 자세한 내용은 [메서드 페이지](https://www.helius.dev/docs/ko/api-reference/privacy/getnullifierqueueelements.md)를 참조하세요.

## 데이터 인코딩

| 값 | 인코딩 |
| - | - |
| 공개 키, 해시, 커밋먼트, 보기 태그, 무효화자 | 32바이트를 나타내는 Base58 문자열 |
| Solana 트랜잭션 서명 | 64바이트를 나타내는 Base58 문자열 |
| 암호문 페이로드, `txViewingPk`, `salt`, 레지스트리 `viewingPubkey` | Base64 문자열 |
| `context.slot` | 인덱서가 영구 저장한 가장 높은 Solana 슬롯 |
| `context.blockTime` | 초 단위 Unix 타임스탬프로 표시된 블록 시간 |

## 오류

HTTP 상태가 200인 경우를 포함하여 `result`를 읽기 전에 JSON-RPC `error` 필드를 확인하세요.

| 코드 | 의미 |
| - | - |
| `-32600` | 요청 검증에 실패했거나, 레코드를 찾지 못했거나, 인덱싱된 증명 루트가 오래되었거나, 요청한 기록이 인덱싱된 기록보다 앞에서 시작합니다. 읽을 수 없는 요청 본문도 HTTP 400과 함께 `-32600`를 반환합니다. 원인은 `message`에서 확인하세요. |
| `-32601` | 알 수 없는 메서드이거나 메서드 경로가 실행 전에 요청을 거부했습니다. 경로 거부에는 HTTP 400이 사용됩니다. |
| `-32602` | 잘못된 키 인코딩 또는 범위를 벗어난 제한값 등으로 인해 매개변수를 구문 분석할 수 없습니다. |
| `-32603` | 내부 서버 오류입니다. |
| `-32016` | 인덱서가 `minContextSlot`, 페이지네이션 토큰의 슬롯 또는 `gt`/`gte` 슬롯 필터에 도달하지 못했습니다. |

HTTP 429는 요청 속도 제한을 나타냅니다. [요청 속도 제한](https://www.helius.dev/docs/ko/billing/rate-limits.md)을 참조하세요. API 키 설정은 [인증](https://www.helius.dev/docs/ko/api-reference/authentication.md)을 참조하세요.


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