> ## 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.
# getProgramAccountsV2
> getProgramAccountsV2 là phiên bản nâng cao của getProgramAccounts, hỗ trợ phân trang dựa trên con trỏ và cập nhật changedSinceSlot để truy vấn các tập hợp tài khoản Solana lớn.
## Tổng quan
`getProgramAccountsV2` là phiên bản nâng cao của phương thức `getProgramAccounts` tiêu chuẩn, được thiết kế cho các ứng dụng cần truy vấn hiệu quả những tập hợp lớn gồm các tài khoản thuộc sở hữu của các chương trình Solana cụ thể. Phương thức này bổ sung khả năng phân trang dựa trên con trỏ và cập nhật tăng dần.
**Các tính năng mới trong V2:**
* **Phân trang dựa trên con trỏ**: Định cấu hình giới hạn từ 1 đến 10.000 tài khoản cho mỗi yêu cầu
* **Cập nhật tăng dần**: Sử dụng `changedSinceSlot` để chỉ truy xuất các tài khoản được sửa đổi gần đây
* **Hiệu suất tốt hơn**: Ngăn lỗi hết thời gian chờ và giảm mức sử dụng bộ nhớ đối với các tập dữ liệu lớn
* **Khả năng tương thích ngược**: Hỗ trợ tất cả tham số `getProgramAccounts` hiện có
* **`withContext` tùy chọn**: `true` thêm `slot` và `apiVersion` trong `result.context`; nếu bỏ qua hoặc đặt là `false` thì các trường này sẽ không được đưa vào
## Lợi ích chính
Xử lý các chương trình có hàng triệu tài khoản bằng cách phân trang kết quả hiệu quả
Sử dụng `changedSinceSlot` để cập nhật tăng dần và đồng bộ hóa dữ liệu theo thời gian thực
Các truy vấn lớn từng bị hết thời gian chờ giờ đây hoạt động ổn định nhờ tính năng phân trang
Xử lý dữ liệu theo từng phần thay vì tải toàn bộ dữ liệu vào bộ nhớ cùng lúc
## Các phương pháp hay nhất về phân trang
**Hành vi phân trang quan trọng**: Điểm kết thúc phân trang chỉ được biểu thị khi **không có tài khoản nào được trả về**. API có thể trả về ít tài khoản hơn giới hạn do quá trình lọc — hãy luôn tiếp tục phân trang cho đến khi `paginationKey` là `null`.
### Mẫu phân trang cơ bản
```typescript theme={"system"}
let allAccounts = [];
let paginationKey = null;
do {
const response = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: '1',
method: 'getProgramAccountsV2',
params: [
"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
{
encoding: 'base64',
filters: [{ dataSize: 165 }],
limit: 5000,
...(paginationKey && { paginationKey })
}
]
})
});
const data = await response.json();
allAccounts.push(...data.result.accounts);
paginationKey = data.result.paginationKey;
} while (paginationKey);
```
### Cập nhật tăng dần
```typescript theme={"system"}
// Get only accounts modified since slot 150000000
const incrementalUpdate = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: '1',
method: 'getProgramAccountsV2',
params: [
programId,
{
encoding: 'jsonParsed',
limit: 1000,
changedSinceSlot: 150000000
}
]
})
});
```
## Mẹo cải thiện hiệu suất
**Kích thước giới hạn tối ưu**: Trong hầu hết trường hợp sử dụng, giới hạn từ 1.000 đến 5.000 tài khoản cho mỗi yêu cầu mang lại sự cân bằng tốt nhất giữa hiệu suất và độ ổn định.
* **Bắt đầu với giới hạn nhỏ hơn** (1000) rồi tăng lên dựa trên hiệu suất mạng
* **Sử dụng kiểu mã hóa phù hợp**: `jsonParsed` để thuận tiện, `base64` để tối ưu hiệu suất
* **Áp dụng bộ lọc** để giảm kích thước tập dữ liệu trước khi phân trang
* **Lưu `paginationKey`** để tiếp tục truy vấn nếu bị gián đoạn
* **Theo dõi thời gian phản hồi** và điều chỉnh giới hạn cho phù hợp
## `withContext` (tùy chọn)
Giá trị Boolean trong đối tượng cấu hình chương trình (`params[1]`). Chỉ cấu trúc của `result` thay đổi, còn bộ lọc, giới hạn và cách phân trang không thay đổi.
```json theme={"system"}
// Omitted or false
{ "jsonrpc": "2.0", "id": "1", "result": { "accounts": [], "paginationKey": null } }
// true — snapshot metadata plus page under `result.value`
{ "jsonrpc": "2.0", "id": "1", "result": {
"context": { "slot": 411895550, "apiVersion": "3.1.9" },
"value": { "accounts": [], "paginationKey": null }
}}
```
## Di chuyển từ getProgramAccounts
Việc di chuyển từ phương thức ban đầu rất đơn giản — chỉ cần thay thế tên phương thức và thêm các tham số phân trang:
```diff theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
- "method": "getProgramAccounts",
+ "method": "getProgramAccountsV2",
"params": [
"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
{
"encoding": "base64",
"filters": [{ "dataSize": 165 }],
+ "limit": 5000
}
]
}
```
## Các phương thức liên quan
Phương thức ban đầu không hỗ trợ phân trang
Phương thức V2 dành cho các truy vấn tài khoản token
## Tham số yêu cầu
Khóa công khai (địa chỉ) của chương trình Solana cần truy vấn tài khoản, dưới dạng chuỗi được mã hóa base-58.
Mức cam kết cho yêu cầu.
* `confirmed`
* `finalized`
* `processed`
Slot tối thiểu mà tại đó yêu cầu có thể được đánh giá.
Khi là `true`, trả về `result.context` (siêu dữ liệu ảnh chụp nhanh: `slot`, `apiVersion`) và lồng
`accounts` cùng `paginationKey` trong `result.value`. Khi là `false` hoặc bị bỏ qua,
các trường đó xuất hiện trực tiếp trên `result` (ví dụ: `result.accounts`). Áp dụng cùng bộ lọc và giới hạn.
Định dạng mã hóa cho dữ liệu tài khoản được trả về.
* `jsonParsed`
* `base58`
* `base64`
* `base64+zstd`
Yêu cầu một phần dữ liệu của tài khoản.
Số byte cần trả về.
Độ lệch byte để bắt đầu đọc.
Số lượng tài khoản tối đa trả về trong mỗi yêu cầu (1–10.000).
Con trỏ phân trang được mã hóa base-58 để truy xuất các trang tiếp theo. Sử dụng paginationKey từ phản hồi trước đó.
Chỉ trả về các tài khoản đã được sửa đổi tại hoặc sau số slot này. Hữu ích cho các bản cập nhật tăng dần.
Hệ thống lọc mạnh mẽ để truy vấn hiệu quả các mẫu dữ liệu tài khoản Solana cụ thể.
## OpenAPI
````yaml vi/openapi/rpc-http/getProgramAccountsV2.yaml POST /
openapi: 3.1.0
info:
title: API RPC Solana
version: 1.0.0
description: >-
API lập chỉ mục tài khoản chương trình Solana nâng cao, hỗ trợ phân trang
dựa trên con trỏ và changedSinceSlot để truy vấn hiệu quả các tập hợp lớn
tài khoản thuộc sở hữu của những chương trình cụ thể. Hỗ trợ cập nhật tăng
dần thông qua tính năng lọc dựa trên slot để đồng bộ hóa dữ liệu theo thời
gian thực.
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://mainnet.helius-rpc.com
description: Điểm cuối RPC Mainnet
- url: https://devnet.helius-rpc.com
description: Điểm cuối RPC Devnet
security: []
paths:
/:
post:
tags:
- RPC
summary: getProgramAccountsV2
description: >
Phiên bản nâng cao của getProgramAccounts, hỗ trợ phân trang dựa trên
con trỏ và changedSinceSlot để truy vấn hiệu quả
các tập hợp lớn tài khoản thuộc sở hữu của những chương trình Solana cụ
thể. Cho phép truy xuất dữ liệu tăng dần với
kích thước trang có thể cấu hình lên đến 10.000 tài khoản cho mỗi yêu
cầu. Tham số changedSinceSlot cho phép chỉ truy xuất
những tài khoản đã được sửa đổi kể từ một slot blockchain cụ thể, rất
phù hợp cho quy trình lập chỉ mục và đồng bộ hóa
dữ liệu theo thời gian thực. Đây là tính năng thiết yếu cho các ứng dụng
xử lý việc khám phá tài khoản chương trình ở quy mô lớn,
chẳng hạn như giao thức DeFi, thị trường NFT và nền tảng phân tích
blockchain.
Lưu ý: Quá trình phân trang chỉ được coi là kết thúc khi không có tài
khoản nào được trả về. API có thể trả về ít tài khoản hơn
giới hạn do quá trình lọc — hãy tiếp tục phân trang cho đến khi
paginationKey là null.
**withContext**: Giá trị boolean không bắt buộc trong đối tượng cấu hình
(cùng với encoding, limit và các tùy chọn khác). Khi
`withContext` là `true`, RPC trả về cấu trúc bao bọc tiêu chuẩn của
Solana: `result.context` (siêu dữ liệu
ảnh chụp nhanh, bao gồm `slot` và thường là `apiVersion`) và
`result.value` chứa `accounts`, `paginationKey`.
Khi `withContext` là `false` hoặc bị bỏ qua, các trường đó được trả về
trực tiếp trong `result`
(ví dụ: `result.accounts`). Bộ lọc, giới hạn và hành vi phân trang không
thay đổi; chỉ cấu trúc JSON
của `result` là khác.
operationId: getProgramAccountsV2
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jsonrpc
- id
- method
- params
properties:
jsonrpc:
type: string
description: Phiên bản giao thức JSON-RPC.
enum:
- '2.0'
example: '2.0'
default: '2.0'
id:
type: string
description: Mã định danh duy nhất cho yêu cầu.
example: '1'
default: '1'
method:
type: string
description: Tên của phương thức RPC cần gọi.
enum:
- getProgramAccountsV2
example: getProgramAccountsV2
default: getProgramAccountsV2
params:
type: array
description: Các tham số cho phương thức phân trang nâng cao.
default:
- TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- encoding: base64
limit: 1000
items:
oneOf:
- type: string
description: >-
Khóa công khai (địa chỉ) của chương trình Solana cần
truy vấn tài khoản, dưới dạng chuỗi được mã hóa
base-58.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- type: object
description: >-
Các tùy chọn cấu hình nâng cao có hỗ trợ phân trang để
tối ưu hóa truy vấn tài khoản chương trình.
properties:
commitment:
type: string
description: Mức cam kết cho yêu cầu.
enum:
- confirmed
- finalized
- processed
example: finalized
minContextSlot:
type: integer
description: >-
Slot tối thiểu mà tại đó yêu cầu có thể được đánh
giá.
example: 1000
withContext:
type: boolean
description: >
Khi là `true`, trả về `result.context` (siêu dữ
liệu ảnh chụp nhanh: `slot`, `apiVersion`) và lồng
`accounts` cùng `paginationKey` trong
`result.value`. Khi là `false` hoặc bị bỏ qua,
các trường đó xuất hiện trực tiếp trong `result`
(ví dụ: `result.accounts`). Các bộ lọc và giới hạn
tương tự vẫn được áp dụng.
example: true
encoding:
type: string
description: >-
Định dạng mã hóa cho dữ liệu tài khoản được trả
về.
enum:
- jsonParsed
- base58
- base64
- base64+zstd
example: base64
dataSlice:
type: object
description: Yêu cầu một phần dữ liệu của tài khoản.
properties:
length:
type: integer
description: Số byte cần trả về.
example: 50
offset:
type: integer
description: Độ lệch byte để bắt đầu đọc.
example: 0
limit:
type: integer
description: >-
Số tài khoản tối đa được trả về cho mỗi yêu cầu
(1–10.000).
minimum: 1
maximum: 10000
example: 1000
paginationKey:
type: string
description: >-
Con trỏ phân trang được mã hóa base-58 để truy
xuất các trang tiếp theo. Sử dụng paginationKey từ
phản hồi trước đó.
example: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
changedSinceSlot:
type: integer
description: >-
Chỉ trả về những tài khoản đã được sửa đổi tại
hoặc sau số slot này. Hữu ích cho các bản cập nhật
tăng dần.
example: 12345678
filters:
type: array
description: >-
Hệ thống lọc mạnh mẽ để truy vấn hiệu quả các mẫu
dữ liệu tài khoản Solana cụ thể.
items:
oneOf:
- type: object
description: >-
Lọc các tài khoản Solana theo kích thước dữ
liệu chính xác tính bằng byte.
properties:
dataSize:
type: integer
description: >-
Kích thước chính xác của dữ liệu tài
khoản tính bằng byte để lọc.
example: 165
- type: object
description: >-
Lọc các tài khoản Solana bằng cách so sánh
dữ liệu tại các độ lệch bộ nhớ cụ thể (bộ
lọc mạnh nhất).
properties:
memcmp:
type: object
description: >-
Bộ lọc so sánh bộ nhớ để tìm các tài
khoản có mẫu dữ liệu cụ thể.
properties:
offset:
type: integer
description: >-
Độ lệch byte trong dữ liệu tài khoản để
thực hiện phép so sánh.
example: 4
bytes:
type: string
description: >-
Dữ liệu được mã hóa base-58 để so sánh
tại vị trí độ lệch đã chỉ định.
example: 3Mc6vR
responses:
'200':
description: Đã truy xuất thành công các tài khoản chương trình được phân trang.
content:
application/json:
schema:
type: object
properties:
jsonrpc:
type: string
description: Phiên bản giao thức JSON-RPC.
enum:
- '2.0'
example: '2.0'
id:
type: string
description: Mã định danh khớp với yêu cầu.
example: '1'
result:
oneOf:
- $ref: '#/components/schemas/ProgramAccountsV2Page'
title: không có withContext
- type: object
title: có withContext
description: >-
Kết quả được bao bọc khi `withContext` là `true` trong
các tùy chọn yêu cầu.
required:
- context
- value
properties:
context:
type: object
description: >-
Siêu dữ liệu ảnh chụp nhanh cho phản hồi của nút
(tính nhất quán của slot, gỡ lỗi).
properties:
slot:
type: integer
description: Slot mà tại đó nút tạo phản hồi này.
example: 411895550
apiVersion:
type: string
description: Phiên bản API RPC khi có sẵn.
example: 3.1.9
value:
$ref: '#/components/schemas/ProgramAccountsV2Page'
'400':
description: >-
Yêu cầu không hợp lệ - Tham số yêu cầu không hợp lệ hoặc yêu cầu
không đúng định dạng.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32602
message: Tham số không hợp lệ
data: {}
id: '1'
'401':
description: Không được phép - Khóa API không hợp lệ hoặc bị thiếu.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32001
message: Không được phép
data: {}
id: '1'
'429':
description: Quá nhiều yêu cầu - Đã vượt quá giới hạn tốc độ.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32005
message: Quá nhiều yêu cầu
data: {}
id: '1'
'500':
description: Lỗi máy chủ nội bộ - Đã xảy ra lỗi trên máy chủ.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32603
message: Lỗi nội bộ
data: {}
id: '1'
'503':
description: Dịch vụ không khả dụng - Dịch vụ tạm thời không khả dụng.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32002
message: Dịch vụ không khả dụng
data: {}
id: '1'
'504':
description: Cổng kết nối hết thời gian chờ - Yêu cầu đã hết thời gian chờ.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32003
message: Cổng kết nối hết thời gian chờ
data: {}
id: '1'
security:
- ApiKeyQuery: []
components:
schemas:
ProgramAccountsV2Page:
type: object
description: >-
Các tài khoản chương trình đã phân trang. Các trường tương tự xuất hiện
trong result khi withContext là false hoặc bị bỏ qua, hoặc trong
result.value khi withContext là true.
properties:
accounts:
type: array
description: Danh sách tài khoản chương trình cho trang hiện tại.
items:
$ref: '#/components/schemas/ProgramAccountV2Entry'
paginationKey:
type: string
description: >-
Con trỏ phân trang cho trang tiếp theo. Chỉ là null khi không có tài
khoản nào được trả về (kết thúc phân trang). Lưu ý rằng số tài khoản
được trả về có thể ít hơn giới hạn do quá trình lọc, nhưng điều này
không cho biết quá trình phân trang đã kết thúc.
example: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
nullable: true
ErrorResponse:
type: object
properties:
jsonrpc:
type: string
description: Phiên bản giao thức JSON-RPC.
enum:
- '2.0'
example: '2.0'
error:
type: object
properties:
code:
type: integer
description: Mã lỗi.
example: -32602
message:
type: string
description: Thông báo lỗi.
data:
type: object
description: Dữ liệu bổ sung về lỗi.
id:
type: string
description: Mã định danh khớp với yêu cầu.
example: '1'
ProgramAccountV2Entry:
type: object
properties:
pubkey:
type: string
description: Pubkey của tài khoản dưới dạng chuỗi được mã hóa base-58.
example: CxELquR1gPP8wHe33gZ4QxqGB3sZ9RSwsJ2KshVewkFY
account:
type: object
description: Thông tin chi tiết về tài khoản.
properties:
lamports:
type: integer
description: Số lamport được gán cho tài khoản này.
example: 15298080
owner:
type: string
description: >-
Pubkey được mã hóa base-58 của chương trình mà tài khoản này
được gán cho.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
data:
type: array
description: Dữ liệu tài khoản ở định dạng nhị phân được mã hóa hoặc JSON.
items:
type: string
example:
- 2R9jLfiAQ9bgdcw6h8s44439
- base64
executable:
type: boolean
description: Cho biết tài khoản có chứa chương trình hay không.
example: false
rentEpoch:
type: integer
description: Epoch mà tại đó tài khoản này sẽ phải trả phí thuê tiếp theo.
example: 28
space:
type: integer
description: Kích thước dữ liệu của tài khoản.
example: 165
securitySchemes:
ApiKeyQuery:
type: apiKey
in: query
name: api-key
description: >-
Khóa API Helius của bạn. Bạn có thể nhận khóa miễn phí trong [bảng điều
khiển](https://dashboard.helius.dev/api-keys).
````