Memperkenalkan Parsed Events Scan API

Memindai Berdasarkan Instruksi Program Solana

Permintaan berikut memindai riwayat Program Pump.fun dan mengembalikan transaksi terurai yang berisi instruksi buy atau sell:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "match": {
      "programs": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "instructions": ["buy", "sell"]
        }
      ]
    },
    "limit": 100
  }'

Dengan permintaan ini, alat demo Parsed Events Scan memindai 261 catatan dan menemukan 100 kecocokan. Alat tersebut mengembalikan 100 peristiwa terbaru dalam 182 md, dengan total biaya hanya 11 kredit:

Nama instruksi dapat menggunakan ejaan dari versi IDL program mana pun yang diketahui atau format snake_case. Parsed Events Scan API memeriksa instruksi tingkat teratas maupun instruksi internal yang dipanggil melalui Cross-program Invocations (CPI).

Program sering memiliki beberapa versi untuk tindakan tertentu. Misalnya, IDL Pump.fun memiliki instruksi buy, buy_exact_sol_in, buy_v2, buy_exact_quote_in_v2, sell, dan sell_v2. Scan API memungkinkan Anda mencantumkan setiap nama instruksi yang ingin dicocokkan.

Aktivitas beli dan jual mencakup sebagian besar aktivitas Pump.fun, sehingga pencocokan berlangsung cukup cepat. Scan memberikan penghematan lebih besar ketika aktivitas yang Anda perlukan jarang terjadi. Misalnya, biaya kreator hanya mencakup sebagian kecil transaksi program:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
    "match": {
      "programs": [
        {
          "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
          "instructions": ["collect_creator_fee"]
        }
      ]
    },
    "limit": 10
  }'

Dengan menggunakan alat demo Parsed Events Scan untuk menemukan sepuluh klaim terbaru, kita dapat melihat bahwa alat ini memindai 3.402 transaksi dalam 182 md dan memerlukan 14 kredit untuk permintaan ini:

Panggilan getTransactionsForAddress yang sebanding akan memerlukan 350 kredit, 25x lebih mahal dibandingkan endpoint pemindaian.

Bagaimana jika program Solana tidak memiliki IDL dengan instruksi bernama?

Untuk menggunakan Parsed Events Scan API dengan program Solana yang tidak memiliki IDL, Anda dapat melakukan pencocokan menggunakan prefiks data instruksi.

Setiap diskriminator dapat berisi satu hingga delapan byte yang dienkode dalam format heksadesimal. Anda dapat menggabungkan nama dan diskriminator untuk satu program; sebuah instruksi akan cocok dengan salah satunya. Contoh:

{
  "match": {
    "programs": [
      {
        "programId": "<PROGRAM_ADDRESS>",
        "discriminators": ["0x66063d1201daebea"]
      }
    ]
  }
}

Memindai Beberapa Program Solana Sekaligus

Anda dapat mencantumkan hingga 20 program dalam satu permintaan Parsed Events Scan API, dan sebuah transaksi dianggap cocok ketika memanggil salah satunya.

Misalnya, permintaan ini memindai perdagangan sebuah dompet untuk mencari kecocokan di Jupiter, DFlow, dan Pump.fun dalam satu pemindaian:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instructions": ["route", "shared_accounts_route", "route_v2", "shared_accounts_route_v2"]
      },
      { "programId": "DF1ow4tspfHX9JwWJsAb9epbkA8hmpSEAtxXy1V27QBH" },
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2", "sell", "sell_v2"]
      }
    ]
  }
}

Memindai Berdasarkan Mint Token

Scan API juga dapat menemukan transaksi yang melibatkan mint token tertentu dengan memeriksa saldo token sebelum dan sesudah transaksi untuk alamat mint tersebut. Secara default, API hanya menghitung saldo milik alamat yang dipindai.

Saat memindai dompet untuk sebuah token, atur tokenAccounts menjadi balanceChanged. Dalam berbagai kasus, transfer token masuk hanya melibatkan akun token dompet, bukan dompet itu sendiri. Karena itu, riwayat dompet secara default tidak menyertakan transaksi tersebut.

Misalnya, permintaan ini menemukan aktivitas wSOL milik Ansem selama September 2026:

