Learn getProgramAccounts use cases, code examples, request parameters, response structure, and tips.
getProgramAccounts
RPC method is a powerful tool for querying the Solana blockchain. It allows you to retrieve all accounts that are owned by a specific on-chain program. This is essential for a wide range of applications, from finding all token accounts associated with a user for a particular token mint, to discovering all user-specific data accounts for a decentralized application.
Due to the potentially large number of accounts a program might own, getProgramAccounts
provides robust filtering capabilities to help you narrow down your search and retrieve only the data you need efficiently.
getProgramAccounts
can find all instances of that structure.programId
(string
, required):
"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
(for the SPL Token Program).options
(object
, optional): A configuration object with the following fields:
commitment
(string
): Specifies the commitment level (e.g., "finalized"
, "confirmed"
).encoding
(string
): Encoding for the data
field within each returned account. Defaults to "base64"
.
"base58"
: Slower alternative for binary data."base64"
: Standard base64 encoding for binary data."base64+zstd"
: Base64 encoded, zstd-compressed binary data."jsonParsed"
: If the RPC node has a parser for the program’s account type (e.g., SPL Token, Stake), the data
field will be a structured JSON object. This is highly recommended for readability and ease of use.filters
(array
): An array of filter objects to apply to the accounts. This is crucial for performance and relevance. You can use up to 4 filters. Common filters include:
dataSize
(object
):
dataSize
(u64
): Filters accounts by their data length in bytes. Example: { "dataSize": 165 }
(for SPL Token accounts).memcmp
(object
): Memory comparison. Compares a slice of the account’s data with the provided bytes.
offset
(usize
): The byte offset into the account data at which to start the comparison.bytes
(string
): A base-58 encoded string of the bytes to match. The byte string must be less than 129 bytes.memcmp
with offset: 0
(where the mint address is stored in a token account) and bytes
set to the mint’s public key.dataSlice
(object
): Returns only a specific slice of each account’s data. Useful for large accounts when you only need partial data.
offset
(usize
): The byte offset from which to start slicing.length
(usize
): The number of bytes to return.dataSlice
is primarily for binary encodings, not jsonParsed
.withContext
(boolean
): If true
, the response will be an RpcResponse
object containing a context
(with slot
) and the value
(the array of accounts). If false
or omitted, it typically returns just the array of accounts. Behavior can vary slightly by RPC provider.minContextSlot
(u64
): The minimum slot that the request can be evaluated at.pubkey
(string
): The base-58 encoded public key of the account.account
(object
):
lamports
(u64
): Balance of the account in lamports.owner
(string
): Base-58 encoded public key of the program that owns this account (this will be the programId
you queried by).data
(string
, array
, or object
): The account’s data, formatted according to the encoding
parameter.
jsonParsed
: A JSON object representing the deserialized account state.base64
: An array ["encoded_string", "base64"]
.executable
(boolean
): Whether the account is executable (i.e., a program itself).rentEpoch
(u64
): The epoch at which this account will next owe rent.space
(u64
, optional): The data length of the account in bytes. Sometimes referred to as data.length
if data is a buffer, or part of the parsed structure.withContext: true
is used, this array will be nested under the value
field of an RpcResponse
object.
dataSize
to filter for token accounts (165 bytes) and memcmp
to match the USDC mint address at offset 0.
dataSize
(165 bytes) and memcmp
at offset 32 (where the owner pubkey is stored in a token account).
memcmp
: Filter accounts that match a specific pattern at a given offsetdataSize
: Filter accounts by their exact data sizegetProgramAccounts
can be resource-intensive on RPC nodes, especially without filters or for programs with many accounts. Always use filters (dataSize
, memcmp
) and dataSlice
where possible to reduce the query scope and response size.getProgramAccounts
calls can hit these limits.memcmp
requires understanding the byte layout of the account data you are querying.jsonParsed
Availability: The jsonParsed
encoding depends on the RPC node having a parser for the specific program’s account types. It’s widely supported for common programs like SPL Token.getProgramAccounts
is an indispensable method for developers needing to query and interact with sets of accounts owned by a program. Mastering its filtering options is key to building efficient and robust Solana applications.