> ## 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 Usar getSignaturesForAddress

> Aprenda casos de uso do getSignaturesForAddress, exemplos de código, parâmetros de solicitação, estrutura de resposta e dicas.

O método RPC [`getSignaturesForAddress`](https://www.helius.dev/docs/api-reference/rpc/http/getsignaturesforaddress) permite que você recupere uma lista de assinaturas de transações confirmadas que envolvem um endereço de conta específico. Isso é útil para buscar o histórico de transações de uma conta. As assinaturas são retornadas em ordem cronológica inversa (mais recentes primeiro).

<Tip>
  Para filtragem avançada, ordenação e histórico de contas de token, use [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress) em vez disso. Observe que `getSignaturesForAddress` não inclui transações envolvendo contas de token associadas.
</Tip>

## Casos de Uso Comuns

* **Histórico de Transações da Conta:** Mostrar as transações passadas para a carteira de um usuário. Para uma análise mais avançada do histórico de transações, considere usar a [Enhanced Transactions API](https://www.helius.dev/docs/enhanced-transactions) da Helius.
* **Auditoria de Atividades:** Revisar todas as transações associadas a um contrato inteligente ou conta específico.
* **Busca de Transação Específica:** Encontrar uma transação específica iterando pelo histórico de uma conta, se apenas o endereço envolvido for conhecido.
* **Indexação de Dados:** Construir um índice local de transações para consultas e análises mais rápidas.

## Parâmetros de Solicitação

1. **`address`** (`string`): (Obrigatório) A chave pública codificada em base-58 da conta para a qual se deseja recuperar assinaturas de transações.
2. **`options`** (`object`, opcional): Um objeto de configuração opcional com os seguintes campos:
   * **`limit`** (`number`, opcional): O número máximo de assinaturas a retornar. O padrão é 1000, e o máximo permitido é 1000.
   * **`before`** (`string`, opcional): Uma assinatura de transação codificada em base-58. Se fornecida, a consulta começará a buscar transações antes desta assinatura.
   * **`until`** (`string`, opcional): Uma assinatura de transação codificada em base-58. Se fornecida, a consulta buscará transações até que esta assinatura seja alcançada (exclusiva).
   * **`commitment`** (`string`, opcional): Especifica o [nível de compromisso](https://www.helius.dev/blog/solana-commitment-levels) a ser usado na consulta. Os valores suportados são `finalized` ou `confirmed`. O compromisso `processed` não é suportado. Se omitido, o compromisso padrão do nó RPC é usado (geralmente `finalized`).
   * **`minContextSlot`** (`number`, opcional): O slot mínimo em que a solicitação pode ser avaliada. Isto não é um filtro para transações históricas, mas define o slot mínimo para o contexto do nó.

<Warning>
  **Lote Não Suportado**

  Este método de arquivamento não suporta lote. Faça solicitações individuais apenas.
</Warning>

## Estrutura de Resposta

O campo `result` da resposta JSON-RPC é uma matriz de objetos de informações de assinatura. Cada objeto possui a seguinte estrutura:

* **`signature`** (`string`): A assinatura de transação codificada em base-58.
* **`slot`** (`u64`): O slot em que a transação foi processada.
* **`err`** (`object` | `null`): Um objeto de erro se a transação falhou, ou `null` se tiver sido bem-sucedida.
* **`memo`** (`string` | `null`): O memo associado à transação, se houver.
* **`blockTime`** (`i64` | `null`): O tempo estimado de produção do bloco contendo a transação, como um timestamp Unix (segundos desde a época). `null` se não disponível.
* **`confirmationStatus`** (`string` | `null`): O status de confirmação da transação (por exemplo, `processed`, `confirmed`, `finalized`). `null` se não disponível (por exemplo, para respostas Helius mais antigas).

## Exemplos

### 1. Obter as Assinaturas Mais Recentes de um Endereço

Este exemplo busca as assinaturas de transação mais recentes (até 1000) para um determinado endereço.

<CodeGroup>
  ```bash cURL theme={"system"}
  # Replace <api-key> with your Helius API key
  # Replace SYSTEM_PROGRAM_ID with the address you want to query
  curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getSignaturesForAddress",
      "params": [
        "11111111111111111111111111111111" 
      ]
    }'
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  // Replace <api-key> with your Helius API key
  const { Connection, PublicKey } = require('@solana/web3.js');

  async function getLatestSignatures() {
    const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
    // Replace with the public key you want to query
    const address = new PublicKey('11111111111111111111111111111111'); 

    try {
      const signatures = await connection.getSignaturesForAddress(address);
      if (signatures && signatures.length > 0) {
        console.log(`Found ${signatures.length} signatures:`);
        signatures.forEach((sigInfo, index) => {
          console.log(`--- Signature ${index + 1} ---`);
          console.log(`  Signature: ${sigInfo.signature}`);
          console.log(`  Slot: ${sigInfo.slot}`);
          console.log(`  Block Time: ${sigInfo.blockTime ? new Date(sigInfo.blockTime * 1000).toLocaleString() : 'N/A'}`);
          console.log(`  Error: ${JSON.stringify(sigInfo.err)}`);
          console.log(`  Memo: ${sigInfo.memo || 'N/A'}`);
          console.log(`  Confirmation Status: ${sigInfo.confirmationStatus || 'N/A'}`);
        });
      } else {
        console.log('No signatures found for this address.');
      }
    } catch (error) {
      console.error('Error fetching signatures:', error);
    }
  }

  getLatestSignatures();
  ```
</CodeGroup>

### 2. Obter Assinaturas com um Limite

Este exemplo busca um número especificado de assinaturas de transações recentes para um endereço.

<CodeGroup>
  ```bash cURL theme={"system"}
  # Replace <api-key> with your Helius API key
  # Replace TARGET_ACCOUNT_ADDRESS with the address you want to query
  curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getSignaturesForAddress",
      "params": [
        "TARGET_ACCOUNT_ADDRESS",
        {
          "limit": 5 
        }
      ]
    }'
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  // Replace <api-key> with your Helius API key
  const { Connection, PublicKey } = require('@solana/web3.js');

  async function getLimitedSignatures() {
    const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
    // Replace with the public key you want to query
    const address = new PublicKey('Vote111111111111111111111111111111111111111'); 
    const limit = 5;

    try {
      const signatures = await connection.getSignaturesForAddress(address, { limit });
      console.log(`Fetched up to ${limit} signatures:`);
      signatures.forEach((sigInfo, index) => {
        console.log(`${index + 1}. Signature: ${sigInfo.signature}, Slot: ${sigInfo.slot}`);
      });
    } catch (error) {
      console.error(`Error fetching limited signatures for ${address.toBase58()}:`, error);
    }
  }

  getLimitedSignatures();
  ```
</CodeGroup>

### 3. Paginação pelo Histórico de Transações

Este exemplo demonstra como buscar o histórico de transações em lotes usando o parâmetro `before`.

<CodeGroup>
  ```bash cURL theme={"system"}
  # Initial request (get the latest 2)
  # Replace <api-key> with your Helius API key
  # Replace TARGET_ACCOUNT_ADDRESS with the address you want to query
  curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getSignaturesForAddress",
      "params": [
        "TARGET_ACCOUNT_ADDRESS",
        { "limit": 2 }
      ]
    }'

  # Suppose the last signature from the above response was LAST_SIGNATURE_FROM_PREVIOUS_BATCH
  # Fetch the next 2 transactions before that one
  curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getSignaturesForAddress",
      "params": [
        "TARGET_ACCOUNT_ADDRESS",
        { 
          "limit": 2,
          "before": "LAST_SIGNATURE_FROM_PREVIOUS_BATCH" 
        }
      ]
    }'
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  // Replace <api-key> with your Helius API key
  const { Connection, PublicKey } = require('@solana/web3.js');

  async function paginateSignatures() {
    const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
    // Replace with the public key you want to query - e.g. a known active address
    const address = new PublicKey('Vote111111111111111111111111111111111111111'); 
    const batchSize = 2;
    let lastSignature = null;
    let allSignatures = [];
    const maxPages = 3; // Limit how many pages we fetch for this example

    try {
      for (let i = 0; i < maxPages; i++) {
        console.log(`Fetching page ${i + 1}...`);
        const options = { limit: batchSize };
        if (lastSignature) {
          options.before = lastSignature;
        }

        const signatures = await connection.getSignaturesForAddress(address, options);
        
        if (signatures.length === 0) {
          console.log('No more signatures found.');
          break;
        }

        signatures.forEach(sigInfo => {
          allSignatures.push(sigInfo.signature);
          console.log(`  Found: ${sigInfo.signature} in slot ${sigInfo.slot}`);
        });
        
        lastSignature = signatures[signatures.length - 1]?.signature;

        if (signatures.length < batchSize || !lastSignature) {
           console.log('Fetched all available signatures or reached end of page.');
           break;
        }
        // Optional: Add a small delay if making many sequential requests
        // await new Promise(resolve => setTimeout(resolve, 200)); 
      }
      console.log(`
  Total signatures fetched (${allSignatures.length}):`);
      allSignatures.forEach((sig, idx) => console.log(`${idx + 1}. ${sig}`));

    } catch (error) {
      console.error('Error paginating signatures:', error);
    }
  }

  paginateSignatures();
  ```
</CodeGroup>

## Dicas para Desenvolvedores

* **Paginação:** Para obter um histórico completo de transações para uma conta ativa, você provavelmente precisará fazer várias solicitações, usando o parâmetro `before` com a última assinatura recebida no lote anterior e um `limit`.
* **Limites de Taxa:** Esteja atento aos limites de taxa do nó RPC ao buscar históricos extensos de transações.
* **Ordem:** As assinaturas são sempre retornadas da mais nova para a mais antiga.
* **Parâmetro `limit`:** O parâmetro `limit` pode ser entre 1 e 1000. Se não especificado, o padrão é 1000.
* **Parâmetro `until`:** Este parâmetro pode ser usado para parar de buscar assinaturas se uma assinatura mais antiga conhecida for alcançada, o que pode ser útil se você só precisar de transações até certo ponto.
* **`minContextSlot`:** Este parâmetro não filtra transações históricas. Ele especifica o slot mínimo que o nó RPC deve usar para seu contexto ao avaliar a solicitação. Se o estado do nó for mais antigo que este slot, ele pode retornar um erro.
* **Detalhes da Transação:** Este método só retorna assinaturas e informações básicas. Para obter detalhes completos da transação, você utilizaria o método `getTransaction` com cada assinatura.
* **Limitação de Conta de Token:** Este método só retorna transações que referenciam diretamente o endereço fornecido. Não inclui transações envolvendo contas de token possuídas pelo endereço. Para um histórico completo de tokens, incluindo contas de token associadas, use [`getTransactionsForAddress`](/docs/pt-BR/rpc/gettransactionsforaddress) com o filtro `tokenAccounts`.

Usando `getSignaturesForAddress` com suas opções de paginação, você pode recuperar e gerenciar efetivamente históricos de transações para qualquer endereço Solana.

## Métodos Relacionados

<CardGroup cols={2}>
  <Card title="getTransactionsForAddress" href="/docs/pt-BR/rpc/gettransactionsforaddress">
    Filtragem avançada, ordenação e histórico de contas de token
  </Card>

  <Card title="getTransaction" href="/docs/pt-BR/api-reference/rpc/http/gettransaction">
    Obter detalhes completos da transação a partir de uma assinatura
  </Card>
</CardGroup>