Yellowstone gRPC quickstart

Connect a TypeScript client to Yellowstone gRPC, authenticate, handle pings, and receive your first Solana block updates.

Start with block metadata to verify the connection without downloading full blocks. The helper below is reused by the other Yellowstone guides.

Install and configure

Use Node.js 20 or later. These examples target @triton-one/yellowstone-grpc 7.0.1. Keep the .mts extension when running them with tsx.

npm install @triton-one/yellowstone-grpc@7.0.1 bs58
npm install --save-dev typescript tsx @types/node
export GRPC_ENDPOINT="https://grpc.solanatracker.io"
export GRPC_API_TOKEN="YOUR_API_TOKEN"

Create the subscription helper

Save this as stream.mts. It fills in the required request maps, replies to server pings, and closes the stream when the consumer exits. Disconnects are surfaced to the caller.

stream.mts

import Yellowstone, {
  CommitmentLevel,
  type SubscribeRequest,
  type SubscribeUpdate,
} from "@triton-one/yellowstone-grpc";

const Client = typeof Yellowstone === "function" ? Yellowstone : Yellowstone.default;

export function makeRequest(
  filters: Partial<SubscribeRequest> = {},
): SubscribeRequest {
  return {
    accounts: {}, slots: {}, transactions: {}, transactionsStatus: {},
    blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
    commitment: CommitmentLevel.CONFIRMED,
    ...filters,
  };
}

export async function* subscribe(
  filters: Partial<SubscribeRequest>,
): AsyncGenerator<SubscribeUpdate> {
  const token = process.env.GRPC_API_TOKEN;
  if (!token) throw new Error("Set GRPC_API_TOKEN before starting");
  const endpoint = process.env.GRPC_ENDPOINT ?? "https://grpc.solanatracker.io";
  // This helper exposes disconnects to the caller instead of auto-reconnecting.
  const client = new Client(endpoint, token, undefined, { enabled: false });
  const stream = await client.subscribe(makeRequest(filters));
  try {
    for await (const update of stream) {
      if (update.ping) {
        await new Promise<void>((resolve, reject) => {
          stream.write(makeRequest({ ping: { id: 1 } }), (error?: Error | null) => {
            if (error) reject(error);
            else resolve();
          });
        });
        continue;
      }
      if (!update.pong) yield update;
    }
  } finally {
    stream.destroy();
  }
}

Receive block metadata

blocks.mts

import { subscribe } from "./stream.mts";

for await (const update of subscribe({ blocksMeta: { blocks: {} } })) {
  if (!update.blockMeta) continue;
  console.log({
    slot: update.blockMeta.slot,
    blockhash: update.blockMeta.blockhash,
    transactions: update.blockMeta.executedTransactionCount,
  });
}

npx tsx blocks.mts

Each row contains a slot, blockhash, and executed transaction count. Stop with Ctrl+C. If nothing arrives, check the token and endpoint in the authentication guide.

Read the payload correctly

Public keys and signatures arrive as bytes; encode them with base58 for display. The client represents protobuf 64-bit integers as strings. Keep raw balances as strings or BigInt until formatting them.

Related guides

Account updates

Transactions

Reliability and performance