> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# getProgramAccountsV2
> Versão aprimorada de getProgramAccounts com paginação baseada em cursor e suporte a changedSinceSlot para consulta eficiente de grandes conjuntos de contas de programas específicos do Solana com atualizações incrementais.
## Visão Geral
`getProgramAccountsV2` é uma versão aprimorada do método padrão `getProgramAccounts`, projetada para aplicativos que precisam consultar eficientemente grandes conjuntos de contas de programas específicos do Solana. Este método introduz paginação baseada em cursor e capacidades de atualização incremental.
**Novos Recursos no V2:**
* **Paginação baseada em cursor**: Configure limites de 1 a 10.000 contas por requisição
* **Atualizações incrementais**: Use `changedSinceSlot` para buscar apenas contas recentemente modificadas
* **Melhor performance**: Evita timeouts e reduz o uso de memória para grandes conjuntos de dados
* **Compatibilidade reversa**: Suporta todos os parâmetros existentes de `getProgramAccounts`
* **Opcional `withContext`**: `true` adiciona `slot` e `apiVersion` sob `result.context`; omita ou `false` e eles não serão incluídos
## Benefícios Principais
Lide com programas com milhões de contas paginando eficientemente pelos resultados
Use `changedSinceSlot` para atualizações incrementais e sincronização de dados em tempo real
Grandes consultas que anteriormente expiravam agora funcionam de forma confiável com paginação
Processe dados em blocos ao invés de carregar tudo na memória de uma vez
## Melhores Práticas de Paginação
**Comportamento Importante da Paginação**: O fim da paginação é indicado apenas quando **nenhuma conta é retornada**. A API pode retornar menos contas do que o limite devido ao filtro - sempre continue paginando até que `paginationKey` seja `null`.
### Padrão Básico de Paginação
```typescript theme={"system"}
let allAccounts = [];
let paginationKey = null;
do {
const response = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: '1',
method: 'getProgramAccountsV2',
params: [
"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
{
encoding: 'base64',
filters: [{ dataSize: 165 }],
limit: 5000,
...(paginationKey && { paginationKey })
}
]
})
});
const data = await response.json();
allAccounts.push(...data.result.accounts);
paginationKey = data.result.paginationKey;
} while (paginationKey);
```
### Atualizações Incrementais
```typescript theme={"system"}
// Get only accounts modified since slot 150000000
const incrementalUpdate = await fetch(`https://mainnet.helius-rpc.com/?api-key=${API_KEY}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: '1',
method: 'getProgramAccountsV2',
params: [
programId,
{
encoding: 'jsonParsed',
limit: 1000,
changedSinceSlot: 150000000
}
]
})
});
```
## Dicas de Performance
**Tamanho de Limite Ótimo**: Para a maioria dos casos de uso, um limite de 1.000-5.000 contas por requisição fornece o melhor equilíbrio de performance e confiabilidade.
* **Comece com limites menores** (1000) e aumente com base na performance da sua rede
* **Use a codificação apropriada**: `jsonParsed` para conveniência, `base64` para performance
* **Aplique filtros** para reduzir o tamanho do conjunto de dados antes da paginação
* **Armazene `paginationKey`** para retomar consultas se interrompidas
* **Monitore os tempos de resposta** e ajuste os limites conforme necessário
## `withContext` (opcional)
Boolean no objeto de configuração do programa (`params[1]`). Apenas a forma de `result` muda, não filtros, limites ou paginação.
```json theme={"system"}
// Omitted or false
{ "jsonrpc": "2.0", "id": "1", "result": { "accounts": [], "paginationKey": null } }
// true — snapshot metadata plus page under `result.value`
{ "jsonrpc": "2.0", "id": "1", "result": {
"context": { "slot": 411895550, "apiVersion": "3.1.9" },
"value": { "accounts": [], "paginationKey": null }
}}
```
## Migração de getProgramAccounts
Migrar do método original é simples - basta substituir o nome do método e adicionar parâmetros de paginação:
```diff theme={"system"}
{
"jsonrpc": "2.0",
"id": "1",
- "method": "getProgramAccounts",
+ "method": "getProgramAccountsV2",
"params": [
"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
{
"encoding": "base64",
"filters": [{ "dataSize": 165 }],
+ "limit": 5000
}
]
}
```
## Métodos Relacionados
Método original sem paginação
Método V2 para consultas de contas de token
## Parâmetros de Requisição
A chave pública do programa Solana (endereço) para consultar contas, como uma string codificada em base-58.
O nível de comprometimento para a requisição.
* `confirmed`
* `finalized`
* `processed`
O slot mínimo em que a requisição pode ser avaliada.
Quando `true`, retorna `result.context` (metadados do instantâneo: `slot`, `apiVersion`) e aninha
`accounts` e `paginationKey` sob `result.value`. Quando `false` ou omitido,
esses campos aparecem diretamente em `result` (por exemplo, `result.accounts`). Mesmos filtros e limites se aplicam.
Formato de codificação para os dados retornados da conta.
* `jsonParsed`
* `base58`
* `base64`
* `base64+zstd`
Solicitar um trecho dos dados da conta.
Número de bytes a serem retornados.
Deslocamento em bytes a partir do qual começar a leitura.
Número máximo de contas a serem retornadas por requisição (1-10.000).
Cursor de paginação codificado em base-58 para buscar páginas subsequentes. Use o paginationKey da resposta anterior.
Retorna apenas contas que foram modificadas a partir ou após este número de slot. Útil para atualizações incrementais.
Sistema de filtragem poderoso para consultar eficientemente padrões específicos de dados de contas Solana.
## OpenAPI
````yaml pt-BR/openapi/rpc-http/getProgramAccountsV2.yaml POST /
openapi: 3.1.0
info:
title: Solana RPC API
version: 1.0.0
description: >-
API de indexação de contas de programa Solana aprimorada com paginação
baseada em cursor e suporte a changedSinceSlot para consultar de forma
eficiente grandes conjuntos de contas pertencentes a programas específicos.
Suporta atualizações incrementais por meio de filtragem baseada em slot para
sincronização de dados em tempo real.
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://mainnet.helius-rpc.com
description: Ponto de extremidade RPC Mainnet
- url: https://devnet.helius-rpc.com
description: Ponto de extremidade RPC Devnet
security: []
paths:
/:
post:
tags:
- RPC
summary: getProgramAccountsV2
description: >
Versão aprimorada do getProgramAccounts com paginação baseada em cursor
e suporte a changedSinceSlot para consultar de forma eficiente grandes
conjuntos de contas pertencentes a programas Solana específicos. Permite
busca de dados incremental com tamanhos de página configuráveis de até
10.000 contas por solicitação. O parâmetro changedSinceSlot permite
recuperar apenas contas modificadas desde um slot específico do
blockchain, perfeito para indexação em tempo real e fluxos de trabalho
de sincronização de dados. Essencial para aplicativos que lidam com
descobertas de contas de programa em larga escala, como protocolos DeFi,
marketplaces de NFT e plataformas de análise de blockchain.
Nota: O fim da paginação é indicado apenas quando nenhuma conta é
retornada. A API pode retornar menos contas do que o limite devido à
filtragem - continue a paginação até que paginationKey seja nulo.
**withContext**: Booleano opcional no objeto de configuração (juntamente
com codificação, limite, etc). Quando `withContext` é `true`, o RPC
retorna a forma padrão envolvida de Solana: `result.context` (metadados
do instantâneo, incluindo `slot` e geralmente `apiVersion`) e
`result.value` contendo `accounts`, `paginationKey`, Quando
`withContext` é `false` ou omitido, esses campos são retornados
diretamente em `result`
(por exemplo, `result.accounts`). Filtros, limites e comportamento de
paginação são inalterados; apenas o formato JSON de `result` difere.
operationId: getProgramAccountsV2
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- jsonrpc
- id
- method
- params
properties:
jsonrpc:
type: string
description: A versão do protocolo JSON-RPC.
enum:
- '2.0'
example: '2.0'
default: '2.0'
id:
type: string
description: Um identificador único para a solicitação.
example: '1'
default: '1'
method:
type: string
description: O nome do método RPC a ser invocado.
enum:
- getProgramAccountsV2
example: getProgramAccountsV2
default: getProgramAccountsV2
params:
type: array
description: Parâmetros para o método paginado aprimorado.
default:
- TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- encoding: base64
limit: 1000
items:
oneOf:
- type: string
description: >-
A chave pública do programa Solana (endereço) para
consultar contas, como uma string codificada em
base-58.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
- type: object
description: >-
Opções de configuração aprimoradas com suporte a
paginação para otimizar consultas de contas de
programa.
properties:
commitment:
type: string
description: O nível de compromisso para a solicitação.
enum:
- confirmed
- finalized
- processed
example: finalized
minContextSlot:
type: integer
description: O slot mínimo que a solicitação pode ser avaliada.
example: 1000
withContext:
type: boolean
description: >
Quando `true`, retorna `result.context` (metadados
do instantâneo: `slot`, `apiVersion`) e aninha
`accounts` e `paginationKey` em `result.value`.
Quando `false` ou omitido,
esses campos aparecem diretamente em `result` (por
exemplo, `result.accounts`). Os mesmos filtros e
limites se aplicam.
example: true
encoding:
type: string
description: >-
Formato de codificação para os dados da conta
retornados.
enum:
- jsonParsed
- base58
- base64
- base64+zstd
example: base64
dataSlice:
type: object
description: Solicitar um fragmento dos dados da conta.
properties:
length:
type: integer
description: Número de bytes a serem retornados.
example: 50
offset:
type: integer
description: >-
Deslocamento em bytes a partir do qual começar
a leitura.
example: 0
limit:
type: integer
description: >-
Número máximo de contas a serem retornadas por
solicitação (1-10.000).
minimum: 1
maximum: 10000
example: 1000
paginationKey:
type: string
description: >-
Cursor de paginação codificado em base-58 para
buscar páginas subsequentes. Use o paginationKey
da resposta anterior.
example: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
changedSinceSlot:
type: integer
description: >-
Retornar apenas contas que foram modificadas a
partir deste número de slot. Útil para
atualizações incrementais.
example: 12345678
filters:
type: array
description: >-
Sistema de filtragem poderoso para consultar
eficientemente padrões de dados específicos de
contas Solana.
items:
oneOf:
- type: object
description: >-
Filtrar contas Solana pelo tamanho exato dos
dados em bytes.
properties:
dataSize:
type: integer
description: >-
O tamanho exato dos dados da conta em
bytes para filtragem.
example: 165
- type: object
description: >-
Filtrar contas Solana comparando dados em
deslocamentos de memória específicos (filtro
mais poderoso).
properties:
memcmp:
type: object
description: >-
Filtro de comparação de memória para
encontrar contas com padrões de dados
específicos.
properties:
offset:
type: integer
description: >-
Deslocamento em bytes dentro dos dados
da conta para realizar a comparação.
example: 4
bytes:
type: string
description: >-
Dados codificados em base-58 para
comparar na posição de deslocamento
especificada.
example: 3Mc6vR
responses:
'200':
description: Contas de programa paginadas recuperadas com sucesso.
content:
application/json:
schema:
type: object
properties:
jsonrpc:
type: string
description: A versão do protocolo JSON-RPC.
enum:
- '2.0'
example: '2.0'
id:
type: string
description: Identificador correspondente à solicitação.
example: '1'
result:
oneOf:
- $ref: '#/components/schemas/ProgramAccountsV2Page'
title: sem withContext
- type: object
title: com withContext
description: >-
Resultado envolvido quando `withContext` é `true` nas
opções de solicitação.
required:
- context
- value
properties:
context:
type: object
description: >-
Metadados instantâneos para a resposta do nó
(consistência do slot, depuração).
properties:
slot:
type: integer
description: Slot em que o nó criou esta resposta.
example: 411895550
apiVersion:
type: string
description: Versão do API RPC quando disponível.
example: 3.1.9
value:
$ref: '#/components/schemas/ProgramAccountsV2Page'
'400':
description: >-
Solicitação inválida - Parâmetros de solicitação inválidos ou
solicitação malformada.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32602
message: Parâmetros inválidos
data: {}
id: '1'
'401':
description: Não autorizado - Chave API inválida ou ausente.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32001
message: Não autorizado
data: {}
id: '1'
'429':
description: Muitas solicitações - Limite de taxa excedido.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32005
message: Muitas solicitações
data: {}
id: '1'
'500':
description: Erro Interno do Servidor - Ocorreu um erro no servidor.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32603
message: Erro interno
data: {}
id: '1'
'503':
description: Serviço Indisponível - O serviço está temporariamente indisponível.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32002
message: Serviço indisponível
data: {}
id: '1'
'504':
description: >-
Tempo limite do gateway - O tempo limite da solicitação foi
atingido.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
jsonrpc: '2.0'
error:
code: -32003
message: Tempo limite do gateway
data: {}
id: '1'
security:
- ApiKeyQuery: []
components:
schemas:
ProgramAccountsV2Page:
type: object
description: >-
Contas de programa paginadas. Os mesmos campos aparecem no resultado
quando withContext é falso ou omitido, ou em result.value quando
withContext é verdadeiro.
properties:
accounts:
type: array
description: Lista de contas de programa para a página atual.
items:
$ref: '#/components/schemas/ProgramAccountV2Entry'
paginationKey:
type: string
description: >-
Cursor de paginação para a próxima página. Nulo apenas quando
nenhuma conta é retornada (fim da paginação). Note que menos contas
do que o limite podem ser retornadas devido à filtragem, mas isso
não indica o fim da paginação.
example: 8WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
nullable: true
ErrorResponse:
type: object
properties:
jsonrpc:
type: string
description: A versão do protocolo JSON-RPC.
enum:
- '2.0'
example: '2.0'
error:
type: object
properties:
code:
type: integer
description: O código de erro.
example: -32602
message:
type: string
description: A mensagem de erro.
data:
type: object
description: Dados adicionais sobre o erro.
id:
type: string
description: Identificador correspondente à solicitação.
example: '1'
ProgramAccountV2Entry:
type: object
properties:
pubkey:
type: string
description: A chave pública da conta como uma string codificada em base-58.
example: CxELquR1gPP8wHe33gZ4QxqGB3sZ9RSwsJ2KshVewkFY
account:
type: object
description: Detalhes sobre a conta.
properties:
lamports:
type: integer
description: Número de lamports atribuídos a esta conta.
example: 15298080
owner:
type: string
description: >-
Chave pública do programa a que esta conta está atribuída,
codificada em base-58.
example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
data:
type: array
description: Dados da conta como binário codificado ou formato JSON.
items:
type: string
example:
- 2R9jLfiAQ9bgdcw6h8s44439
- base64
executable:
type: boolean
description: Indica se a conta contém um programa.
example: false
rentEpoch:
type: integer
description: A época em que esta conta deverá pagar o aluguel novamente.
example: 28
space:
type: integer
description: O tamanho dos dados da conta.
example: 165
securitySchemes:
ApiKeyQuery:
type: apiKey
in: query
name: api-key
description: >-
Sua chave API da Helius. Você pode obter uma gratuitamente no
[dashboard](https://dashboard.helius.dev/api-keys).
````