> ## 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. # Tổng quan và hướng dẫn về getTransfersByAddress > Truy vấn các đối tượng chuyển token và SOL gốc đã được phân tích, dễ đọc cho một địa chỉ Solana, với các bộ lọc theo mint, thời gian, số lượng và đối tác. ## Tổng quan [`getTransfersByAddress`](/docs/vi/api-reference/rpc/http/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](/docs/vi/billing/plans) trở lên và tiêu tốn 10 tín dụng cho mỗi yêu cầu. 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. 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. 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ô. 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`](/docs/vi/rpc/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`](/docs/vi/api-reference/rpc/http/gettransaction) theo lô (xem [Truy xuất toàn bộ giao dịch cho các hàng chuyển](#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ế](#hạn-chế). ## Bắt đầu nhanh ```javascript theme={"system"} 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: ["86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"] }) }); const data = await response.json(); console.log(data.result.data); ``` ## 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í đó. Đị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). Đố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. 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. 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 Lọc theo địa chỉ mint token. Sử dụng `So11111111111111111111111111111111111111111` cho SOL gốc và `So11111111111111111111111111111111111111112` cho WSOL. 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. Các bộ lọc bổ sung cho số lượng, thời gian khối và slot. Số lượt chuyển tối đa cần trả về. Phạm vi: từ 1 đến 100. Con trỏ từ phản hồi trước để phân trang. Mức cam kết dữ liệu. * `finalized` * `confirmed` Slot tối thiểu mà tại đó yêu cầu có thể được đánh giá Thứ tự kết quả. * `desc`: mới nhất trước * `asc`: cũ nhất trước ## Phản hồi ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "result": { "data": [ { "signature": "5GEX7Q3X5Q8yJGbKYoR7mtzQmG8tpoEwzjPgqVmn3y5xg3yKwqXcDdN5YVcc9V6vA4TuH5iM6FHRVhTxvz4AX2zG", "slot": 315073428, "blockTime": 1736159420, "type": "transfer", "fromUserAccount": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx", "toUserAccount": "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", "fromTokenAccount": "HcvK3EJ74iM9g11cUgsaPvLSrhCvCwcrWxBNd87LsC1x", "toTokenAccount": "CBcYniR9G9CN3zGMnwNE4SWbqkYWvCFVreEob9xHnQCY", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": "2500000", "decimals": 6, "uiAmount": "2.5", "confirmationStatus": "finalized", "transactionIdx": 35, "instructionIdx": 1, "innerInstructionIdx": 0 } ], "paginationToken": "315073428:35:1:0:splTransfer" } } ``` ### 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. ```json theme={"system"} { "gt": 1000000, "gte": 1000000, "lt": 1000000000, "lte": 1000000000 } ``` | Bộ lọc | Kiểu | Mô tả | | ----------- | ------------------ | ----------------------------------------------------------------- | | `amount` | `ComparisonFilter` | Số lượng chuyển thô, không phải số lượng hiển thị trên giao diện. | | `blockTime` | `ComparisonFilter` | Dấu thời gian khối tính bằng giây Unix. | | `slot` | `ComparisonFilter` | Số slot. | ## 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 | Mô tả | `fromUserAccount` | `toUserAccount` | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----------------------------- | | `transfer` | Chuyển token tiêu chuẩn hoặc SOL giữa hai ví. | Người gửi | Người nhận | | `mint` | Token mới được mint vào một ví. | `null` | Người nhận | | `burn` | Token bị tiêu hủy vĩnh viễn. | Người gửi | `null` | | `wrap` | SOL được bọc thành WSOL. Bị loại trừ theo mặc định trong `solMode: "merged"`. | `null` | Chủ sở hữu | | `unwrap` | WSOL được mở bọc trở lại thành SOL gốc hoặc tiền thuê được thu hồi khi đóng tài khoản token. Bị loại trừ theo mặc định trong `solMode: "merged"`. | Chủ sở hữu | `null` hoặc đích nhận lamport | | `changeOwner` | Quyền sở hữu tài khoản token thay đổi bằng SetAuthority. | Chủ sở hữu cũ | Chủ sở hữu mới | | `withdrawWithheldFee` | Phí Token-2022 bị giữ lại được thu từ một mint hoặc các tài khoản. | `null` | Người nhận phí | ### Loại chuyển và lệnh | Loại chuyển | Các lệnh được hỗ trợ | Khả năng hiển thị mặc định | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | `transfer` | `SystemProgram::Transfer`, `SystemProgram::TransferWithSeed`, `SystemProgram::WithdrawNonceAccount`, `SystemProgram::CreateAccount`, `SystemProgram::CreateAccountWithSeed`, `SystemProgram::CreateAccountAllowPrefund` | Luôn luôn | | `transfer` | `Token::Transfer`, `Token::TransferChecked`, `Token-2022::Transfer`, `Token-2022::TransferChecked` | Luôn luôn | | `transfer` | `Token-2022::TransferCheckedWithFee`, với các trường `feeAmount` và `feeUiAmount` | Luôn luôn | | `mint` | `Token::MintTo`, `Token::MintToChecked` | Luôn luôn | | `burn` | `Token::Burn`, `Token::BurnChecked` | Luôn luôn | | `wrap` | `Token::SyncNative`, `Token::InitializeAccount`, `Token::InitializeAccount2`, `Token::InitializeAccount3` khi được dùng để xử lý vòng đời WSOL | Chỉ `solMode: "separate"` | | `unwrap` | `Token::CloseAccount` trên WSOL có số dư lớn hơn 0 | Chỉ `solMode: "separate"` | | `unwrap` | Thu hồi tiền thuê bằng `Token::CloseAccount` đối với tài khoản token không phải WSOL hoặc tài khoản WSOL có số dư token bằng 0 | Chỉ `solMode: "separate"` | | `changeOwner` | `Token::SetAuthority(AccountOwner)` | Luôn luôn | | `withdrawWithheldFee` | `Token-2022::WithdrawWithheldTokensFromMint`, `Token-2022::WithdrawWithheldTokensFromAccounts` | Luôn luôn | ## 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`. ```json theme={"system"} { "signature": "WcvF2eFxArpqRJySzDuiP6Xw8BMprWytMpYCxk2ExBt5C1WyxWzDWcCWXW8iKQVYR9AtdQxPE1uu1SMEZvbbhdr", "slot": 409259683, "blockTime": 1774635210, "type": "transfer", "fromUserAccount": "5aZZ4duJUKiMsJN9vRsoAn4SDX7agvKu7Q3QdFWRfWze", "toUserAccount": "FESSvM1cVUchc13XQY8e41oeYxMnyqQNYVZwoznfJsTo", "fromTokenAccount": "3VUYGjYktCzNhDVymNb3Z1iHewtfPFRvdA53qSWuxdXy", "toTokenAccount": "51cEFBA1virMuPqHXvNGs8FKKTMqeEVKzugv1hqPU2Zc", "mint": "CKfatsPMUf8SkiURsDXs7eK6GWb4Jsd6UDbs7twMCWxo", "amount": "48650000", "decimals": 5, "uiAmount": "486.5", "feeAmount": "13450000", "feeUiAmount": "134.5", "confirmationStatus": "finalized", "transactionIdx": 1315, "instructionIdx": 4, "innerInstructionIdx": 0 } ``` ## Ví dụ ### Lọc theo USDC ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } ] } ``` ### Các lượt chuyển đến từ một người gửi ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "with": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx", "direction": "in" } ] } ``` ### Phạm vi số lượng và thời gian ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "mint": "So11111111111111111111111111111111111111112", "filters": { "amount": { "gte": 1000000000, "lt": 10000000000 }, "blockTime": { "gte": 1735718400, "lt": 1738396800 } } } ] } ``` ### Yêu cầu được phân trang ```json theme={"system"} { "jsonrpc": "2.0", "id": "1", "method": "getTransfersByAddress", "params": [ "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", { "limit": 50, "paginationToken": "315069220:308:2:1:splTransfer" } ] } ``` ### 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`](/docs/vi/api-reference/rpc/http/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. ```javascript theme={"system"} const API_KEY = "YOUR_API_KEY"; const RPC_URL = `https://mainnet.helius-rpc.com/?api-key=${API_KEY}`; const OWNER_ADDRESS = "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"; async function rpc(method, params) { const response = await fetch(RPC_URL, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: "1", method, params }) }); const body = await response.json(); if (body.error) { throw new Error(body.error.message); } return body.result; } async function getAllTransfers(address) { const transfers = []; let paginationToken; do { const result = await rpc("getTransfersByAddress", [ address, { limit: 100, ...(paginationToken ? { paginationToken } : {}) } ]); transfers.push(...result.data); paginationToken = result.paginationToken; } while (paginationToken); return transfers; } async function getTransactionsInBatches(signatures, batchSize = 100) { const transactions = []; for (let i = 0; i < signatures.length; i += batchSize) { const batch = signatures.slice(i, i + batchSize).map((signature, index) => ({ jsonrpc: "2.0", id: `${i + index}`, method: "getTransaction", params: [ signature, { encoding: "jsonParsed", maxSupportedTransactionVersion: 1 } ] })); const response = await fetch(RPC_URL, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(batch) }); const results = await response.json(); for (const item of results) { if (item.error) { throw new Error(item.error.message); } transactions.push(item.result); } } return transactions; } const transfers = await getAllTransfers(OWNER_ADDRESS); const signatures = [...new Set(transfers.map((transfer) => transfer.signature))]; const transactions = await getTransactionsInBatches(signatures); console.log(`Fetched ${transfers.length} transfer rows`); console.log(`Fetched ${transactions.length} unique transactions`); ``` ## 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 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. Lược đồ yêu cầu và phản hồi đầy đủ cho getTransfersByAddress. Nạp bù và đồng bộ dữ liệu chuyển vào chỉ mục của riêng bạn. So sánh tất cả các phương thức dữ liệu lịch sử của Solana.