curl --request POST \
  --url "https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=$HELIUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "address": "<ANSEM_WALLET_ADDRESS>",
    "match": {
      "mints": [{ "mint": "So11111111111111111111111111111111111111112" }]
    },
    "tokenAccounts": "balanceChanged",
    "time": {
      "gte": 1788220800,
      "lte": 1790812800
    }
  }'

Scan API menemukan 53 transaksi yang cocok setelah memindai total 7.555 transaksi:

Menggabungkan Program dan Mint

Developer dapat mengatur programs dan mints untuk mempersempit hasil. Saat digabungkan, transaksi harus memenuhi kedua kriteria agar cocok. Namun, untuk mempersempit aktivitas program ke satu token, alamat yang dipindai lebih penting daripada filternya.

Misalnya, pindai alamat mint token alih-alih program Pump.fun untuk menemukan setiap perdagangan Pump.fun bagi token tertentu. Setiap pembelian atau penjualan mencantumkan mint sebagai akun sehingga akan cocok secara default:

{
  "address": "<MINT_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2", "sell", "sell_v2"]
      }
    ]
  }
}

Riwayat mint hanya berisi aktivitas token tersebut, sedangkan riwayat program berisi perdagangan untuk setiap token. Karena itu, memindai riwayat program akan menghabiskan anggaran untuk transaksi yang tidak relevan.

Memilih Cakupan Kecocokan

Secara default, instruksi program dan saldo token suatu mint hanya dihitung jika melibatkan alamat yang dipindai. Saldo token melibatkan alamat tersebut jika alamat itu memiliki akun token, atau jika alamat itu merupakan mint saldo tersebut. Sebuah instruksi melibatkan alamat tersebut ketika:

• Salah satu akunnya adalah alamat tersebut
• Salah satu akunnya adalah akun token milik alamat tersebut
• Alamat tersebut adalah mint, dan salah satu akun instruksi merupakan akun token untuk mint tersebut
• Alamat tersebut adalah program yang dipanggil

Atur "scope": "transaction" pada program atau mint untuk menghitungnya di bagian mana pun dalam transaksi. Gunakan ini ketika alamat hanya membayar biaya, mengeksekusi tx multisig, atau bukan merupakan akun dari instruksi yang Anda cocokkan.

Misalnya, permintaan ini menemukan transaksi sebuah token yang juga memindahkan USDC. Dalam cakupan default, saldo USDC harus menjadi milik alamat mint sehingga tidak ada yang akan cocok:

{
  "address": "<MINT_ADDRESS>",
  "match": {
    "mints": [
      { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "scope": "transaction" }
    ]
  },
  "returnShape": "signatures"
}

Program juga menerima cakupan kecocokan yang sama. Permintaan ini menemukan swap Jupiter yang biayanya dibayar oleh relayer.

Relayer hanya menandatangani transaksi sebagai pembayar biaya sehingga bukan merupakan salah satu akun instruksi rute. Karena itu, tidak satu pun transaksi ini akan cocok dalam cakupan default:

{
  "address": "<RELAYER_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
        "instructions": ["route", "shared_accounts_route", "route_v2", "shared_accounts_route_v2"],
        "scope": "transaction"
      }
    ]
  },
  "returnShape": "signatures"
}

Logika yang sama berlaku untuk anggota multisig yang mengeksekusi proposal. Instruksi yang dijalankan multisig beroperasi pada akun vault, bukan akun anggota. Karena itu, memindai riwayat anggota untuk instruksi tersebut memerlukan cakupan transaction.

Melacak SOL Native

SOL native tidak memiliki saldo token sehingga pemindaian mencocokkannya berdasarkan lamport.

Berikan mint SOL native (So11111111111111111111111111111111111111111), yang berbeda dari wrapped SOL. Sebuah transaksi dianggap cocok ketika saldo SOL alamat yang dipindai berubah, tanpa menghitung biaya yang dibayarnya:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "mints": [{ "mint": "So11111111111111111111111111111111111111111" }]
  },
  "time": { "gte": 1788220800, "lt": 1790812800 }
}

Ini menangkap SOL yang dibayarkan program tanpa instruksi transfer, seperti penjualan Pump.fun. Ini juga menangkap pergerakan insidental seperti tip Jito serta biaya sewa yang dibayarkan untuk atau dikembalikan dari akun.

