Chuyển đến nội dung chính
POST
getHistoricalTokenAccountsByOwner
getHistoricalTokenAccountsByOwner đang ở giai đoạn Beta. Các tham số, mức giá, định dạng phản hồi và phạm vi dữ liệu có thể thay đổi.

Tổng quan

getHistoricalTokenAccountsByOwner trả về các tài khoản SPL Token và Token-2022 mà một ví sở hữu tại một slot trước đây hoặc ngay sau một giao dịch cụ thể trong slot đó. Đây là phương thức RPC độc quyền của Helius. getTokenAccountsByOwner tiêu chuẩn chỉ trả về trạng thái hiện tại. Với kiểu mã hóa jsonParsed, số lượng token sử dụng số chữ số thập phân của từng mint tại vị trí được yêu cầu, do đó số dư phản ánh lượng token mà ví nắm giữ tại thời điểm đó. Dữ liệu lịch sử có sẵn từ slot 444,959,999 (ngày 7 tháng 9 năm 2026) trở đi, tương ứng với trạng thái tại thời điểm bắt đầu epoch 1030. getHistoricalTokenAccountsByOwner có sẵn trên mainnet cho các gói Business trở lên và có giá 0 credit cho mỗi lệnh gọi trong giai đoạn beta. Mức giá có thể thay đổi.

Điểm khác biệt so với getTokenAccountsByOwner

  • Bộ lọc mint hoặc chương trình là tùy chọn. Khi không có bộ lọc, bạn nhận được mọi tài khoản token mà ví sở hữu. Để thu hẹp kết quả, hãy đặt mint hoặc programId trong đối tượng cấu hình (tham số thứ ba), nhưng không đặt cả hai.
  • Tham số thứ hai là đối tượng truy vấn dùng để chọn vị trí trong lịch sử, không phải bộ lọc mint hoặc chương trình.
  • result.value là một đối tượng có accounts và paginationKey, không phải một mảng.

Chọn một vị trí trong lịch sử

Tham số thứ hai là một đối tượng truy vấn:
  • Bị bỏ qua hoặc {}: slot mới nhất đã được lập chỉ mục, giới hạn theo mức cam kết được yêu cầu.
  • { "slot": 445000000 }: cuối slot 445,000,000.
  • { "slot": 445000000, "transactionIndex": 10 }: ngay sau khi giao dịch tại chỉ mục 10 trong slot đó được thực thi.
Xem Hướng dẫn về tài khoản lịch sử để tìm hiểu cách hoạt động của các vị trí.

Yêu cầu mẫu

Yêu cầu này trả về các tài khoản token USDC của ví tại thời điểm cuối slot 445,000,000:

Phân trang qua tất cả tài khoản token

Kết quả được sắp xếp trước tiên theo mint, sau đó theo địa chỉ tài khoản token. Mỗi phản hồi trả về value.accounts và value.paginationKey, một con trỏ có dạng <mint>:<tokenAccount>. Truyền lại con trỏ này trong yêu cầu tiếp theo cho đến khi nó là null.
Một trang có thể có ít mục hoặc thậm chí trống nhưng vẫn chứa paginationKey. Chỉ khi paginationKey là null thì bạn mới đến cuối.
Luôn truyền một slot rõ ràng khi phân trang. Nếu bỏ qua, mỗi trang sẽ đọc slot mới nhất đã được lập chỉ mục, vì vậy các trang có thể đến từ những thời điểm khác nhau.

Đọc phản hồi

Mỗi mục trong value.accounts có pubkey của tài khoản token và một đối tượng account. Đối tượng tài khoản có các trường giống getAccountInfo, cùng với lastUpdatedAt:
  • lastUpdatedAt.slot và lastUpdatedAt.transactionIndex xác định thao tác ghi đã tạo ra trạng thái này.
  • lastUpdatedAt.slot bằng 444,959,999 với transactionIndex là null có nghĩa là tài khoản token chưa thay đổi kể từ khi phạm vi dữ liệu lịch sử bắt đầu.
  • context.slot là slot mới nhất mà Helius đã lập chỉ mục khi xử lý yêu cầu, không phải slot bạn đã truy vấn.

Lỗi

