> ## 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 Privacy Rings API

> Solana Privacy Ringsの暗号化されたUTXO、シールドトランザクション履歴、Merkle証明、公開ユーザーレジストリレコードを照会します。

Solana Privacy Rings APIは、プライバシーインデクサーにクエリを送信します。暗号化状態と公開トランザクションメタデータを返します。ウォレットはペイロードを復号し、非公開の残高と履歴を読み取ります。概念については[プライバシーの概要](https://www.helius.dev/docs/ja/privacy.md)を、入金、送金、出金のフローについては[SDK](https://www.helius.dev/docs/ja/privacy/sdk.md)を参照してください。

## 公開残高と非公開残高

非公開残高はUTXO（未使用トランザクション出力）に保存されます。UTXOはSolanaアカウントではありません。

| | 公開残高 | 非公開残高 |
| - | - | - |
| 残高 | Solanaアカウント内のLamport、またはSPL Tokenアカウント内の`amount` | 1つの資産に対する未使用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/ja/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/ja/privacy/endpoints.md)を起動した後に`http://127.0.0.1:8784/{method}`を使用してください。

## メソッド

> [card] [getEncryptedUtxosByTags](https://www.helius.dev/docs/ja/api-reference/privacy/getencryptedutxosbytags.md)
>
> ビュータグまたはリングを使用して暗号化出力を検出します。

> [card] [getShieldedTransactionsByTags](https://www.helius.dev/docs/ja/api-reference/privacy/getshieldedtransactionsbytags.md)
>
> ビュータグまたはリングを使用してシールドトランザクション履歴を照会します。

> [card] [getShieldedTransactionsBySignature](https://www.helius.dev/docs/ja/api-reference/privacy/getshieldedtransactionsbysignature.md)
>
> 1つのSolanaトランザクションのシールドイベントを取得します。

> [card] [getShieldedTransactionsByNullifiers](https://www.helius.dev/docs/ja/api-reference/privacy/getshieldedtransactionsbynullifiers.md)
>
> 指定したNullifierを使用したトランザクションを検索します。

> [card] [getMerkleProofs](https://www.helius.dev/docs/ja/api-reference/privacy/getmerkleproofs.md)
>
> 状態ツリーのコミットメントに対する包含証明を取得します。

> [card] [getNonInclusionProofs](https://www.helius.dev/docs/ja/api-reference/privacy/getnoninclusionproofs.md)
>
> Nullifier値に対する非包含証明を取得します。

> [card] [getNullifierQueueElements](https://www.helius.dev/docs/ja/api-reference/privacy/getnullifierqueueelements.md)
>
> キューに入っているNullifierをシーケンス順に読み取ります。

> [card] [getUserRecords](https://www.helius.dev/docs/ja/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です。1つのトランザクションに一致する出力またはイベントは、同じページにまとめられます。
* nullではない`paginationToken`を、同じタグまたはNullifier、リング、スロットフィルターとともに変更せずに再度渡します。レスポンストークンが`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/ja/api-reference/privacy/getnullifierqueueelements.md)を参照してください。

## データエンコーディング

| 値 | エンコーディング |
| - | - |
| 公開鍵、ハッシュ、コミットメント、ビュータグ、Nullifier | 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/ja/billing/rate-limits.md)を参照してください。APIキーの設定については、[認証](https://www.helius.dev/docs/ja/api-reference/authentication.md)を参照してください。


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