Mendapatkan Transaksi Terurai, Tanda Tangan, atau Jumlah

returnShape menentukan data yang disertakan respons untuk hasil yang cocok:

Misalnya, permintaan ini menghitung pembelian Pump.fun oleh seorang trader pada Sep 2026 tanpa mengembalikan transaksi:

{
  "address": "<WALLET_ADDRESS>",
  "match": {
    "programs": [
      {
        "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
        "instructions": ["buy", "buy_exact_sol_in", "buy_v2"]
      }
    ]
  },
  "returnShape": "count",
  "time": { "gte": 1788220800, "lt": 1790812800 }
}

Untuk penghitungan, signatures dan count mengabaikan limit dan mencakup setiap kecocokan dalam rentang yang dipindai oleh permintaan. Untuk menghitung riwayat yang panjang, lanjutkan paginasi dan jumlahkan scan.matchedTransactions.

Ketiga format tersebut memiliki biaya yang sama.

Mengontrol Banyaknya Riwayat yang Dipindai Setiap Permintaan

Pemindaian dapat memeriksa hingga 10.000 transaksi per permintaan dan mengembalikan hingga 100 kecocokan.

Kolom budget.maxScannedTransactions mengontrol batas tersebut dan memiliki nilai default 10.000. Kolom limit mengontrol jumlah kecocokan yang dikembalikan endpoint; kolom ini menerima nilai dari 1 hingga 100 dan memiliki nilai default 100.

Kedua kontrol ini terpisah karena kecocokan bisa jarang ditemukan. Artinya, sebuah permintaan dapat memindai ribuan tx dan hanya mengembalikan beberapa kecocokan.

Secara default, permintaan pemindaian hanya menyertakan transaksi yang berhasil.

Atur status menjadi failed atau any untuk menyertakan transaksi yang gagal. Transaksi yang gagal menyertakan error program yang telah didekode jika IDL program mendefinisikannya.

Ringkasan Pemindaian

Setiap respons menyertakan ringkasan scan:

{
  "data": [],
  "paginationToken": "460903064:422",
  "scan": {
    "stoppedOn": "budget",
    "scannedTransactions": 2000,
    "matchedTransactions": 0,
    "scannedThrough": {
      "slot": 460903064,
      "blockTime": 1792856105
    },
    "creditsCharged": 12
  }
}

Ringkasan tersebut memberi tahu Anda:

• Alasan pemindaian berhenti
• Jumlah transaksi yang dipindai
• Jumlah transaksi yang cocok
• Slot dan waktu blok terakhir yang dipindai
• Jumlah kredit yang digunakan permintaan

Cara Kerja Paginasi Pemindaian

Ketika pemindaian berhenti, kolom scan.stoppedOn memberikan alasannya:

• windowEnd: pemindaian mencapai akhir riwayat atau jendela
• limit: respons berisi jumlah kecocokan yang diminta
• budget: permintaan mencapai anggaran pemindaian transaksinya
• deadline: permintaan mencapai batas waktunya

Jika respons menyertakan paginationToken, kirim token tersebut dalam permintaan berikutnya dan lanjutkan meskipun array data saat ini kosong. Hasil kosong dapat berarti permintaan telah menghabiskan anggarannya sebelum menemukan kecocokan, bukan berarti tidak ada kecocokan setelahnya.

Misalnya, loop ini mengumpulkan perdagangan Pump.fun selama satu jam terakhir.

Perhatikan bahwa batas time dan batas permintaan mencegahnya menelusuri seluruh riwayat:

const PUMP_PROGRAM = "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P";
const ONE_HOUR_AGO = Math.floor(Date.now() / 1000) - 3600;
const MAX_REQUESTS = 50;

let paginationToken;
let requests = 0;

