Ikhtisar dan Tutorial getTransfersByAddress

Ikhtisar

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 atau yang lebih tinggi dan dikenai biaya 10 kredit per permintaan.

Parsed transfer objects

Mengembalikan catatan transfer yang mudah dibaca dengan akun, jumlah, desimal, dan jenis transfer yang telah diuraikan.

Reconciliation ready

Memodelkan SOL, WSOL, biaya Token-2022, mint, burn, dan perubahan pemilik akun agar saldo dapat direkonsiliasi secara akurat.

Mint, time, and amount filters

Mempersempit riwayat transfer berdasarkan alamat mint, rentang waktu blok, atau rentang jumlah mentah.

Counterparty filters

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 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 secara batch (lihat 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.

Mulai cepat

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.

string

wajib

Alamat dompet pemilik dengan pengodean Base58 yang transfernya akan dikueri. Masukkan alamat pemilik dompet, bukan associated token account (ATA).

object

Objek konfigurasi opsional untuk pemfilteran, paginasi, komitmen, pengurutan, serta perilaku SOL/WSOL.

string

Filter berdasarkan alamat pihak lawan. Hanya mengembalikan transfer ke atau dari alamat ini.

string

default:"any"

Filter berdasarkan arah transfer relatif terhadap address.

in: transfer yang diterima oleh address
out: transfer yang dikirim oleh address
any: transfer masuk dan keluar

string

Filter berdasarkan alamat mint token. Gunakan So11111111111111111111111111111111111111111 untuk SOL native dan So11111111111111111111111111111111111111112 untuk WSOL.

string

default:"merged"

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.

object

Filter tambahan untuk jumlah, waktu blok, dan slot.

number

default:"100"

Jumlah maksimum transfer yang akan dikembalikan. Rentang: 1 hingga 100.

string

Kursor dari respons sebelumnya untuk paginasi.

string

default:"finalized"

Tingkat komitmen data.

finalized
confirmed

number

Slot minimum tempat permintaan dapat dievaluasi

string

default:"desc"

Urutan hasil.

desc: terbaru terlebih dahulu
asc: terlama terlebih dahulu

Respons

{
  "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.

{
  "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.

{
  "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

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getTransfersByAddress",
  "params": [
    "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  ]
}

Transfer masuk dari pengirim

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getTransfersByAddress",
  "params": [
    "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
    {
      "with": "7hPhaUpydpvm8wtiS3k4LPZKUmivQRs7YQmpE1hFshHx",
      "direction": "in"
    }
  ]
}

Rentang jumlah dan waktu

{
  "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

{
  "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 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.

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

getTransactionsForAddress

Riwayat transaksi lengkap dengan dukungan pemfilteran, pengurutan, dan akun token.

API reference

Skema permintaan dan respons lengkap untuk getTransfersByAddress.

Indexing guide

Lakukan backfill dan sinkronkan data transfer ke indeks Anda sendiri.

Historical data overview

Bandingkan semua metode data historis Solana.

Memulai

Streaming Data & Pemantauan Peristiwa

API Data & RPC

Perdagangan

Mengirim Transaksi

Dompet sebagai Layanan

Privasi

Sumber Daya

Ikhtisar dan Tutorial getTransfersByAddress

Ikhtisar

Parsed transfer objects

Reconciliation ready

Mint, time, and amount filters

Counterparty filters

Kapan perlu menggunakannya

Akurasi dan rekonsiliasi

Mulai cepat

Parameter permintaan

Respons

Detail kolom respons

Filter

Jenis transfer

Jenis transfer dan instruksi

Perilaku SOL dan wSOL

Biaya transfer Token-2022

Contoh

Filter berdasarkan USDC

Transfer masuk dari pengirim

Rentang jumlah dan waktu

Permintaan dengan paginasi

Ambil transaksi lengkap untuk baris transfer

Batasan

Langkah berikutnya

getTransactionsForAddress

API reference

Indexing guide

Historical data overview

​Ikhtisar

Parsed transfer objects

Reconciliation ready

Mint, time, and amount filters

Counterparty filters

​Kapan perlu menggunakannya

​Akurasi dan rekonsiliasi

​Mulai cepat

​Parameter permintaan

​Respons

​Detail kolom respons

​Filter

​Jenis transfer

​Jenis transfer dan instruksi

​Perilaku SOL dan wSOL

​Biaya transfer Token-2022

​Contoh

​Filter berdasarkan USDC

​Transfer masuk dari pengirim

​Rentang jumlah dan waktu

​Permintaan dengan paginasi

​Ambil transaksi lengkap untuk baris transfer

​Batasan

​Langkah berikutnya

getTransactionsForAddress

API reference

Indexing guide

Historical data overview

Ikhtisar

Kapan perlu menggunakannya

Akurasi dan rekonsiliasi

Mulai cepat

Parameter permintaan

Respons

Detail kolom respons

Filter

Jenis transfer

Jenis transfer dan instruksi

Perilaku SOL dan wSOL

Biaya transfer Token-2022

Contoh

Filter berdasarkan USDC

Transfer masuk dari pengirim

Rentang jumlah dan waktu

Permintaan dengan paginasi

Ambil transaksi lengkap untuk baris transfer

Batasan

Langkah berikutnya