Tổng quan
getTransfersByAddress là phương thức RPC độc quyền của Helius, trả về các đối tượng chuyển token và SOL gốc đã được phân tích, dễ đọc cho một địa chỉ ví. Phương thức này không thuộc RPC Solana tiêu chuẩn.
Phương thức này tập trung vào hoạt động chuyển tài sản, vì vậy trả về các bản ghi chuyển ngắn gọn thay vì toàn bộ payload giao dịch. Mỗi bản ghi được chuẩn hóa với tài khoản chủ sở hữu và tài khoản token đã phân tích, mint, số lượng thô, số chữ số thập phân, số lượng hiển thị trên giao diện, vị trí lệnh và trạng thái xác nhận. Nhờ đó, bạn có thể đối soát biến động số dư mà không cần tự triển khai lại logic phân tích token Solana.
Phương thức này yêu cầu gói Developer trở lên và tiêu tốn 10 tín dụng cho mỗi yêu cầu.
Parsed transfer objects
Trả về các bản ghi chuyển dễ đọc với tài khoản, số lượng, số chữ số thập phân và loại chuyển đã được phân tích.
Reconciliation ready
Mô hình hóa SOL, WSOL, phí Token-2022, hoạt động mint, burn và thay đổi chủ sở hữu tài khoản để có thể đối soát số dư chính xác.
Mint, time, and amount filters
Thu hẹp lịch sử chuyển theo địa chỉ mint, khoảng thời gian khối hoặc khoảng số lượng thô.
Counterparty filters
Lọc các lượt chuyển theo người gửi hoặc người nhận bằng
with và direction.Khi nào nên sử dụng
Sử dụnggetTransfersByAddress khi bạn cần:
- Lịch sử chuyển của ví để theo dõi thanh toán hoặc hoạt động chuyển
- Phân tích hoạt động danh mục đầu tư và biến động token
- Đối soát số dư đáng tin cậy cho sổ cái và kế toán
- Báo cáo chuyển theo từng đối tác cụ thể (ai đã gửi hoặc nhận tài sản gì)
- Xử lý SOL/WSOL, phí Token-2022, mint và burn theo cách chuẩn hóa mà không cần viết trình phân tích
getTransactionsForAddress khi cần toàn bộ dữ liệu giao dịch, lịch sử chỉ gồm chữ ký hoặc hoạt động không phải chuyển tài sản. Một cách triển khai phổ biến là phân trang các lượt chuyển tại đây, sau đó truy xuất toàn bộ giao dịch cơ sở bằng các lệnh gọi getTransaction theo lô (xem Truy xuất toàn bộ giao dịch cho các hàng chuyển).
Độ chính xác và đối soát
getTransfersByAddress được xây dựng cho các ứng dụng cần lịch sử chuyển đáng tin cậy để phục vụ sổ cái, theo dõi thanh toán, hoạt động danh mục đầu tư và đối soát số dư. Thay vì trả về payload giao dịch thô và để trình phân tích của bạn tự xử lý mọi trường hợp biên, API trả về các đối tượng chuyển đã chuẩn hóa.
Phản hồi mô hình hóa rõ ràng những trường hợp chuyển thường khiến việc đối soát lịch sử Solana trở nên khó khăn:
- Chuyển token SPL tiêu chuẩn và SOL gốc.
- Chuyển Token-2022 có phí bị giữ lại, được biểu diễn dưới dạng các hàng
transferthông thường với các trường phí riêng. - Mint và burn, được biểu diễn dưới dạng lượt chuyển có người gửi hoặc người nhận là
null. - Hành vi bọc và mở bọc SOL, với chế độ mặc định được thiết kế để tránh các hàng vòng đời gây nhiễu.
- Thay đổi chủ sở hữu tài khoản token thông qua SetAuthority.
- Rút phí bị giữ lại của Token-2022.
- Luồng qua tài khoản trung gian, được trả về dưới dạng các bản ghi chuyển cơ sở thay vì bị gộp thành biến động ròng ước đoán.
Bắt đầu nhanh
Tham số yêu cầu
Truyền địa chỉ ví của chủ sở hữu, không phải tài khoản token liên kết (ATA). API tìm hoạt động chuyển cho các tài khoản token thuộc sở hữu của ví đó.string
bắt buộc
Địa chỉ ví của chủ sở hữu được mã hóa Base58 cần truy vấn các lượt chuyển. Truyền địa chỉ ví của chủ sở hữu, không phải tài khoản token liên kết (ATA).
object
Đối tượng cấu hình tùy chọn dành cho việc lọc, phân trang, mức cam kết, thứ tự và hành vi SOL/WSOL.
string
Lọc theo địa chỉ đối tác. Chỉ trả về các lượt chuyển đến hoặc từ địa chỉ này.
string
mặc định:"any"
Lọc theo hướng chuyển tương ứng với
address.in: các lượt chuyển màaddressnhận đượcout: các lượt chuyển doaddressgửi điany: các lượt chuyển đến và đi
string
Lọc theo địa chỉ mint token. Sử dụng
So11111111111111111111111111111111111111111 cho SOL gốc và So11111111111111111111111111111111111111112 cho WSOL.string
mặc định:"merged"
Kiểm soát cách biểu diễn SOL gốc và WSOL.
merged: WSOL được xử lý như SOL gốc. Các hàng vòng đời bọc và mở bọc bị loại trừ, đồng thời giá trị mint WSOL được thay bằng mint SOL gốc.separate: WSOL được giữ nguyên dưới dạng một mint riêng biệt, đồng thời các hàng vòng đời bọc và mở bọc được đưa vào.
object
Các bộ lọc bổ sung cho số lượng, thời gian khối và slot.
number
mặc định:"100"
Số lượt chuyển tối đa cần trả về. Phạm vi: từ 1 đến 100.
string
Con trỏ từ phản hồi trước để phân trang.
string
mặc định:"finalized"
Mức cam kết dữ liệu.
finalizedconfirmed
number
Slot tối thiểu mà tại đó yêu cầu có thể được đánh giá
string
mặc định:"desc"
Thứ tự kết quả.
desc: mới nhất trướcasc: cũ nhất trước
Phản hồi
Chi tiết các trường phản hồi
fromUserAccountvàtoUserAccountluôn xuất hiện. Khi một phía không tồn tại, giá trị lànull.fromTokenAccountvàtoTokenAccountchỉ được đưa vào khi các điểm cuối tài khoản token có ý nghĩa đối với hàng đó. Các trường này bị lược bỏ hoàn toàn đối với lượt chuyển SOL gốc.- Lượt chuyển mint chỉ có một phía:
fromUserAccountlànullvà chỉ có thể được trả về dưới dạng lượt chuyển đến cho người nhận. - Lượt chuyển burn chỉ có một phía:
toUserAccountlànullvà chỉ có thể được trả về dưới dạng lượt chuyển đi cho chủ sở hữu thực hiện burn.
Bộ lọc
Sử dụng bộ lọc so sánh cho các truy vấn phạm vi số. Tất cả các trường so sánh đều không bắt buộc và có thể kết hợp với nhau.Loại chuyển
Trườngtype xác định hành vi chuyển được biểu diễn trong mỗi hàng.
Loại chuyển và lệnh
Hành vi của SOL và wSOL
SOL tồn tại trên Solana dưới hai dạng thường xuất hiện cùng nhau trong hoạt động thực tế của người dùng:- SOL gốc là tài sản gốc của chuỗi. Nó tồn tại trực tiếp trong ví hoặc tài khoản dưới dạng lamport. Một SOL bằng 1.000.000.000 lamport.
- Wrapped SOL (WSOL, thường được viết là wSOL) là dạng biểu diễn SOL dưới dạng token SPL. Nó sử dụng mint WSOL
So11111111111111111111111111111111111111112và tồn tại trong tài khoản token, tương tự USDC hoặc bất kỳ token SPL nào khác.
getTransfersByAddress sử dụng solMode: "merged". Trong chế độ này:
- SOL gốc và WSOL được coi là một tài sản SOL khi truy vấn theo
So11111111111111111111111111111111111111111. - Các hàng chuyển WSOL được chuẩn hóa thành mint SOL gốc để lịch sử được định giá bằng SOL dễ đối soát hơn.
- Các hàng vòng đời bọc và mở bọc bị loại trừ vì chúng thường biểu diễn biến động giữa các tài khoản do cùng một chủ sở hữu kiểm soát, không phải khoản thanh toán cho người dùng khác.
- Các lượt chuyển SOL và WSOL giữa các chủ sở hữu khác nhau vẫn được biểu diễn dưới dạng lượt chuyển.
- Tiền thuê thu hồi từ
CloseAccountđược biểu diễn dưới dạng một hàngunwrapSOL gốc khi các hàng vòng đời đóng tài khoản được trả về.
solMode: "separate" khi cần WSOL dưới dạng một mint token SPL riêng biệt hoặc muốn kiểm tra các bản ghi vòng đời bọc và mở bọc. Trong chế độ này, WSOL giữ nguyên mint So11111111111111111111111111111111111111112, còn các bản ghi bọc/mở bọc được trả về với type: "wrap" hoặc type: "unwrap".
Đối với việc đóng tài khoản WSOL trong solMode: "separate", các bản ghi unwrap cho mint WSOL biểu diễn số dư token WSOL còn lại được trả về dưới dạng SOL. Tiền thuê được hoàn lại từ tài khoản token đã đóng được trả về dưới dạng một hàng unwrap SOL gốc riêng biệt.
Phí chuyển Token-2022
Các lệnh Token-2022TransferCheckedWithFee được biểu diễn dưới dạng một bản ghi chuyển với type: "transfer". Số lượng tại đích được trả về trong amount; chi tiết phí bị giữ lại được trả về trong feeAmount và feeUiAmount.
Đối với các lượt chuyển có phí, nguồn bị ghi nợ amount + feeAmount, còn đích được ghi có amount.
Ví dụ
Lọc theo USDC
Các lượt chuyển đến từ một người gửi
Phạm vi số lượng và thời gian
Yêu cầu được phân trang
Truy xuất toàn bộ giao dịch cho các hàng chuyển
getTransfersByAddress trả về các hàng chuyển đã phân tích, không phải toàn bộ payload giao dịch. Nếu cần toàn bộ giao dịch cho mỗi lượt chuyển, trước tiên hãy phân trang các lượt chuyển, loại bỏ bản trùng lặp theo signature, sau đó truy xuất toàn bộ giao dịch bằng các lệnh gọi getTransaction theo lô.
Không thể xử lý getTransfersByAddress theo lô trên nhiều địa chỉ chủ sở hữu. Hãy truy vấn từng địa chỉ chủ sở hữu, sau đó xử lý theo lô các yêu cầu getTransaction thu được theo chữ ký. Một giao dịch có thể tạo ra nhiều hàng chuyển, vì vậy hãy luôn loại bỏ chữ ký trùng lặp trước khi truy xuất giao dịch.
Hạn chế
- Các giao dịch thất bại không được đưa vào V1.
- Các biến động SOL ẩn chỉ được suy ra từ thay đổi số dư không được hỗ trợ trong V1.
harvestWithheldTokensToMintkhông được hỗ trợ trong V1 vì không cho biết số lượng đã thu.- Luồng qua tài khoản trung gian không được rút gọn. Nếu một giao dịch chuyển tiền qua các tài khoản trung gian, các bản ghi chuyển cơ sở sẽ được trả về.
- Không thể xử lý theo lô trên nhiều địa chỉ chủ sở hữu. Hãy truy vấn từng chủ sở hữu.
Các bước tiếp theo
getTransactionsForAddress
Toàn bộ lịch sử giao dịch với khả năng lọc, sắp xếp và hỗ trợ tài khoản token.
API reference
Lược đồ yêu cầu và phản hồi đầy đủ cho getTransfersByAddress.
Indexing guide
Nạp bù và đồng bộ dữ liệu chuyển vào chỉ mục của riêng bạn.
Historical data overview
So sánh tất cả các phương thức dữ liệu lịch sử của Solana.