preconfSubscribe

Start a subscription to Preconfirmations — transactions delivered at the scheduled-transaction stage, before they are collected into entries and converted into shreds. This is the lowest-latency transaction signal Helius offers.

Endpoints

preconfSubscribe is served from the Helius Gatekeeper endpoint:

wss://beta.helius-rpc.com/?api-key=<API_KEY>

The beta hostname refers to the Gatekeeper rollout, not the maturity of Preconfirmations — it will become the standard endpoint as traffic migrates to Gatekeeper.

The stream is not continuous. Coverage scales with the share of network stake forwarding to Helius, so expect slots with no messages — handle these gaps gracefully. See Coverage.

Authorizations

string

required

Your Helius API key, passed as the api-key query parameter. Requires a Professional plan or higher.

Body

array

Optional. Omit params to receive every scheduled transaction. To narrow the stream, pass a filter object as the first element — filtering happens server-side, so you only pay for and receive the transactions you care about.

Hide Filter

Every field is optional — a missing field means “no constraint” for that predicate, so an empty filter matches every transaction. Set fields combine with AND, evaluated in the order regionInclude → accountExclude → accountRequired → accountInclude.

boolean

false drops failed (reverted) transactions; success and unknown-status transactions still pass. true — like omitting the field — keeps every status.

string[]

If non-empty, the transaction must originate from one of these regions. Transactions without region information are dropped when this is set.

string[]

If non-empty, the transaction must reference at least one of these accounts (base58 pubkeys). Capped at 500 entries.

string[]

The transaction is dropped if it references any of these accounts. Takes precedence over accountInclude. Capped at 500 entries.

string[]

The transaction must reference all of these accounts. Capped at 500 entries.

An invalid account value or unrecognized region code returns JSON-RPC error -32602 (invalid params). Account filters match more than the transaction’s static account keys — Helius resolves v0 address lookup tables server-side, so accountInclude, accountExclude, and accountRequired also match accounts a transaction loads through an ALT.

Region codes

Code	Location	Code	Location
`slc`	Salt Lake City	`tyo`	Tokyo
`fra`	Frankfurt	`ams`	Amsterdam
`lon`	London	`dal`	Dallas
`pit`	Pittsburgh	`dub`	Dublin
`sgp`	Singapore	`mia`	Miami
`ewr`	Newark	`lax`	Los Angeles
`iad`	Ashburn	`sea`	Seattle

Response

integer

Subscription id (needed to unsubscribe)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe",
  "params": [
    {
      "failed": false,
      "regionInclude": ["ewr", "fra"],
      "accountInclude": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"]
    }
  ]
}

const WebSocket = require('ws');

const ws = new WebSocket('wss://beta.helius-rpc.com/?api-key=<API_KEY>');

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'preconfSubscribe'
    // Optional filter:
    // params: [{ failed: false, accountInclude: ['9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'] }]
  }));

  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) | bincode(VersionedTransaction)
  const buf = Buffer.from(data);
  const version = buf.readUInt8(0);
  if (version !== 1) return; // unknown schema version; update your decoder
  const slot = buf.readBigUInt64LE(1);
  const txIndex = buf.readBigUInt64LE(9);
  const status = buf.readUInt8(17); // 0 = failed, 1 = success, 2 = unknown
  const txBytes = buf.subarray(18); // bincode-serialized VersionedTransaction

  console.log('Scheduled transaction:', { slot, txIndex, status, bytes: txBytes.length });
});

{ "jsonrpc": "2.0", "id": 1, "result": 24040 }

version   u8              payload schema version, currently 1
slot      u64 (LE)        slot the transaction is scheduled in
tx_index  u64 (LE)        index of the transaction within the slot
status    u8              0 = failed, 1 = success, 2 = unknown
tx        bincode bytes   bincode(VersionedTransaction)

Notifications

After the JSON acknowledgement, notifications are delivered as binary WebSocket frames (not JSON). Each frame is a packed byte layout carrying a single scheduled transaction:

Bytes	Field	Type	Description
0	`version`	`u8`	Payload schema version. Currently `1`.
1–8	`slot`	`u64` (little-endian)	The slot the transaction is scheduled in.
9–16	`tx_index`	`u64` (little-endian)	Index of the transaction within the slot.
17	`status`	`u8`	Transaction status: `0` = failed, `1` = success, `2` = unknown. Execution status is reported by validators on a best-effort basis — `2` when it’s unavailable.
18+	`transaction`	`bincode(VersionedTransaction)`	The scheduled transaction, bincode-serialized.

Read the fields in order, then bincode-deserialize the remaining bytes into a VersionedTransaction to read instructions, accounts, and the signature.

Always read and check the version byte first. It is currently 1. If Helius needs to update the payload format, the version will increment — branch on it so your decoder keeps working across schema changes.

A preconfirmation is an early signal, not a guarantee. The transaction has not yet landed onchain and could still fail or be dropped. Confirm landing through standard commitment checks before treating it as final.

Pricing

Preconfirmations require a Professional plan or higher and cost 10 credits per message — one message per streamed transaction. See Credits for details.

Preconfirmations Overview

What Preconfirmations are and where they sit in the validator pipeline.

preconfUnsubscribe

Stop a subscription by its id.

getValidityProof

preconfUnsubscribe

⌘I

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "preconfSubscribe",
  "params": [
    {
      "failed": false,
      "regionInclude": ["ewr", "fra"],
      "accountInclude": ["9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"]
    }
  ]
}

const WebSocket = require('ws');

const ws = new WebSocket('wss://beta.helius-rpc.com/?api-key=<API_KEY>');

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'preconfSubscribe'
    // Optional filter:
    // params: [{ failed: false, accountInclude: ['9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'] }]
  }));

  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) | bincode(VersionedTransaction)
  const buf = Buffer.from(data);
  const version = buf.readUInt8(0);
  if (version !== 1) return; // unknown schema version; update your decoder
  const slot = buf.readBigUInt64LE(1);
  const txIndex = buf.readBigUInt64LE(9);
  const status = buf.readUInt8(17); // 0 = failed, 1 = success, 2 = unknown
  const txBytes = buf.subarray(18); // bincode-serialized VersionedTransaction

  console.log('Scheduled transaction:', { slot, txIndex, status, bytes: txBytes.length });
});

{ "jsonrpc": "2.0", "id": 1, "result": 24040 }

version   u8              payload schema version, currently 1
slot      u64 (LE)        slot the transaction is scheduled in
tx_index  u64 (LE)        index of the transaction within the slot
status    u8              0 = failed, 1 = success, 2 = unknown
tx        bincode bytes   bincode(VersionedTransaction)

Get Started

Data Streaming & Event Listening

Data APIs & RPCs

Trading

Sending Transactions

Account Management

Endpoints

Authorizations

Body

Region codes

Response

Notifications

Pricing

Preconfirmations Overview

preconfUnsubscribe

​Endpoints

​Authorizations

​Body

​Region codes

​Response

​Notifications

​Pricing

​Related

Preconfirmations Overview

preconfUnsubscribe

Endpoints

Authorizations

Body

Region codes

Response

Notifications

Pricing

Related