Migrasi dari Enhanced Transactions ke Parsed Events

Mengapa perlu bermigrasi?

Enhanced Transactions API adalah produk lama dalam mode pemeliharaan: produk ini masih berfungsi, tetapi tidak lagi menerima jenis parser atau pengembangan fitur baru. Penerusnya adalah Parsed Events, yang mendekode instruksi melalui katalog IDL yang juga mendukung Parsed Streams. Perbedaannya terletak pada cara transaksi didekode. Enhanced Transactions mengklasifikasikan transaksi ke dalam salah satu daftar tetap jenis peristiwa (TRANSFER, SWAP, NFT_SALE, …) dan menampilkan ringkasan siap pakai untuk jenis yang dikenalnya. Parsed Events mendekode setiap instruksi berdasarkan IDL milik program itu sendiri — lebih dari 3.600 program — menjadi argumen dan akun bernama, lalu menyusun ringkasan di atasnya:

	Transaksi yang Disempurnakan	Peristiwa Terurai
Model dekode	Jenis peristiwa tetap, parser terkurasi	Katalog IDL, 3.600+ program
Detail instruksi	Hanya ringkasan peristiwa	Setiap instruksi, argumen dan akun yang didekode, termasuk CPI
Program tanpa parser	Output `UNKNOWN` generik	Data mentah dan akun selalu dikembalikan untuk setiap instruksi
Kredit per permintaan	100	10
Paginasi	Cursor tanda tangan, error pencarian runtime yang perlu ditangani	`paginationToken` (cursor tanda tangan tetap tersedia)
Error program yang didekode	Tidak	Ya (`decodedError`)
Payload transaksi mentah	Tidak	Opsional (`rawTransaction`: `json`, `jsonParsed`, atau `base64`)
Status	Lama, mode pemeliharaan	Tersedia secara umum, dikembangkan secara aktif

Parsed Events tersedia secara umum di semua paket, termasuk Free, dengan biaya 10 kredit per permintaan. Enhanced Transactions tetap berfungsi dalam mode pemeliharaan sehingga Anda dapat bermigrasi sesuai kebutuhan.

Pemetaan titik akhir

Kedua metode Parsed Events merupakan permintaan POST ke https://mainnet.helius-rpc.com, yang diautentikasi dengan parameter kueri api-key yang sudah Anda gunakan:

Enhanced Transactions	Parsed Events
`POST /v0/transactions`	`POST /v1/parsed-events/transactions`
`GET /v0/addresses/{address}/transactions`	`POST /v1/parsed-events/transaction-history`

Titik akhir riwayat memindahkan semua masukan dari parameter string kueri ke isi JSON. Isi permintaan menolak bidang yang tidak dikenal sehingga kesalahan ketik langsung menghasilkan kegagalan, bukan diabaikan secara diam-diam.

Sebelum dan sesudah

Tugas yang sama — mengambil riwayat terurai untuk dompet — di kedua API:

const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&limit=100&sort-order=desc`;

const response = await fetch(url);
const transactions = await response.json(); // flat array of enriched transactions

for (const tx of transactions) {
  console.log(tx.signature, tx.type, tx.description);
}

const url = "https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY";

const response = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address: "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K",
    limit: 100,
    sortOrder: "desc",
  }),
});
const page = await response.json(); // { data: [...], paginationToken }

for (const item of page.data) {
  if (item.parserStatus !== "OK") continue;
  console.log(item.signature, item.parsed.summary?.type, item.parsed.summary?.description);
}

Pemetaan parameter

Parse Transactions

POST /v0/transactions → POST /v1/parsed-events/transactions

Lama	Baru
`transactions` (isi)	`transactions` — tidak berubah
`commitment`	`commitment` — `confirmed` (bawaan) atau `finalized`; `processed` tidak didukung

Opsi baru tanpa padanan lama: rawTransaction mengembalikan transaksi Solana asli bersama hasil yang diurai, yang dikodekan sebagai json, jsonParsed, atau base64.

Riwayat Transaksi

GET /v0/addresses/{address}/transactions → POST /v1/parsed-events/transaction-history. Setiap parameter kueri menjadi bidang isi JSON:

Parameter kueri lama	Kolom isi baru
`{address}` (jalur)	`address`
`limit`	`limit`
`before-signature`	`beforeSignature`
`after-signature`	`afterSignature`
`sort-order`	`sortOrder`
`commitment`	`commitment`
`token-accounts`	`tokenAccounts` (`none`, `balanceChanged`, atau `all`)
`gt-time`	`time.gt`
`gte-time`	`time.gte`
`lt-time`	`time.lt`
`lte-time`	`time.lte`
`gt-slot`	`slot.gt`
`gte-slot`	`slot.gte`
`lt-slot`	`slot.lt`
`lte-slot`	`slot.lte`

Tiga nilai bawaan berubah dalam proses ini:

Nilai bawaan limit menjadi 100, bukan 10.
Nilai bawaan commitment menjadi confirmed, bukan finalized; processed tidak didukung.
sortOrder mempertahankan nilai asc/desc yang sama, dengan desc sebagai nilai bawaan.

Untuk paginasi, sebaiknya gunakan paginationToken dari respons sebelumnya, bukan beforeSignature — lihat Sederhanakan paginasi di bawah. Parameter lama type tidak memiliki padanan langsung dalam Peristiwa Terurai. Untuk memfilter di sisi server, gunakan endpoint pemindaian (POST /v1/parsed-events/scan), yang hanya mengembalikan transaksi yang memanggil program atau instruksi dalam match.programs, atau mengakses mint token dalam match.mints. Jika tidak, lakukan pemfilteran di sisi klien pada parsed.summary.type (swap, transfer, add_liquidity, …), atau pada instruksi yang telah didekode, yang lebih presisi daripada jenis tetap lama. Untuk feed real-time khusus jenis, Aliran Terurai melakukan pemfilteran di sisi server pada tingkat instruksi.

Pemetaan bidang respons

Enhanced Transactions menampilkan array datar berisi transaksi yang diperkaya. Parsed Events membungkus setiap hasil dalam sebuah amplop — { signature, parserStatus, parsed } — dan respons riwayat membungkus array dalam objek halaman dengan paginationToken. Bidang yang diurai dipetakan sebagai berikut:

Bidang lama	Bidang baru
`description`	`parsed.summary.description` — `summary` bernilai `null` jika tidak ada ringkasan tingkat transaksi yang berlaku
`type` (`TRANSFER`, `SWAP`, …)	`parsed.summary.type` (`transfer`, `swap`, …) — kumpulan yang lebih kecil; detail per instruksi dipindahkan ke `parsed.instructions[]`
`source` (`SYSTEM_PROGRAM`, `JUPITER`, …)	`parsed.summary.parsedData.protocol`, atau per instruksi sebagai `instructions[].programName`
`events` (`events.swap`, `events.nft`, …)	`parsed.summary.parsedData` — payload terstruktur yang menggunakan jenis ringkasan sebagai kunci
`fee` / `feePayer`	`parsed.fee` / `parsed.feePayer` — tidak berubah
`signature`	`signature` (tingkat amplop)
`slot`	`parsed.slot`
`timestamp`	`parsed.blockTime`
`transactionError`	`parsed.error`, ditambah `parsed.decodedError` dengan nama galat milik program jika metadata tersedia
`nativeTransfers`	`parsed.nativeTransfers` — struktur yang sama (`fromUserAccount`, `toUserAccount`, `amount` dalam lamport)
`tokenTransfers`	`parsed.tokenTransfers` — bidang akun yang sama, tetapi `tokenAmount` (desimal yang telah diskalakan) menjadi `rawTokenAmount` (bilangan bulat mentah) ditambah `decimals`

Perubahan terbesar adalah bidang baru tanpa padanan lama: parsed.instructions[] memuat setiap instruksi tingkat atas dan internal dalam urutan eksekusi, dengan decoded.args dan decoded.accounts yang dinamai berdasarkan IDL program. Jika Enhanced Transactions memberi Anda satu ringkasan peristiwa per transaksi, Parsed Events memberi Anda ringkasan serta daftar lengkap instruksi yang telah didekode. Lihat Respons Terurai untuk setiap bidang.

Langkah-langkah migrasi

Swap the endpoints

Arahkan panggilan Parse Transactions ke POST /v1/parsed-events/transactions dan panggilan riwayat ke POST /v1/parsed-events/transaction-history. Host yang sama, parameter kueri api-key yang sama. Permintaan riwayat berubah dari GET dengan parameter kueri menjadi POST dengan isi JSON — pindahkan setiap parameter sesuai pemetaan di atas.

Update the response handling

Buka amplop baru: periksa parserStatus === "OK", lalu baca bidang dari parsed, bukan dari tingkat teratas. Ubah nama timestamp menjadi blockTime, baca description dan type dari summary (dengan menangani null), lalu bagi rawTokenAmount dengan 10^decimals di tempat kode lama membaca tokenAmount.

Replace type filtering

Jika kode lama meneruskan type=..., filter item yang ditampilkan di sisi klien berdasarkan parsed.summary.type atau parsed.instructions[] — misalnya, “instruksi dengan programId adalah Jupiter dan instructionName adalah route” menggantikan type=SWAP dengan sesuatu yang benar-benar dapat Anda verifikasi. Jika filter jenis digunakan untuk menyediakan umpan waktu nyata, pindahkan konsumennya ke Parsed Streams, yang melakukan filter di sisi server pada tingkat instruksi.

Simplify pagination

Ganti perulangan kursor before-signature dengan paginationToken:

let paginationToken = null;
const results = [];

do {
  const response = await fetch("https://mainnet.helius-rpc.com/v1/parsed-events/transaction-history?api-key=YOUR_API_KEY", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      address: "YOUR_ADDRESS_HERE",
      limit: 100,
      ...(paginationToken && { paginationToken }),
    }),
  });
  const page = await response.json();
  results.push(...page.data);
  paginationToken = page.paginationToken;
} while (paginationToken);

Perulangan berakhir saat paginationToken tidak ada. Galat pencarian runtime lama (“Gagal menemukan peristiwa dalam periode pencarian”) beserta penanganan tanda tangan kelanjutannya sepenuhnya hilang — hapus kode tersebut.

Verify against the old output

Untuk alamat sampel, ambil halaman yang sama dari kedua API dan bandingkan kumpulan tanda tangan, biaya, serta jumlah transfer. Kemudian lakukan deployment dan hapus jalur kode lama. Enhanced Transactions tetap berfungsi selama Anda bermigrasi — tidak ada penghentian paksa.

Perbedaan perilaku yang perlu ditinjau

Default commitment. Riwayat secara default menggunakan confirmed, sedangkan endpoint lama secara default menggunakan finalized. Teruskan commitment: "finalized" secara eksplisit jika pipeline Anda bergantung pada finalitas. processed tidak didukung.
Kesalahan per item. Tanda tangan yang tidak dapat diuraikan tidak lagi menyebabkan permintaan gagal — tanda tangan tersebut dikembalikan sebagai item dengan parserStatus: "ERROR" dan parserError. Tangani kesalahan tersebut per item, bukan per permintaan.
Cakupan ringkasan. summary adalah null untuk transaksi yang tidak memiliki tindakan tingkat transaksi yang dikenali. API lama mengembalikan type: "UNKNOWN" dalam kasus tersebut; API baru tetap memberikan setiap instruksi yang telah didekode agar dapat Anda gunakan.
Akses dan biaya. Parsed Events tersedia di semua paket dan dikenai biaya 10 kredit per permintaan, turun dari 100 kredit untuk Enhanced Transactions.

Biarkan agen AI melakukan migrasi

Jika Anda menggunakan Claude Code, Cursor, atau agen pemrograman lainnya, tempelkan prompt di bawah ke sesi agen repositori Anda. Agen tersebut akan menemukan lokasi pemanggilan Enhanced Transactions dan menulis ulang pemanggilan itu.

Migrate this codebase from the Helius Enhanced Transactions API to the Helius
Parsed Events API.

## Background

Parsed Events is the successor to Enhanced Transactions. Same host
(https://mainnet.helius-rpc.com) and api-key query parameter; new paths,
JSON bodies, and response shapes.
Docs: https://www.helius.dev/docs/parsed-events/quickstart.md and
https://www.helius.dev/docs/parsed-events/parsed-response.md

## Step 1: Find the old call sites

Search for:
- POST requests to /v0/transactions
- GET requests to /v0/addresses/<address>/transactions (any query parameters)
- Pagination loops using before-signature / after-signature cursors, and
  handlers for the "Failed to find events within the search period" error

## Step 2: Rewrite each call site

Parse transactions:
- POST /v0/transactions -> POST /v1/parsed-events/transactions
- Body keeps { transactions: [...] }; optionally add commitment
  ("confirmed" default or "finalized") and rawTransaction ("json",
  "jsonParsed", or "base64" to return the original transaction).

Transaction history:
- GET /v0/addresses/{address}/transactions?... ->
  POST /v1/parsed-events/transaction-history with a JSON body.
- Parameter mapping (query -> body): address path segment -> address;
  limit -> limit (default is now 100, not 10);
  before-signature -> beforeSignature (prefer paginationToken, see below);
  after-signature -> afterSignature; sort-order -> sortOrder;
  commitment -> commitment (default is now "confirmed", not "finalized";
  "processed" unsupported); token-accounts -> tokenAccounts;
  gt-time/gte-time/lt-time/lte-time -> time.gt/.gte/.lt/.lte;
  gt-slot/gte-slot/lt-slot/lte-slot -> slot.gt/.gte/.lt/.lte.
- type=... has no direct equivalent. To filter server-side, call
  POST /v1/parsed-events/scan with the same history fields plus
  match.programs ([{ programId, instructions }]) and/or match.mints
  ([{ mint }]).
  Otherwise filter returned items client-side on parsed.summary?.type
  (lowercase: "swap", "transfer", ...) or on parsed.instructions[]
  (programId / instructionName).

Response shape changes:
- Each item is now { signature, parserStatus, parsed } — check
  parserStatus === "OK" and read fields from parsed.
- Field renames: timestamp -> parsed.blockTime; description ->
  parsed.summary?.description; type -> parsed.summary?.type;
  source -> parsed.summary?.parsedData?.protocol or
  parsed.instructions[].programName; events -> parsed.summary?.parsedData.
- nativeTransfers: unchanged shape under parsed.nativeTransfers.
- tokenTransfers: tokenAmount (pre-scaled decimal) is replaced by
  rawTokenAmount (raw integer string/number) plus decimals — divide by
  10**decimals where the old amount was used.
- History responses wrap results as { data, paginationToken }. Loop while
  paginationToken is present, passing it back in the next request body.
  Delete continuation-signature error handling for the old runtime type
  search — it no longer exists.

## Step 3: Constraints and cleanup

- Keep the same Helius API key and host; only paths, methods, bodies, and
  response handling change.
- Never hardcode an API key; keep reading it from the existing config or
  environment variable.
- Preserve the surrounding code style and error handling conventions.
- Leave Enhanced Transaction webhook payload handling unchanged — this
  migration covers only the /v0/transactions and /v0/addresses REST calls.

## Step 4: Verify

- Run the project's type checks and tests.
- Do NOT make any API calls yourself. Instead, write a standalone script
  (e.g. scripts/verify-parsed-events-migration.mjs) that fetches one page of
  history for an address from both APIs — the old
  GET /v0/addresses/{address}/transactions and the new
  POST /v1/parsed-events/transaction-history — and prints whether the
  signature sets, fees, and native transfer amounts match, listing any
  differences. Read the API key from an environment variable and the address
  from a CLI argument.
- Tell the user how to run it, for example:
  HELIUS_API_KEY=... node scripts/verify-parsed-events-migration.mjs <address>
- Summarize every call site changed and flag any you were unsure about.

Prompt ini mandiri — agen tidak memerlukan akses ke halaman ini. Untuk dokumentasi yang siap digunakan agen, pencarian MCP, dan keterampilan, lihat Helius untuk agen AI.

Langkah berikutnya

Parsed Events Quickstart

Urai transaksi pertama Anda, ambil riwayat alamat, dan telusuri hasil halaman demi halaman.

Parsed Response

Referensi bidang untuk transaksi, transfer, dan instruksi yang telah diurai.

Parsed Streams

Pendekodean yang sama secara waktu nyata melalui WebSocket, dengan filter di sisi server.

getTransactionsForAddress

Riwayat transaksi mentah dengan dukungan akun token dan filter di sisi server.

Mulai di Sini

Data Real-Time

Perdagangan Berlatensi Rendah

Data Historis & Dompet

Panduan Metode RPC

Kesiapan Produksi

Menggunakan Orb

Panduan Praktis Lainnya

Migrasi dari Enhanced Transactions ke Parsed Events

Mengapa perlu bermigrasi?

Pemetaan titik akhir

Sebelum dan sesudah

Pemetaan parameter

Parse Transactions

Riwayat Transaksi

Pemetaan bidang respons

Langkah-langkah migrasi

Perbedaan perilaku yang perlu ditinjau

Biarkan agen AI melakukan migrasi

Langkah berikutnya

Parsed Events Quickstart

Parsed Response

Parsed Streams

getTransactionsForAddress

​Mengapa perlu bermigrasi?

​Pemetaan titik akhir

​Sebelum dan sesudah

​Pemetaan parameter

​Parse Transactions

​Riwayat Transaksi

​Pemetaan bidang respons

​Langkah-langkah migrasi

​Perbedaan perilaku yang perlu ditinjau

​Biarkan agen AI melakukan migrasi

​Langkah berikutnya

Parsed Events Quickstart

Parsed Response

Parsed Streams

getTransactionsForAddress

Mengapa perlu bermigrasi?

Pemetaan titik akhir

Sebelum dan sesudah

Pemetaan parameter

Parse Transactions

Riwayat Transaksi

Pemetaan bidang respons

Langkah-langkah migrasi

Perbedaan perilaku yang perlu ditinjau

Biarkan agen AI melakukan migrasi

Langkah berikutnya