TypeScript JetStream Client

Install

npm install @orbitflare/sdk @grpc/grpc-js yaml

@grpc/grpc-js and yaml are optional peer dependencies. Install them only if you use JetStream (or YAML config).

Building the client

import { JetstreamClientBuilder } from '@orbitflare/sdk/jetstream';
import type { RetryPolicy } from '@orbitflare/sdk';

const client = new JetstreamClientBuilder()
  .url('http://ny.jetstream.orbitflare.com')
  .fallbackUrl('http://fra.jetstream.orbitflare.com')
  .retry({
    initialDelayMs: 100,
    maxDelayMs: 30_000,
    multiplier: 2.0,
    maxAttempts: 0,
  })
  .timeoutSecs(30)
  .keepaliveSecs(60)
  .pingIntervalSecs(10)
  .maxMissedPongs(3)
  .channelCapacity(4096)
  .build();

Minimal:

const client = new JetstreamClientBuilder()
  .url('http://ny.jetstream.orbitflare.com')
  .build();

URL falls back to ORBITFLARE_JETSTREAM_URL env var. All builder methods are identical to the gRPC client - same defaults, same behavior.

Writing a YAML config

JetStream supports transaction and account filters. No slots, blocks, or commitment - those are Yellowstone-specific.

# jetstream.yml
transactions:
  raydium:
    account_include:
      - "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"
  pumpfun:
    account_include:
      - "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"

accounts:
  my_wallet:
    account:
      - "YOUR_WALLET_ADDRESS"
    owner:
      - "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"

YAML filter reference

transactions - named filters. account_include matches transactions involving those addresses. account_exclude removes matches. account_required means all listed addresses must appear. accounts - watch specific addresses with account, or all accounts owned by a program with owner. Supports ${ENV_VAR} expansion.

Subscribing and reading events

From YAML

const stream = client.subscribeYaml('jetstream.yml');

Programmatically

import { proto } from '@orbitflare/sdk/proto';

const request: proto.jetstream.SubscribeRequest = {
  transactions: {
    target: {
      accountInclude: [someAddress],
      accountExclude: [],
      accountRequired: [],
    },
  },
  accounts: {},
  ping: { id: 1 },
};

const stream = client.subscribe(request);

With the typed builder

SubscribeRequestBuilder and TransactionFilter build the same request without hand-writing proto. Each TransactionFilter exposes accountInclude, accountExclude, and accountRequired, so you get autocomplete and compile-time checking on the filter shape.

import {
  SubscribeRequestBuilder,
  TransactionFilter,
} from '@orbitflare/sdk/jetstream';

const request = new SubscribeRequestBuilder()
  .transactions(
    'pumpfun',
    new TransactionFilter()
      .accountInclude(['6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P'])
      .accountRequired(['So11111111111111111111111111111111111111112']),
  )
  .build();

const stream = client.subscribe(request);

Reading the stream

for await (const update of stream) {
  if (update.transaction) {
    // update.transaction.slot - the slot number
    // update.transaction.transaction - transaction info with signature, accountKeys,
    //   instructions, addressTableLookups
  } else if (update.account) {
    // update.account.slot - the slot
    // update.account.account - account info (pubkey, lamports, owner, data)
    // update.account.isStartup - true during initial snapshot
  }
}

Closing, multiple streams, reconnection, and ping/pong all work identically to the gRPC client.

Full example

A stream that watches Raydium AMM swaps and prints each transaction’s signature and instruction count.

import bs58 from 'bs58';
import { JetstreamClientBuilder } from '@orbitflare/sdk/jetstream';

async function main() {
  const client = new JetstreamClientBuilder()
    .url('http://ny.jetstream.orbitflare.com')
    .build();

  const stream = client.subscribeYaml('jetstream.yml');
  let count = 0;

  console.log('streaming raydium txs...');

  for await (const update of stream) {
    if (update.transaction) {
      count += 1;
      const info = update.transaction.transaction;
      if (info?.signature) {
        const sig = bs58.encode(info.signature);
        const numIx = info.instructions.length;
        const numAccounts = info.accountKeys.length;
        console.log(
          `#${count} slot=${update.transaction.slot} sig=${sig.slice(0, 16)}... ix=${numIx} accounts=${numAccounts}`,
        );
      }
    }
  }
}

void main();

With this jetstream.yml:

transactions:
  raydium:
    account_include:
      - "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"

JetStream v2

JetStream v2 runs on the same endpoints and authentication as v1 and is fully additive: v1 keeps working unchanged. What v2 adds:

