Filter Messages

Overview

Filters define which updates you want to receive from the Geyser stream. Each filter type allows you to specify criteria for matching accounts, transactions, blocks, or slots.

Account Filters

SubscribeRequestFilterAccounts

Filters for account updates.

message SubscribeRequestFilterAccounts {
  repeated string account = 2;
  repeated string owner = 3;
  repeated SubscribeRequestFilterAccountsFilter filters = 4;
  optional bool nonempty_txn_signature = 5;
}

account

repeated string

List of specific account public keys to subscribe to. If specified, you’ll only receive updates for these exact accounts.

owner

repeated string

List of program public keys. If specified, you’ll receive updates for all accounts owned by these programs.

filters

repeated SubscribeRequestFilterAccountsFilter

Additional filter criteria for accounts (memcmp, datasize, token account state, lamports). Multiple filters are combined with AND logic.

nonempty_txn_signature

bool

If true, only include account updates that have an associated transaction signature. Useful for filtering out startup account loads.

{
  "account": [
    "7xLk17EQQ5KLDLDe44wCmupJKJjTGd8hs3eSVVhCx932",
    "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
  ]
}

{
  "owner": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"]
}

Account Filter Types

SubscribeRequestFilterAccountsFilter

message SubscribeRequestFilterAccountsFilter {
  oneof filter {
    SubscribeRequestFilterAccountsFilterMemcmp memcmp = 1;
    uint64 datasize = 2;
    bool token_account_state = 3;
    SubscribeRequestFilterAccountsFilterLamports lamports = 4;
  }
}

memcmp

SubscribeRequestFilterAccountsFilterMemcmp

Memory comparison filter. Matches accounts where specific bytes at an offset match the provided data.

datasize

uint64

Data size filter. Matches accounts with exactly this many bytes of data.

token_account_state

bool

Token account state filter. If true, matches valid SPL token accounts.

lamports

SubscribeRequestFilterAccountsFilterLamports

Lamports filter. Matches accounts based on their lamport balance.

SubscribeRequestFilterAccountsFilterMemcmp

Memory comparison filter for matching specific bytes in account data.

message SubscribeRequestFilterAccountsFilterMemcmp {
  uint64 offset = 1;
  oneof data {
    bytes bytes = 2;
    string base58 = 3;
    string base64 = 4;
  }
}

offset

uint64

required

Byte offset in the account data where the comparison should begin.

data

oneof

required

Data to compare at the offset. Provide in one of three formats:

bytes - Raw bytes
base58 - Base58-encoded string
base64 - Base64-encoded string

Example: Memcmp Filter for Specific Mint

{
  "memcmp": {
    "offset": 0,
    "base58": "So11111111111111111111111111111111111111112"
  }
}

SubscribeRequestFilterAccountsFilterLamports

Filter accounts based on lamport balance.

message SubscribeRequestFilterAccountsFilterLamports {
  oneof cmp {
    uint64 eq = 1;
    uint64 ne = 2;
    uint64 lt = 3;
    uint64 gt = 4;
  }
}

uint64

Equal to: matches accounts with exactly this many lamports.

uint64

Not equal to: matches accounts without exactly this many lamports.

uint64

Less than: matches accounts with fewer than this many lamports.

uint64

Greater than: matches accounts with more than this many lamports.

Example: Filter by Lamport Balance

{
  "lamports": {
    "gt": 1000000000
  }
}

Example: Combined Account Filters

{
  "owner": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
  "filters": [
    {
      "datasize": 165
    },
    {
      "memcmp": {
        "offset": 0,
        "base58": "So11111111111111111111111111111111111111112"
      }
    }
  ]
}

Transaction Filters

SubscribeRequestFilterTransactions

Filters for transaction updates.

message SubscribeRequestFilterTransactions {
  optional bool vote = 1;
  optional bool failed = 2;
  optional string signature = 5;
  repeated string account_include = 3;
  repeated string account_exclude = 4;
  repeated string account_required = 6;
}

vote

bool

Vote transaction filter:

true - Only vote transactions
false - Only non-vote transactions
null (not set) - All transactions

failed

bool

