> ## 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.

# Visão Geral e Tutorial de getTransactionsForAddress

> Aprenda como consultar o histórico de transações Solana com filtragem avançada, ordenação bidirecional e paginação eficiente usando este método RPC exclusivo do Helius.

## Visão Geral

[`getTransactionsForAddress`](/docs/pt-BR/api-reference/rpc/http/gettransactionsforaddress) é um método RPC exclusivo do Helius que retorna o histórico de transações de um endereço com filtragem avançada, ordenação flexível e paginação eficiente. Não faz parte do RPC padrão do Solana.

Diferentemente do `getSignaturesForAddress`, que só retorna assinaturas e ignora contas de tokens associadas, o `getTransactionsForAddress` pode retornar dados completos de transações, incluindo a atividade da conta de token associada (ATA) de uma carteira, em uma única chamada. Isso o torna o caminho mais rápido para um histórico completo de endereços para retroalimentação, indexação e análises.

Este método retorna até 1.000 transações completas por chamada.

<CardGroup cols={2}>
  <Card title="Ordenação flexível" icon="arrows-up-down">
    Ordenar cronologicamente (mais antigo primeiro) ou inverso (mais recente primeiro).
  </Card>

  <Card title="Filtragem avançada" icon="filter">
    Filtrar por intervalos de tempo, slots, assinaturas, status e transferências de tokens.
  </Card>

  <Card title="Dados completos de transações" icon="database">
    Obtenha detalhes completos das transações em uma única chamada, sem necessidade de getTransaction de acompanhamento.
  </Card>

  <Card title="Contas de tokens" icon="layer-group">
    Incluir transações para contas de tokens associadas a um endereço.
  </Card>
</CardGroup>

## Quando usar isso

Use `getTransactionsForAddress` quando você precisar de:

* Histórico completo de tokens de carteira, incluindo contas de tokens associadas
* Um retrocesso rápido em uma única chamada para um indexador ou pipeline de dados
* Análise e relatórios de transações baseados em tempo ou slot
* Filtragem de status para manter apenas transações bem-sucedidas ou apenas falhas
* Reprodução histórica cronológica (ordenação do mais antigo para o mais recente)
* Análise de lançamento de tokens: primeiras transações de mint e primeiros detentores
* Histórico de financiamento de carteiras e descoberta de contrapartes
* Relatórios de conformidade e auditoria para um período de tempo específico

Para histórico analisado e somente transferência (pagamentos, reconciliação de saldo), use [`getTransfersByAddress`](/docs/pt-BR/rpc/gettransfersbyaddress) em vez disso.

### Suporte de rede

| Rede    | Suportado | Período de Retenção |
| ------- | --------- | ------------------- |
| Mainnet | Sim       | Ilimitado           |
| Devnet  | Sim       | 2 semanas           |
| Testnet | Não       | N/A                 |

## Início Rápido

