> ## 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 Obter o Histórico de Transações da Carteira Solana

> Obtenha o histórico completo de transações de qualquer carteira Solana com alterações de saldo para cada transação. Perfeito para rastreadores de portfólio, ferramentas de contabilidade e plataformas de análise.

<Note>
  A Wallet API está em Beta. Os endpoints e formatos de resposta podem mudar.
</Note>

## Visão Geral

O endpoint Histórico de Transações recupera o histórico completo de transações para uma carteira Solana usando a Enhanced Transactions API. Ele retorna transações analisadas e legíveis, com alterações de saldo para cada transação, em ordem cronológica inversa (mais recentes primeiro).

O endpoint retorna até 100 transações por solicitação, então a paginação é manual. Use o parâmetro `before` com `pagination.nextCursor` para buscar a próxima página, e leia `pagination.hasMore` para saber quando mais resultados estão disponíveis. Cada solicitação é uma única chamada de API e custa 100 créditos.

O parâmetro `tokenAccounts` controla se as transações envolvendo contas de token pertencentes à carteira são incluídas:

* `balanceChanged` (recomendado): inclui transações que alteraram saldos de contas de token, filtrando spam.
* `none`: apenas interações diretas com a carteira.
* `all`: todas as transações de contas de token, incluindo spam.

<Warning>
  O filtro `tokenAccounts` depende do campo `owner` nos metadados de saldo do token, 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. Veja o [tutorial getTransactionsForAddress](/docs/pt-BR/rpc/gettransactionsforaddress#limitations-and-edge-cases) para uma solução alternativa.
</Warning>

## Quando usar isto

Use a API de Histórico de Transações quando precisar:

* **Exibir um feed de transações**: mostrar aos usuários seu histórico completo de transações.
* **Calcular PnL**: rastrear ganhos e perdas em todas as transações.
* **Impostos e contabilidade**: gerar relatórios completos de transações para declaração de impostos.
* **Análise de portfólio**: analisar padrões de negociação e atividade.
* **Trilhas de auditoria**: manter registros completos da atividade da carteira.
* **Reconstrução de saldo**: reconstruir saldos atuais a partir de dados históricos.

## Início Rápido

### Consulta de histórico básico

Obtenha as transações mais recentes com alterações de saldo:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    const getTransactionHistory = async (address) => {
      const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY`;

      const response = await fetch(url);
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      const data = await response.json();

      console.log(`Found ${data.data.length} transactions`);

      // Display recent transactions
      data.data.forEach(tx => {
        const date = new Date(tx.timestamp * 1000).toLocaleString();
        const status = tx.error ? 'Failed' : 'Success';

        console.log(`\n${status} - ${date}`);
        console.log(`Signature: ${tx.signature.slice(0, 20)}...`);
        console.log(`Fee: ${tx.fee} SOL`);

        // Show balance changes
        tx.balanceChanges.forEach(change => {
          const sign = change.amount > 0 ? '+' : '';
          console.log(`  ${sign}${change.amount} ${change.mint === 'SOL' ? 'SOL' : change.mint.slice(0, 8)}...`);
        });
      });

      return data;
    };

    getTransactionHistory("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");
    ```
  </Tab>

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

    def get_transaction_history(address: str):
        url = f"https://api.helius.xyz/v1/wallet/{address}/history"
        headers = {"X-Api-Key": "YOUR_API_KEY"}

        response = requests.get(url, headers=headers)
        response.raise_for_status()

        data = response.json()

        print(f"Found {len(data['data'])} transactions")

        # Display recent transactions
        for tx in data['data']:
            date = datetime.fromtimestamp(tx['timestamp']).strftime('%Y-%m-%d %H:%M:%S')
            status = 'Failed' if tx.get('error') else 'Success'

            print(f"\n{status} - {date}")
            print(f"Signature: {tx['signature'][:20]}...")
            print(f"Fee: {tx['fee']} SOL")

            # Show balance changes
            for change in tx['balanceChanges']:
                sign = '+' if change['amount'] > 0 else ''
                mint_display = 'SOL' if change['mint'] == 'SOL' else change['mint'][:8] + '...'
                print(f"  {sign}{change['amount']} {mint_display}")

        return data

    get_transaction_history("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/history?api-key=YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

### Paginação para histórico completo

Busque todas as transações usando paginação com o parâmetro `before`:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={"system"}
    const getAllTransactionHistory = async (address) => {
      let allTransactions = [];
      let before = null;

      do {
        const url = before
          ? `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&before=${before}`
          : `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY`;

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

        allTransactions = allTransactions.concat(data.data);
        before = data.pagination.hasMore ? data.pagination.nextCursor : null;

        console.log(`Fetched ${allTransactions.length} transactions so far...`);

      } while (before);

      console.log(`\nTotal transactions: ${allTransactions.length}`);
      return allTransactions;
    };

    getAllTransactionHistory("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY");
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    def get_all_transaction_history(address: str):
        all_transactions = []
        before = None

        while True:
            url = f"https://api.helius.xyz/v1/wallet/{address}/history"
            params = {"api-key": "YOUR_API_KEY"}

            if before:
                params["before"] = before

            response = requests.get(url, params=params, headers={"X-Api-Key": "YOUR_API_KEY"})
            response.raise_for_status()

            data = response.json()
            all_transactions.extend(data['data'])

            print(f"Fetched {len(all_transactions)} transactions so far...")

            if not data['pagination']['hasMore']:
                break

            before = data['pagination']['nextCursor']

        print(f"\nTotal transactions: {len(all_transactions)}")
        return all_transactions

    get_all_transaction_history("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY")
    ```
  </Tab>
</Tabs>

## Parâmetros de consulta

| Parâmetro       | Tipo    | Padrão         | Descrição                                                                                      |
| --------------- | ------- | -------------- | ---------------------------------------------------------------------------------------------- |
| `limit`         | inteiro | 100            | Número máximo de transações por solicitação (1-100)                                            |
| `before`        | string  | -              | Buscar transações antes desta assinatura (use `pagination.nextCursor` da resposta anterior)    |
| `after`         | string  | -              | Buscar transações após esta assinatura (para paginação em ordem ascendente)                    |
| `type`          | string  | -              | Filtrar por tipo de transação (ex.: SWAP, TRANSFER, NFT\_SALE, TOKEN\_MINT)                    |
| `tokenAccounts` | string  | balanceChanged | Filtrar transações envolvendo contas de token: `none`, `balanceChanged` (recomendado) ou `all` |

### Tipos de transação disponíveis

O parâmetro `type` suporta filtragem por esses tipos de transação:

`SWAP`, `TRANSFER`, `NFT_SALE`, `NFT_BID`, `NFT_LISTING`, `NFT_MINT`, `NFT_CANCEL_LISTING`, `TOKEN_MINT`, `BURN`, `COMPRESSED_NFT_MINT`, `COMPRESSED_NFT_TRANSFER`, `COMPRESSED_NFT_BURN`, `CREATE_STORE`, `WHITELIST_CREATOR`, `ADD_TO_WHITELIST`, `REMOVE_FROM_WHITELIST`, `AUCTION_MANAGER_CLAIM_BID`, `EMPTY_PAYMENT_ACCOUNT`, `UPDATE_PRIMARY_SALE_METADATA`, `ADD_TOKEN_TO_VAULT`, `ACTIVATE_VAULT`, `INIT_VAULT`, `INIT_BANK`, `INIT_STAKE`, `MERGE_STAKE`, `SPLIT_STAKE`, `CREATE_AUCTION_MANAGER`, `START_AUCTION`, `CREATE_AUCTION_MANAGER_V2`, `UPDATE_EXTERNAL_PRICE_ACCOUNT`, `EXECUTE_TRANSACTION`

### Exemplos de filtro

<Tabs>
  <Tab title="Filtrar por Tipo">
    ```javascript theme={"system"}
    // Get only SWAP transactions
    const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&type=SWAP`;
    ```
  </Tab>

  <Tab title="Filtro de Contas de Token">
    ```javascript theme={"system"}
    // Exclude spam by only including transactions that changed token balances
    const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&tokenAccounts=balanceChanged`;

    // Only show direct wallet interactions
    const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&tokenAccounts=none`;
    ```
  </Tab>

  <Tab title="Filtros Combinados">
    ```javascript theme={"system"}
    // Get only NFT sales that changed balances
    const url = `https://api.helius.xyz/v1/wallet/${address}/history?api-key=YOUR_API_KEY&type=NFT_SALE&tokenAccounts=balanceChanged`;
    ```
  </Tab>
</Tabs>

## Formato da resposta

```json theme={"system"}
{
  "data": [
    {
      "signature": "5wHu1qwD7Jsj3xqWjdSEJmYr3Q5f5RjXqjqQJ7jqEj7jqEj7jqEj7jqEj7jqEj7jqE",
      "timestamp": 1704067200,
      "slot": 250000000,
      "fee": 0.000005,
      "feePayer": "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
      "error": null,
      "balanceChanges": [
        {
          "mint": "So11111111111111111111111111111111111111111",
          "amount": -0.05,
          "decimals": 9
        },
        {
          "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "amount": 50.0,
          "decimals": 6
        }
      ]
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "5wHu1qwD7Jsj3xqWjdSEJmYr3Q5f5RjXqjqQJ7jqEj7jqEj7jqEj7jqEj7jqEj7jqE"
  }
}
```

### Notas sobre os campos

* **`timestamp`**: segundos Unix. Pode ser `null` para transações muito recentes que ainda não foram totalmente processadas.
* **`error`**: `null` para transações bem-sucedidas; um valor de erro para as falhas. Transações falhas ainda geram taxas.
* **`balanceChanges`**: como as posses da carteira mudaram na transação — um `amount` positivo é tokens recebidos, um `amount` negativo é tokens enviados ou gastos.
* **`mint`** (dentro de `balanceChanges`): endereço de mint dos tokens, ou `"SOL"` para SOL nativo.
* **`amount`** (dentro de `balanceChanges`): **legível**, já dividido por `decimals` — `-0.05` significa -0,05 SOL, não -0,05 lamports. Este endpoint não inclui um campo `amountRaw` bruto.

#### Exemplo de alterações de saldo

```javascript theme={"system"}
// Swap: Sold 0.05 SOL, received 5 USDC
{
  "balanceChanges": [
    { "mint": "SOL", "amount": -0.05, "decimals": 9 },
    { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": 5.0, "decimals": 6 }
  ]
}

// Simple transfer: Sent 10 USDC
{
  "balanceChanges": [
    { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": -10.0, "decimals": 6 }
  ]
}
```

## Casos de uso

### Calcular volume total de negociação

Some todas as transferências para obter o volume de negociação:

```javascript theme={"system"}
const calculateTradingVolume = async (address, tokenMint) => {
  const transactions = await getAllTransactionHistory(address);

  let totalVolume = 0;

  transactions.forEach(tx => {
    tx.balanceChanges.forEach(change => {
      if (change.mint === tokenMint) {
        totalVolume += Math.abs(change.amount);
      }
    });
  });

  console.log(`Total ${tokenMint} volume: ${totalVolume}`);
  return totalVolume;
};

// Example: Calculate total USDC volume
calculateTradingVolume(
  "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" // USDC
);
```

### Gerar um relatório de impostos

Crie um relatório de transações para declaração de impostos:

```javascript theme={"system"}
const generateTaxReport = async (address, year) => {
  const transactions = await getAllTransactionHistory(address);

  const startDate = new Date(`${year}-01-01`).getTime() / 1000;
  // Set to end of December 31st (23:59:59.999) to include all transactions from that day
  const endDate = new Date(`${year}-12-31T23:59:59.999Z`).getTime() / 1000;

  const taxableTransactions = transactions
    .filter(tx => tx.timestamp >= startDate && tx.timestamp <= endDate)
    .map(tx => ({
      date: new Date(tx.timestamp * 1000).toISOString(),
      signature: tx.signature,
      fee: tx.fee,
      balanceChanges: tx.balanceChanges,
      explorerUrl: `https://orbmarkets.io/tx/${tx.signature}`
    }));

  console.log(`Found ${taxableTransactions.length} transactions in ${year}`);

  // Export as JSON
  const report = {
    address,
    year,
    transactionCount: taxableTransactions.length,
    transactions: taxableTransactions
  };

  console.log(JSON.stringify(report, null, 2));
  return report;
};

generateTaxReport("86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY", 2024);
```

### Rastreamento de transações falhas

Encontre todas as transações falhas para entender erros:

```javascript theme={"system"}
const getFailedTransactions = async (address) => {
  const data = await getTransactionHistory(address);

  const failed = data.data.filter(tx => tx.error !== null);

  console.log(`Found ${failed.length} failed transactions`);

  failed.forEach(tx => {
    const date = new Date(tx.timestamp * 1000).toLocaleString();
    console.log(`\n${date}`);
    console.log(`Signature: ${tx.signature}`);
    console.log(`Error: ${tx.error}`);
    console.log(`Fee Paid: ${tx.fee} SOL`);
  });

  return failed;
};
```

### Reconstruir um saldo histórico

Calcule qual era o saldo em um ponto específico no tempo:

```javascript theme={"system"}
const getHistoricalBalance = async (address, targetTimestamp) => {
  const transactions = await getAllTransactionHistory(address);

  // Filter to transactions before target date
  const relevantTxs = transactions.filter(tx => tx.timestamp <= targetTimestamp);

  // Sum all balance changes
  const balances = {};

  relevantTxs.forEach(tx => {
    tx.balanceChanges.forEach(change => {
      if (!balances[change.mint]) {
        balances[change.mint] = 0;
      }
      balances[change.mint] += change.amount;
    });
  });

  console.log(`Historical balances as of ${new Date(targetTimestamp * 1000).toLocaleString()}:`);
  Object.entries(balances).forEach(([mint, balance]) => {
    console.log(`${mint}: ${balance}`);
  });

  return balances;
};

// Example: Get balances on Jan 1, 2024
getHistoricalBalance(
  "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
  new Date("2024-01-01").getTime() / 1000
);
```

Para o saldo exato de um único token em um ponto no tempo, o endpoint [Saldo Histórico](/docs/pt-BR/wallet-api/balance-at) lê diretamente dos pós-saldos on-chain em vez de somar as alterações no lado do cliente.

### Analisar taxas de transação

Calcule as taxas totais pagas:

```javascript theme={"system"}
const analyzeFees = async (address) => {
  const transactions = await getAllTransactionHistory(address);

  const totalFees = transactions.reduce((sum, tx) => sum + tx.fee, 0);
  const avgFee = totalFees / transactions.length;

  const successfulTxs = transactions.filter(tx => !tx.error);
  const failedTxs = transactions.filter(tx => tx.error);

  const wastedFees = failedTxs.reduce((sum, tx) => sum + tx.fee, 0);

  console.log(`Total Transactions: ${transactions.length}`);
  console.log(`Successful: ${successfulTxs.length}`);
  console.log(`Failed: ${failedTxs.length}`);
  console.log(`Total Fees Paid: ${totalFees.toFixed(6)} SOL`);
  console.log(`Average Fee: ${avgFee.toFixed(6)} SOL`);
  console.log(`Wasted on Failed Txs: ${wastedFees.toFixed(6)} SOL`);

  return {
    totalFees,
    avgFee,
    wastedFees,
    successRate: (successfulTxs.length / transactions.length) * 100
  };
};
```

## Melhores práticas

* **Use paginação para o histórico completo.** Algumas carteiras têm centenas de milhares de transações; sempre faça paginação ao buscá-las.
* **Cacheie dados históricos.** Transações históricas nunca mudam. Armazene-as localmente em cache e busque apenas transações novas.
* **Maneje transações falhas.** Verifique o campo `error` para diferenciar transações bem-sucedidas de falhas. Transações falhas ainda geram taxas.
* **Use timestamps para filtragem por data.** Timestamps estão em segundos Unix. Converta para datas locais para exibição e filtragem.

## Erros comuns

| Código de Erro | Descrição                                | Solução                                                    |
| -------------- | ---------------------------------------- | ---------------------------------------------------------- |
| 400            | Formato de endereço de carteira inválido | Verifique se o endereço é um endereço Solana base58 válido |
| 401            | API key ausente ou inválida              | Verifique se sua API key está incluída na solicitação      |
| 429            | Limite de taxa excedido                  | Reduza a frequência das solicitações ou atualize seu plano |

## Próximos passos

<CardGroup cols={3}>
  <Card title="Transferências de Tokens" icon="arrow-right-arrow-left" href="/docs/pt-BR/wallet-api/transfers">
    Uma visão somente de transferências com informações de remetente/destinatário — mais simples que o histórico completo.
  </Card>

  <Card title="Visão Geral da Wallet API" icon="wallet" href="/docs/pt-BR/wallet-api/overview">
    Todos os endpoints da Wallet API e convenções compartilhadas.
  </Card>

  <Card title="Referência de API" icon="code" href="/docs/pt-BR/api-reference/wallet-api/history">
    Esquemas de solicitação e resposta para histórico de transações.
  </Card>
</CardGroup>