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

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

O método RPC [`getTokenAccountsByDelegate`](https://www.helius.dev/docs/api-reference/rpc/http/gettokenaccountsbydelegate) recupera todas as contas SPL Token que aprovaram uma chave pública específica como delegado. Um delegado tem autoridade para realizar certas ações na conta de token, como transferir ou queimar tokens, até o valor delegado.

Este método é útil para serviços que gerenciam autoridade delegada ou precisam descobrir em quais contas de token uma chave específica pode atuar em nome de.

## Casos Comuns de Uso

* **Listar Ativos Delegados:** Exibir todas as contas de token para as quais uma carteira ou programa específico recebeu autoridade delegada.
* **Gerenciamento Automatizado de Tokens:** Serviços que executam ações em nome dos usuários (por exemplo, formadores de mercado automatizados, protocolos de staking que gerenciam recompensas tokenizadas) podem usar isso para encontrar contas com as quais estão autorizados a interagir.
* **Auditoria de Delegações:** Revisar quais contas delegaram autoridade para um endereço específico.
* **Revogação de Delegações:** Identificar contas de token das quais a autoridade delegada precisa ser revogada (embora a revogação em si seja uma transação separada).

## Parâmetros de Solicitação

1. **`delegatePubkey`** (string, obrigatório): A chave pública codificada em base-58 da conta do delegado cujas contas de token associadas você deseja encontrar.

2. **`filter`** (objeto, obrigatório): Um objeto JSON que **deve** especificar `mint` ou `programId` para filtrar as contas:
   * **`mint`** (string): A chave pública codificada em base-58 de um token mint específico. Se fornecido, a consulta retornará apenas contas de token deste tipo específico que estão delegadas para `delegatePubkey`.
   * **`programId`** (string): A chave pública codificada em base-58 do programa de token que possui as contas. Isso geralmente será o programa padrão SPL Token (`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`) ou o programa Token-2022 (`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`).

3. **`options`** (objeto, opcional): Um objeto de configuração opcional com os seguintes campos comuns:
   * **`commitment`** (string, opcional): Especifica o [nível de comprometimento](https://www.helius.dev/blog/solana-commitment-levels).
   * **`encoding`** (string, opcional): A codificação para dados de conta. `"jsonParsed"` é altamente recomendada, pois retorna informações de conta legíveis para humanos. Outras opções incluem `"base64"`, `"base64+zstd"`. O padrão é `"base64"` se não especificado.
   * **`dataSlice`** (objeto, opcional): Permite recuperar apenas uma fatia específica dos dados da conta. Contém campos `offset` (usize) e `length` (usize). Aplicável apenas para codificações `base58`, `base64`, ou `base64+zstd`.
   * **`minContextSlot`** (u64, opcional): O slot mínimo em que a solicitação pode ser avaliada.

## Estrutura de Resposta

O campo `result.value` na resposta JSON-RPC é uma matriz de objetos. Cada objeto representa uma conta de token que tem `delegatePubkey` como seu delegado e corresponde aos critérios `filter`. Cada objeto na matriz tem dois campos:

* **`pubkey`** (string): A chave pública codificada em base-58 da própria conta de token.
* **`account`** (objeto): Um objeto contendo informações detalhadas sobre a conta de token:
  * **`lamports`** (u64): O saldo de lamports da conta de token (para isenção de aluguel).
  * **`owner`** (string): A chave pública do programa que possui esta conta (por exemplo, o programa Token).
  * **`data`**: Os dados da conta. Se a codificação `"jsonParsed"` for usada, isso será um objeto com um campo `program` (por exemplo, `"spl-token"`) e um campo `parsed` contendo informações estruturadas:
    * **`parsed.info`**: Um objeto com detalhes como:
      * **`mint`** (string): O endereço de mint do token.
      * **`owner`** (string): O proprietário da conta de token (não o delegado).
      * **`tokenAmount`** (objeto): O saldo total de tokens nesta conta (`amount`, `decimals`, `uiAmount`, `uiAmountString`).
      * **`delegate`** (string): A chave pública do delegado (deve corresponder ao `delegatePubkey` da solicitação).
      * **`delegatedAmount`** (objeto): A quantidade de tokens que o delegado está autorizado a gerenciar (`amount`, `decimals`, `uiAmount`, `uiAmountString`).
      * **`isNative`** (boolean): Indica se a conta possui SOL encapsulado.
      * **`state`** (string): O estado da conta de token (por exemplo, `"initialized"`).
    * **`parsed.type`** (string): O tipo da conta (por exemplo, `"account"`).
  * **`executable`** (boolean): Se a conta é executável.
  * **`rentEpoch`** (u64): A época em que esta conta deverá aluguel novamente.
  * **`space`** (u64, se `jsonParsed` não for usado): O comprimento dos dados brutos da conta em bytes.

**Exemplo de Resposta (com codificação `jsonParsed`):**

```json theme={"system"}
{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "slot": 183458000
    },
    "value": [
      {
        "pubkey": "SomeTokenAccountPubkey1...",
        "account": {
          "data": {
            "program": "spl-token",
            "parsed": {
              "info": {
                "delegate": "DelegatePubkeyProvidedInRequest...",
                "delegatedAmount": {
                  "amount": "1000000000",
                  "decimals": 9,
                  "uiAmount": 1.0,
                  "uiAmountString": "1.0"
                },
                "isNative": false,
                "mint": "TokenMintPubkey...",
                "owner": "ActualOwnerOfTheTokenAccount...",
                "state": "initialized",
                "tokenAmount": {
                  "amount": "5000000000",
                  "decimals": 9,
                  "uiAmount": 5.0,
                  "uiAmountString": "5.0"
                }
              },
              "type": "account"
            },
            "space": 165
          },
          "executable": false,
          "lamports": 2039280,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // SPL Token Program
          "rentEpoch": 382
        }
      }
      // ... potentially other token accounts delegated to the same delegate
    ]
  },
  "id": 1
}
```

## Exemplos de Código

<CodeGroup>
  ```bash cURL theme={"system"}
  # Replace <DELEGATE_PUBKEY> and <TOKEN_MINT_PUBKEY> or <TOKEN_PROGRAM_ID>
  # Example using programId (SPL Token Program)
  curl -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getTokenAccountsByDelegate",
      "params": [
        "<DELEGATE_PUBKEY>",
        { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
        { "encoding": "jsonParsed" }
      ]
    }' \
    <YOUR_RPC_URL>

  # Example using a specific mint
  curl -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getTokenAccountsByDelegate",
      "params": [
        "<DELEGATE_PUBKEY>",
        { "mint": "<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 findDelegatedAccounts(delegateAddress, filter, encoding = 'jsonParsed') {
    // Replace with your RPC endpoint
    const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
    const delegatePubKey = new PublicKey(delegateAddress);

    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.getTokenAccountsByDelegate(
        delegatePubKey,
        actualFilter,
        { encoding }
      );

      console.log(`Found ${accounts.value.length} token accounts delegated to ${delegateAddress}:`);
      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(`    Owner: ${accInfo.account.data.parsed.info.owner}`);
          console.log(`    Delegated Amount: ${accInfo.account.data.parsed.info.delegatedAmount.uiAmountString}`);
        }
        // console.log(JSON.stringify(accInfo.account.data, null, 2)); // For full data
      });

    } catch (error) {
      console.error(`Error fetching token accounts by delegate for ${delegateAddress}:`, error);
    }
  }

  // Replace with an actual delegate public key
  const exampleDelegate = '4Nd1mBQtrMJVYVfKf2PJy9NZUZdTAsp7D4xWLs4gDB4T'; 

  // Example 1: Find all SPL Token program accounts delegated to `exampleDelegate`
  findDelegatedAccounts(exampleDelegate, { programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' });

  // Example 2: Find accounts for a specific mint (e.g., USDC) delegated to `exampleDelegate`
  // const usdcMint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
  // findDelegatedAccounts(exampleDelegate, { mint: usdcMint });
  ```
</CodeGroup>

## Dicas para Desenvolvedores

* **Requisito de Filtro:** Você *deve* fornecer `mint` ou `programId` no parâmetro de filtro. Não é possível consultar todas as contas delegadas para todos os tipos de token sem um desses filtros.
* **Codificação:** Usar `"jsonParsed"` para a opção `encoding` é altamente recomendado para facilitar o manuseio dos dados, pois decodifica os dados binários da conta em um formato JSON estruturado.
* **Desempenho:** Consultar com `programId` pode ser mais intensivo em recursos do que consultar com `mint`, especialmente se o delegado tiver autoridade sobre muitos tipos de token diferentes. Alguns provedores de RPC podem ter limites de taxa mais rígidos para este método.
* **Quantidade Delegada:** O `delegatedAmount` na resposta indica o número máximo de tokens que o delegado está atualmente autorizado a usar. Isso pode ser menos que o total `tokenAmount` na conta.
* **Revogação de Delegação:** Este método apenas recupera informações. Para revogar uma delegação, o proprietário da conta de token deve enviar uma instrução `Revoke` para o programa SPL Token.

Este guia fornece uma visão geral abrangente de como usar `getTokenAccountsByDelegate` para encontrar contas SPL Token com base em seu delegado aprovado.