Các phương thức liên quan

Historical Accounts Guide

Cách hoạt động của vị trí, phạm vi dữ liệu và lastUpdatedAt đối với các phương thức tài khoản lịch sử

getHistoricalAccountInfo

Đọc một tài khoản tại một slot trước đây

getTransactionsForAddress

Tìm slot và transactionIndex của các giao dịch bạn muốn kiểm tra

getTokenAccountsByOwnerV2

Phân trang qua các tài khoản token hiện tại của một ví

Tham số yêu cầu

string
bắt buộc
Địa chỉ được mã hóa Base-58 của ví sở hữu các tài khoản token. Truyền ví chủ sở hữu, không phải tài khoản token.
number
Slot dùng để đọc trạng thái. Trả về tài khoản ở thời điểm cuối slot này. Slot sớm nhất được hỗ trợ là 444959999, tương ứng với trạng thái tại thời điểm bắt đầu epoch 1030. Khi bị bỏ qua, phương thức sẽ đọc slot mới nhất đã được lập chỉ mục, giới hạn theo mức cam kết được yêu cầu.
number
Vị trí của một giao dịch trong slot. Trả về trạng thái tài khoản ngay sau khi giao dịch đó được thực thi thay vì tại thời điểm cuối slot. Yêu cầu phải có slot.
string
Chỉ trả về các tài khoản token cho mint này. Không thể kết hợp với programId.
string
Chỉ trả về các tài khoản token do chương trình token này sở hữu. Không thể kết hợp với mint.
  • TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
  • TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
string
mặc định:"base64"
Định dạng mã hóa cho dữ liệu tài khoản. Với jsonParsed, số lượng token sử dụng số chữ số thập phân của mint tại vị trí được yêu cầu. base58 và binary không được hỗ trợ.
  • base64
  • base64+zstd
  • jsonParsed
object
Chỉ trả về một phần dữ liệu của từng tài khoản. Áp dụng cho kiểu mã hóa base64 và base64+zstd.
number
bắt buộc
Độ lệch byte để bắt đầu đọc.
number
bắt buộc
Số byte cần trả về.
number
mặc định:"5000"
Số lượng tài khoản token tối đa cần trả về (1-5.000).
string
Con trỏ từ paginationKey của phản hồi trước, có dạng &lt;mint&gt;:&lt;tokenAccount&gt;. Khi cũng đặt mint, mint của con trỏ phải khớp với giá trị đó.
string
mặc định:"finalized"
Mức cam kết. processed không được hỗ trợ.
  • finalized
  • confirmed
number
Slot tối thiểu mà tại đó yêu cầu có thể được đánh giá.

Ủy quyền

api-key
string
query
bắt buộc

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.

Nội dung

application/json
jsonrpc
enum<string>
mặc định:2.0
bắt buộc

Phiên bản giao thức JSON-RPC.

Tùy chọn có sẵn:
2.0
Ví dụ:

"2.0"

id
string
mặc định:1
bắt buộc

Mã định danh duy nhất cho yêu cầu.

Ví dụ:

"1"

method
enum<string>
mặc định:getHistoricalTokenAccountsByOwner
bắt buộc

Tên phương thức RPC cần gọi.

Tùy chọn có sẵn:
getHistoricalTokenAccountsByOwner
Ví dụ:

"getHistoricalTokenAccountsByOwner"

params
(string | Truy vấn · object | Cấu hình · object)[]
bắt buộc

Mảng chứa địa chỉ ví của chủ sở hữu, một đối tượng truy vấn tùy chọn để chọn vị trí trong lịch sử và một đối tượng cấu hình tùy chọn.

Required array length: 1 - 3 elements

Địa chỉ được mã hóa base-58 của ví từng sở hữu các tài khoản token. Truyền ví của chủ sở hữu, không phải tài khoản token.

Ví dụ:

"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"

Phản hồi

Đã truy xuất thành công một trang tài khoản token lịch sử.

jsonrpc
enum<string>

Phiên bản giao thức JSON-RPC.

Tùy chọn có sẵn:
2.0
Ví dụ:

"2.0"

id
string

Mã định danh khớp với yêu cầu.

Ví dụ:

"1"

result
object