<Steps>
  <Step title="Obtenha sua chave API">
    Obtenha sua chave API no [Painel do Helius](https://dashboard.helius.dev/api-keys).
  </Step>

  <Step title="Consulta com recursos avançados">
    Obtenha todas as transações bem-sucedidas para uma carteira entre duas datas, ordenadas cronologicamente:

    ```javascript theme={"system"}
    // Get successful transactions between Jan 1-31, 2025 in chronological order
    const response = await fetch('https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: 1,
        method: 'getTransactionsForAddress',
        params: [
          'YOUR_ADDRESS_HERE',
          {
            transactionDetails: 'full',
            sortOrder: 'asc',
            limit: 1000,
            filters: {
              blockTime: {
                gte: 1735689600,   // Jan 1, 2025
                lt: 1738368000     // Before Feb 1, 2025
              },
              status: 'succeeded',  // Only successful transactions
              tokenAccounts: 'balanceChanged' // Include associated token accounts
            }
          }
        ]
      })
    });

    const data = await response.json();
    console.log('Successful transactions in January:', data.result.data);
    ```
  </Step>

  <Step title="Compreender os parâmetros">
    Este exemplo mostra os recursos chave:

    * **transactionDetails**: defina como `'full'` para obter dados completos de transações em uma única chamada
    * **sortOrder**: use `'asc'` para ordem cronológica (mais antigo primeiro) ou `'desc'` para o mais recente primeiro
    * **filters.blockTime**: defina intervalos de tempo com `gte` (maior ou igual) e `lte` (menor ou igual)
    * **filters.status**: filtre apenas `'succeeded'` ou `'failed'` transações
    * **filters.tokenAccounts**: inclua transferências, mints e queimas para contas de tokens associadas
  </Step>
</Steps>

## Parâmetros de solicitação

<ParamField body="address" type="string" required>
  Chave pública codificada em Base-58 da conta para consultar o histórico de transações
</ParamField>

<ParamField body="transactionDetails" type="string" default="signatures">
  Nível de detalhe da transação a ser retornado:

  * `signatures`: Informações básicas de assinatura (mais rápido)
  * `full`: Dados completos da transação (elimina a necessidade de chamadas getTransaction, suporta limite de até 1.000)
</ParamField>

<ParamField body="sortOrder" type="string" default="desc">
  Ordem de classificação dos resultados:

  * `desc`: Mais recente primeiro (padrão)
  * `asc`: Mais antigo primeiro (cronológico, ótimo para análise histórica)
</ParamField>

<ParamField body="limit" type="number" default="1000">
  Máximo de transações a serem retornadas:

  * Até 1000 quando `transactionDetails: "signatures"`
  * Até 1000 quando `transactionDetails: "full"`
</ParamField>

<ParamField body="paginationToken" type="string">
  Token de paginação da resposta anterior (formato: `"slot:position"`)
</ParamField>

<ParamField body="commitment" type="string" default="finalized">
  Nível de comprometimento: `finalized` ou `confirmed`. O compromisso `processed` não é suportado.
</ParamField>

<ParamField body="filters" type="object">
  Opções avançadas de filtragem para restringir os resultados.
</ParamField>

<ParamField body="filters.slot" type="object">
  Filtrar por número de slot usando operadores de comparação: `gte`, `gt`, `lte`, `lt`

  Exemplo: `{ "slot": { "gte": 1000, "lte": 2000 } }`
</ParamField>

<ParamField body="filters.blockTime" type="object">
  Filtrar por timestamp Unix usando operadores de comparação: `gte`, `gt`, `lte`, `lt`, `eq`

  Exemplo: `{ "blockTime": { "gte": 1640995200, "lte": 1641081600 } }`
</ParamField>

<ParamField body="filters.signature" type="object">
  Filtrar por assinatura de transação usando operadores de comparação: `gte`, `gt`, `lte`, `lt`

  Exemplo: `{ "signature": { "lt": "SIGNATURE_STRING" } }`
</ParamField>

<ParamField body="filters.status" type="string">
  Filtrar por status de sucesso/fracasso da transação:

  * `succeeded`: Apenas transações bem-sucedidas
  * `failed`: Apenas transações falhas
  * `any`: Ambas bem-sucedidas e falhas (padrão)

  Exemplo: `{ "status": "succeeded" }`
</ParamField>

<ParamField body="filters.tokenAccounts" type="string" default="none">
  Filtrar transações para contas de tokens relacionadas:

  * `none`: Apenas retornar transações que fazem referência ao endereço fornecido (padrão)
  * `balanceChanged`: Retornar transações que fazem referência ao endereço fornecido ou modificam o saldo de uma conta de token de propriedade do endereço fornecido (recomendado)
  * `all`: Retornar transações que fazem referência ao endereço fornecido ou a qualquer conta de token de propriedade do endereço fornecido

  Exemplo: `{ "tokenAccounts": "balanceChanged" }`
</ParamField>

<ParamField body="filters.tokenTransfer" type="object">
  Filtrar para transações onde o endereço consultado participou de uma transferência de token que corresponde a uma contraparte, direção, mint ou faixa de quantidade bruta. Todos os campos são opcionais e combinados com semântica AND.

  Exemplo: `{ "tokenTransfer": { "direction": "in", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } }`
</ParamField>

<ParamField body="filters.tokenTransfer.with" type="string">
  Endereço da contraparte. Combina transferências cuja outra parte é este endereço.
</ParamField>

<ParamField body="filters.tokenTransfer.direction" type="string" default="any">
  Filtrar por direção da transferência em relação ao endereço consultado:

  * `in`: Transferências recebidas pelo endereço consultado
  * `out`: Transferências enviadas pelo endereço consultado
  * `any`: Transferências de entrada e saída
</ParamField>

<ParamField body="filters.tokenTransfer.mint" type="string">
  Mint do token para filtrar.
</ParamField>

<ParamField body="filters.tokenTransfer.amount" type="object">
  Comparação de valores usando a quantidade bruta on-chain, não a quantidade ajustada pela UI ou por decimais. Suporta `gt`, `gte`, `lt`, e `lte`.
</ParamField>

<ParamField body="encoding" type="string">
  Formato de codificação para dados de transação (apenas aplica-se quando `transactionDetails: "full"`). O mesmo que `getTransaction` API. Opções: `json`, `jsonParsed`, `base64`, `base58`
</ParamField>

<ParamField body="maxSupportedTransactionVersion" type="number">
  Defina a versão máxima da transação a ser retornada. Se omitido, apenas transações legadas serão retornadas. Defina como `0` para incluir todas as transações versionadas.
</ParamField>

<ParamField body="minContextSlot" type="number">
  O slot mínimo em que a solicitação pode ser avaliada
</ParamField>

### Medição

Respostas bem-sucedidas são medidas pelo que é retornado:

| Tipo de resposta        | Créditos                                                                                |
| ----------------------- | --------------------------------------------------------------------------------------- |
| Transações completas    | 10 créditos por 100 transações retornadas, arredondado para cima; mínimo de 10 créditos |
| Apenas assinaturas      | 10 créditos fixos, independentemente da contagem                                        |
| Respostas de API falhas | Gratuito                                                                                |

## Resposta

O formato da resposta depende de `transactionDetails`. O modo de assinaturas retorna registros de assinatura leves; o modo completo retorna objetos completos de transação e metadata.

<Tabs>
  <Tab title="Resposta de Assinaturas">
    ```json theme={"system"}
    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "data": [
          {
            "signature": "5h6xBEauJ3PK6SWCZ1PGjBvj8vDdWG3KpwATGy1ARAXFSDwt8GFXM7W5Ncn16wmqokgpiKRLuS83KUxyZyv2sUYv",
            "slot": 1054,
            "transactionIndex": 42,
            "err": null,
            "memo": null,
            "blockTime": 1641038400,
            "confirmationStatus": "finalized"
          }
        ],
        "paginationToken": "1055:5"
      }
    }
    ```
  </Tab>

  <Tab title="Resposta Completa de Transações">
    ```json theme={"system"}
    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "data": [
          {
            "slot": 1054,
            "transactionIndex": 42,
            "blockTime": 1641038400,
            "transaction": {
              "signatures": ["5h6xBEauJ3PK6SWCZ1PGjBvj8vDdWG3KpwATGy1ARAXFSDwt8GFXM7W5Ncn16wmqokgpiKRLuS83KUxyZyv2sUYv"],
              "message": {
                "accountKeys": ["...", "..."],
                "instructions": [...],
                // Complete transaction structure
              }
            },
            "meta": {
              "fee": 5000,
              "preBalances": [1000000, 2000000],
              "postBalances": [999995000, 2000000],
              // Complete metadata
            }
          }
        ],
        "paginationToken": "1055:5"
      }
    }
    ```
  </Tab>
</Tabs>

### Campos de Resposta

| Campo                | Tipo           | Descrição                                                                                                              |
| -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `signature`          | string         | Assinatura da transação (codificada em base-58). Somente no modo de assinaturas.                                       |
| `slot`               | number         | O slot contendo o bloco com esta transação.                                                                            |
| `transactionIndex`   | number         | O índice baseado em zero da transação dentro de seu bloco. Útil para ordenação de transações e reconstrução de blocos. |
| `blockTime`          | number \| null | Tempo estimado de produção como timestamp Unix (segundos desde a época).                                               |
| `err`                | object \| null | Erro se a transação falhou, nulo se bem-sucedida. Somente no modo de assinaturas.                                      |
| `memo`               | string \| null | Memo associado à transação. Somente no modo de assinaturas.                                                            |
| `confirmationStatus` | string         | Status de confirmação do cluster da transação. Somente no modo de assinaturas.                                         |
| `transaction`        | object         | Dados completos da transação. Somente no modo completo.                                                                |
| `meta`               | object         | Metadata de status da transação. Somente no modo completo.                                                             |
| `paginationToken`    | string \| null | Token para buscar a próxima página, ou nulo se não houver mais resultados.                                             |

O campo `transactionIndex` é exclusivo para `getTransactionsForAddress`. Outros endpoints semelhantes como `getSignaturesForAddress`, `getTransaction` e `getTransactions` não incluem este campo.

## Filtros

Você pode usar operadores de comparação para `slot`, `blockTime`, e `signature`, além dos filtros especiais `status`, `tokenAccounts`, e `tokenTransfer`. A combinação de múltiplos filtros reduz o resultado à sua interseção.

### Operadores de comparação

Esses operadores funcionam como consultas de banco de dados para dar a você controle preciso sobre seu intervalo de dados.

| Operador | Nome Completo  | Descrição                                               | Exemplo                         |
| -------- | -------------- | ------------------------------------------------------- | ------------------------------- |
| `gte`    | Maior ou Igual | Incluir valores ≥ valor especificado                    | `slot: { gte: 100 }`            |
| `gt`     | Maior Que      | Incluir valores > valor especificado                    | `blockTime: { gt: 1641081600 }` |
| `lte`    | Menor ou Igual | Incluir valores ≤ valor especificado                    | `slot: { lte: 2000 }`           |
| `lt`     | Menor Que      | Incluir valores \< valor especificado                   | `blockTime: { lt: 1641168000 }` |
| `eq`     | Igual          | Incluir valores exatamente iguais (somente `blockTime`) | `blockTime: { eq: 1641081600 }` |

### Filtros de Enumeração

| Filtro          | Descrição                                             | Valores                            |
| --------------- | ----------------------------------------------------- | ---------------------------------- |
| `status`        | Filtrar transações por sucesso/fracasso               | `succeeded`, `failed`, ou `any`    |
| `tokenAccounts` | Filtrar transações para contas de tokens relacionadas | `none`, `balanceChanged`, ou `all` |

Exemplos de filtros combinados:

```javascript theme={"system"}
// Time range with successful transactions only
"filters": {
  "blockTime": {
    "gte": 1640995200,
    "lte": 1641081600
  },
  "status": "succeeded"
}

// Slot range
"filters": {
  "slot": {
    "gte": 1000,
    "lte": 2000
  }
}

// Only failed transactions
"filters": {
  "status": "failed"
}
```

### Contas de tokens associadas

No Solana, uma carteira não segura tokens diretamente. Em vez disso, a carteira possui contas de tokens, e essas contas de tokens armazenam os tokens. Quando alguém envia USDC para você, ele vai para sua conta de token USDC, não para o endereço principal da sua carteira.

Este método é exclusivo porque pode consultar **histórico completo de tokens**, incluindo contas de tokens associadas (ATAs) de uma carteira. Métodos RPC nativos como `getSignaturesForAddress` não incluem ATAs.

O filtro `tokenAccounts` controla esse comportamento:

* **`none`** (padrão): Retorna apenas transações que referenciam diretamente o endereço da carteira. Use isso quando você só se importa com interações diretas da carteira.
* **`balanceChanged`** (recomendado): Retorna transações que referenciam o endereço da carteira ou modificam o saldo de uma conta de token de propriedade da carteira. Isso elimina spam e operações não relacionadas como coletas de taxas ou delegações, fornecendo uma visão limpa da atividade significativa da carteira.
* **`all`**: Retorna todas as transações que referenciam o endereço da carteira ou qualquer conta de token de propriedade da carteira.

O filtro `tokenAccounts` não suporta transações anteriores a dezembro de 2022. Ele depende de metadados de transferência de tokens introduzidos no Solana no slot 111,491,819. Para cobrir atividades anteriores, veja a [solução alternativa de conta de token histórica](#limitations-and-edge-cases).

### Filtro de transferência de tokens

O filtro `tokenTransfer` restringe os resultados para transações onde o endereço consultado participou de uma transferência de token que corresponde a critérios específicos: uma contraparte particular, mint, direção ou faixa de valores.

Use-o para responder a perguntas como:

* Quando esta carteira recebeu USDC de uma contraparte específica?
* Mostrar todas as transferências de saída acima de 1.000 tokens.
* Quando esta carteira já interagiu com este mint específico?

O filtro é um campo opcional dentro do objeto `filters` da configuração da solicitação:

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTransactionsForAddress",
  "params": [
    "<address>",
    {
      "filters": {
        "tokenTransfer": {}
      }
    }
  ]
}
```

Todos os campos dentro de `tokenTransfer` são opcionais. A combinação de múltiplos campos é tratada como AND.

| Campo       | Tipo                         | Padrão  | Descrição                                                                                                        |
| ----------- | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `with`      | string (pubkey)              | -       | Endereço da contraparte. Combina transferências cuja outra parte é este endereço.                                |
| `direction` | `"in"` \| `"out"` \| `"any"` | `"any"` | Se o endereço consultado recebeu, enviou ou ambos.                                                               |
| `mint`      | string (pubkey)              | -       | Mint do token para filtrar.                                                                                      |
| `amount`    | object                       | -       | Comparação de valores. Usufrui da quantidade bruta on-chain, não da quantidade ajustada pela UI ou por decimais. |

Operadores de faixa de valores:

| Operador | Significado            |
| -------- | ---------------------- |
| `gt`     | Estritamente maior que |
| `gte`    | Maior ou igual         |
| `lt`     | Estritamente menor que |
| `lte`    | Menor ou igual         |

Você pode combinar operadores de valor, como `{ "gte": 1000000, "lte": 5000000 }` para um intervalo fechado. `tokenTransfer` compõe-se com os outros filtros de nível superior (`slot`, `blockTime`, `status`, e `tokenAccounts`); o resultado final é a interseção.

## Exemplos

### Análise baseada no tempo

Gerar relatórios mensais de transações:

```javascript theme={"system"}
// Get all successful transactions for January 2025
const startTime = Math.floor(new Date('2025-01-01').getTime() / 1000);
const endTime = Math.floor(new Date('2025-02-01').getTime() / 1000);

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTransactionsForAddress",
  "params": [
    "WALLET_OR_PROGRAM_ADDRESS",
    {
      "transactionDetails": "signatures",
      "filters": {
        "blockTime": {
          "gte": startTime,
          "lt": endTime
        },
        "status": "succeeded"
      },
      "limit": 1000
    }
  ]
}
```

Processo para análise:

```javascript theme={"system"}
// Calculate daily transaction volume
const dailyStats = {};
response.result.data.forEach(tx => {
  const date = new Date(tx.blockTime * 1000).toISOString().split('T')[0];
  dailyStats[date] = (dailyStats[date] || 0) + 1;
});