Failed transaction filter:

true - Only failed transactions
false - Only successful transactions
null (not set) - All transactions

signature

string

Subscribe to updates for a specific transaction signature.

account_include

repeated string

List of account public keys. If specified, only transactions that read or write to at least one of these accounts will be included.

account_exclude

repeated string

List of account public keys. If specified, transactions that read or write to any of these accounts will be excluded.

account_required

repeated string

List of account public keys. If specified, only transactions that read or write to ALL of these accounts will be included. More restrictive than account_include.

Example: Non-Vote Transactions Only

{
  "vote": false,
  "failed": false
}

Example: Transactions Involving Specific Accounts

{
  "account_include": [
    "7xLk17EQQ5KLDLDe44wCmupJKJjTGd8hs3eSVVhCx932",
    "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
  ],
  "vote": false
}

Example: Specific Transaction Signature

{
  "signature": "5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7"
}

SubscribeRequestFilterDeshredTransactions

Filters for deshred transactions (received before execution).

message SubscribeRequestFilterDeshredTransactions {
  optional bool vote = 1;
  repeated string account_include = 2;
  repeated string account_exclude = 3;
  repeated string account_required = 4;
}

Similar to SubscribeRequestFilterTransactions but for pre-execution transactions. Does not include failed or signature filters since execution hasn’t occurred yet.

vote

bool

Vote transaction filter:

true - Only vote transactions
false - Only non-vote transactions
null (not set) - All transactions

account_include

repeated string

List of account public keys. Includes transactions that reference at least one of these accounts (including accounts loaded via address lookup tables).

account_exclude

repeated string

List of account public keys. Excludes transactions that reference any of these accounts.

account_required

repeated string

List of account public keys. Only includes transactions that reference ALL of these accounts.

SubscribeRequestFilterBlocks

Filters for block updates.

message SubscribeRequestFilterBlocks {
  repeated string account_include = 1;
  optional bool include_transactions = 2;
  optional bool include_accounts = 3;
  optional bool include_entries = 4;
}

account_include

repeated string

List of account public keys. If specified, only blocks containing transactions that touch these accounts will be included. If empty, all blocks are included.

include_transactions

bool

If true, include full transaction data in block updates. Default is false to reduce bandwidth.

include_accounts

bool

If true, include full account update data in block updates. Default is false to reduce bandwidth.

include_entries

bool

If true, include entry data in block updates. Default is false.

Example: All Blocks with Transaction Data

{
  "include_transactions": true,
  "include_accounts": false
}

Example: Blocks Involving Specific Accounts

{
  "account_include": [
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
  ],
  "include_transactions": true
}

SubscribeRequestFilterBlocksMeta

Filter for block metadata updates (without full transaction/account data).

message SubscribeRequestFilterBlocksMeta {}

This is an empty filter - simply include it to subscribe to block metadata updates.

Example: Block Metadata Only

{}

Slot Filters

SubscribeRequestFilterSlots

Filters for slot updates.

message SubscribeRequestFilterSlots {
  optional bool filter_by_commitment = 1;
  optional bool interslot_updates = 2;
}

filter_by_commitment

bool

If true, only send slot updates that match the commitment level specified in the SubscribeRequest. If false or not set, send all slot status updates regardless of commitment.

interslot_updates

bool

If true, send additional slot status updates between major commitment levels (e.g., FIRST_SHRED_RECEIVED, CREATED_BANK, COMPLETED). Default is false.

Example: All Slot Updates

{}

Example: Commitment-Filtered Slots with Inter-Slot Updates

{
  "filter_by_commitment": true,
  "interslot_updates": true
}

Entry Filters

SubscribeRequestFilterEntry

Filter for Proof of History entry updates.

message SubscribeRequestFilterEntry {}

This is an empty filter - simply include it to subscribe to entry updates.

Example: Entry Updates

{}

Commitment Levels

CommitmentLevel Enum

Defines when updates are sent based on confirmation status.

enum CommitmentLevel {
  PROCESSED = 0;
  CONFIRMED = 1;
  FINALIZED = 2;
}

PROCESSED

Updates sent as soon as the transaction/block is processed by a validator. Fastest but may be subject to rollback.

