in-solana by Supanode

Yellowstone gRPC Subscription Filters

TL;DR

  • - Yellowstone gRPC uses protobuf filter messages to subscribe to specific data
  • - Five filter types cover accounts, transactions, slots, blocks and entries
  • - Filters can match by account address, program owner, transaction signature or account inclusion
  • - Multiple filters combine with OR logic within the same subscribe request

Yellowstone gRPC subscriptions use protobuf filter messages to select which data the server streams to your client. Each filter type targets a different data category.

Filter types

FilterStreamsKey fields
accountsAccount updatesaccount, owner, filters
transactionsTransaction notificationsvote, failed, account_include, account_exclude
slotsSlot status changesfilter_by_commitment
blocksFull block dataaccount_include, include_transactions, include_accounts, include_entries
entryPoH entry data(no additional fields)

Account filters

Subscribe to updates for specific accounts or all accounts owned by a program:

{
  "accounts": {
    "my_filter": {
      "account": ["So11111111111111111111111111111111111111112"],
      "owner": [],
      "filters": []
    }
  }
}
  • account — list of base58 account addresses to watch
  • owner — list of program IDs; streams updates for any account owned by these programs
  • filters — optional memcmp or datasize filters on account data, similar to getProgramAccounts

An empty account and owner with no filters streams all account updates. This produces extremely high volume.

Transaction filters

Subscribe to transactions involving specific accounts:

{
  "transactions": {
    "my_filter": {
      "vote": false,
      "failed": false,
      "account_include": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
      "account_exclude": []
    }
  }
}
  • vote — include validator vote transactions (usually false)
  • failed — include failed transactions
  • account_include — only transactions involving these accounts
  • account_exclude — exclude transactions involving these accounts

Slot filters

{
  "slots": {
    "my_filter": {
      "filter_by_commitment": true
    }
  }
}

Streams slot status updates: processed, confirmed, finalized.

Combining filters

A single subscribe request can include multiple named filters across types. Messages from all active filters arrive on the same stream, each tagged with its filter name. Filters of the same type combine with OR logic — a message matching any filter is delivered.

FAQ

Can I update filters without reconnecting? Yes. Send a new SubscribeRequest on the existing stream to replace the active filter set.

What happens if my filter matches too much data? The server may drop your connection or apply backpressure. Start with narrow filters (specific accounts) and widen only as needed.

Do filters support regex or wildcards? No. Account addresses and program IDs must be exact base58 strings.

Sources

Updated: