Subscribe

Subscribe to accounts, transactions, blocks, and slot updates to receive real-time notifications using the high-performance gRPC API.

Authorizations

x-token · string · required

Your Helius API key. You can get one for free in the dashboard.

Message

The gRPC API supports multiple subscription types that can be combined in a single request:

accounts · object

Subscribe to account updates. Returns data when specified accounts are modified.

Hide properties

account · array

Array of account pubkeys to monitor.

owner · array

Array of owner pubkeys to monitor (all accounts owned by these programs).

filters · object

Optional filters to apply.

Show filter options

memcmp · object

Filter by specific bytes at an offset in account data.

Show properties

offset · integer

Position in bytes to start comparing data.

bytes · string

The data to compare against (bytes format).

base58 · string

The data to compare against (base58 format).

base64 · string

The data to compare against (base64 format).

datasize · integer

Filter by exact account data size in bytes.

token_account_state · boolean

Filter to only token accounts.

lamports · object

Filter by SOL balance with comparisons.

Show comparison operators

eq · integer

Equal to specified amount.

ne · integer

Not equal to specified amount.

lt · integer

Less than specified amount.

gt · integer

Greater than specified amount.

nonempty_txn_signature · boolean

If true, only include updates caused by a transaction. If false, only include updates not caused by a transaction. If undefined, include all updates.

slots · object

Subscribe to slot updates.

Hide properties

filter_by_commitment · boolean

Filter slots by commitment level.

interslot_updates · boolean

Include intermediate slot status updates (PROCESSED, CONFIRMED, FINALIZED, FIRST_SHRED_RECEIVED, COMPLETED, CREATED_BANK, DEAD).

transactions · object

Subscribe to transaction updates.

Hide properties

vote · boolean

Include vote transactions.

failed · boolean

Include failed transactions.

signature · string

Monitor specific transaction signature.

account_include · array

Only include transactions affecting these accounts.

account_exclude · array

Exclude transactions affecting these accounts.

account_required · array

Transactions must affect all of these accounts.

token_accounts · enum

Optional associated token account (ATA) expansion (field tag 30, TokenAccountExpansionControlFlag). When set, an account_include wallet also matches transactions where it owns an SPL token balance — for example, incoming token transfers that touch the wallet’s token account rather than its pubkey. Two variants:

• ALL (0) — match any transaction referencing a token balance the wallet owns, even if unchanged. Higher volume.
• BALANCE_CHANGED (1) — match when the wallet owns a token balance whose amount changed (or whose token account was closed) in the transaction.

To disable expansion, leave the field absent (None) — there is no “off” enum value. An out-of-range integer is rejected at config build: Invalid token_accounts value, expected ALL (0) or BALANCE_CHANGED (1).

ALL is the zero value. A client that sets the enum to 0 expecting “default/off” gets ALL — the broadest, highest-volume mode. The only way to mean “no expansion” is to omit the field entirely.

transactions_status · object

Subscribe to transaction status updates.

Hide properties

vote · boolean

Include vote transactions.

failed · boolean

Include failed transactions.

signature · string

Monitor specific transaction signature.

account_include · array

Only include transactions affecting these accounts.

account_exclude · array

Exclude transactions affecting these accounts.

account_required · array

Transactions must affect all of these accounts.

blocks · object

Subscribe to block updates.

Hide properties

account_include · array

Only include blocks with transactions affecting these accounts.

include_transactions · boolean

Include full transaction details.

include_accounts · boolean

Include account updates.

include_entries · boolean

Include block entries.

blocks_meta · object

Subscribe to block metadata updates (lighter than full block updates).

Hide returns

slot · integer

Slot number.

blockhash · string

Blockhash.

rewards · array

Rewards information.

block_time · integer

Block time.

block_height · integer

Block height.

parent_slot · integer

Parent slot.

parent_blockhash · string

Parent blockhash.

executed_transaction_count · integer

Transaction count.

entries_count · integer

Entry count.

entry · object

Subscribe to entry updates.

Hide returns

slot · integer

Slot number.

index · integer

Entry index.

num_hashes · integer

Number of hashes.

hash · string

Hash.

executed_transaction_count · integer

Transaction count.

starting_transaction_index · integer

Starting transaction index.

commitment · enum

The commitment level for the subscription:

Hide levels

PROCESSED · integer

(0): Processed by the current node.

CONFIRMED · integer

(1): Confirmed by supermajority of the cluster.

FINALIZED · integer

(2): Finalized by the cluster.

accounts_data_slice · array

Specifies partial account data to receive:

Hide properties

offset · integer

Position in bytes to start reading data.

length · integer

Number of bytes to read.

ping · object

Enable ping-pong messages for connection health monitoring.

Hide properties

id · integer

Numeric identifier for the ping.

from_slot · integer

Starting slot to receive updates from. Updates for slots before this value will be excluded.

Accounts Subscription

{
  "slots": {
      "slots": {}
  },
  "accounts": {
      "user-defined-label": {
          "account": [
              "DjUF9ASpyMbVpGJmTvzfSbCgUWj6JowwLh8dGAJzSPmu",
              "5U3bH5b6XtG99aVCE9ycvDgBKQx3fVT8WwTNbMToFuEr"
          ],
          "owner": [
              "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
          ],
          "filter": {
              "memcmp": {
                  "offset": 0,
                  "bytes": "0102030405"
              },
              "datasize": 165,
              "token_account_state": true,
              "lamports": {
                  "gt": 100000000
              }
          },
          "nonempty_txn_signature": true
      }
  },
  "transactions": {},
  "blocks": {},
  "blocks_meta": {},
  "accounts_data_slice": [],
  "commitment": 1
}

Commitment Levels

All subscriptions support the following commitment levels:

• PROCESSED: Processed by the current node (0)
• CONFIRMED: Confirmed by supermajority of the cluster (1)
• FINALIZED: Finalized by the cluster (2)

Response Structure

Subscription responses include:

• filters: The filter names that matched this update
• One of the following update types:
  • account: Account data, owner, lamports, executable status, etc.
  • slot: Slot information and status updates
  • transaction: Full transaction details, signature, and metadata
  • transaction_status: Transaction execution status (success/error)
  • block: Complete block data with transactions, accounts, rewards, etc.
  • block_meta: Lightweight block metadata without full transaction details
  • entry: Entry details within a block
  • ping/pong: Connection health check messages
• created_at: Timestamp when the update was created

Account Update

{
  "filters": ["accounts"],
  "account": {
    "account": {
      "pubkey": "BASE58_ENCODED_PUBKEY",
      "lamports": 12345678,
      "owner": "BASE58_ENCODED_OWNER",
      "executable": false,
      "rent_epoch": 361,
      "data": "BASE64_ENCODED_DATA",
      "write_version": 123,
      "txn_signature": "BASE58_ENCODED_SIGNATURE"
    },
    "slot": 189554321,
    "is_startup": false
  },
  "created_at": "2023-04-28T12:34:56.789Z"
}