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

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

O método RPC [`getTokenAccountsByOwner`](https://www.helius.dev/docs/api-reference/rpc/http/gettokenaccountsbyowner) é usado para recuperar todas as contas SPL [Token](https://www.helius.dev/blog/how-to-get-token-holders-on-solana) possuídas por uma chave pública específica. Este é um método fundamental para carteiras e aplicações que precisam exibir as posses de tokens de um usuário ou interagir com suas várias contas de tokens.

Você deve filtrar a consulta por um token específico `mint` ou um `programId` (por exemplo, o SPL Token Program ou Token-2022 Program).

Para carteiras com amplos portfólios de tokens, considere usar o [`getTokenAccountsByOwnerV2`](/docs/pt-BR/api-reference/rpc/http/gettokenaccountsbyownerv2) que oferece suporte a paginação baseada em cursor com tamanhos de página configuráveis até 10.000 contas por requisição.

## Casos de Uso Comuns

* **Exibição de Portfólio do Usuário:** Obtenção de todas as contas de tokens (e, portanto, saldos) para o endereço de carteira de um usuário para mostrar seu portfólio completo de tokens.
* **Lógica de Aplicação:** Identificação de uma conta de token específica de um usuário para um determinado mint antes de iniciar uma transferência ou outra interação.
* **Verificação:** Verificação de quais contas de tokens um proprietário possui para um determinado tipo de token.
* **Indexação de Detentores de Tokens:** Embora menos eficiente para indexação global do que outros métodos, pode ser usada para encontrar contas para um conjunto conhecido de proprietários.

## Parâmetros de Requisição

1. **`ownerPubkey`** (string, obrigatório): A chave pública codificada em base-58 do proprietário da conta cuja contas de tokens você deseja recuperar.

2. **`filter`** (objeto, obrigatório): Um objeto JSON que **deve** especificar `mint` ou `programId`:
   * **`mint`** (string): A chave pública codificada em base-58 de um mint de token específico. Se fornecido, apenas contas de token para este mint possuídas por `ownerPubkey` serão retornadas.
   * **`programId`** (string): A chave pública codificada em base-58 do Programa de Tokens que governa as contas. Valores comuns são:
     * SPL Token Program: `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`
     * Token-2022 Program: `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`

3. **`options`** (objeto, opcional): Um objeto de configuração opcional que pode incluir:
   * **`commitment`** (string, opcional): Especifica o [nível de compromisso](https://www.helius.dev/blog/solana-commitment-levels).
   * **`encoding`** (string, opcional): A codificação para dados da conta. `"jsonParsed"` é altamente recomendada. Outras opções: `"base64"`, `"base64+zstd"`. O padrão é `"base64"`.
   * **`dataSlice`** (objeto, opcional): Para recuperar um segmento específico dos dados da conta (`offset`: usize, `length`: usize). Apenas para codificações `base58`, `base64`, ou `base64+zstd`.
   * **`minContextSlot`** (u64, opcional): O slot mínimo para a consulta.

## Estrutura de Resposta

O campo `result.value` na resposta JSON-RPC é um array de objetos. Cada objeto corresponde a uma conta SPL Token possuída por `ownerPubkey` e que corresponde ao `filter`.

Cada objeto no array `value` contém:

* **`pubkey`** (string): A chave pública codificada em base-58 da própria conta de token.
* **`account`** (objeto): Informações detalhadas sobre a conta de token:
  * **`lamports`** (u64): Saldo de Lamport para isenção de aluguel.
  * **`owner`** (string): O programa proprietário (por exemplo, a chave pública do Programa de Tokens).
  * **`data`**: Dados da conta. Se a codificação `"jsonParsed"` for usada, isto contém:
    * **`program`** (string): por exemplo, `"spl-token"`.
    * **`parsed`**: Um objeto com informações estruturadas:
      * **`info`**: Detalhes como:
        * **`mint`** (string): O endereço do mint do token.
        * **`owner`** (string): O proprietário da conta de token (isso deve corresponder ao `ownerPubkey` da requisição).
        * **`tokenAmount`** (objeto): O saldo de tokens (`amount`, `decimals`, `uiAmount`, `uiAmountString`).
        * **`state`** (string): Estado da conta de token (por exemplo, `"initialized"`).
        * **`isNative`** (booleano): Se a conta possui SOL encapsulado.
        * **`delegate`** (string, opcional): O endereço do delegado, se houver.
        * **`delegatedAmount`** (objeto, opcional): O valor delegado se um delegado estiver definido.
      * **`type`** (string): por exemplo, `"account"`.
  * **`executable`** (booleano): Se a conta é executável.
  * **`rentEpoch`** (u64): Próxima época de vencimento do aluguel.
  * **`space`** (u64, se não `jsonParsed`): Comprimento dos dados brutos da conta em bytes.

**Exemplo de Resposta (com codificação `jsonParsed`, filtrado por `programId`):**

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "slot": 183459000
    },
    "value": [
      {
        "pubkey": "AssociatedTokenAccountPubkey1...",
        "account": {
          "data": {
            "program": "spl-token",
            "parsed": {
              "info": {
                "isNative": false,
                "mint": "SomeTokenMintPubkey...",
                "owner": "OwnerPubkeyProvidedInRequest...",
                "state": "initialized",
                "tokenAmount": {
                  "amount": "1000000000", // 1 token if decimals is 9
                  "decimals": 9,
                  "uiAmount": 1.0,
                  "uiAmountString": "1.0"
                }
              },
              "type": "account"
            },
            "space": 165
          },
          "executable": false,
          "lamports": 2039280,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
          "rentEpoch": 380
        }
      },
      {
        "pubkey": "AnotherAssociatedTokenAccountPubkey...",
        "account": {
          // ... similar structure for another token owned by the same owner
        }
      }
    ]
  },
  "id": 1
}
```

## Exemplos de Código

<CodeGroup>
  ```bash cURL theme={"system"}
  # Replace <OWNER_PUBKEY> and <TOKEN_MINT_PUBKEY> or <TOKEN_PROGRAM_ID>

  # Example filtering by programId (SPL Token Program)
  curl -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getTokenAccountsByOwner",
      "params": [
        "<OWNER_PUBKEY>",
        { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
        { "encoding": "jsonParsed" }
      ]
    }' \
    <YOUR_RPC_URL>

  # Example filtering by a specific mint
  curl -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getTokenAccountsByOwner",
      "params": [
        "<OWNER_PUBKEY>",
        { "mint": "<SPECIFIC_TOKEN_MINT_PUBKEY>" },
        { "encoding": "jsonParsed", "commitment": "confirmed" }
      ]
    }' \
    <YOUR_RPC_URL>
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  const { Connection, PublicKey } = require('@solana/web3.js');

  async function findOwnerTokenAccounts(ownerAddress, filter, encoding = 'jsonParsed') {
    // Replace with your RPC endpoint
    const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
    const ownerPubKey = new PublicKey(ownerAddress);

    try {
      let actualFilter;
      if (filter.mint) {
        actualFilter = { mint: new PublicKey(filter.mint) };
      } else if (filter.programId) {
        actualFilter = { programId: new PublicKey(filter.programId) };
      } else {
        console.error("Filter must contain either 'mint' or 'programId'");
        return;
      }

      const accounts = await connection.getTokenAccountsByOwner(
        ownerPubKey,
        actualFilter,
        { encoding }
      );

      console.log(`Found ${accounts.value.length} token accounts for owner ${ownerAddress}:`);
      accounts.value.forEach(accInfo => {
        console.log(`  Token Account: ${accInfo.pubkey.toBase58()}`);
        if (encoding === 'jsonParsed' && accInfo.account.data.parsed) {
          console.log(`    Mint: ${accInfo.account.data.parsed.info.mint}`);
          console.log(`    Balance: ${accInfo.account.data.parsed.info.tokenAmount.uiAmountString}`);
        }
        // console.log(JSON.stringify(accInfo, null, 2)); // For full details
      });

    } catch (error) {
      console.error(`Error fetching token accounts for owner ${ownerAddress}:`, error);
    }
  }

  // Replace with an actual owner's public key
  const exampleOwner = 'HXtBm8XZbxaTt41uqaKhwUAa6Z1aPyvJdsZVENiWsetg'; // Example wallet address

  // Example 1: Find all SPL Token Program accounts owned by `exampleOwner`
  findOwnerTokenAccounts(exampleOwner, { programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' });

  // Example 2: Find USDC token accounts owned by `exampleOwner`
  // const usdcMint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
  // findOwnerTokenAccounts(exampleOwner, { mint: usdcMint });

  // Example 3: Find Token-2022 Program accounts owned by `exampleOwner`
  // findOwnerTokenAccounts(exampleOwner, { programId: 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb' });
  ```
</CodeGroup>

## Dicas para Desenvolvedores

* **Requisito de Filtro:** Você *deve* fornecer `mint` ou `programId` no filtro. Não é possível consultar todas as contas de token para um proprietário em todos os tipos de token sem um desses filtros principais.
* **Contas de Tokens Associados:** Este método retornará todas as contas de token possuídas pela chave pública, incluindo Contas de Tokens Associadas padrão (ATAs) e quaisquer outras contas SPL de token que possam possuir (por exemplo, de implementações de carteiras mais antigas ou configurações personalizadas).
* **Codificação:** Usar `"jsonParsed"` para a opção `encoding` é altamente recomendado. Ele decodifica os dados binários da conta em uma estrutura JSON mais utilizável.
* **Desempenho:** Se um proprietário tiver um número muito grande de contas de token (especialmente ao filtrar apenas por `programId`), a resposta poderá ser grande. Para esses casos, use o [`getTokenAccountsByOwnerV2`](/docs/pt-BR/api-reference/rpc/http/gettokenaccountsbyownerv2) que oferece suporte embutido para paginação.
* **Token-2022 (Extensões de Token):** Se estiver trabalhando com tokens criados usando o programa Token-2022 (que suporta extensões como taxas de transferência, juros, etc.), certifique-se de usar o `programId` correto: `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`.

Este guia fornece uma compreensão completa do método RPC `getTokenAccountsByOwner`, permitindo que você recupere informações de contas de tokens de forma eficiente para qualquer endereço Solana.

## Paginação para Grandes Portfólios de Tokens

Para carteiras com extensas posses de tokens, use [`getTokenAccountsByOwnerV2`](/docs/pt-BR/api-reference/rpc/http/gettokenaccountsbyownerv2) que oferece:

* **Paginação baseada em cursor**: Defina `limit` (1-10.000) e use `paginationKey` para navegar pelos resultados
* **Atualizações incrementais**: Use `changedSinceSlot` para buscar apenas contas de tokens modificadas desde um slot específico
* **Melhor desempenho**: Evita timeouts e permite rastreamento em tempo real do portfólio
* **Comportamento de paginação**: O fim da paginação é indicado apenas quando nenhuma conta de token é retornada. Menos contas que o limite podem ser retornadas devido a filtragem - continue a paginação até que `paginationKey` seja nulo

```typescript theme={"system"}
// Example: Paginated query for all token accounts
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: "getTokenAccountsByOwnerV2",
    params: [
      "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
      {
        encoding: "jsonParsed",
        limit: 1000
      }
    ]
  })
});

const data = await response.json();
console.log(`Found ${data.result.value.length} token accounts`);
if (data.result.paginationKey) {
  console.log("More results available, use paginationKey for next page");
  // Continue pagination even if fewer than limit accounts were returned
} else {
  console.log("End of pagination - no more token accounts available");
}
```

## Métodos Relacionados

<CardGroup cols={2}>
  <Card title="getTokenAccountsByOwnerV2" href="/docs/pt-BR/api-reference/rpc/http/gettokenaccountsbyownerv2">
    Versão paginada com navegação baseada em cursor para grandes portfólios
  </Card>

  <Card title="getTokenAccountBalance" href="/docs/pt-BR/api-reference/rpc/http/gettokenaccountbalance">
    Obtenha o saldo de uma conta de token específica
  </Card>
</CardGroup>