getTransfersByAddress: Lịch sử chuyển tiền trên Solana đã phân tích chỉ với 1 lệnh gọi

Tại sao cần một phương thức RPC dành riêng cho việc chuyển tiền?

Hầu hết sản phẩm ví, thanh toán và danh mục đầu tư không cần toàn bộ payload giao dịch. Chúng cần dữ liệu chuyển tiền.

Vậy họ làm gì? Mỗi đội ngũ viết một phiên bản khác nhau của cùng một trình phân tích chuyển tiền, và đáng tiếc là phần lớn đều xử lý sai các trường hợp biên.

Trước đây, để xây dựng lịch sử chuyển tiền rõ ràng trên Solana, nhà phát triển phải:

1. Lấy các chữ ký bằng getSignaturesForAddress
2. Truy xuất từng chữ ký bằng getTransaction
3. Phân tích số dư trước/sau, số dư token và các chỉ thị nội bộ
4. Tái dựng các lượt chuyển, xử lý sự khác biệt về phí giữa SPL Token và Token-2022, đồng thời loại bỏ dữ liệu nhiễu do bọc/mở bọc WSOL
5. Lặp lại trên nhiều trang, xử lý thử lại và lưu kết quả

Ngay cả khi phương thức getTransactionsForAddress gộp bước 1 và 2 vào một lệnh gọi, nhà phát triển vẫn phải tự thực hiện các bước 3–5.

Giờ đây, getTransfersByAddress thực hiện công việc này cho bạn và trả về kết quả dưới dạng danh sách có cấu trúc.

Phản hồi của getTransfersByAddress

Mỗi đối tượng chuyển tiền bao gồm chữ ký, slot, thời gian khối, loại chuyển, người gửi, người nhận, mint, số lượng (dạng thô và UI), số thập phân, trạng thái xác nhận và chỉ mục chỉ thị chính xác để bạn có thể ánh xạ từng lượt chuyển về giao dịch nguồn.

{
  "signature": "<TX_SIGNATURE>",
  "slot": 315073428,
  "blockTime": 1736159420,
  "type": "transfer",
  "fromUserAccount": "<SENDER_WALLET>",
  "toUserAccount": "<RECIPIENT_WALLET>",
  "fromTokenAccount": "<SENDER_TOKEN_ACCOUNT>",
  "toTokenAccount": "<RECIPIENT_TOKEN_ACCOUNT>",
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "2500000",
  "decimals": 6,
  "uiAmount": "2.5",
  "confirmationStatus": "finalized",
  "transactionIdx": 35,
  "instructionIdx": 1,
  "innerInstructionIdx": 0
}

Trường loại cho biết chính xác điều gì đã xảy ra — transfer, transferFee, mint, burn, wrap, unwrap, changeAccountOwner hoặc withdrawWithheldFee — nên bạn không cần suy luận hành vi từ dữ liệu chương trình thô.

Tại sao việc phân tích các lượt chuyển trên Solana lại khó?

Một lượt chuyển trong giao dịch Solana không phải là một khái niệm đơn nhất.

Đây là một danh mục ẩn chứa nhiều trường hợp biên, và chỉ cần xử lý sai một trường hợp cũng sẽ làm hỏng dữ liệu của bạn.

SOL và WSOL

SOL gốc và Wrapped SOL trông giống như cùng một tài sản đối với người dùng, nhưng chúng nằm ở các phần khác nhau của giao dịch.

SOL gốc di chuyển thông qua số dư lamport trước/sau trên các tài khoản hệ thống. WSOL di chuyển thông qua số dư SPL token trên các tài khoản token.

Người dùng thực hiện hoán đổi trên Jupiter có thể bọc SOL thành WSOL, đổi WSOL lấy USDC rồi không bao giờ mở bọc — để lại một tài khoản token WSOL.

Từ góc nhìn của người dùng, họ đã chi SOL. Từ góc nhìn của mạng, đã có ba lượt chuyển và một thao tác bọc.

Tệ hơn nữa, bản thân thao tác bọc không phải là chuyển cho một chủ sở hữu khác — cùng một ví chỉ đang chuyển lamport vào tài khoản token của chính nó. Tính thao tác này là một lượt chuyển sẽ ghi nhận trùng hoạt động của người dùng.

Phí chuyển Token-2022

Token-2022 đã giới thiệu TransferCheckedWithFee, trong đó khoản ghi nợ của người gửi không khớp với khoản ghi có của người nhận.

Phần chênh lệch được giữ lại trong tài khoản token của người nhận dưới dạng phí và sau đó có thể được thanh toán cho cơ quan quản lý phí thông qua withdrawWithheldFee.