Runtime-managed filters - add and remove filters on a live stream without reconnecting.
Per-message sequence numbers - every response carries a monotonic sequence, so you can detect dropped messages.
Opt-in enrichment - request fee payer, program ids, compute-unit price, compute limit, resolved address-table addresses, and more, per transaction.
Slot lifecycle events - a separate server stream of slot alive/complete/dead events.

Import it from the jetstream/v2 entry point. The builder is identical to v1 (same methods, defaults, ORBITFLARE_JETSTREAM_URL env var, and failover):

import { JetstreamClientBuilder, TransactionFilter } from '@orbitflare/sdk/jetstream/v2';

const client = new JetstreamClientBuilder()
  .url('http://ny.jetstream.orbitflare.com')
  .fallbackUrl('http://fra.jetstream.orbitflare.com')
  .build();

Building typed filters

Each filter is a TransactionFilter with a client-chosen id (via .withId()). The id is echoed back on every matching transaction and in the filter-validation acknowledgement, so you can correlate matches and remove the filter later.

const filter = new TransactionFilter()
  .accountInclude(['6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P'])
  .includeEnrichment(true)
  .withId('pumpfun');

A filter must set at least one of accountInclude, accountExclude, or accountRequired; empty (match-everything) filters are rejected. includeEnrichment is optional (default off) and applies to the whole subscription: if any active filter enables it, every transaction you receive is enriched.

Subscribing to transactions

const stream = client.subscribeTransactions([filter]);

for await (const resp of stream) {
  if (resp.transaction) {
    // resp.sequence - monotonic per-stream sequence number
    // resp.transaction.filterIds - which of your filters this tx matched
    const tx = resp.transaction.transaction;
    if (tx) {
      // tx.slot, tx.signature, tx.accountKeys, tx.instructions
      // enrichment (only when includeEnrichment is set): tx.feePayer,
      //   tx.programIds, tx.computeUnitPrice, tx.computeLimit,
      //   tx.loadedWritableAddresses, tx.loadedReadonlyAddresses
      console.log(`seq=${resp.sequence} slot=${tx.slot} cuPrice=${tx.computeUnitPrice}`);
    }
  } else if (resp.filterValidation) {
    // one per filter after each add/remove
    const r = resp.filterValidation;
    console.log(`filter ${r.filterId} accepted=${r.accepted} ${r.rejectionReason}`);
  } else if (resp.heartbeat) {
    // resp.heartbeat.serverTsMs - server wall-clock, ms since epoch
  } else if (resp.pong) {
    // resp.pong.pingId
  }
}

Managing filters on a live stream

Take a handle from the stream and add or remove filters without reconnecting. Removals reference the filter id you assigned with .withId().

const handle = stream.handle();

handle.addFilters([
  new TransactionFilter()
    .accountInclude(['675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8'])
    .withId('raydium'),
]);

handle.removeFilters(['pumpfun']);

Slot lifecycle events

subscribeSlots() is a separate server stream and takes no filters.

const slots = client.subscribeSlots();

for await (const event of slots) {
  // event.slot, event.status (a SlotStatus enum: alive / complete / dead),
  // event.parentSlot, event.currentLeader, event.sequence
  console.log(`slot=${event.slot} status=${event.status}`);
}

Health probes

getVersion() and ping() are unary calls with the same failover as the streams.

console.log(`version=${await client.getVersion()}`);
console.log(`ping=${await client.ping(7)}`);

For the full protobuf specification, message shapes, enrichment fields, and slot statuses, see the JetStream v2 Protocol Reference.

Get Started

Agents

Products

Solutions

Fetching Data

RPC

Data Streaming

Trading APIs

TypeScript JetStream Client

Install

Building the client

Writing a YAML config

YAML filter reference

Subscribing and reading events

From YAML

Programmatically

With the typed builder

Reading the stream

Full example

JetStream v2

Building typed filters

Subscribing to transactions

Managing filters on a live stream

Slot lifecycle events

Health probes

​Install

​Building the client

​Writing a YAML config

​YAML filter reference

​Subscribing and reading events

​From YAML

​Programmatically

​With the typed builder

​Reading the stream

​Full example

​JetStream v2

​Building typed filters

​Subscribing to transactions

​Managing filters on a live stream

​Slot lifecycle events

​Health probes

Install

Building the client

Writing a YAML config

YAML filter reference

Subscribing and reading events

From YAML

Programmatically

With the typed builder

Reading the stream

Full example

JetStream v2

Building typed filters

Subscribing to transactions

Managing filters on a live stream

Slot lifecycle events

Health probes