console.log('Daily Transaction Counts:', dailyStats);
```

### Criação de mint de token

Encontrar a transação de criação de mint para um token específico:

```javascript theme={"system"}
{
  "jsonrpc": "2.0",
  "id": "find-first-mints",
  "method": "getTransactionsForAddress",
  "params": [
    MINT_ADDRESS, // Token mint address
    {
      "encoding": "jsonParsed",
      "maxSupportedTransactionVersion": 0,
      "sortOrder": "asc",  // Chronological order from the beginning
      "limit": 10,
      "transactionDetails": "full"
    }
  ]
}
```

Para criação de pool de liquidez, consultar o endereço do pool:

```javascript theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTransactionsForAddress", 
  "params": [
    "POOL_ADDRESS_HERE", // Raydium/Meteora pool address
    {
      "transactionDetails": "full",
      "sortOrder": "asc",  // First transaction is usually pool creation
      "limit": 1
    }
  ]
}
```

Isso encontra o momento exato em que um mint de token ou pool de liquidez foi criado, incluindo o endereço do criador e os parâmetros iniciais.

### Transações de financiamento

Descobrir quem financiou um endereço específico:

```javascript theme={"system"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getTransactionsForAddress",
  "params": [
    "TARGET_WALLET_ADDRESS",
    {
      "transactionDetails": "full",
      "sortOrder": "asc",  // Oldest first
      "limit": 10
    }
  ]
}
```

Em seguida, analisar os dados da transação para encontrar transferências de SOL:

```javascript theme={"system"}
response.result.data.forEach(tx => {
  // Look for SOL transfers in preBalances/postBalances
  const balanceChanges = tx.meta.preBalances.map((pre, index) => 
    tx.meta.postBalances[index] - pre
  );
  
  // Positive balance change = incoming SOL
  balanceChanges.forEach((change, index) => {
    if (change > 0) {
      console.log(`Received ${change} lamports from ${tx.transaction.message.accountKeys[index]}`);
    }
  });
});
```

As primeiras transações frequentemente revelam a fonte do financiamento e podem ajudar a identificar endereços relacionados ou padrões de financiamento.

### Transferências de tokens

Filtrar por `tokenTransfer` para isolar movimentos específicos de tokens.

Entradas de USDC para um endereço:

```json theme={"system"}
{
  "filters": {
    "tokenTransfer": {
      "direction": "in",
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  }
}
```

Grandes transferências de saída para uma contraparte específica:

```json theme={"system"}
{
  "filters": {
    "tokenTransfer": {
      "with": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "direction": "out",
      "amount": { "gte": 1000000000 }
    }
  }
}
```

Combinado com intervalo de slots e status:

```json theme={"system"}
{
  "filters": {
    "status": "succeeded",
    "slot": { "gte": 100000000, "lte": 200000000 },
    "tokenTransfer": {
      "direction": "in",
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": { "gte": 5000000 }
    }
  }
}
```

## Paginação

Quando você tem mais transações do que o seu limite, use o `paginationToken` da resposta para buscar a próxima página. O token é uma string simples no formato `"slot:position"` que informa a API de onde continuar.

Use o token de paginação de cada resposta para buscar a próxima página:

```javascript theme={"system"}
// First request
let paginationToken = null;
let allTransactions = [];

const getNextPage = async (paginationToken = null) => {
  const params = [
    'ADDRESS',
    {
      transactionDetails: 'signatures',
      limit: 100,
      ...(paginationToken && { paginationToken })
    }
  ];

  const response = await fetch(rpcUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'getTransactionsForAddress',
      params
    })
  });

  const data = await response.json();
  return data.result;
};

