> ## 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.
# Cara Menggunakan preconfSubscribe
> Streaming transaksi Solana dengan latensi serendah mungkin menggunakan metode WebSocket preconfSubscribe — berlangganan, memfilter, dan mendekode payload.
**Gunakan [Sender Max](/docs/id/sending-transactions/sender-max) (tip minimum: 0,001 SOL) untuk
menindaklanjuti Preconfirmations.** Preconfirmation hanya memberikan manfaat jika transaksi Anda
masuk
lebih dahulu — Sender Max adalah cara tercepat untuk melakukannya. Bangun dengan Sender Max sejak
awal untuk mendapatkan manfaat penuh dari Preconfirmations.
## Apa itu `preconfSubscribe`?
`preconfSubscribe` adalah metode WebSocket Helius yang melakukan streaming [Preconfirmations](/docs/id/pre-confirmations/overview) — transaksi yang dikirim sebelum dikumpulkan ke dalam entri dan dipecah menjadi shred. Ini adalah sinyal transaksi dengan latensi terendah yang ditawarkan Helius. Satu langganan mengirimkan preconfirmation Helius, yang dipancarkan segera setelah leader mengeksekusi transaksi dan menyertakan status eksekusinya, serta [preconfirmation BAM](/docs/id/pre-confirmations/overview#prekonfirmasi-bam) dari validator yang menjalankan klien Block Assembly Marketplace milik Jito, yang dipancarkan saat validator berkomitmen untuk mengeksekusi transaksi. Akses memerlukan [paket Professional atau yang lebih tinggi](/docs/id/billing/plans) — lihat [Harga](#harga).
Streaming ini tidak berlangsung terus-menerus. Cakupan meningkat sesuai proporsi stake yang
diteruskan ke Helius atau menjalankan BAM, jadi mungkin ada slot tanpa pesan — tangani
jeda ini dengan baik. Lihat [Cakupan](/docs/id/pre-confirmations/overview#cakupan).
`preconfSubscribe` dilayani dari `wss://beta.helius-rpc.com` — endpoint [Gatekeeper](/docs/id/gatekeeper/overview) Helius — bukan `mainnet.helius-rpc.com`. Lakukan autentikasi dengan API key Anda sebagai parameter kueri.
```
wss://beta.helius-rpc.com/?api-key=
```
Nama host `beta` merujuk pada peluncuran [Gatekeeper](/docs/id/gatekeeper/overview),
bukan tingkat kematangan Preconfirmations. Preconfirmations pertama kali diluncurkan pada
endpoint Gatekeeper; endpoint ini akan menjadi endpoint standar saat Helius
memigrasikan lalu lintas ke Gatekeeper.
## Berlangganan
Kirim permintaan JSON-RPC dengan metode `preconfSubscribe`. Server merespons dengan ID langganan, lalu melakukan streaming notifikasi untuk setiap transaksi. Teruskan [filter](#pemfilteran) opsional sebagai elemen `params` pertama agar hanya menerima transaksi yang cocok; hilangkan `params` untuk menerima seluruh streaming dari Helius dan BAM.
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "preconfSubscribe"
}
```
### Respons Langganan
```json theme={"system"}
{
"jsonrpc": "2.0",
"result": 24040,
"id": 1
}
```
Simpan `result` — ini adalah ID langganan yang Anda gunakan untuk [berhenti berlangganan](#berhenti-berlangganan). Setelah konfirmasi ini, notifikasi dialirkan sebagai frame biner (lihat di bawah).
## Pemfilteran
Secara default, `preconfSubscribe` melakukan streaming setiap transaksi dari kedua sumber. Untuk mempersempit streaming, teruskan objek filter sebagai elemen pertama `params`. Pemfilteran dilakukan di sisi server, sehingga Anda hanya membayar dan menerima transaksi yang Anda perlukan.
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "preconfSubscribe",
"params": [
{
"includeBam": true,
"failed": false,
"regionInclude": ["ewr", "fra"],
"accountInclude": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"],
"accountExclude": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
"accountRequired": ["11111111111111111111111111111111"]
}
]
}
```
Setiap bidang bersifat opsional — bidang yang tidak disertakan berarti "tanpa batasan" untuk predikat tersebut, sehingga filter kosong (atau tanpa `params`) cocok dengan setiap transaksi dari kedua sumber.
| Bidang | Jenis | Semantik |
| ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `includeBam` | `boolean` | Nilai default-nya adalah `true`. `false` menghapus preconfirmation BAM sehingga Anda hanya menerima preconfirmation Helius. |
| `failed` | `boolean` | `true` hanya mengembalikan transaksi yang gagal (dibatalkan); `false` hanya mengembalikan transaksi yang berhasil. Kedua nilai tersebut mengecualikan transaksi Helius dengan status yang tidak diketahui. Hilangkan bidang ini untuk menerima semua status. |
| `regionInclude` | `string[]` | Jika tidak kosong, transaksi harus berasal dari **salah satu** [wilayah](#pemfilteran-lokasi) ini. |
| `accountInclude` | `string[]` | Jika tidak kosong, transaksi harus merujuk pada **setidaknya satu** akun ini. |
| `accountExclude` | `string[]` | Transaksi dibuang jika merujuk pada **salah satu** akun ini. Memiliki prioritas atas `accountInclude`. |
| `accountRequired` | `string[]` | Transaksi harus merujuk pada **semua** akun ini. |
Aturan filter:
* Semua predikat digabungkan dengan AND dan dievaluasi dalam urutan `includeBam` → `failed` → `regionInclude` → `accountExclude` → `accountRequired` → `accountInclude`.
* Preconfirmation dengan status yang tidak diketahui mengabaikan filter status `failed` dan tetap dikirimkan jika cocok dengan filter sumber, wilayah, dan akun.
* Akun adalah pubkey yang dikodekan dengan base58. Nilai yang tidak valid mengembalikan error JSON-RPC `-32602` (parameter tidak valid).
* Setiap daftar akun dibatasi hingga **500** entri.
Untuk hanya menerima preconfirmation Helius:
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "preconfSubscribe",
"params": [{ "includeBam": false }]
}
```
### Resolusi address lookup table (ALT)
Filter akun tidak hanya mencocokkan kunci akun statis transaksi — Helius menyelesaikan [address lookup table](/docs/id/glossary#address-lookup-table-alt) v0 di sisi server, sehingga `accountInclude`, `accountExclude`, dan `accountRequired` juga mencocokkan akun yang dimuat transaksi melalui ALT.
Artinya, Anda dapat memfilter berdasarkan akun apa pun yang disentuh transaksi, meskipun akun tersebut hanya muncul di balik lookup table — Anda tidak perlu mengelola pemetaan ALT atau menyelesaikan tabel sendiri. Cukup teruskan pubkey akun dan Helius akan menangani resolusinya sebelum filter diterapkan.
### Pemfilteran lokasi
Gunakan `regionInclude` untuk hanya menerima transaksi yang berasal dari wilayah tertentu. Teruskan satu atau beberapa kode wilayah; transaksi lolos jika wilayah asalnya cocok dengan salah satunya.
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 1,
"method": "preconfSubscribe",
"params": [{ "regionInclude": ["ewr", "fra"] }]
}
```
Wilayah asal bergantung pada sumbernya. Untuk preconfirmation Helius, wilayah asal adalah wilayah Helius yang menerima transaksi. Untuk preconfirmation BAM, wilayah asal adalah endpoint BAM regional yang memancarkan preconfirmation, bukan tempat Helius menerimanya. Endpoint BAM di Singapura dan Dallas dipetakan ke `sgp` dan `dal`.
Kode wilayah yang valid:
| Kode | Lokasi |
| ----- | ------------------ |
| `slc` | Salt Lake City |
| `fra` | Frankfurt |
| `lon` | London |
| `pit` | Pittsburgh |
| `sgp` | Singapura |
| `ewr` | Newark |
| `tyo` | Tokyo |
| `ams` | Amsterdam |
| `dal` | Dallas |
| `dub` | Dublin |
| `mia` | Miami |
| `lax` | Los Angeles |
| `iad` | Ashburn |
| `sea` | Seattle |
| `hkg` | Hong Kong |
| `sqq` | Šiauliai, Lituania |
Saat `regionInclude` ditetapkan, transaksi yang tidak memiliki informasi wilayah akan dibuang. Kode wilayah yang tidak dikenali mengembalikan error JSON-RPC `-32602` (parameter tidak valid).
## Payload notifikasi
Notifikasi dikirim sebagai frame WebSocket **biner** (bukan JSON). Preconfirmation Helius dan BAM menggunakan tata letak yang sama. Setiap frame adalah tata letak byte yang dikemas dan memuat satu transaksi:
| Byte | Bidang | Jenis | Deskripsi |
| ---- | ------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0 | `version` | `u8` | Versi skema payload. Saat ini `1`. |
| 1–8 | `slot` | `u64` (little-endian) | Slot tempat transaksi berada. |
| 9–16 | `tx_index` | `u64` (little-endian) | Indeks transaksi di dalam slot. Selalu `0` untuk preconfirmation BAM — BAM mengurutkan transaksi berdasarkan ID urutan dan posisi bundle, bukan indeks slot, dan keduanya tidak disertakan dalam streaming ini. |
| 17 | `status` | `u8` | Status transaksi: `0` = gagal, `1` = berhasil, `2` = tidak diketahui. |
| 18+ | `transaction` | `bytes` | Transaksi dalam format wire Solana. Lihat [Mendekode transaksi](#mendekode-transaksi). |
Payload tidak memiliki bidang sumber. Jangan menyimpulkan asal BAM dari `tx_index = 0` karena preconfirmation Helius dapat memiliki nilai yang sama.
### Membedakan kedua sumber
Karena tidak ada bidang sumber, Anda tidak dapat melabeli pesan sembarang sebagai Helius atau BAM. Byte `status` memberikan pengklasifikasi satu arah:
* **`status` adalah `0` atau `1`** — pesan tersebut adalah preconfirmation Helius dan transaksi telah dieksekusi. BAM tidak pernah melaporkan nilai-nilai ini.
* **`status` adalah `2`** — sumbernya ambigu: dapat berupa preconfirmation BAM atau preconfirmation Helius yang status eksekusinya tidak tersedia.
Tidak ada bidang lain yang dapat membedakannya. ID urutan dan posisi bundle BAM tidak disertakan dalam streaming ini, sehingga tidak ada metadata pengurutan BAM yang dapat digunakan sebagai acuan. Selain itu, `regionInclude` adalah filter langganan, bukan bidang payload, sehingga tidak dapat dibaca per pesan.
Jika Anda memerlukan setiap pesan dalam satu streaming untuk membawa jenis bukti yang sama, tetapkan `includeBam: false` — tindakan ini hanya menyisakan preconfirmation Helius, yang semuanya dipancarkan saat eksekusi oleh leader. Tidak ada filter khusus BAM.
**Selalu baca dan periksa byte `version` terlebih dahulu.** Nilainya saat ini adalah `1`. Jika
Helius perlu memperbarui format payload, versinya akan bertambah — buat percabangan
berdasarkan versi agar dekoder Anda tetap berfungsi saat skema berubah.
Preconfirmation adalah sinyal awal, bukan jaminan. Transaksi belum
masuk secara onchain dan masih dapat dibuang — selain itu, status eksekusi preconfirmation Helius
mencerminkan hasil lokal leader, yang belum final hingga
blok dikonfirmasi. Konfirmasikan bahwa transaksi telah masuk melalui pemeriksaan commitment standar
sebelum menganggapnya final.
### Mendekode transaksi
Byte transaksi diteruskan tepat seperti yang diserialisasi oleh validator, dalam enkode wire standar untuk versi transaksi tersebut. Transaksi legacy dan v0 menggunakan tata letak signatures-first yang dihasilkan `bincode`. Transaksi v1 ([SIMD-0385](https://github.com/solana-foundation/solana-improvement-documents/blob/main/proposals/0385-transaction-v1.md)) menggunakan tata letak message-first dengan tanda tangan di bagian akhir, sehingga `bincode` gagal pada payload v1. Gunakan dekoder yang menangani setiap versi:
* **Rust:** [`agave-transaction-view`](https://docs.rs/agave-transaction-view) mengurai transaksi legacy, v0, dan v1 secara langsung tanpa salinan perantara. Ini adalah opsi yang direkomendasikan. [`wincode`](https://docs.rs/wincode), serializer kompatibel bincode yang digunakan oleh SDK Solana saat ini, juga mendekode v1 menjadi `VersionedTransaction`.
* **JavaScript / TypeScript:** pastikan versi pustaka Anda mendukung transaksi v1. Implementasi `VersionedTransaction.deserialize` yang lebih lama hanya menangani legacy dan v0. Gunakan `@solana/kit` 8.0+ atau `@solana/web3.js` v3. Lihat [Dukungan transaksi v1](/docs/id/rpc/transaction-v1).
```rust theme={"system"}
use agave_transaction_view::transaction_view::TransactionView;
// `frame` is the full binary WebSocket message
let tx_bytes = &frame[18..];
let tx = TransactionView::try_new_unsanitized(tx_bytes)?;
println!("version: {:?}", tx.version()); // Legacy, V0, or V1
println!("signature: {}", tx.signatures()[0]);
for ix in tx.instructions_iter() {
println!("program index {}: {} bytes", ix.program_id_index, ix.data.len());
}
```
## Notifikasi duplikat
Preconfirmation Helius dan BAM dideduplikasi per sumber, bukan lintas sumber. Sebagian kecil transaksi mencapai Helius melalui keduanya, sehingga Anda dapat menerima tanda tangan yang sama dua kali, dan kedua salinan tersebut dapat melaporkan slot yang berbeda.
Lakukan deduplikasi berdasarkan tanda tangan di klien dan buat tindakan yang dipicu transaksi bersifat idempoten, sehingga notifikasi kedua tidak memicu tindakan yang sama dua kali. Konfirmasikan eksekusi dan masuknya transaksi melalui pemeriksaan commitment standar.
## Contoh
```javascript theme={"system"}
const WebSocket = require('ws');
const ws = new WebSocket('wss://beta.helius-rpc.com/?api-key=');
ws.on('open', () => {
ws.send(JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'preconfSubscribe' // Helius and BAM preconfirmations by default
// Optional: txs from EWR/FRA touching a given account; Helius txs must be successful.
// BAM ignores the status filter; region and account filters still apply.
// params: [{ failed: false, regionInclude: ['ewr', 'fra'], accountInclude: ['9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'] }]
// Optional: Helius preconfirmations only
// params: [{ includeBam: false }]
}));
// Keep the connection alive
setInterval(() => ws.ping(), 30_000);
});
ws.on('message', (data, isBinary) => {
// The subscribe acknowledgement arrives as a JSON text frame
if (!isBinary) {
const msg = JSON.parse(data.toString());
if (msg.id === 1) console.log('Subscribed, ID:', msg.result);
return;
}
// Notifications arrive as binary frames:
// version (u8) | slot (u64 LE) | tx_index (u64 LE) | status (u8) | transaction bytes
const buf = Buffer.from(data);
const version = buf.readUInt8(0); // currently 1 — branch on this if it changes
if (version !== 1) return; // unknown schema version; update your decoder
const slot = buf.readBigUInt64LE(1);
const txIndex = buf.readBigUInt64LE(9); // always 0 for BAM preconfirmations
const status = buf.readUInt8(17); // 0 = failed, 1 = success, 2 = unknown
const txBytes = buf.subarray(18); // transaction in Solana wire format (legacy, v0, or v1)
console.log('Preconfirmation:', { version, slot, txIndex, status, bytes: txBytes.length });
// Decode txBytes with a decoder that supports transaction v1 (see "Decoding the transaction")
});
ws.on('error', console.error);
ws.on('close', () => process.exit(1));
```
## Berhenti berlangganan
Untuk berhenti menerima notifikasi, panggil `preconfUnsubscribe` dengan ID langganan yang dikembalikan oleh `preconfSubscribe`.
```json theme={"system"}
{
"jsonrpc": "2.0",
"id": 2,
"method": "preconfUnsubscribe",
"params": [24040]
}
```
```json theme={"system"}
{
"jsonrpc": "2.0",
"result": true,
"id": 2
}
```
## Harga
Preconfirmations memerlukan **paket Professional atau yang lebih tinggi** dan berbiaya **10 kredit per pesan** — satu pesan per transaksi yang dialirkan — yang ditagihkan dari paket Anda. Lihat [Kredit](/docs/id/billing/credits) untuk detailnya.
Penagihan dilakukan per pesan, bukan per tanda tangan unik. Transaksi yang dikirim oleh Helius dan BAM dihitung dua kali. Tetapkan `includeBam: false` jika Anda hanya menginginkan preconfirmation Helius.
Preconfirmations adalah produk baru dan harganya dapat berubah.
## Terkait
Penjelasan tentang Preconfirmations dan posisinya dalam pipeline validator.
Streaming transaksi dengan commitment confirmed menggunakan pemfilteran lengkap.
Parameter permintaan, bidang filter, dan tata letak notifikasi biner.