Skip to main content

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ụng getTransfersByAddress 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
Thay vào đó, hãy sử dụng 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 transfer thô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.
Đối với các sự kiện chuyển hiển thị được hỗ trợ, tính năng này cho phép đố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. Các trường hợp loại trừ đã biết, chẳng hạn như biến động SOL ẩn chỉ được suy ra từ thay đổi số dư, được nêu trong phần Hạn chế.

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à address nhận được
  • out: các lượt chuyển do address gửi đi
  • any: 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.
  • finalized
  • confirmed
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ước
  • asc: cũ nhất trước

Phản hồi

Chi tiết các trường phản hồi

  • fromUserAccount và toUserAccount luôn xuất hiện. Khi một phía không tồn tại, giá trị là null.
  • fromTokenAccount và toTokenAccount chỉ đượ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: fromUserAccount là null và 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: toUserAccount là null và 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ường type 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 So11111111111111111111111111111111111111112 và 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.
Người dùng và ứng dụng bọc SOL khi cần SOL hoạt động như một token SPL, thường dành cho DeFi, hoán đổi, nghiệp vụ kế toán dựa trên tài khoản token hoặc giao diện chương trình chỉ chấp nhận token SPL. Quá trình bọc thường cấp vốn cho một tài khoản token bằng SOL gốc và đồng bộ số SOL đó thành WSOL. Quá trình mở bọc đóng tài khoản token WSOL và trả SOL về một đích nhận lamport. Vòng đời đó có thể tạo ra lịch sử khó hiểu nếu bạn chỉ muốn trả lời một câu hỏi đơn giản như “bao nhiêu SOL đã được chuyển giữa ví này và người khác?” Một thao tác bọc hoặc mở bọc thường chuyển SOL giữa các tài khoản do cùng một chủ sở hữu kiểm soát. Nếu các hàng vòng đời này được hiển thị mặc định như những lượt chuyển thông thường, ứng dụng có thể đếm trùng hoạt động hoặc hiển thị nghiệp vụ ghi sổ nội bộ như các khoản thanh toán bên ngoài. Theo mặc định, 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àng unwrap SOL gốc khi các hàng vòng đời đóng tài khoản được trả về.
Sử dụng 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-2022 TransferCheckedWithFee đượ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.
  • harvestWithheldTokensToMint khô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.