// Paginate through all results
do {
  const result = await getNextPage(paginationToken);
  allTransactions.push(...result.data);
  paginationToken = result.paginationToken;
  
  console.log(`Fetched ${result.data.length} transactions, total: ${allTransactions.length}`);
} while (paginationToken);
```

### Múltiplos endereços

Você não pode consultar vários endereços em uma única solicitação. Cada consulta de endereço conta como uma solicitação de API separada e é medida de acordo. Para buscar transações para múltiplos endereços, consulte cada endereço dentro do mesmo tempo ou janela de slots, depois mescle e ordene:

```javascript theme={"system"}
const addresses = ['Address1...', 'Address2...', 'Address3...'];

// Query all addresses in parallel with slot filter
const results = await Promise.all(
  addresses.map(address => 
    fetch(rpcUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: 1,
        method: 'getTransactionsForAddress',
        params: [address, {
          sortOrder: 'desc',
          filters: { slot: { gt: 250000000 } }
        }]
      })
    }).then(r => r.json())
  )
);

// Merge and sort by slot
const allTransactions = results
  .flatMap(r => r.result.data)
  .sort((a, b) => b.slot - a.slot);
```

Para escaneamentos de histórico maiores, itere por janelas de tempo ou slots (por exemplo, 1000 slots de cada vez) e repita este padrão.

## Melhores práticas

**Desempenho.** Use `transactionDetails: "signatures"` quando você não precisar de dados completos de transação. Use tamanhos de página razoáveis para melhores tempos de resposta, e filtre por intervalos de tempo ou slots específicos para consultas mais direcionadas.

**Filtragem.** Comece com filtros amplos e vá estreitando progressivamente. Use filtros baseados em tempo para análises e fluxos de trabalho de relatórios, e combine múltiplos filtros para consultas precisas que visam tipos de transações específicos ou períodos de tempo.

**Paginação.** Armazene tokens de paginação quando precisar retomar consultas grandes mais tarde. Monitore a profundidade da paginação para planejamento de desempenho, e use ordem ascendente quando precisar reproduzir eventos históricos em ordem cronológica.

**Tratamento de erros.** Lide com limites de taxa de forma elegante com backoff exponencial. Valide endereços antes de fazer solicitações, e armazene em cache os resultados quando apropriado para reduzir o uso da API.

## Limitações e casos extremos

Um pequeno conjunto de endereços roteia para arquivamento legado, são limitados à fallback de escaneamento de slots, ou retornam vazio. A descoberta de contas de tokens antes do slot 111.491.819 também requer uma solução alternativa. Expanda as seções abaixo para obter todos os detalhes.

<Accordion title="Endereços não suportados e roteados especialmente">
  **Roteado para arquivamento antigo.** Solicitações para estes endereços são roteadas para nosso sistema de arquivamento antigo.

  | Endereço                                      | Nome                                                                                                                |
  | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
  | `Stake11111111111111111111111111111111111111` | [Programa de Stake](https://orbmarkets.io/address/Stake11111111111111111111111111111111111111/history)              |
  | `StakeConfig11111111111111111111111111111111` | [Configuração de Stake](https://orbmarkets.io/address/StakeConfig11111111111111111111111111111111/history)          |
  | `Sysvar1111111111111111111111111111111111111` | [Sysvar Owner](https://orbmarkets.io/address/Sysvar1111111111111111111111111111111111111/history)                   |
  | `AddressLookupTab1e1111111111111111111111111` | [Tabela de Pesquisa de Endereço](https://orbmarkets.io/address/AddressLookupTab1e1111111111111111111111111/history) |
  | `BPFLoaderUpgradeab1e11111111111111111111111` | [Loader Atualizável BPF](https://orbmarkets.io/address/BPFLoaderUpgradeab1e11111111111111111111111/history)         |

  **Fallback de escaneamento de slot.** Solicitações para esses endereços são encaminhadas para nosso novo sistema de arquivamento, e podem ser consultadas através de uma abordagem de escaneamento slot a slot (máx. 100 slots). No entanto, esses dados não são indexados.

  | Endereço                                      | Nome                                                                                                      |
  | --------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
  | `11111111111111111111111111111111`            | [Programa do Sistema](https://orbmarkets.io/address/11111111111111111111111111111111/history)             |
  | `ComputeBudget111111111111111111111111111111` | [Orçamento de Cálculo](https://orbmarkets.io/address/ComputeBudget111111111111111111111111111111/history) |
  | `MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr` | [Programa de Memo](https://orbmarkets.io/address/MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr/history)     |
  | `Vote111111111111111111111111111111111111111` | [Programa de Voto](https://orbmarkets.io/address/Vote111111111111111111111111111111111111111/history)     |

  **Retorna vazio (`is_reserved_address`).** Solicitações são encaminhadas para nosso novo sistema de arquivamento, entretanto, os dados não são indexados, e as consultas retornam vazio.

  | Endereço                                       | Nome                                                                                                                     |
  | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
  | `BPFLoader1111111111111111111111111111111111`  | [Loader BPF (obsoleto)](https://orbmarkets.io/address/BPFLoader1111111111111111111111111111111111/history)               |
  | `BPFLoader2111111111111111111111111111111111`  | [Loader BPF](https://orbmarkets.io/address/BPFLoader2111111111111111111111111111111111/history)                          |
  | `Config1111111111111111111111111111111111111`  | [Programa de Configuração](https://orbmarkets.io/address/Config1111111111111111111111111111111111111/history)            |
  | `Ed25519SigVerify111111111111111111111111111`  | [Programa Ed25519](https://orbmarkets.io/address/Ed25519SigVerify111111111111111111111111111/history)                    |
  | `Feature111111111111111111111111111111111111`  | [Programa de Recurso](https://orbmarkets.io/address/Feature111111111111111111111111111111111111/history)                 |
  | `KeccakSecp256k11111111111111111111111111111`  | [Programa Secp256k1](https://orbmarkets.io/address/KeccakSecp256k11111111111111111111111111111/history)                  |
  | `LoaderV411111111111111111111111111111111111`  | [Loader V4](https://orbmarkets.io/address/LoaderV411111111111111111111111111111111111/history)                           |
  | `NativeLoader1111111111111111111111111111111`  | [Loader Nativo](https://orbmarkets.io/address/NativeLoader1111111111111111111111111111111/history)                       |
  | `SysvarC1ock11111111111111111111111111111111`  | [Clock Sysvar](https://orbmarkets.io/address/SysvarC1ock11111111111111111111111111111111/history)                        |
  | `SysvarEpochSchedu1e111111111111111111111111`  | [Schedule Sysvar de Época](https://orbmarkets.io/address/SysvarEpochSchedu1e111111111111111111111111/history)            |
  | `SysvarFees111111111111111111111111111111111`  | [Sysvar de Taxas](https://orbmarkets.io/address/SysvarFees111111111111111111111111111111111/history)                     |
  | `Sysvar1nstructions1111111111111111111111111`  | [Sysvar de Instruções](https://orbmarkets.io/address/Sysvar1nstructions1111111111111111111111111/history)                |
  | `SysvarRecentB1ockHashes11111111111111111111`  | [Sysvar de Hashes de Blocos Recentes](https://orbmarkets.io/address/SysvarRecentB1ockHashes11111111111111111111/history) |
  | `SysvarRent111111111111111111111111111111111`  | [Sysvar de Aluguel](https://orbmarkets.io/address/SysvarRent111111111111111111111111111111111/history)                   |
  | `SysvarRewards111111111111111111111111111111`  | [Sysvar de Recompensas](https://orbmarkets.io/address/SysvarRewards111111111111111111111111111111/history)               |
  | `SysvarS1otHashes111111111111111111111111111`  | [Sysvar de Hashes de Slots](https://orbmarkets.io/address/SysvarS1otHashes111111111111111111111111111/history)           |
  | `SysvarS1otHistory11111111111111111111111111`  | [Sysvar de História de Slots](https://orbmarkets.io/address/SysvarS1otHistory11111111111111111111111111111/history)      |
  | `SysvarStakeHistory1111111111111111111111111`  | [Sysvar de História de Estacas](https://orbmarkets.io/address/SysvarStakeHistory1111111111111111111111111/history)       |
  | `SysvarEpochRewards11111111111111111111111111` | [Sysvar de Recompensas de Época](https://orbmarkets.io/address/SysvarEpochRewards11111111111111111111111111/history)     |
  | `SysvarLastRestartS1ot1111111111111111111111`  | [Sysvar de Último Reinício de Slot](https://orbmarkets.io/address/SysvarLastRestartS1ot1111111111111111111111/history)   |
</Accordion>

<Accordion title="Solução alternativa: descoberta de conta de token histórica (antes do slot 111,491,819)">
  Para endereços com atividade de conta de token antes do slot 111,491,819, o filtro `tokenAccounts` não pode determinar a propriedade porque o campo `owner` nos metadados de balanço de tokens ainda não existia. Para obter resultados completos, você pode descobrir essas contas de tokens manualmente, analisando instruções de transações iniciais, depois consultar `getTransactionsForAddress` em paralelo para cada uma.

  ```javascript theme={"system"}
  const HELIUS_RPC = "https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY";
  const OWNER_CUTOFF_SLOT = 111_491_819;

  async function rpcCall(method, params) {
    const res = await fetch(HELIUS_RPC, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ jsonrpc: "2.0", id: "1", method, params }),
    });
    const json = await res.json();
    if (json.error) throw new Error(json.error.message);
    return json.result;
  }

  // Step 1: Discover token accounts owned by the address before the cutoff slot
  // by parsing initializeAccount instructions and transfer authorities.
  async function discoverHistoricalTokenAccounts(address) {
    const tokenAccounts = new Set();
    let paginationToken = null;

    do {
      const result = await rpcCall("getTransactionsForAddress", [
        address,
        {
          transactionDetails: "full",
          encoding: "jsonParsed",
          maxSupportedTransactionVersion: 0,
          sortOrder: "asc",
          limit: 100,
          filters: { slot: { lt: OWNER_CUTOFF_SLOT } },
          ...(paginationToken && { paginationToken }),
        },
      ]);
      if (!result?.data?.length) break;

      for (const entry of result.data) {
        const tx = entry.transaction;
        const meta = entry.meta;
        if (!tx || !meta) continue;

        const allInstructions = [
          ...(tx.message?.instructions ?? []),
          ...(meta.innerInstructions ?? []).flatMap((inner) => inner.instructions ?? []),
        ];

        for (const ix of allInstructions) {
          // AToken program "create" instruction
          if (ix.program === "spl-associated-token-account") {
            if (ix.parsed?.type === "create" && ix.parsed.info?.wallet === address && ix.parsed.info?.account) {
              tokenAccounts.add(ix.parsed.info.account);
            }
            continue;
          }

          if (ix.program !== "spl-token" && ix.program !== "spl-token-2022") continue;
          const type = ix.parsed?.type;
          const info = ix.parsed?.info;

          // Token account initialization
          if (type === "initializeAccount" || type === "initializeAccount2" || type === "initializeAccount3") {
            if (info?.owner === address && info?.account) tokenAccounts.add(info.account);
          }

          // Transfers where our address is the authority (source account is ours)
          if (type === "transfer" || type === "transferChecked") {
            if (info?.authority === address && info?.source) tokenAccounts.add(info.source);
          }
        }
      }
      paginationToken = result.paginationToken;
    } while (paginationToken);

    return Array.from(tokenAccounts);
  }

  // Step 2: Fetch all signatures for an address with pagination
  async function fetchAllSignatures(address, filters) {
    const allSignatures = [];
    let paginationToken = null;

    do {
      const result = await rpcCall("getTransactionsForAddress", [
        address,
        {
          transactionDetails: "signatures",
          sortOrder: "asc",
          limit: 1000,
          ...(filters && { filters }),
          ...(paginationToken && { paginationToken }),
        },
      ]);
      if (!result?.data?.length) break;
      allSignatures.push(...result.data);
      paginationToken = result.paginationToken;
    } while (paginationToken);

    return allSignatures;
  }

  // Step 3: Get complete history by combining tokenAccounts:"all" with
  // individual queries for historical token accounts
  async function getCompleteHistory(address) {
    const historicalAccounts = await discoverHistoricalTokenAccounts(address);

    if (historicalAccounts.length === 0) {
      return fetchAllSignatures(address, { tokenAccounts: "all" });
    }

    // Query main address with tokenAccounts:"all" + each historical account in parallel
    const results = await Promise.all([
      fetchAllSignatures(address, { tokenAccounts: "all" }),
      ...historicalAccounts.map((addr) => fetchAllSignatures(addr)),
    ]);

    // Merge and deduplicate by signature
    const seen = new Set();
    const merged = [];
    for (const batch of results) {
      for (const tx of batch) {
        if (!seen.has(tx.signature)) {
          seen.add(tx.signature);
          merged.push(tx);
        }
      }
    }
    return merged.sort((a, b) => a.slot - b.slot);
  }
  ```
</Accordion>

## Como isso é diferente de getSignaturesForAddress?

Se você está familiarizado com o método padrão `getSignaturesForAddress`, o `getTransactionsForAddress` colapsa fluxos de trabalho em várias etapas em uma única chamada e adiciona filtragem, ordenação e suporte a contas de tokens.

### Obtenha transações completas em uma única chamada

Com o `getSignaturesForAddress`, você precisa de duas etapas:

```javascript theme={"system"}
// Step 1: Get signatures
const signatures = await connection.getSignaturesForAddress(address, { limit: 1000 });

