API Reference

gRPC Streaming

This document outlines how to interact with the gRPC-based streaming service for Solana data. Unlike a traditional JSON RPC, gRPC lets you subscribe to a variety of Solana events—such as slots, account changes, blocks, and transactions—in real time through long-lived streams.

Overview

  • Real-time Solana Data: Stream blocks, slots, transactions, and account updates directly to your application.
  • Flexible Filters: Narrow down data by setting filters on account addresses, owners, program data size, transaction types, and more.
  • Keep-Alive Mechanisms: Use a ping/pong approach to prevent your connection from timing out behind certain load balancers or cloud providers.
  • Unary (Single-Request) Methods: In addition to subscriptions, gRPC offers single-request calls (e.g., getting a blockhash or checking Solana version).

To use this product, you'll have to purchase a dedicated node here: https://hellomoon.io/dedicated-nodes

Getting Started

  1. Generate gRPC stubs (if necessary): You’ll need client libraries in the programming language of your choice. Example clients may already be available in the project’s source (e.g., Go, Rust, TypeScript).
  2. Establish a Connection: Point your gRPC client to the service endpoint.
  3. Build a Subscribe Request: Specify what data you want to receive (slots, accounts, transactions, blocks, etc.) and which filters to apply.
  4. Listen for Streaming Updates: Handle incoming notifications according to your application’s needs (e.g., updating a database or triggering application logic).

Subscription Structure

Common Fields

  • commitment: Defines the desired commitment level (processed, confirmed, or finalized).
  • accounts_data_slice: An optional array specifying { offset, length } for partial account data retrieval. Useful when you only need specific parts of large account data.
  • ping: If set to true, the server will periodically respond with a “pong” message. This helps keep connections alive where idle streams might otherwise be closed by network providers.

Slots

A slots subscription notifies you when a new Solana slot is processed. You can also filter by commitment level to receive only certain confirmations.

Accounts

An accounts subscription sends updates whenever a specified account or set of accounts changes. You can filter:

  • account: An array of public keys. Receives changes for any matching key.
  • owner: An array of public keys corresponding to account owners.
  • filters: Similar to the classic Solana getProgramAccounts filters, supporting dataSize and memcmp constraints (in bytes, base58, or base64 format).

If no fields are set, changes to all accounts will be streamed. If fields are present, they act as a logical AND, and multiple values within each field act as OR (except for filters, which individually act as logical AND).

Transactions

Transaction subscriptions can include or exclude various categories and specific accounts:

  • vote: Include or exclude vote transactions.
  • failed: Include or exclude failed transactions.
  • signature: Only receive transactions matching a specific signature.
  • account_include: Receive transactions that involve at least one account from the list.
  • account_exclude: Exclude transactions that involve any account from the list.
  • account_required: Only receive transactions that include all listed accounts.
    By default, all transactions are included if no filter fields are set.

Blocks

Block subscriptions deliver reconstructed blocks (including transactions, account changes, and entries) as soon as they are available. You can specify:

  • account_include: Return block data only if it contains transactions or updates involving specific accounts.
  • include_transactions: When set, the block’s transactions are provided in the message.
  • include_accounts: When set, the block’s account updates are included in the message.
  • include_entries: When set, any “entries” that make up the block are included.

Note: There’s a known limitation in block reconstruction for some validator-generated blocks, where the number of block entries can show as zero due to incomplete metadata. This may result in partial or missing transaction data.

Block Metadata

Similar to Blocks but primarily for higher-level metadata. This subscription does not include full transactions or account updates.

Keep-Alive with Ping/Pong

Some infrastructure layers (e.g., load balancers, reverse proxies) drop gRPC connections that remain idle. To counter this, set the ping field in your subscription request to true. You will periodically receive a “pong” message from the server, and you can respond (or simply process it) to keep the stream active.

Unary RPC Methods

Besides streaming subscriptions, there are a few single-request methods that can simplify routine queries:

  • Ping: Check connectivity (often used internally; not always necessary).
  • GetLatestBlockhash: Retrieve the network’s most recently processed blockhash.
  • GetBlockHeight: Query the current block height.
  • GetSlot: Request the current slot.
  • IsBlockhashValid: Verify if a given blockhash is still valid.
  • GetVersion: Return information about the Solana version.

Use these lightweight calls when you only need a single piece of information rather than a continuous stream.

Connection Tips

Idle Timeout: If your application is behind a load balancer or a service with idle timeouts, leverage the ping subscription field so the server can regularly respond with pong messages.
Filter Usage: Use filters judiciously. Overly broad filters can generate high message volume, while overly restrictive ones may miss data you need.
Handling Errors: Be prepared for partial blocks or missing transaction entries on certain edge cases, due to upstream issues in Solana block metadata.

Additional Resources

Official gRPC Subscriptions Reference