Một trình phân tích đơn giản chỉ thấy một lượt chuyển và xác định sai số lượng. Một trình phân tích cẩn thận sẽ phát hiện phần mở rộng phí, tách chỉ thị thành một lượt chuyển và một khoản phí giữ lại được tích lũy, đồng thời theo dõi riêng tài khoản phí.

Mint và đốt token

Token được mint vào một tài khoản không có người gửi. Token bị đốt không có người nhận. Cả hai đều trông giống như "lượt chuyển" trong phần chênh lệch số dư trước/sau, nhưng việc đánh đồng chúng với chuyển tiền giữa các ví sẽ làm sai lệch dữ liệu phân tích đối tác giao dịch — bạn sẽ thấy các ví "nhận" tiền từ địa chỉ zero và "gửi" tiền vào hư không.

getTransfersByAddress biểu diễn những trường hợp này bằng các loại mint và burn, với fromUserAccount hoặc toUserAccount được đặt thành null, để bạn có thể bao gồm hoặc loại trừ chúng tùy theo sản phẩm đang xây dựng.

Lợi ích của getTransfersByAddress

Phương thức getTransfersByAddress chấp nhận các bộ lọc mà trước đây yêu cầu truy xuất và phân tích toàn bộ lịch sử giao dịch ở phía máy khách. 

Tìm kiếm theo mint

Chỉ trả về các lượt chuyển của một token cụ thể.

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getTransfersByAddress",
  "params": [
    "<WALLET_ADDRESS>",
    { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }
  ]
}

Tìm kiếm theo số lượng

Lọc theo số lượng thô bằng các phép so sánh gt, gte, lt, lte. Hữu ích để phát hiện cá voi, bỏ qua số dư vụn (tức các tài khoản có lượng token không đáng kể) hoặc đánh dấu hoạt động bất thường.

{
  "params": [
    "<WALLET_ADDRESS>",
    {
      "mint": "So11111111111111111111111111111111111111112",
      "filters": {
        "amount": { "gte": 1000000000, "lt": 10000000000 }
      }
    }
  ]
}

Tìm kiếm theo thời gian

Thời gian khối được hỗ trợ dưới dạng khoảng dấu thời gian Unix. Khoảng slot hoạt động tương tự cho các truy vấn cần độ chính xác đến từng slot.

{
  "params": [
    "<WALLET_ADDRESS>",
    {
      "filters": {
        "blockTime": { "gte": 1735718400, "lt": 1738396800 }
      }
    }
  ]
}

Tìm kiếm theo đối tác giao dịch

Kết hợp các tham số with và direction để truy vấn các lượt chuyển giữa hai ví cụ thể theo một trong hai hướng.

{
  "params": [
    "<WALLET_ADDRESS>",
    {
      "with": "<COUNTERPARTY_WALLET>",
      "direction": "in"
    }
  ]
}

Chế độ SOL

Vì SOL gốc và WSOL xuất hiện khác nhau trên Solana nhưng thường có cùng ý nghĩa với người dùng, phương thức getTransfersByAddress cung cấp tham số solMode.

merged (mặc định)

WSOL được xử lý như SOL gốc.

Các hàng bọc và mở bọc bị loại trừ, còn truy vấn theo mint SOL gốc sẽ trả về cả các lượt chuyển SOL gốc và WSOL.

separate

Trong chế độ này, WSOL được giữ lại dưới dạng một mint riêng biệt, đồng thời các hàng trong vòng đời bọc và mở bọc được đưa vào để có thể kiểm tra đầy đủ.

Hầu hết trường hợp sử dụng cho sản phẩm thường sẽ phù hợp với merged. Hoạt động đối soát, kế toán và phân tích cấp giao thức thường cần separate.

Phân trang và sắp xếp

Phân trang tiêu chuẩn dựa trên con trỏ thông qua paginationToken, tối đa 100 bản ghi mỗi trang. sortOrder chấp nhận asc và desc.

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getTransfersByAddress",
  "params": [
    "<WALLET_ADDRESS>",
    { "limit": 50, "paginationToken": "315069220:308:2:1" }
  ]
}

Khi nào nên dùng getTransfersByAddress

getTransfersByAddress và getTransactionsForAddress tương tự nhau nhưng phục vụ các mục đích riêng biệt. 

Bắt đầu

Phương thức getTransfersByAddress hiện có trên tất cả các gói trả phí, bắt đầu từ gói Developer. Mỗi yêu cầu tốn 10 tín dụng và được tính vào nhóm giới hạn tốc độ RPC tiêu chuẩn của bạn.

Sử dụng phương thức này với URL Helius RPC hiện có của bạn:

const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "1",
    method: "getTransfersByAddress",
    params: ["<WALLET_ADDRESS>"]
  })
});

const data = await response.json();
console.log(data.result.data);

Đọc tài liệu tham chiếu API để biết đầy đủ thông tin về tham số và phản hồi.