Subscribe to Accounts

Account subscriptions allow you to monitor changes to Solana accounts in real-time. This is essential for tracking token balances, program state changes, and any other on-chain data stored in accounts.

Overview

Account subscriptions provide real-time updates whenever an account’s data, lamports, or owner changes. You can filter accounts by:

• Specific account addresses
• Account owner (program)
• Data size
• Memory comparisons (byte patterns at specific offsets)

Filter Structure

1
message SubscribeRequestFilterAccounts {
2
    repeated string account = 2;
3
    repeated string owner = 3;
4
    repeated SubscribeRequestFilterAccountsFilter filters = 4;
5
    optional bool nonempty_txn_signature = 5;
6
}
7
8
message SubscribeRequestFilterAccountsFilter {
9
    oneof filter {
10
        SubscribeRequestFilterAccountsFilterMemcmp memcmp = 1;
11
        uint64 datasize = 2;
12
        bool token_account_state = 3;
13
        SubscribeRequestFilterAccountsFilterLamports lamports = 4;
14
    }
15
}
16
17
message SubscribeRequestFilterAccountsFilterMemcmp {
18
    uint64 offset = 1;
19
    oneof data {
20
        bytes bytes = 2;
21
        string base58 = 3;
22
        string base64 = 4;
23
    }
24
}
25
26
message SubscribeRequestFilterAccountsFilterLamports {
27
    oneof cmp {
28
        uint64 eq = 1;
29
        uint64 ne = 2;
30
        uint64 lt = 3;
31
        uint64 gt = 4;
32
    }
33
}

Filter Options

Account Address Filter

Monitor specific accounts by their public key addresses.

Field: account
Type: repeated string

Use Cases:

• Track a specific token account balance
• Monitor a user’s wallet
• Watch a liquidity pool account
• Track NFT metadata accounts

Owner Filter

Subscribe to all accounts owned by a specific program.

Field: owner
Type: repeated string

Use Cases:

• Monitor all accounts for a specific program
• Track all token accounts (Token Program owned)
• Watch all accounts for a custom program
• Monitor DEX program accounts

Memcmp Filter

Filter accounts by matching byte patterns at specific offsets in the account data.

Field: memcmp (within filters)
Type: SubscribeRequestFilterAccountsFilterMemcmp

Use Cases:

• Filter token accounts for a specific mint
• Match accounts with specific discriminators
• Find accounts containing specific pubkeys

Data Size Filter

Filter accounts by their data size.

Field: datasize (within filters)
Type: uint64

Use Cases:

• Filter by account type based on size
• Optimize bandwidth by excluding large accounts
• Target specific program account types

Token Account State Filter

Filter only for token accounts.

Field: token_account_state (within filters)
Type: bool

Lamports Filter

Filter accounts by their lamport balance.

Field: lamports (within filters)
Type: SubscribeRequestFilterAccountsFilterLamports

Comparison operators:

• eq - Equal to
• ne - Not equal to
• lt - Less than
• gt - Greater than

Use Cases:

• Find accounts with specific balance
• Monitor accounts above/below threshold
• Filter out empty accounts

Nonempty Transaction Signature

Only receive account updates that are associated with a transaction.

Field: nonempty_txn_signature
Type: optional bool

Combining Filters

You can combine multiple filters to narrow your subscription to match specific patterns.

Response Structure

When an account changes, you receive a SubscribeUpdateAccount message:

1
message SubscribeUpdateAccount {
2
    SubscribeUpdateAccountInfo account = 1;
3
    uint64 slot = 2;
4
    bool is_startup = 3;
5
}
6
7
message SubscribeUpdateAccountInfo {
8
    bytes pubkey = 1;
9
    uint64 lamports = 2;
10
    bytes owner = 3;
11
    bool executable = 4;
12
    uint64 rent_epoch = 5;
13
    bytes data = 6;
14
    uint64 write_version = 7;
15
    optional bytes txn_signature = 8;
16
}