CONFIRMED

Updates sent after the block is confirmed by a supermajority of the cluster. Default level. Balance between speed and safety.

FINALIZED

Updates sent only after the block is finalized (rooted). Safest but slowest. Immune to rollbacks.

SubscribeRequest - Main request message that uses these filters
Account Messages - Account update message details
Transaction Messages - Transaction update message details
Block Messages - Block update message details
Slot Messages - Slot update message details

gRPC Methods

Message Types

Configuration

Overview

Account Filters

SubscribeRequestFilterAccounts

Account Filter Types

SubscribeRequestFilterAccountsFilter

SubscribeRequestFilterAccountsFilterMemcmp

Example: Memcmp Filter for Specific Mint

SubscribeRequestFilterAccountsFilterLamports

Example: Filter by Lamport Balance

Example: Combined Account Filters

Transaction Filters

SubscribeRequestFilterTransactions

Example: Non-Vote Transactions Only

Example: Transactions Involving Specific Accounts

Example: Specific Transaction Signature

SubscribeRequestFilterDeshredTransactions

Block Filters

SubscribeRequestFilterBlocks

Example: All Blocks with Transaction Data

Example: Blocks Involving Specific Accounts

SubscribeRequestFilterBlocksMeta

Example: Block Metadata Only

Slot Filters

SubscribeRequestFilterSlots

Example: All Slot Updates

Example: Commitment-Filtered Slots with Inter-Slot Updates

Entry Filters

SubscribeRequestFilterEntry

Example: Entry Updates

Commitment Levels

CommitmentLevel Enum

Build docs developers (and LLMs) love

gRPC Methods

Message Types

Configuration

​Overview

​Account Filters

​SubscribeRequestFilterAccounts

​Example: Subscribe to Specific Accounts

​Example: Subscribe to All Token Program Accounts

​Account Filter Types

​SubscribeRequestFilterAccountsFilter

​SubscribeRequestFilterAccountsFilterMemcmp

Example: Memcmp Filter for Specific Mint

​SubscribeRequestFilterAccountsFilterLamports

Example: Filter by Lamport Balance

​Example: Combined Account Filters

​Transaction Filters

​SubscribeRequestFilterTransactions

​Example: Non-Vote Transactions Only

​Example: Transactions Involving Specific Accounts

​Example: Specific Transaction Signature

​SubscribeRequestFilterDeshredTransactions

​Block Filters

​SubscribeRequestFilterBlocks

​Example: All Blocks with Transaction Data

​Example: Blocks Involving Specific Accounts

​SubscribeRequestFilterBlocksMeta

​Example: Block Metadata Only

​Slot Filters

​SubscribeRequestFilterSlots

​Example: All Slot Updates

​Example: Commitment-Filtered Slots with Inter-Slot Updates

​Entry Filters

​SubscribeRequestFilterEntry

​Example: Entry Updates

​Commitment Levels

​CommitmentLevel Enum

​Related

Build docs developers (and LLMs) love

Overview

Account Filters

SubscribeRequestFilterAccounts

Example: Subscribe to Specific Accounts

Example: Subscribe to All Token Program Accounts

Account Filter Types

SubscribeRequestFilterAccountsFilter

SubscribeRequestFilterAccountsFilterMemcmp

SubscribeRequestFilterAccountsFilterLamports

Example: Combined Account Filters

Transaction Filters

SubscribeRequestFilterTransactions

Example: Non-Vote Transactions Only

Example: Transactions Involving Specific Accounts

Example: Specific Transaction Signature

SubscribeRequestFilterDeshredTransactions

Block Filters

SubscribeRequestFilterBlocks

Example: All Blocks with Transaction Data

Example: Blocks Involving Specific Accounts

SubscribeRequestFilterBlocksMeta

Example: Block Metadata Only

Slot Filters

SubscribeRequestFilterSlots

Example: All Slot Updates

Example: Commitment-Filtered Slots with Inter-Slot Updates

Entry Filters

SubscribeRequestFilterEntry

Example: Entry Updates

Commitment Levels

CommitmentLevel Enum

Related