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

# Histórico de Transações

> Recupere um histórico de transações legível para qualquer endereço Solana com filtragem, intervalos de tempo e slots, e paginação.

<Warning>
  A Enhanced Transactions API é um produto legado em modo de manutenção. Ainda funciona e estas páginas permanecem disponíveis, mas não está recebendo novos tipos de parser ou melhorias. Seu sucessor é o [Parsed Events](/docs/pt-BR/parsed-events), que decodifica instruções através do catálogo IDL e está em beta fechado. Você também pode usar [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress) para histórico de transações e preenchimento retroativo, e a [Wallet API](/docs/pt-BR/wallet-api/overview) para dados legíveis de carteira.
</Warning>

## Visão Geral

O endpoint de Histórico de Transações retorna um histórico de transações legível para qualquer endereço Solana. Em vez de lidar com dados brutos de instruções e listas de contas, você obtém informações estruturadas sobre:

* O que aconteceu na transação (transferências, trocas, atividades de NFT).
* Quais contas estavam envolvidas.
* Quantos SOL ou quantos tokens foram transferidos.
* Metadados associados (endereços de mint de tokens, nomes de tokens, símbolos de tokens e mais).

Envie uma solicitação `GET` para `/v0/addresses/{address}/transactions`. Sob o capô, este endpoint é alimentado pelo método RPC [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress).

## Quando usar isso

* Você está exibindo o histórico de transações de um endereço para usuários (carteiras, rastreadores de portfólio, exploradores).
* Você deseja um histórico pré-analisado e legível sem escrever seu próprio decodificador.
* Você precisa filtrar o histórico por tipo de transação, intervalo de tempo ou intervalo de slots.
* Você precisa do histórico completo de tokens de uma carteira, incluindo contas de token associadas (ATAs) — veja abaixo.

Para novos projetos, [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress) é o caminho nativo moderno da Helius com filtragem no servidor e buscas de contas de token.

## Início Rápido

<Steps>
  <Step title="Obtenha sua chave de API">
    Inscreva-se em [dashboard.helius.dev](https://dashboard.helius.dev) e copie sua chave de API.
  </Step>

  <Step title="GET no endpoint de transações do endereço">
    Recupere o histórico de transações para qualquer endereço Solana.

    <Tabs>
      <Tab title="JavaScript">
        ```javascript theme={"system"}
        const fetchWalletTransactions = async () => {
          const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K"; // Replace with target wallet
          const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY`;

          const response = await fetch(url);
          const transactions = await response.json();
          console.log("Wallet transactions:", transactions);
        };

        fetchWalletTransactions();
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={"system"}
        import requests

        def fetch_wallet_transactions():
            wallet_address = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K"  # Replace with target wallet
            url = f"https://mainnet.helius-rpc.com/v0/addresses/{wallet_address}/transactions?api-key=YOUR_API_KEY"

            response = requests.get(url)
            transactions = response.json()
            print("Wallet transactions:", transactions)

        fetch_wallet_transactions()
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Filtrar e paginar">
    Restrinja os resultados com os filtros `type`, de tempo e de slot abaixo, depois pagine por endereços de alto volume com cursores de assinatura.
  </Step>
</Steps>

## Suporte de Rede

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

## Parâmetros da Solicitação

| Parâmetro          | Descrição                                                            | Padrão      | Exemplo                          |
| ------------------ | -------------------------------------------------------------------- | ----------- | -------------------------------- |
| `limit`            | Número de transações a retornar (1-100)                              | 10          | `&limit=25`                      |
| `before-signature` | Buscar transações antes dessa assinatura (use com `sort-order=desc`) | -           | `&before-signature=sig123...`    |
| `after-signature`  | Buscar transações depois dessa assinatura (use com `sort-order=asc`) | -           | `&after-signature=sig456...`     |
| `type`             | Filtrar por tipo de transação                                        | -           | `&type=NFT_SALE`                 |
| `sort-order`       | Ordem de classificação para resultados                               | `desc`      | `&sort-order=asc`                |
| `token-accounts`   | Filtrar transações para contas de token relacionadas                 | `none`      | `&token-accounts=balanceChanged` |
| `commitment`       | Nível de compromisso                                                 | `finalized` | `&commitment=confirmed`          |

### Filtragem baseada em tempo

| Parâmetro  | Descrição                                   | Exemplo                |
| ---------- | ------------------------------------------- | ---------------------- |
| `gt-time`  | Transações após este timestamp Unix         | `&gt-time=1656442333`  |
| `gte-time` | Transações em ou após este timestamp Unix   | `&gte-time=1656442333` |
| `lt-time`  | Transações antes deste timestamp Unix       | `&lt-time=1656442333`  |
| `lte-time` | Transações em ou antes deste timestamp Unix | `&lte-time=1656442333` |

### Filtragem baseada em slots

| Parâmetro  | Descrição                         | Exemplo               |
| ---------- | --------------------------------- | --------------------- |
| `gt-slot`  | Transações após este slot         | `&gt-slot=148277128`  |
| `gte-slot` | Transações em ou após este slot   | `&gte-slot=148277128` |
| `lt-slot`  | Transações antes deste slot       | `&lt-slot=148277128`  |
| `lte-slot` | Transações em ou antes deste slot | `&lte-slot=148277128` |

Notas sobre filtragem:

* Parâmetros de tempo usam timestamps Unix (segundos desde a época); parâmetros de slot usam números de slots Solana.
* Você não pode combinar filtros baseados em tempo e em slots na mesma solicitação.
* Use `sort-order=asc` para ascendente (mais antigo primeiro) ou `sort-order=desc` para descendente (mais recente primeiro).
* Use filtros de tempo ou de slots para reduzir o espaço de busca quando você souber o período aproximado, e emparelhe-os com `limit` para controlar o tamanho da página.

## Contas de token associadas

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

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

O filtro `token-accounts` controla este comportamento:

* **`none`** (padrão) — apenas retorna transações que referenciam diretamente o endereço da carteira. Use isso quando você se importa apenas 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 possuída pela carteira. Isso filtra spam e operações não relacionadas como cobrança de taxas ou delegações, oferecendo 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 possuída pela carteira.

<Warning>
  O filtro `token-accounts` depende do campo `owner` nos metadados de saldo de tokens, que não estava disponível antes do slot 111,491,819 (\~dezembro de 2022). Transações envolvendo contas de token ativas antes deste slot podem estar ausentes dos resultados `balanceChanged` e `all`. Veja o [tutorial getTransactionsForAddress](/docs/pt-BR/rpc/gettransactionsforaddress#limitations-and-edge-cases) para uma solução alternativa com um exemplo completo de código.
</Warning>

## Filtros

### Filtrar por tipo de transação

Obtenha apenas tipos específicos de transação, como vendas de NFT, transferências de tokens ou trocas:

<Tabs>
  <Tab title="Vendas de NFT">
    ```javascript theme={"system"}
    const fetchNftSales = async () => {
      const tokenAddress = "GjUG1BATg5V4bdAr1csKys1XK9fmrbntgb1iV7rAkn94"; // NFT mint address
      const url = `https://mainnet.helius-rpc.com/v0/addresses/${tokenAddress}/transactions?api-key=YOUR_API_KEY&type=NFT_SALE`;

      const response = await fetch(url);
      const nftSales = await response.json();
      console.log("NFT sale transactions:", nftSales);
    };
    ```
  </Tab>

  <Tab title="Transferências de Token">
    ```javascript theme={"system"}
    const fetchTokenTransfers = async () => {
      const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K"; // Wallet address
      const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&type=TRANSFER`;

      const response = await fetch(url);
      const transfers = await response.json();
      console.log("Transfer transactions:", transfers);
    };
    ```
  </Tab>

  <Tab title="Trocas">
    ```javascript theme={"system"}
    const fetchSwapTransactions = async () => {
      const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K"; // Wallet address
      const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&type=SWAP`;

      const response = await fetch(url);
      const swaps = await response.json();
      console.log("Swap transactions:", swaps);
    };
    ```
  </Tab>
</Tabs>

Para a lista completa de tipos de transação suportados, veja a [referência da API de Histórico de Transações](/docs/pt-BR/api-reference/enhanced-transactions/gettransactionsbyaddress).

### Filtragem por tipo em tempo de execução

<Note>
  A filtragem por tipo acontece em tempo de execução: a API busca transações sequencialmente até encontrar pelo menos 50 itens correspondentes. Se não encontrar nenhuma correspondência dentro da janela de busca, retorna um erro com uma assinatura para continuar a busca a partir de. Isso é um comportamento esperado, não uma falha.
</Note>

Quando nenhuma transação correspondente é encontrada dentro da janela de busca atual, a API retorna uma resposta de erro assim:

```json theme={"system"}
{
  "error": "Failed to find events within the search period. To continue search, query the API again with the `before-signature` parameter set to 2UKbsu95YzxGjUGYRg2znozmmVADVgmnhHqzDxq8Xfb3V5bf2NHUkaXGPrUpQnRFVHVKbawdQXtm4xJt9njMDHvg."
}
```

Para continuar, use a assinatura da mensagem de erro com o parâmetro apropriado (`before-signature` para descendente, `after-signature` para ascendente) em sua próxima solicitação.

<Accordion title="Loop de continuação para filtros de tipo (exemplo completo)">
  ```javascript theme={"system"}
  const fetchFilteredTransactions = async (sortOrder = 'desc') => {
    const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
    const transactionType = "NFT_SALE";
    let continuationSignature = null;
    let allFilteredTransactions = [];
    let maxRetries = 10; // Prevent infinite loops
    let retryCount = 0;

    // Determine which parameter to use based on sort order
    const continuationParam = sortOrder === 'asc' ? 'after-signature' : 'before-signature';

    while (retryCount < maxRetries) {
      // Build URL with optional continuation parameter
      let url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&type=${transactionType}&sort-order=${sortOrder}`;

      if (continuationSignature) {
        url += `&${continuationParam}=${continuationSignature}`;
      }

      try {
        const response = await fetch(url);
        const data = await response.json();

        // Check if we received an error about search period
        if (data.error && data.error.includes("Failed to find events within the search period")) {
          // Extract the signature from the error message
          const signatureMatch = data.error.match(/parameter set to ([A-Za-z0-9]+)/);

          if (signatureMatch && signatureMatch[1]) {
            console.log(`No results in this period. Continuing search from: ${signatureMatch[1]}`);
            continuationSignature = signatureMatch[1];
            retryCount++;
            continue; // Continue searching with new signature
          } else {
            console.log("No more transactions to search");
            break;
          }
        }

        // Check if we received transactions
        if (Array.isArray(data) && data.length > 0) {
          console.log(`Found ${data.length} ${transactionType} transactions`);
          allFilteredTransactions = [...allFilteredTransactions, ...data];

          // Set continuation signature for next page
          continuationSignature = data[data.length - 1].signature;
          retryCount = 0; // Reset retry count since we found results
        } else {
          console.log("No more transactions found");
          break;
        }

      } catch (error) {
        console.error("Error fetching transactions:", error);
        break;
      }
    }

    console.log(`Total ${transactionType} transactions found: ${allFilteredTransactions.length}`);
    return allFilteredTransactions;
  };

  // Usage examples:
  // Descending order (newest first) - uses 'before-signature' parameter
  fetchFilteredTransactions('desc');

  // Ascending order (oldest first) - uses 'after-signature' parameter
  fetchFilteredTransactions('asc');
  ```

  Pontos chave:

  * A API busca até 50 transações por vez ao usar filtros de tipo.
  * Se não encontrar correspondências, use a assinatura da mensagem de erro para continuar buscando.
  * Use `before-signature` ao buscar em ordem descendente (padrão, mais recente primeiro).
  * Use `after-signature` ao buscar em ordem ascendente (mais antigo primeiro) — necessário para buscas cronológicas.
  * Implemente um limite máximo de tentativas para prevenir loops infinitos.
</Accordion>

## Exemplos

Os seguintes cenários cobrem intervalos de tempo e slots, ordem de classificação, ATAs e filtros combinados.

<Accordion title="Filtrar por intervalo de tempo">
  Obtenha transações dentro de uma janela de tempo específica:

  <Tabs>
    <Tab title="Últimas 24 Horas">
      ```javascript theme={"system"}
      const fetchRecentTransactions = async () => {
        const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
        const now = Math.floor(Date.now() / 1000);
        const oneDayAgo = now - (24 * 60 * 60);

        const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&gte-time=${oneDayAgo}&lte-time=${now}`;

        const response = await fetch(url);
        const transactions = await response.json();
        console.log("Transactions from last 24 hours:", transactions);
      };
      ```
    </Tab>

    <Tab title="Intervalo de Data Específico">
      ```javascript theme={"system"}
      const fetchTransactionsByDateRange = async () => {
        const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";

        // January 1, 2024 to January 31, 2024
        const startTime = Math.floor(new Date('2024-01-01').getTime() / 1000);
        const endTime = Math.floor(new Date('2024-01-31').getTime() / 1000);

        const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&gte-time=${startTime}&lte-time=${endTime}`;

        const response = await fetch(url);
        const transactions = await response.json();
        console.log("Transactions in January 2024:", transactions);
      };
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Filtrar por intervalo de slots">
  Obtenha transações dentro de um intervalo específico de slots:

  ```javascript theme={"system"}
  const fetchTransactionsBySlotRange = async () => {
    const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
    const startSlot = 148000000;
    const endSlot = 148100000;

    const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&gte-slot=${startSlot}&lte-slot=${endSlot}`;

    const response = await fetch(url);
    const transactions = await response.json();
    console.log(`Transactions between slots ${startSlot} and ${endSlot}:`, transactions);
  };
  ```
</Accordion>

<Accordion title="Mudar ordem de classificação">
  Obtenha transações em ordem ascendente (mais antigo primeiro):

  ```javascript theme={"system"}
  const fetchOldestTransactions = async () => {
    const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
    const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&sort-order=asc&limit=10`;

    const response = await fetch(url);
    const transactions = await response.json();
    console.log("10 oldest transactions:", transactions);
  };
  ```
</Accordion>

<Accordion title="Incluir transferências para contas de token relacionadas">
  Consulte o histórico completo de uma carteira, incluindo endereços de token associados (ATAs):

  ```javascript theme={"system"}
  const fetchTransactionsWithATA = async () => {
    const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";

    const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&token-accounts=balanceChanged&sort-order=desc&limit=50`;

    const response = await fetch(url);
    const transactions = await response.json();
    console.log("Most recent transactions (including ATA transfers)", transactions);
  };
  ```
</Accordion>

<Accordion title="Combinar múltiplos filtros">
  Combine filtragem de tipo com um intervalo de tempo e ordem de classificação personalizada:

  ```javascript theme={"system"}
  const fetchFilteredTransactionsAdvanced = async () => {
    const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";

    // Get NFT sales from the last 7 days, oldest first
    const now = Math.floor(Date.now() / 1000);
    const sevenDaysAgo = now - (7 * 24 * 60 * 60);

    const url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&type=NFT_SALE&gte-time=${sevenDaysAgo}&sort-order=asc&limit=50`;

    const response = await fetch(url);
    const transactions = await response.json();
    console.log("NFT sales from last 7 days (oldest first):", transactions);
  };
  ```
</Accordion>

## Paginação

Para endereços de alto volume, pagine através dos resultados usando a última assinatura em cada lote como cursor:

```javascript theme={"system"}
const fetchAllTransactions = async () => {
  const walletAddress = "2k5AXX4guW9XwRQ1AKCpAuUqgWDpQpwFfpVFh3hnm2Ha"; // Replace with target wallet
  const baseUrl = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY`;
  let url = baseUrl;
  let lastSignature = null;
  let allTransactions = [];

  while (true) {
    if (lastSignature) {
      url = baseUrl + `&before-signature=${lastSignature}`;
    }

    const response = await fetch(url);

    // Check response status
    if (!response.ok) {
      console.error(`API error: ${response.status}`);
      break;
    }

    const transactions = await response.json();

    if (transactions && transactions.length > 0) {
      console.log(`Fetched batch of ${transactions.length} transactions`);
      allTransactions = [...allTransactions, ...transactions];
      lastSignature = transactions[transactions.length - 1].signature;
    } else {
      console.log(`Finished! Total transactions: ${allTransactions.length}`);
      break;
    }
  }

  return allTransactions;
};
```

Para paginar dentro de um intervalo de tempo, mantenha os filtros de tempo em cada solicitação e avance o cursor `before-signature` a cada loop:

```javascript theme={"system"}
const fetchAllTransactionsInTimeRange = async () => {
  const walletAddress = "M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K";
  const startTime = Math.floor(new Date('2024-01-01').getTime() / 1000);
  const endTime = Math.floor(new Date('2024-01-31').getTime() / 1000);

  let beforeSignature = null;
  let allTransactions = [];

  while (true) {
    let url = `https://mainnet.helius-rpc.com/v0/addresses/${walletAddress}/transactions?api-key=YOUR_API_KEY&gte-time=${startTime}&lte-time=${endTime}&limit=100`;

    if (beforeSignature) {
      url += `&before-signature=${beforeSignature}`;
    }

    const response = await fetch(url);
    const transactions = await response.json();

    if (!Array.isArray(transactions) || transactions.length === 0) {
      break;
    }

    allTransactions = [...allTransactions, ...transactions];
    beforeSignature = transactions[transactions.length - 1].signature;

    console.log(`Fetched ${transactions.length} transactions, total: ${allTransactions.length}`);
  }

  console.log(`Total transactions in time range: ${allTransactions.length}`);
  return allTransactions;
};
```

## Próximos passos

<CardGroup cols={2}>
  <Card title="getTransactionsForAddress" icon="clock-rotate-left" href="/docs/pt-BR/rpc/gettransactionsforaddress">
    O substituto moderno e nativo da Helius para histórico de transações e preenchimento retroativo.
  </Card>

  <Card title="Wallet API" icon="wallet" href="/docs/pt-BR/wallet-api/overview">
    Endpoints REST para dados de carteira legíveis: saldos, histórico e transferências.
  </Card>

  <Card title="Parse Transactions" icon="code" href="/docs/pt-BR/enhanced-transactions/parse-transactions">
    Analise uma ou mais assinaturas de transação em dados legíveis.
  </Card>

  <Card title="Visão geral de Obtenção de Dados" icon="database" href="/docs/pt-BR/getting-data">
    Compare cada opção da Helius para consulta de dados Solana.
  </Card>
</CardGroup>