// Step 2: Get transaction details (1,000 additional calls!)
const transactions = await Promise.all(
  signatures.map(sig => connection.getTransaction(sig.signature))
);
```

Com o `getTransactionsForAddress`, é uma chamada:

```javascript theme={"system"}
const response = await fetch(heliusRpcUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'getTransactionsForAddress',
    params: [
      address,
      {
        transactionDetails: 'full',
        limit: 1000
      }
    ]
  })
});
```

### Obtenha histórico de tokens em uma única chamada

Com o `getSignaturesForAddress`, você precisa primeiro chamar `getTokenAccountsByOwner` e depois consultar para cada conta de token:

```javascript theme={"system"}
// OLD WAY (with getSignaturesForAddress)
// Step 1: Get all token accounts owned by this wallet
const tokenAccounts = await connection.getTokenAccountsByOwner(
  new PublicKey(walletAddress),
  { programId: TOKEN_PROGRAM_ID }
);

// Step 2: Fetch signatures for the wallet itself
const walletSignatures = await connection.getSignaturesForAddress(
  new PublicKey(walletAddress),
  { limit: 1000 }
);

// Step 3: Fetch signatures for EVERY token account (this is the painful part)
const tokenAccountSignatures = await Promise.all(
  tokenAccounts.value.map(async (account) => {
    return connection.getSignaturesForAddress(
      account.pubkey,
      { limit: 1000 }
    );
  })
);