async function scanHistory() {
  const response = await fetch(
    `https://mainnet.helius-rpc.com/v1/parsed-events/scan?api-key=${process.env.HELIUS_API_KEY}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        address: PUMP_PROGRAM,
        match: {
          programs: [{ programId: PUMP_PROGRAM, instructions: ["buy", "sell"] }],
        },
        time: { gte: ONE_HOUR_AGO },
        limit: 100,
        ...(paginationToken && { paginationToken }),
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }

  return response.json();
}

do {
  const page = await scanHistory();
  requests++;

  for (const transaction of page.data) {
    console.log(transaction.signature);
  }

  paginationToken = page.paginationToken;
} while (paginationToken && requests < MAX_REQUESTS);

Hasil Terurai Tanpa Pipeline Sisi Klien

Setiap item dalam data menggunakan format TransactionResult yang sama seperti endpoint Parsed Events Parse Transactions. Jika tersedia, hasil dapat mencakup instruksi yang telah didekode, transfer, perubahan akun, peristiwa, ringkasan transaksi, dan data terurai khusus protokol. Jika aplikasi Anda juga memerlukan payload transaksi Solana asli, atur rawTransaction menjadi "json", "jsonParsed", atau "base64".

Perbedaan utamanya terletak pada tempat alur kerja riwayat dijalankan.

Aplikasi Anda mendefinisikan pencarian satu kali, sementara Parsed Events Scan API menangani paginasi riwayat, pencocokan, dan penguraian sebelum mengembalikan transaksi yang relevan.

Gunakan SDK Helius Terbaru

SDK TypeScript dan Rust kami mendukung Parsed Events API dan endpoint pemindaian baru.

SDK TypeScript menyediakan pemindaian sebagai helius.parsedEvents.scan(). Jenis respons mengikuti returnShape yang diteruskan:

const { scan } = await helius.parsedEvents.scan({
  address: "<WALLET_ADDRESS>",
  match: {
    programs: [{ programId: "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P", instructions: ["buy", "sell"] }],
  },
  returnShape: "count",
});

console.log(scan.matchedTransactions, scan.stoppedOn);

SDK Rust juga menyediakan scan, scan_signatures, dan scan_count di helius.parsed_events(), yang semuanya menerima ScanRequest yang sama.

Harga Parsed Events Scan API

Setiap permintaan Parsed Events Scan API memerlukan 10 kredit ditambah 1 kredit untuk setiap halaman riwayat yang dipindai. Satu halaman riwayat berisi hingga 1.000 transaksi.

Misalnya, permintaan yang menggunakan anggaran default 10.000 transaksi memerlukan maksimal 20 kredit. Respons melaporkan biaya tepatnya dalam scan.creditsCharged.

Sebagai perbandingan, biaya pemindaian adalah sepersepuluh dari biaya paginasi riwayat yang sama dengan getTransactionsForAddress, yang memerlukan 100 kredit per halaman (hingga 1.000 transaksi).

Mengontrol Penggunaan

Untuk mengontrol penggunaan, gunakan alamat sespesifik mungkin dan tambahkan batas slot atau waktu jika memungkinkan. Lebih sedikit transaksi yang tidak relevan berarti lebih banyak kecocokan berguna dalam setiap permintaan.

Mengganti Enhanced Transactions API dengan Parsed Events API

Enhanced Transactions API tetap tersedia dalam mode pemeliharaan, tetapi tidak menerima jenis parser atau pengembangan fitur baru. Parsed Events adalah penerusnya dan menggunakan katalog IDL Helius untuk mendekode instruksi di ribuan program Solana. Jika belum, bermigrasilah ke Parsed Events API.

Apa perbedaannya?

Enhanced Transactions API mengelompokkan aktivitas ke dalam kumpulan jenis transaksi tetap, seperti swap, transfer, dan penjualan NFT. Sementara itu, Parsed Events Scan API mendukung pencarian yang lebih presisi berdasarkan instruksi program, diskriminator mentah, mint token, atau kombinasi kriteria tersebut. Helius menerapkan filter itu saat memindai riwayat alamat dan hanya menguraikan transaksi yang cocok.

Parsed Events API memberi developer cakupan program yang lebih luas dan kontrol lebih besar atas kueri historis tanpa perlu memelihara pemindai sisi klien.

Mulai Menggunakan

Gunakan Parsed Events Scan API ketika Anda mengetahui aktivitas onchain yang diperlukan, tetapi tidak ingin membangun dan memelihara pemindai riwayat sisi klien. Baca referensi Scan Transaction History API untuk melihat skema permintaan, kolom respons, batas, error, dan contoh lainnya secara lengkap.

Untuk terus menjelajahi kemampuan Scan API, lihat alat Scan baru di dasbor Helius Anda. Cobalah memindai alamat berdasarkan program, mint, dan filter.