Solana gRPC

Solana Yellowstone gRPC establishes a persistent stream and pushes data to your application as events occur on-chain. This makes it well suited for systems that need fresh Solana data immediately, such as trading infrastructure, indexers, real-time analytics, wallets, and monitoring services.

With Tatum’s Yellowstone gRPC endpoint, you can retrieve:

• Account updates
• Transactions
• Slots
• Blocks
• Block metadata
• And more

Getting Started

Set Up Your Environment

This guide uses Node.js with TypeScript and the official Yellowstone gRPC client under MacOS. You'll need two things installed on your Mac before writing any code: Node.js and grpcurl.

1. Install Node.js (if you don't have it)
   TypeScript

   brew install node
   //Verify you have version 18 or higher:
   node -v

2. Install grpcurl (optional)
   Command-line tool for testing gRPC endpoints directly. It's useful for verifying your connection before running any code:
   TypeScript

   brew install grpcurl

3. Create your project folder and install Yellowstone gRPC client with dependencies:
   TypeScript

   mkdir tatum-grpc-test //Use any other name of your choice
   cd tatum-grpc-test
   npm init -y
   npm install @triton-one/yellowstone-grpc
   npm install -D tsx typescript @types/node

   📘

   Note

   Use tsx instead of ts-node to run TypeScript files directly. It's faster and requires no additional tsconfig.json setup.

4. Download the Yellowstone proto files. These define the gRPC service schema and are required for grpcurl smoke tests:
   TypeScript

   curl -o geyser.proto https://raw.githubusercontent.com/rpcpool/yellowstone-grpc/master/yellowstone-grpc-proto/proto/geyser.proto
   curl -o solana-storage.proto https://raw.githubusercontent.com/rpcpool/yellowstone-grpc/master/yellowstone-grpc-proto/proto/solana-storage.proto
   
   //Your project folder should now look like this:
   tatum-grpc-test/
   ├── geyser.proto
   ├── solana-storage.proto
   ├── node_modules/
   ├── package.json
   └── get-block.ts      // ← your script goes here

5. Verify your connection with grpcurl before writing any code .
   • Tatum-specific: The gRPC endpoint is solana-mainnet-grpc.gateway.tatum.io:443.
   • Authentication uses the x-token header. This is the same as the x-api-key used on Tatum's REST endpoints and Gateway, just under a different header name as required by the Yellowstone protocol.
   TypeScript

   grpcurl \
     -proto geyser.proto \
     -import-path . \
     -H "x-token: YOUR_API_KEY" \
     solana-mainnet-grpc.gateway.tatum.io:443 \
   geyser.Geyser/GetVersion
   //Expected Response Format:
   {
     "version": "{\"version\":{\"package\":\"yellowstone-grpc-geyser\",\"version\":\"12.1.0+solana.3.1.10\",\"proto\":\"12.1.0+solana.3.1.10\",\"solana\":\"3.1.10\",\"git\":\"f0ae884\",\"rustc\":\"1.86.0\",\"buildts\":\"2026-03-12T09:16:09.772120954Z\"},\"extra\":{\"hostname\":\"relevant-marten\"}}"
   }

   🚧

   Attention

   • If you see a version response, your endpoint and API key are working.
   • If this step fails, no amount of Node.js code will fix it. Confirm your environment setup and credentials

Authentication in Yellowstone gRPC client

1. Get the Solana gRPC URL
2. Fetch and an API Key from your Tatum Dashboard Account for authentication
3. Make sure your requests are Authenticated:

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

const ENDPOINT    = "https://solana-mainnet-grpc.gateway.tatum.io";
const X_TOKEN     = "YOUR_API_KEY";

Example Requests

🚧

Attention

These are basic examples. For production use, we encourage implement error handling, reconnection logic, and data processing.

Retrieve an account

import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  "slots": {
    "slots": {}
  },
  "accounts": {
    "wsol/usdc": {
      "account": ["8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6"]
    }
  },
  "transactions": {},
  "blocks": {},
  "blocksMeta": {},
  "accountsDataSlice": [],
  "commitment": CommitmentLevel.CONFIRMED
};

Retrieve all finalized non-vote and non-failed transactions

import { CommitmentLevel } from "@triton-one/yellowstone-grpc";

const request = {
  "slots": {
    "slots": {}
  },
  "accounts": {},
  "transactions": {
    "alltxs": {
      "vote": false,
      "failed": false
    }
  },
  "blocks": {},
  "blocksMeta": {},
  "accountsDataSlice": [],
  "commitment": CommitmentLevel.FINALIZED
};

Retrieve slots

const request = {
  "slots": {
    "incoming_slots": {}
  },
  "accounts": {},
  "transactions": {},
  "blocks": {},
  "blocksMeta": {},
  "accountsDataSlice": []
};

Retrieve blocks

const request = {
  "slots": {},
  "accounts": {},
  "transactions": {},
  "blocks": {
    "blocks": {}
  },
  "blocksMeta": {},
  "accountsDataSlice": []
};

Retrieve block metadata

const request = {
  "slots": {},
  "accounts": {},
  "transactions": {},
  "blocks": {},
  "blocksMeta": {
    "blockmetadata": {}
  },
  "accountsDataSlice": []
};