// Step 4: Merge all results together
const allSignatures = [
  ...walletSignatures,
  ...tokenAccountSignatures.flat()
];

// Step 5: Deduplicate (many transactions touch multiple accounts)
const seen = new Set();
const uniqueSignatures = allSignatures.filter((sig) => {
  if (seen.has(sig.signature)) {
    return false;
  }
  seen.add(sig.signature);
  return true;
});

// Step 6: Sort chronologically
const sortedSignatures = uniqueSignatures.sort(
  (a, b) => a.slot - b.slot
);

return sortedSignatures;
```

Com o `getTransactionsForAddress`, você só precisa definir `filters.tokenAccounts`:

```javascript theme={"system"}
// NEW WAY (with getTransactionsForAddress)
const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "helius-example",
    method: "getTransactionsForAddress",
    params: [
      walletAddress,
      {
        filters: {
          tokenAccounts: "all"
        },
        sortOrder: "asc",
        limit: 100
      }
    ]
  })
});

const { result } = await response.json();
return result;
```

### Capacidades adicionais

<CardGroup cols={2}>
  <Card title="Ordenação cronológica" icon="arrow-up">
    Ordenar transações do mais antigo para o mais novo com `sortOrder: 'asc'`.
  </Card>

  <Card title="Filtragem baseada no tempo" icon="clock">
    Filtrar por intervalos de tempo usando filtros `blockTime`.
  </Card>

  <Card title="Filtragem de status" icon="filter">
    Obtenha apenas transações bem-sucedidas ou falhas com o filtro `status`.
  </Card>

  <Card title="Paginação mais simples" icon="list">
    Use `paginationToken` em vez de `before` / `until` assinaturas confusas.
  </Card>
</CardGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Guia de Indexação" icon="layer-group" href="/docs/pt-BR/rpc/how-to-index-solana-data">
    Use getTransactionsForAddress para retroalimentar e sincronizar um índice Solana.
  </Card>

  <Card title="getTransfersByAddress" icon="arrow-right-arrow-left" href="/docs/pt-BR/rpc/gettransfersbyaddress">
    Histórico analisado e apenas transferência para pagamentos e reconciliação.
  </Card>

  <Card title="Referência da API" icon="code" href="/docs/pt-BR/api-reference/rpc/http/gettransactionsforaddress">
    Esquema completo de solicitação e resposta para getTransactionsForAddress.
  </Card>

  <Card title="Visão geral de dados históricos" icon="clock-rotate-left" href="/docs/pt-BR/rpc/historical-data">
    Compare todos os métodos de dados históricos do Solana.
  </Card>
</CardGroup>