> ## 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.
# Ikhtisar dan Tutorial getTransfersByAddress
> Kueri objek transfer token dan SOL native yang telah diuraikan dan mudah dibaca untuk suatu alamat Solana, dengan filter berdasarkan mint, waktu, jumlah, dan pihak lawan.
## Ikhtisar
[`getTransfersByAddress`](/docs/id/api-reference/rpc/http/gettransfersbyaddress) adalah metode RPC eksklusif Helius yang mengembalikan objek transfer token dan SOL native yang telah diuraikan dan mudah dibaca untuk suatu alamat dompet. Metode ini bukan bagian dari RPC Solana standar.
Metode ini berfokus pada aktivitas transfer, sehingga mengembalikan catatan transfer ringkas, bukan payload transaksi lengkap. Setiap catatan dinormalisasi dengan akun pemilik dan token yang telah diuraikan, mint, jumlah mentah, desimal, jumlah UI, posisi instruksi, dan status konfirmasi. Dengan demikian, Anda dapat merekonsiliasi pergerakan saldo tanpa mengimplementasikan ulang penguraian token Solana.
Metode ini memerlukan [paket Developer](/docs/id/billing/plans) atau yang lebih tinggi dan dikenai biaya 10 kredit per permintaan.
Mengembalikan catatan transfer yang mudah dibaca dengan akun, jumlah, desimal, dan jenis transfer yang telah diuraikan.
Memodelkan SOL, WSOL, biaya Token-2022, mint, burn, dan perubahan pemilik akun agar saldo dapat direkonsiliasi secara akurat.
Mempersempit riwayat transfer berdasarkan alamat mint, rentang waktu blok, atau rentang jumlah mentah.
Memfilter transfer berdasarkan pengirim atau penerima dengan `with` dan `direction`.
## Kapan perlu menggunakannya
Gunakan `getTransfersByAddress` saat Anda memerlukan:
* Riwayat transfer dompet untuk pembayaran atau pemantauan transfer
* Aktivitas portofolio dan analitik pergerakan token
* Rekonsiliasi saldo yang dapat diandalkan untuk buku besar dan akuntansi
* Laporan transfer khusus pihak lawan (siapa yang mengirim atau menerima apa)
* Penanganan SOL/WSOL, biaya Token-2022, mint, dan burn yang dinormalisasi tanpa menulis parser
Sebagai gantinya, gunakan [`getTransactionsForAddress`](/docs/id/rpc/gettransactionsforaddress) saat Anda memerlukan data transaksi lengkap, riwayat yang hanya berisi tanda tangan, atau aktivitas selain transfer. Pola yang umum adalah menelusuri transfer per halaman di sini, lalu mengambil transaksi lengkap yang mendasarinya dengan panggilan [`getTransaction`](/docs/id/api-reference/rpc/http/gettransaction) secara batch (lihat [Ambil transaksi lengkap untuk baris transfer](#ambil-transaksi-lengkap-untuk-baris-transfer)).
## Akurasi dan rekonsiliasi
`getTransfersByAddress` dibuat untuk aplikasi yang memerlukan riwayat transfer yang dapat diandalkan untuk buku besar, pelacakan pembayaran, aktivitas portofolio, dan rekonsiliasi saldo. Alih-alih mengembalikan payload transaksi mentah dan menyerahkan setiap kasus khusus kepada parser Anda, API mengembalikan objek transfer yang dinormalisasi.
Respons secara eksplisit memodelkan kasus transfer yang umumnya menyulitkan rekonsiliasi riwayat Solana:
* Transfer token SPL standar dan SOL native.
* Transfer Token-2022 dengan biaya yang ditahan, yang direpresentasikan sebagai baris `transfer` biasa dengan kolom biaya terpisah.
* Mint dan burn, yang direpresentasikan sebagai transfer dengan pengirim atau penerima `null`.
* Perilaku wrapping dan unwrapping SOL, dengan mode default yang dirancang untuk menghindari baris siklus hidup yang tidak diperlukan.
* Perubahan pemilik akun token melalui SetAuthority.
* Penarikan biaya Token-2022 yang ditahan.
* Alur akun perantara, yang dikembalikan sebagai catatan transfer yang mendasarinya, bukan digabungkan menjadi perkiraan pergerakan bersih.
Untuk peristiwa transfer terlihat yang didukung, hal ini memungkinkan Anda merekonsiliasi pergerakan saldo tanpa mengimplementasikan ulang logika penguraian token Solana. Pengecualian yang diketahui, seperti pergerakan SOL tersembunyi yang hanya disimpulkan dari perubahan saldo, dijelaskan dalam [Batasan](#batasan).
## Mulai cepat
```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);
```
## Parameter permintaan
Masukkan alamat pemilik dompet, bukan associated token account (ATA). API menemukan aktivitas transfer untuk akun token yang dimiliki dompet tersebut.
Alamat dompet pemilik dengan pengodean Base58 yang transfernya akan dikueri. Masukkan alamat pemilik dompet, bukan associated token account (ATA).
Objek konfigurasi opsional untuk pemfilteran, paginasi, komitmen, pengurutan, serta perilaku SOL/WSOL.
Filter berdasarkan alamat pihak lawan. Hanya mengembalikan transfer ke atau dari alamat ini.
Filter berdasarkan arah transfer relatif terhadap `address`.
* `in`: transfer yang diterima oleh `address`
* `out`: transfer yang dikirim oleh `address`
* `any`: transfer masuk dan keluar
Filter berdasarkan alamat mint token. Gunakan `So11111111111111111111111111111111111111111` untuk SOL native dan `So11111111111111111111111111111111111111112` untuk WSOL.
Mengontrol cara SOL native dan WSOL direpresentasikan.
* `merged`: WSOL diperlakukan sebagai SOL native. Baris siklus hidup wrap dan unwrap dikecualikan, dan nilai mint WSOL ditulis ulang menjadi mint SOL native.
* `separate`: WSOL dipertahankan sebagai mint yang berbeda, dan baris siklus hidup wrap dan unwrap disertakan.
Filter tambahan untuk jumlah, waktu blok, dan slot.
Jumlah maksimum transfer yang akan dikembalikan. Rentang: 1 hingga 100.
Kursor dari respons sebelumnya untuk paginasi.
Tingkat komitmen data.
* `finalized`
* `confirmed`
Slot minimum tempat permintaan dapat dievaluasi
Urutan hasil.
* `desc`: terbaru terlebih dahulu
* `asc`: terlama terlebih dahulu
## Respons
```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"
}
}
```
### Detail kolom respons
* `fromUserAccount` dan `toUserAccount` selalu ada. Jika salah satu sisi tidak ada, nilainya adalah `null`.
* `fromTokenAccount` dan `toTokenAccount` hanya disertakan saat endpoint akun token relevan untuk baris tersebut. Keduanya sepenuhnya dihilangkan untuk transfer SOL native.
* Transfer mint bersifat satu sisi: `fromUserAccount` adalah `null`, dan transfer tersebut hanya dapat dikembalikan sebagai transfer masuk bagi penerima.
* Transfer burn bersifat satu sisi: `toUserAccount` adalah `null`, dan transfer tersebut hanya dapat dikembalikan sebagai transfer keluar bagi pemilik yang melakukan burn.
## Filter
Gunakan filter perbandingan untuk kueri rentang numerik. Semua kolom perbandingan bersifat opsional dan dapat digabungkan.
```json theme={"system"}
{
"gt": 1000000,
"gte": 1000000,
"lt": 1000000000,
"lte": 1000000000
}
```
| Filter | Jenis | Deskripsi |
| ----------- | ------------------ | ---------------------------------------- |
| `amount` | `ComparisonFilter` | Jumlah transfer mentah, bukan jumlah UI. |
| `blockTime` | `ComparisonFilter` | Stempel waktu blok dalam detik Unix. |
| `slot` | `ComparisonFilter` | Nomor slot. |
## Jenis transfer
Kolom `type` mengidentifikasi perilaku transfer yang direpresentasikan oleh setiap baris.
| Jenis | Deskripsi | `fromUserAccount` | `toUserAccount` |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | -------------------------- |
| `transfer` | Transfer token atau SOL standar antara dua dompet. | Pengirim | Penerima |
| `mint` | Token baru yang dicetak ke dompet. | `null` | Penerima |
| `burn` | Token yang dimusnahkan secara permanen. | Pengirim | `null` |
| `wrap` | SOL yang di-wrap menjadi WSOL. Secara default dikecualikan dalam `solMode: "merged"`. | `null` | Pemilik |
| `unwrap` | WSOL yang di-unwrap kembali menjadi SOL native, atau rent yang diperoleh kembali dari penutupan akun token. Secara default dikecualikan dalam `solMode: "merged"`. | Pemilik | `null` atau tujuan lamport |
| `changeOwner` | Kepemilikan akun token diubah dengan SetAuthority. | Pemilik lama | Pemilik baru |
| `withdrawWithheldFee` | Biaya Token-2022 yang ditahan dan dikumpulkan dari mint atau akun. | `null` | Penerima biaya |
### Jenis transfer dan instruksi
| Jenis transfer | Instruksi yang dicakup | Visibilitas default |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `transfer` | `SystemProgram::Transfer`, `SystemProgram::TransferWithSeed`, `SystemProgram::WithdrawNonceAccount`, `SystemProgram::CreateAccount`, `SystemProgram::CreateAccountWithSeed`, `SystemProgram::CreateAccountAllowPrefund` | Selalu |
| `transfer` | `Token::Transfer`, `Token::TransferChecked`, `Token-2022::Transfer`, `Token-2022::TransferChecked` | Selalu |
| `transfer` | `Token-2022::TransferCheckedWithFee`, dengan kolom `feeAmount` dan `feeUiAmount` | Selalu |
| `mint` | `Token::MintTo`, `Token::MintToChecked` | Selalu |
| `burn` | `Token::Burn`, `Token::BurnChecked` | Selalu |
| `wrap` | `Token::SyncNative`, `Token::InitializeAccount`, `Token::InitializeAccount2`, `Token::InitializeAccount3` saat digunakan untuk penanganan siklus hidup WSOL | Hanya `solMode: "separate"` |
| `unwrap` | `Token::CloseAccount` pada WSOL dengan saldo lebih besar dari nol | Hanya `solMode: "separate"` |
| `unwrap` | Pemulihan rent `Token::CloseAccount` untuk akun token non-WSOL, atau akun WSOL dengan saldo token nol | Hanya `solMode: "separate"` |
| `changeOwner` | `Token::SetAuthority(AccountOwner)` | Selalu |
| `withdrawWithheldFee` | `Token-2022::WithdrawWithheldTokensFromMint`, `Token-2022::WithdrawWithheldTokensFromAccounts` | Selalu |
## Perilaku SOL dan wSOL
SOL tersedia di Solana dalam dua bentuk yang sering muncul bersama dalam aktivitas pengguna nyata:
* **SOL native** adalah aset native rantai. Aset ini berada langsung di dompet atau akun sebagai lamport. Satu SOL setara dengan 1.000.000.000 lamport.
* **Wrapped SOL (WSOL, sering ditulis wSOL)** adalah representasi token SPL dari SOL. Aset ini menggunakan mint WSOL `So11111111111111111111111111111111111111112` dan berada dalam akun token, seperti USDC atau token SPL lainnya.
Pengguna dan aplikasi melakukan wrap pada SOL saat mereka memerlukan SOL untuk berperilaku seperti token SPL, biasanya untuk DeFi, swap, akuntansi berbasis akun token, atau antarmuka program yang hanya menerima token SPL. Proses wrapping biasanya mendanai akun token dengan SOL native dan menyinkronkannya menjadi WSOL. Proses unwrapping menutup akun token WSOL dan mengembalikan SOL ke tujuan lamport.
Siklus hidup tersebut dapat menghasilkan riwayat yang membingungkan jika Anda mencoba menjawab pertanyaan sederhana seperti "berapa banyak SOL yang berpindah antara dompet ini dan pihak lain?" Proses wrap atau unwrap sering memindahkan SOL di antara akun yang dikendalikan oleh pemilik yang sama. Jika baris siklus hidup tersebut ditampilkan secara default sebagai transfer biasa, aplikasi dapat menghitung aktivitas dua kali atau menampilkan pembukuan internal sebagai pembayaran eksternal.
Secara default, `getTransfersByAddress` menggunakan `solMode: "merged"`. Dalam mode ini:
* SOL native dan WSOL diperlakukan sebagai satu aset SOL saat melakukan kueri berdasarkan `So11111111111111111111111111111111111111111`.
* Baris transfer WSOL dinormalisasi ke mint SOL native agar riwayat dalam denominasi SOL lebih mudah direkonsiliasi.
* Baris siklus hidup wrap dan unwrap dikecualikan karena biasanya merepresentasikan pergerakan antara akun yang dikendalikan oleh pemilik yang sama, bukan pembayaran kepada pengguna lain.
* Transfer SOL dan WSOL antara pemilik yang berbeda tetap direpresentasikan sebagai transfer.
* Rent yang diperoleh kembali dari `CloseAccount` direpresentasikan sebagai baris `unwrap` SOL native saat baris siklus hidup penutupan akun dikembalikan.
Gunakan `solMode: "separate"` saat Anda memerlukan WSOL sebagai mint token SPL yang berbeda atau ingin memeriksa catatan siklus hidup wrap dan unwrap. Dalam mode ini, WSOL mempertahankan mint `So11111111111111111111111111111111111111112`, dan catatan wrap/unwrap dikembalikan dengan `type: "wrap"` atau `type: "unwrap"`.
Untuk penutupan akun WSOL dalam `solMode: "separate"`, catatan `unwrap` untuk mint WSOL merepresentasikan sisa saldo token WSOL yang dikembalikan sebagai SOL. Rent yang dikembalikan dari akun token yang ditutup akan dikembalikan sebagai baris `unwrap` SOL native terpisah.
## Biaya transfer Token-2022
Instruksi `TransferCheckedWithFee` Token-2022 direpresentasikan sebagai satu catatan transfer dengan `type: "transfer"`. Jumlah tujuan dikembalikan dalam `amount`; detail biaya yang ditahan dikembalikan dalam `feeAmount` dan `feeUiAmount`.
Untuk transfer dengan biaya, `amount + feeAmount` didebit dari sumber, sedangkan `amount` dikreditkan ke tujuan.
```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
}
```
## Contoh
### Filter berdasarkan USDC
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
"method": "getTransfersByAddress",
"params": [
"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
{
"mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
]
}
```
### Transfer masuk dari pengirim
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
"method": "getTransfersByAddress",
"params": [
"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
{
"with": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx",
"direction": "in"
}
]
}
```
### Rentang jumlah dan waktu
```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
}
}
}
]
}
```
### Permintaan dengan paginasi
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
"method": "getTransfersByAddress",
"params": [
"86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
{
"limit": 50,
"paginationToken": "315069220:308:2:1:splTransfer"
}
]
}
```
### Ambil transaksi lengkap untuk baris transfer
`getTransfersByAddress` mengembalikan baris transfer yang telah diuraikan, bukan payload transaksi lengkap. Jika Anda memerlukan transaksi lengkap untuk setiap transfer, telusuri transfer per halaman terlebih dahulu, hapus duplikat berdasarkan `signature`, lalu ambil transaksi lengkap dengan panggilan [`getTransaction`](/docs/id/api-reference/rpc/http/gettransaction) secara batch.
`getTransfersByAddress` tidak dapat dijalankan secara batch untuk beberapa alamat pemilik. Kueri satu alamat pemilik pada satu waktu, lalu jalankan permintaan `getTransaction` yang dihasilkan secara batch berdasarkan tanda tangan. Satu transaksi dapat menghasilkan beberapa baris transfer, jadi selalu hapus tanda tangan duplikat sebelum mengambil transaksi.
```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`);
```
## Batasan
* Transaksi yang gagal tidak disertakan dalam V1.
* Pergerakan SOL tersembunyi yang hanya disimpulkan dari perubahan saldo tidak didukung dalam V1.
* `harvestWithheldTokensToMint` tidak didukung dalam V1 karena tidak menunjukkan jumlah yang dikumpulkan.
* Alur akun perantara tidak disederhanakan. Jika transaksi memindahkan dana melalui akun perantara, catatan transfer yang mendasarinya akan dikembalikan.
* Tidak dapat dijalankan secara batch untuk beberapa alamat pemilik. Kueri satu pemilik pada satu waktu.
## Langkah berikutnya
Riwayat transaksi lengkap dengan dukungan pemfilteran, pengurutan, dan akun token.
Skema permintaan dan respons lengkap untuk getTransfersByAddress.
Lakukan backfill dan sinkronkan data transfer ke indeks Anda sendiri.
Bandingkan semua metode data historis Solana.