> ## 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. # Como Indexar Dados Solana > Aprenda a construir, preencher e manter índices Solana atualizados. ## Visão Geral O blockchain Solana armazena dados em um livro-razão sequencial, apenas-apêndice. Isso é ótimo para integridade de dados e rendimento de transações, mas tem um custo significativo: torna a consulta a [dados históricos](/docs/pt-BR/rpc/historical-data) muito ineficiente e proibitivamente lenta. Operações complexas muitas vezes envolvem filtragem, agregação ou junção de dados de várias fontes. Nesses casos, fazer consultas diretas ao Solana é impraticável para a maioria das aplicações do mundo real. Para resolver isso, a maioria das empresas constrói índices privados dos dados históricos do Solana. Este guia cobre todo o ciclo de vida: preenchendo dados históricos com [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress) e outros métodos RPC arquivais, escolhendo um banco de dados e mantendo o índice atualizado com streaming em tempo real. ## Quando usar isso Construa um índice quando: * Seu produto precisa de consultas rápidas e filtradas que chamadas RPC diretas são muito lentas (por exemplo, contas de tokens de uma carteira e saldos, ou todo o histórico de um par de negociação) * Você precisa filtrar, agregar ou unir dados on-chain, ou combiná-los com dados off-chain (preços de CEX, KYC, rótulos) * Você está computando coisas como PnL, análises de titulares ou histórico de vendas de NFT que requerem dados pré-processados e consultáveis * Você está atendendo muitos usuários e não pode se dar ao luxo de latência por solicitação contra a cadeia Se você só precisa de dados padrão de carteira ou ativos, uma API gerenciada pode ser mais simples do que executar seu próprio índice. Veja [Opções complementares](#next-steps) abaixo. ## O que significa indexar dados do Solana? Indexar é o processo de consultar dados do blockchain Solana e armazená-los em um banco de dados de backend (por exemplo, PostgreSQL, ClickHouse) que pode ser usado para atender prontamente solicitações de clientes sem precisar consultar diretamente o blockchain usando [chamadas Solana RPC](/docs/pt-BR/api-reference/rpc/http-methods). Um indexador geralmente faz quatro coisas: 1. **Preencher dados históricos:** usar [métodos RPC arquivais](/docs/pt-BR/rpc/guides/overview#historical-data-archival) para consultar todos os dados históricos 2. **Transmitir novos dados:** processar novos blocos quando forem confirmados pela rede 3. **Analisar e transformar dados:** extrair dados relevantes dos blocos confirmados (por exemplo, transações, mudanças de estado, etc.) 4. **Organizar dados em um banco de dados:** atualizar o índice com os novos dados ### Por que a maioria das empresas constrói índices Solana? As empresas constroem índices Solana porque seus negócios dependem de fornecer acesso rápido e em tempo real a dados de blockchain específicos que as RPCs nativas não oferecem (por exemplo, histórico de vendas de NFT). As empresas também utilizam índices personalizados para combinar dados off-chain (por exemplo, preços de Exchanges Centralizadas, informações KYC, etc.) com seus dados on-chain. #### Exemplo de Carteira Por exemplo, se uma carteira Solana precisar retornar rapidamente as contas de tokens de um usuário e seus saldos, consultar o Solana diretamente com [`getTokenAccountsByOwner`](/docs/pt-BR/api-reference/rpc/http/gettokenaccountsbyowner) e [`getTokenAccountBalance`](/docs/pt-BR/api-reference/rpc/http/gettokenaccountbalance) é muito lento e pode tornar seu produto inutilizável. Em vez disso, as carteiras geralmente mantêm seus próprios índices de endereços de clientes, tokens e saldos de contas. #### Exemplo de Negociação Da mesma forma, uma empresa de negociação de criptomoedas pode querer registrar toda a atividade de negociação que acontece em um par de negociação específico (por exemplo, [SOL-USDC](https://orbmarkets.io/address/So11111111111111111111111111111111111111112/markets?sort_by=volume24h\&sort_type=desc)) ou [mercado](https://orbmarkets.io/) específico para testar seus algoritmos de negociação. Consultar diretamente o blockchain para esses dados seria muito lento para qualquer análise prática de negociação. Em vez disso, traders quantitativos podem optar por construir índices para o mercado SOL-USDC e mantê-lo atualizado com as últimas negociações usando produtos de streaming em tempo real como [LaserStream](/docs/pt-BR/laserstream). #### Exemplo de Filtragem Imagine que um usuário deseja filtrar transações por critérios específicos em seu aplicativo de frontend (por exemplo, por tipo de token, valor da transferência, data ou endereço da carteira). Sem um indexador, seu app precisaria escanear milhões de transações através de centenas de milhares de blocos, verificando cada uma contra os critérios de filtragem. Este processo é muito lento para experiências de usuário modernas. #### Exemplo de PnL Para calcular o lucro e perda (PnL) de um trader, você precisaria: * Encontrar todas as transações associadas à sua carteira em um determinado período * Filtrar transações de swap e rotulá-las como compras ou vendas * Determinar quantas taxas o usuário pagou durante cada swap * Obter os dados de preço histórico para cada token no momento de cada trade * Agregar o PnL de cada transação para calcular o PnL total do trader Calcular tudo isso em tempo real é impraticável e requer uma solução mais rápida e escalável. Com um índice, todas essas informações já estão processadas e armazenadas em um banco de dados consultável. Agora, calcular o PnL de um trader se torna uma única chamada de API atendida instantaneamente. Vamos analisar três abordagens para preencher um índice Solana e mantê-lo atualizado. ## Passo 1: Obter os dados históricos O primeiro passo para construir um índice Solana é obter todos os dados históricos que você considera relevantes. Existem três principais maneiras de fazer isso: 1. [**getTransactionsForAddress**](/docs/pt-BR/rpc/gettransactionsforaddress) (recomendado) 2. [**getSignaturesForAddress**](/docs/pt-BR/rpc/guides/getsignaturesforaddress) e [**getTransaction**](/docs/pt-BR/rpc/guides/gettransaction) 3. [**getBlock**](/docs/pt-BR/rpc/guides/getblock) ### Método 1: getTransactionsForAddress (recomendado) O método RPC [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress) permite que você obtenha todos os detalhes de transações para um segmento arbitrário de dados do blockchain. Devido às suas poderosas habilidades de filtragem, você não perderá tempo recuperando dados que não são necessários para seu índice e, graças à sua funcionalidade de pesquisa reversa, você pode obter transações em ordem cronológica. #### Passos para usar este método * Determine o período de tempo do qual você precisa de dados e configure o filtro de acordo * Configure `transactionDetails` para `full` para obter todos os detalhes da transação * Configure o filtro `tokenAccounts` para incluir transações de contas de token associadas se necessário * Paginar nos resultados usando `paginationToken` * A cada iteração, extraia os dados que você precisa e armazene-os em seu banco de dados #### Benefícios de usar getTransactionsForAddress As principais vantagens de usar o [endpoint gTFA](/docs/pt-BR/api-reference/rpc/http/gettransactionsforaddress) são velocidade e simplicidade. Com filtros baseados em slot e tempo, suporte a contas de token, pesquisa reversa e paginação, você pode obter qualquer dado que quiser, de qualquer momento na história do Solana, tudo com uma única chamada sem lógica complexa de looping ou retry. Ao contrário de [`getSignaturesForAddress`](/docs/pt-BR/rpc/guides/getsignaturesforaddress), ele também pode incluir transações envolvendo contas de token associadas possuídas pelo endereço. Se seu índice é especificamente sobre movimento de token e SOL nativo (pagamentos, livros-razão, reconciliação de saldos), [`getTransfersByAddress`](/docs/pt-BR/rpc/gettransfersbyaddress) retorna linhas de transferência analisadas e prontas para reconciliação em vez de transações completas, o que pode economizar uma etapa de análise. ### Método 2: getSignaturesForAddress e getTransaction Antes do lançamento do gTFA, a abordagem padrão para consultar dados históricos era fazer loop recursivo sobre assinaturas usando [`getSignaturesForAddress`](/docs/pt-BR/rpc/guides/getsignaturesforaddress) (do mais novo para o mais antigo) e então chamar [`getTransaction`](/docs/pt-BR/rpc/guides/gettransaction) para extrair os detalhes completos da transação. #### Passos para usar este método Aqui estão os passos básicos para usar este método: * Chame `getSignaturesForAddress` * Armazene a assinatura da última transação recebida desta chamada * Para a próxima chamada a `getSignaturesForAddress`, configure o parâmetro `before` para esta assinatura * Repita isso em um loop pelo tempo necessário * Para cada assinatura de transação obtida desta forma, chame `getTransaction` para obter seus detalhes completos * Insira os dados relevantes no seu banco de dados #### Desvantagens deste método Infelizmente, para usar este método você precisa: * Começar pela transação mais recente e trabalhar para trás * Fazer uma chamada RPC adicional para cada transação * Construir uma fila segura para threads para lidar com o processamento simultâneo * Construir lógica de retries e backoffs para evitar perda de dados e limitações de taxa * Não inclui transações envolvendo contas de token associadas possuídas pelo endereço Embora esse método funcione, é mais complicado, menos flexível e consome muito mais [créditos](/docs/pt-BR/billing/credits). Para um histórico completo de carteira incluindo contas de token, use [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress) em vez disso. ### Método 3: Use getBlock O método [`getBlock`](/docs/pt-BR/rpc/guides/getblock) é mais eficaz quando uma alta porcentagem de transações nos blocos alvo são relevantes para sua análise, como indexar as transações de [programas Solana frequentemente usados](/docs/pt-BR/orb/explore-programs) como o Aggregator do DFlow, o programa Pump.fun ou o programa Token do Solana. #### Passos para usar este método O processo básico para consultar dados históricos com `getBlock` inclui: * Decidir sobre um intervalo de tempo para consultar * Converter este intervalo de tempo em números de slot * Buscar os blocos correspondentes sequencialmente (para frente ou para trás) * Para cada bloco, filtrar as transações que são relevantes para seu índice * Armazenar as informações relevantes deles no seu índice Para a maioria dos casos de uso, este método é intrinsecamente desperdiçador, pois você está recuperando todas as transações em um bloco quando tipicamente apenas uma pequena fração será relevante para sua análise. Use este método apenas quando estiver examinando as transações de programas frequentemente usados ou quando a filtragem baseada em endereço não puder capturar seus dados-alvo. ## Passo 2: Sincronize os dados Solana com seu banco de dados Depois de buscar dados históricos, você precisa transformá-los e armazená-los eficientemente em um banco de dados. **Sua escolha de armazenamento deve ser adaptada ao seu caso de uso específico** — não há solução única para todos. O banco de dados certo depende do tamanho do seu conjunto de dados, requisitos de latência, padrões de consulta e expertise da equipe. ### Opção 1: Bancos de Dados SQL Armazenar dados Solana em bancos de dados relacionais como PostgreSQL é recomendado para a maioria dos casos de uso. SQL é flexível, ubíquo e fácil de aprender. Bancos de dados relacionais modernos podem escalar para além de 100M+ linhas, e ainda oferecem os benefícios de conformidade ACID, joins complexos e poderosos índices secundários. Use **SQLite** para prototipagem, desenvolvimento local ou quando você quiser zero configuração com um banco de dados de arquivo único. É ideal quando seu conjunto de dados permanece abaixo de alguns gigabytes. Use **PostgreSQL** para aplicações de produção que precisam de replicação de dados, acesso simultâneo de múltiplos clientes ou recursos avançados como busca em texto completo e operadores JSON. Para a maioria dos indexadores Solana em nível de produção, o PostgreSQL é nossa escolha recomendada. #### Exemplo de Implementação: Como exemplo, mostraremos como armazenar transferências de tokens em um banco de dados PostgreSQL. Primeiro, crie uma tabela: ```sql theme={"system"} CREATE TABLE token_transfers ( id BIGSERIAL PRIMARY KEY, slot BIGINT NOT NULL, timestamp TIMESTAMP NOT NULL, signature BYTEA NOT NULL UNIQUE, token_mint BYTEA NOT NULL, source_address BYTEA NOT NULL, destination_address BYTEA NOT NULL, amount BIGINT NOT NULL, decimals SMALLINT NOT NULL, program_id BYTEA ); ``` Depois, adicione índices em colunas frequentemente consultadas: ```sql theme={"system"} CREATE INDEX idx_source_address ON token_transfers (source_address); CREATE INDEX idx_destination_address ON token_transfers (destination_address); CREATE INDEX idx_token_mint ON token_transfers (token_mint); ``` Você também pode criar índices parciais caso apenas um subconjunto dos dados seja frequentemente consultado. Veja como criar um índice apenas para transferências de alto valor: ```sql theme={"system"} CREATE INDEX idx_large_transfers ON token_transfers(amount) WHERE amount > 1000000; ``` Ao preencher dados, certifique-se de usar INSERTs em massa e declarações preparadas para velocidade de escrita ideal. ### Opção 2: Bancos de Dados Colunares Bancos de dados colunares são otimizados para consultas analíticas, agregações e dados de séries temporais de alto volume. Se você precisar indexar vários bilhões de transações, bancos de dados colunares como ClickHouse ou Cassandra são a melhor opção. Use **ClickHouse** quando você precisar de consultas analíticas em tempo real em grandes conjuntos de dados — é otimizado para leituras rápidas, agregações e análise de séries temporais. Use **Cassandra** quando você precisar de taxa de escrita extremamente alta, escalabilidade horizontal sem esforço e alta tolerância a falhas. Isso o torna ideal para a ingestão contínua de grandes volumes de dados Solana. #### Exemplo de Implementação: Mostraremos como armazenar transferências de tokens em um banco de dados ClickHouse. Para esse propósito, crie uma tabela que use o [Motor de tabela MergeTree](https://clickhouse.com/docs/engines/table-engines/mergetree-family/mergetree). É projetado para altas taxas de ingestão, tornando-o ideal para indexação. Use este comando: ```sql theme={"system"} CREATE TABLE token_transfers ( block_time DateTime, slot UInt64, signature FixedString(64), token_mint FixedString(32), source_address FixedString(32), destination_address FixedString(32), amount UInt64, decimals UInt8, program_id FixedString(32), date Date DEFAULT toDate(block_time) ) ENGINE = MergeTree() PARTITION BY toYYYYMM(date) ORDER BY (token_mint, date) SETTINGS index_granularity = 8192; ``` Nesta configuração, `(token_mint, date)` é definido como a chave primária e de ordenação. O ClickHouse organizará os dados no disco de acordo com sua chave de ordenação. Isso é ótimo para consultar um único [token mint](/docs/pt-BR/orb/explore-mint-addresses) e restringir a resposta por intervalos de data. Aqui está um exemplo de consulta: ```sql theme={"system"} SELECT date, signature, source_address, destination_address, amount FROM token_transfers WHERE token_mint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' AND block_time BETWEEN '2025-01-01' AND '2025-01-31' ``` Assinaturas de transação e endereços são armazenados usando o formato de dados `FixedString(N)` que armazena exatamente N bytes. O ClickHouse comprime automaticamente os dados, o que reduz os custos de armazenamento em 10-20x e melhora o desempenho das consultas. Para otimizar o desempenho das consultas, use Materialized Views para pré-calcular agregações comuns. Por exemplo, você poderia pré-calcular o volume de transferência diária de tokens para ser usado em gráficos relacionados a volume em um painel. ### Opção 3: Data Lakes Data lakes são ideais para armazenar grandes quantidades de dados de blockchain brutos e processados para arquivamento de longo prazo e consultas analíticas. Uma implementação simples usa o formato de dados Parquet com o Amazon Athena. **Parquet** é um formato de arquivo de dados orientado por colunas projetado para armazenamento e recuperação eficiente de dados. **Amazon Athena** é um serviço de consulta interativa que permite analisar dados armazenados no Amazon S3 usando SQL padrão sem necessidade de configurar infraestrutura ou carregar dados em um banco de dados separado. Data lakes são recomendados apenas se você precisar consultar grandes quantidades de dados não estruturados. Para a maioria dos casos de uso, recomendamos usar um banco de dados SQL (Opção 1). #### Exemplo de Implementação: Queremos criar um arquivo de transferências de tokens e consultá-los. Primeiro, precisamos armazená-los no S3: Crie um bucket chamado `solana_index` e particione seus dados de transferência de tokens por tempo usando esta estrutura de chave: ```text theme={"system"} s3://solana_index/token_transfers/YYYY/MM/DD/part-00000.parquet ``` As transferências de cada dia são armazenadas em um arquivo Parquet separado em sua pasta de data correspondente. À medida que você processa as transferências do Solana, transforme-as no formato Parquet e escreva-as no respectivo objeto S3. Depois, você [cria uma tabela](https://docs.aws.amazon.com/athena/latest/ug/step-2-create-a-table.html) no Athena e a conecta ao bucket. Isso permite executar consultas diretamente nos dados do bucket: ```sql theme={"system"} SELECT block_time, signature, source_address, destination_address, amount FROM token_transfers WHERE token_mint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' AND block_time BETWEEN TIMESTAMP '2025-01-01 00:00:00' AND TIMESTAMP '2025-01-31 23:59:59'; ``` ### Use Frameworks de Indexação Use [**Carbon**](https://github.com/sevenlabs-hq/carbon) e frameworks semelhantes para evitar escrever código boilerplate e configurar seu indexador em horas em vez de dias. #### Principais recursos: * Decodificadores pré-construídos para programas populares (programa Token, protocolos DeFi, Metaplex) * Fontes de dados configuráveis (RPC, LaserStream, WebSockets Aprimorados) * Suporte embutido tanto para preenchimento quanto para streaming em tempo real * Saídas para múltiplos backends de armazenamento (Postgres vem por padrão) * Totalmente personalizável: você pode configurar suas próprias fontes de dados, decodificadores e sinks de dados ## **Passo 3: Mantenha seu índice atualizado** Após preencher dados históricos, você precisa de uma solução de streaming em tempo real para manter seu índice atualizado com novas atividades de blockchain. Sem isso, seu índice se desatualiza. ### Método 1: LaserStream (recomendado) Recomendamos [LaserStream gRPC](/docs/pt-BR/laserstream/grpc) como sua escolha padrão para todos os casos de uso de indexação em produção. É desenvolvido especificamente para streaming de dados confiável, ultrabaixa latência e à prova de falhas. Alguns benefícios de usar LaserStream incluem: * **Reprodução histórica de 24 horas**: se seu indexador desconectar, o LaserStream [reproduz automaticamente](/docs/pt-BR/laserstream/historical-replay) todas as transações perdidas de onde você parou * **Reconexão automática**: nossos [SDKs LaserStream](/docs/pt-BR/laserstream/clients) (Rust, Go, JS/TS) lidam perfeitamente com interrupções de rede para você * **Failover de nó**: sua conexão LaserStream agrega dados de múltiplos nós simultaneamente, garantindo o máximo de uptime Combinando velocidade e confiabilidade, o LaserStream é ideal para aplicações em tempo real como feeds de transações ao vivo, painéis de negociação e atualizações instantâneas de saldo. #### Como Usar o LaserStream para Indexação Use o método [`subscribe`](/docs/pt-BR/api-reference/laserstream/grpc/subscribe) para assinar eventos de blockchain. Aqui estão algumas melhores práticas: * **Restrinja seu filtro o máximo possível**: Inscreva-se apenas nos dados que você realmente precisa indexar para minimizar o consumo de largura de banda e o processamento necessário. * **Use o nível de compromisso `confirmed`**: Isso equilibra latência e finalização. O nível `processed` pode ser muito pouco confiável, enquanto `finalized` adiciona \~13 segundos de latência * **Defina `failed: false`** a menos que você precise especificamente rastrear transações falhadas * **Exclua transações de votação** (`vote: false`) já que não são relevantes para indexação Vamos ver um exemplo. Use a seguinte assinatura para indexar todas as novas transferências de tokens: ```ts theme={"system"} { transactions: { "transfers": { vote: false, failed: false, accountsInclude: [ '​​TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA', 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb' ] } }, commitment: CommitmentLevel.CONFIRMED, accounts: {}, slots: {}, transactionsStatus: {}, blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [] } ``` ### Método 2: Use LaserStream WebSocket [LaserStream WebSocket](/docs/pt-BR/rpc/websocket) — a variante WebSocket do LaserStream, incluindo a extensão `transactionSubscribe` específica do Helius — roda no mesmo backend que o LaserStream gRPC e é uma alternativa de streaming em tempo real mais econômica quando você não precisa de gRPC. Você deve usar o LaserStream WebSocket quando: * Sua aplicação pode tolerar lacunas de dados ocasionais * Atualizações em tempo real são importantes, mas não críticas * Você tem infraestrutura existente para detectar e preencher dados faltantes * As restrições de orçamento são significativas e você precisa minimizar os custos de streaming * Você está prototipando ou testando antes de se comprometer com o LaserStream No entanto, existem algumas compensações a considerar ao escolher WebSockets: * **Velocidade**: LaserStream WebSocket roda no mesmo backend que o LaserStream gRPC, mas o protocolo WebSocket adiciona enquadramento JSON e sobrecarga por mensagem — para a latência mais baixa possível nos mesmos dados, use [LaserStream gRPC](/docs/pt-BR/laserstream) * **Confiabilidade**: Sem garantia de reprodução histórica. Se seu WebSocket desconectar, você precisará detectar manualmente e preencher lacunas usando métodos RPC * **Complexidade**: Requer infraestrutura adicional de monitoramento para garantir a completude dos dados #### Como Usar WebSockets para Indexação Para atualizar um índice que armazena todas as transferências de tokens, você se inscreveria em [`transactionSubscribe`](/docs/pt-BR/rpc/websocket/transaction-subscribe) assim: ```ts theme={"system"} { jsonrpc: '2.0', id: 1, method: 'transactionSubscribe', params: [ { failed: false, accountInclude: [ '​​TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA', 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb' ] }, { commitment: 'confirmed', encoding: 'jsonParsed', transactionDetails: 'full', maxSupportedTransactionVersion: 0 } ] } ``` ## Comece agora Construir um índice robusto de Solana e preencher dados requer resolver três desafios principais: 1. Buscar dados históricos de maneira eficiente 2. Transformar e armazenar dados para recuperações rápidas 3. Manter dados Solana indexados atualizados em tempo real Com nosso novo [sistema de arquivamento de última geração](https://www.helius.dev/blog/introducing-gettransactionsforaddress), chamadas arquivais como [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress), e soluções de streaming de dados líderes de mercado como LaserStream, construir um índice Solana é mais fácil e mais prático do que nunca. ## Opções complementares Executar seu próprio índice dá a você controle total, mas nem sempre é necessário. Para necessidades comuns, uma API gerenciada do Helius pode substituir ou complementar um índice personalizado: * **[DAS API](/docs/pt-BR/das-api)** — consulte NFTs, tokens fungíveis e ativos comprimidos (metadados, propriedade, saldos, por proprietário/coleção/criador) sem indexar dados de ativos por conta própria. * **[Wallet API](/docs/pt-BR/wallet-api/overview)** — endpoints REST de alto nível para saldos de carteiras, histórico, transferências e identidade, com valores em USD e uma forma de resposta mais simples. Muitas equipes usam esses para dados de portfólio, token e carteira, e reservam um índice personalizado para dados específicos de propósito que as APIs gerenciadas não cobrem. ## Próximos passos * [Inscreva-se para uma conta gratuita do Helius](https://www.helius.dev) para obter acesso à API * Leia o [guia getTransactionsForAddress](/docs/pt-BR/rpc/gettransactionsforaddress) para preenchimento * Explore a [visão geral do LaserStream](/docs/pt-BR/laserstream) para streaming em tempo real * Revise a [visão geral de dados históricos](/docs/pt-BR/rpc/historical-data) para todos os métodos de arquivamento