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

# API Vòng riêng tư Solana

> Truy vấn UTXO được mã hóa, lịch sử giao dịch được bảo vệ, bằng chứng Merkle và bản ghi đăng ký người dùng công khai cho Vòng riêng tư Solana.

API Vòng riêng tư Solana truy vấn bộ lập chỉ mục quyền riêng tư. API này trả về trạng thái được mã hóa và siêu dữ liệu giao dịch công khai. Ví của bạn giải mã các tải trọng để đọc số dư riêng tư và lịch sử. Xem [tổng quan về quyền riêng tư](https://www.helius.dev/docs/vi/privacy.md) để tìm hiểu các khái niệm và [SDK](https://www.helius.dev/docs/vi/privacy/sdk.md) để biết các quy trình nạp, chuyển và rút tiền.

## Số dư công khai và riêng tư

Số dư riêng tư được lưu trữ trong các UTXO (đầu ra giao dịch chưa chi tiêu). UTXO không phải là tài khoản Solana.

| | Số dư công khai | Số dư riêng tư |
| - | - | - |
| Số dư | Lamport trong tài khoản Solana hoặc `amount` trong tài khoản SPL Token | Tổng các UTXO chưa chi tiêu của một tài sản |
| Khả năng hiển thị | Công khai trên chuỗi | Được mã hóa trên chuỗi |
| Tìm tài khoản token hoặc đầu ra | [`getTokenAccountsByOwner`](https://solana.com/docs/rpc/http/gettokenaccountsbyowner) trả về các tài khoản SPL Token thuộc sở hữu của một địa chỉ | `getEncryptedUtxosByTags` trả về các đầu ra được mã hóa khớp với thẻ xem hoặc một vòng |
| Đọc số dư | [`getBalance`](https://solana.com/docs/rpc/http/getbalance) cho SOL; [`getTokenAccountBalance`](https://solana.com/docs/rpc/http/gettokenaccountbalance) cho tài khoản SPL Token | Ví của bạn giải mã các đầu ra, kiểm tra đầu ra nào chưa được chi tiêu và cộng tổng số lượng cho từng tài sản |

Xem [Trạng thái riêng tư và UTXO](https://www.helius.dev/docs/vi/privacy/concepts/utxo.md) để tìm hiểu cách lưu trữ và chi tiêu số dư riêng tư.

## Điểm cuối và xác thực

Gửi yêu cầu JSON-RPC 2.0 đến đường dẫn của phương thức bằng khóa API Helius của bạn:

```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` phải khớp với phân đoạn đường dẫn cuối cùng của URL. Đường dẫn phương thức chấp nhận một yêu cầu duy nhất; các yêu cầu theo lô, trường `method` trùng lặp và trường hợp đường dẫn/nội dung không khớp sẽ trả về HTTP 400 trước khi thực thi.

Để phát triển cục bộ, hãy sử dụng `http://127.0.0.1:8784/{method}` sau khi khởi động [ngăn xếp cục bộ](https://www.helius.dev/docs/vi/privacy/endpoints.md).

## Phương thức

> [card] [getEncryptedUtxosByTags](https://www.helius.dev/docs/vi/api-reference/privacy/getencryptedutxosbytags.md)
>
> Tìm các đầu ra được mã hóa theo thẻ xem hoặc vòng.

> [card] [getShieldedTransactionsByTags](https://www.helius.dev/docs/vi/api-reference/privacy/getshieldedtransactionsbytags.md)
>
> Truy vấn lịch sử giao dịch được bảo vệ theo thẻ xem hoặc vòng.

> [card] [getShieldedTransactionsBySignature](https://www.helius.dev/docs/vi/api-reference/privacy/getshieldedtransactionsbysignature.md)
>
> Truy xuất các sự kiện được bảo vệ cho một giao dịch Solana.

> [card] [getShieldedTransactionsByNullifiers](https://www.helius.dev/docs/vi/api-reference/privacy/getshieldedtransactionsbynullifiers.md)
>
> Tìm các giao dịch đã chi tiêu những giá trị vô hiệu hóa được cung cấp.

> [card] [getMerkleProofs](https://www.helius.dev/docs/vi/api-reference/privacy/getmerkleproofs.md)
>
> Tìm nạp bằng chứng bao hàm cho các cam kết cây trạng thái.

> [card] [getNonInclusionProofs](https://www.helius.dev/docs/vi/api-reference/privacy/getnoninclusionproofs.md)
>
> Tìm nạp bằng chứng không bao hàm cho các giá trị vô hiệu hóa.

> [card] [getNullifierQueueElements](https://www.helius.dev/docs/vi/api-reference/privacy/getnullifierqueueelements.md)
>
> Đọc các giá trị vô hiệu hóa trong hàng đợi theo thứ tự tuần tự.

> [card] [getUserRecords](https://www.helius.dev/docs/vi/api-reference/privacy/getuserrecords.md)
>
> Tra cứu các đăng ký địa chỉ được bảo vệ công khai.

## Phân trang

`getEncryptedUtxosByTags`, `getShieldedTransactionsByTags` và `getShieldedTransactionsByNullifiers` trả về một trang trong `result`:

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

* `data` nhóm kết quả theo giao dịch Solana, được sắp xếp theo slot và chữ ký tăng dần. Phương thức UTXO được mã hóa sử dụng một mảng `outputs` trong mỗi nhóm; các phương thức lịch sử giao dịch sử dụng một mảng `events`.
* `limit` đếm số giao dịch Solana, từ 1 đến 1.000 và mặc định là 1.000. Các đầu ra hoặc sự kiện khớp của một giao dịch được giữ cùng nhau trên một trang.
* Truyền lại nguyên trạng một `paginationToken` khác null với cùng thẻ hoặc giá trị vô hiệu hóa, vòng và bộ lọc slot. Tiếp tục cho đến khi token phản hồi là `null`.
* `filters.slot` chấp nhận các giới hạn `gt`, `gte`, `lt` và `lte`. Các giới hạn được cung cấp được kết hợp bằng AND. Sau khi một lần đọc không giới hạn đạt đến token null, hãy lưu `context.slot` của trang đó và tiếp tục sau bằng cách đặt `filters.slot.gt` thành giá trị này. Một lần đọc bị giới hạn bởi `lt` hoặc `lte` chỉ bao phủ các slot đến giới hạn đó; hãy tiếp tục từ giới hạn, không phải từ `context.slot`.
* Đặt `minContextSlot` để yêu cầu slot tối thiểu đã được lưu bền vững của bộ lập chỉ mục. Bộ lập chỉ mục cũng yêu cầu slot của `paginationToken` và của mọi bộ lọc `gt` hoặc `gte`. Nếu chưa bắt kịp bất kỳ slot nào trong số này, bộ lập chỉ mục trả về lỗi `-32016` cùng với `error.data.contextSlot`; hãy thử lại sau khi bộ lập chỉ mục bắt kịp.

Phản hồi lịch sử cũng có thể bao gồm `outputTreeId`, ID cây trạng thái mới nhất không bị tạm dừng. Trường này bị bỏ qua khi không khả dụng. Mỗi đầu ra xác định cây riêng của mình bằng `outputContext.treeId`.

`getNullifierQueueElements` sử dụng phân trang dựa trên trình tự; xem [trang phương thức](https://www.helius.dev/docs/vi/api-reference/privacy/getnullifierqueueelements.md) tương ứng.

## Mã hóa dữ liệu

| Giá trị | Kiểu mã hóa |
| - | - |
| Khóa công khai, hàm băm, cam kết, thẻ xem, giá trị vô hiệu hóa | Chuỗi Base58 biểu diễn 32 byte |
| Chữ ký giao dịch Solana | Chuỗi Base58 biểu diễn 64 byte |
| Tải trọng bản mã, `txViewingPk`, `salt`, `viewingPubkey` của sổ đăng ký | Chuỗi Base64 |
| `context.slot` | Slot Solana cao nhất được bộ lập chỉ mục lưu bền vững |
| `context.blockTime` | Thời gian khối dưới dạng dấu thời gian Unix tính bằng giây |

## Lỗi

Kiểm tra trường `error` của JSON-RPC trước khi đọc `result`, kể cả khi trạng thái HTTP là 200.

| Mã | Ý nghĩa |
| - | - |
| `-32600` | Xác thực yêu cầu không thành công, không tìm thấy bản ghi, gốc bằng chứng đã lập chỉ mục đã lỗi thời hoặc lịch sử được yêu cầu bắt đầu trước lịch sử đã lập chỉ mục. Nội dung yêu cầu không thể đọc cũng trả về `-32600` với HTTP 400. Đọc `message` để biết nguyên nhân. |
| `-32601` | Phương thức không xác định hoặc đường dẫn phương thức đã từ chối yêu cầu trước khi thực thi. Trường hợp bị từ chối do đường dẫn sử dụng HTTP 400. |
| `-32602` | Không thể phân tích cú pháp tham số, chẳng hạn như kiểu mã hóa khóa không hợp lệ hoặc giới hạn nằm ngoài phạm vi. |
| `-32603` | Lỗi máy chủ nội bộ. |
| `-32016` | Bộ lập chỉ mục chưa đạt đến `minContextSlot`, slot của token phân trang hoặc bộ lọc slot `gt`/`gte`. |

HTTP 429 cho biết yêu cầu đang bị giới hạn tốc độ; xem [giới hạn tốc độ](https://www.helius.dev/docs/vi/billing/rate-limits.md). Xem [xác thực](https://www.helius.dev/docs/vi/api-reference/authentication.md) để biết cách thiết lập khóa API.


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