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

# Visão Geral da Wallet API (Beta)

> Consulte dados de carteira Solana com a Wallet API. Obtenha saldos, histórico de transações, transferências, informações de identidade e fontes de financiamento em uma única solicitação.

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

## O que é a Wallet API?

A Wallet API fornece endpoints REST de alto nível para consultar dados completos de uma carteira Solana — saldos, histórico de transações, transferências de tokens, resolução de identidade, saldos históricos e fontes de financiamento. Em vez de fazer várias chamadas RPC e analisar dados brutos da blockchain, você obtém informações estruturadas e legíveis por humanos com preços em USD em uma única solicitação.

Ela é criada para carteiras, rastreadores de portfólio, exploradores, processadores de pagamento, ferramentas fiscais e sistemas de conformidade e AML. Todos os endpoints compartilham a URL base `https://api.helius.xyz` e retornam quantias em unidades legíveis por humanos (não é necessária conversão de lamports).

## Por que Helius para dados de carteira?

<CardGroup cols={2}>
  <Card title="Uma chamada REST" icon="bolt">
    Saldos estruturados, histórico e transferências sem juntar respostas
    RPC brutas.
  </Card>

  <Card title="Preço em USD embutido" icon="dollar-sign">
    Os saldos de tokens incluem valores em USD e totais de portfólio, originados do DAS.
  </Card>

  <Card title="Resolução de identidade" icon="address-card">
    Mais de 32.500 contas e programas rotulados, além de mais de 21,5 milhões de tags categóricas para
    exchanges, protocolos e instituições.
  </Card>

  <Card title="Saída legível por humanos" icon="book-open">
    Dados claros, ajustados em decimal em vez de lamports brutos e instruções.
  </Card>
</CardGroup>

## Principais endpoints

<CardGroup cols={2}>
  <Card title="Identidade da Carteira" icon="address-card" href="/docs/pt-BR/wallet-api/identity">
    Identifique carteiras conhecidas por endereço ou domínio SNS/ANS — exchanges, protocolos,
    instituições.
  </Card>

  <Card title="Saldos da Carteira" icon="scale-balanced" href="/docs/pt-BR/wallet-api/balances">
    Todos os saldos de tokens e NFTs com valores em USD, logotipos e metadados.
  </Card>

  <Card title="Saldo Histórico" icon="clock" href="/docs/pt-BR/wallet-api/balance-at">
    Um saldo de token ou SOL em um timestamp, data/hora ou slot passado.
  </Card>

  <Card title="Histórico da Carteira" icon="clock-rotate-left" href="/docs/pt-BR/wallet-api/history">
    Histórico completo de transações com alterações de saldo para cada transação.
  </Card>

  <Card title="Transferências de Token" icon="arrow-right-arrow-left" href="/docs/pt-BR/wallet-api/transfers">
    Todas as transferências de entrada e saída com informações do remetente/destinatário.
  </Card>

  <Card title="Fonte de Financiamento" icon="money-bill-transfer" href="/docs/pt-BR/wallet-api/funded-by">
    A fonte de financiamento original de uma carteira, rastreada até seu primeiro SOL recebido.
  </Card>
</CardGroup>

## Qual endpoint devo usar?

| Você precisa                                        | Use este                                              | Retorna                                                     |
| --------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------- |
| Quem é uma carteira (exchange, protocolo, etiqueta) | [Identidade](/docs/pt-BR/wallet-api/identity)              | Nome, categoria e tags para endereços conhecidos            |
| O portfólio atual de uma carteira                   | [Saldos](/docs/pt-BR/wallet-api/balances)                  | Todos os tokens e NFTs com valores em USD                   |
| Um saldo em um momento passado                      | [Saldo Histórico](/docs/pt-BR/wallet-api/balance-at)       | Um saldo de token ou SOL em um timestamp/data/hora/slot     |
| Atividade completa de transações                    | [Histórico](/docs/pt-BR/wallet-api/history)                | Transações analisadas com alterações de saldo por transação |
| Apenas transferências enviadas/recebidas            | [Transferências](/docs/pt-BR/wallet-api/transfers)         | Visão no nível de transferência com contraparte e direção   |
| Onde se originaram os fundos de uma carteira        | [Fonte de Financiamento](/docs/pt-BR/wallet-api/funded-by) | Primeiro SOL recebido e seu remetente                       |

Referência rápida das rotas subjacentes (URL base `https://api.helius.xyz`):

* `GET /v1/wallet/{wallet}/identity` — obter identidade da carteira por endereço ou domínio SNS/ANS
* `POST /v1/wallet/batch-identity` — consulta de identidade em lote (até 100 endereços e/ou domínios)
* `GET /v1/wallet/{wallet}/balances` — obter todos os saldos de tokens e NFTs
* `GET /v1/wallet/{wallet}/balance-at` — obter um saldo de token ou SOL em um timestamp, data/hora ou slot passado
* `GET /v1/wallet/{wallet}/history` — obter histórico de transações com alterações de saldo
* `GET /v1/wallet/{wallet}/transfers` — obter toda a atividade de transferência de tokens
* `GET /v1/wallet/{wallet}/funded-by` — encontrar a fonte de financiamento original

## Autenticação

Todas as solicitações para a Wallet API exigem uma chave de API. Você pode passá-la como um parâmetro de consulta ou como um cabeçalho:

<Tabs>
  <Tab title="Parâmetro de Consulta">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/{wallet}/balances?api-key=YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Cabeçalho">
    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/{wallet}/balances" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

## Requisitos do plano

Os endpoints de identidade e fonte de financiamento exigem um plano pago. No plano Gratuito, solicitações para esses endpoints retornam `403 Forbidden`. Todos os outros endpoints estão abertos em todos os planos, incluindo Gratuito.

| Endpoint                             | Plano gratuito              |
| ------------------------------------ | --------------------------- |
| `GET /v1/wallet/{wallet}/identity`   | `403` — apenas planos pagos |
| `POST /v1/wallet/batch-identity`     | `403` — apenas planos pagos |
| `GET /v1/wallet/{wallet}/funded-by`  | `403` — apenas planos pagos |
| `GET /v1/wallet/{wallet}/balances`   | Disponível                  |
| `GET /v1/wallet/{wallet}/balance-at` | Disponível                  |
| `GET /v1/wallet/{wallet}/history`    | Disponível                  |
| `GET /v1/wallet/{wallet}/transfers`  | Disponível                  |

Qualquer nível pago desbloqueia os endpoints restritos — Developer, Business, e todos os níveis superiores (como Enterprise). Para habilitar consultas de identidade e fonte de financiamento, [faça upgrade do seu plano no painel](https://dashboard.helius.dev).

## Quantias e unidades

A Wallet API é uma abstração de alto nível sobre dados brutos do Solana. Todos os campos `amount` nas respostas são **legíveis por humanos** — já divididos pelo `decimals` do token — para que você possa exibi-los diretamente sem qualquer conversão. Chamadas RPC brutas do Solana retornam valores em lamports (a menor unidade, 10⁻⁹ SOL); a Wallet API não. `"amount": 1.5` significa 1.5 SOL, não 1.5 lamports.

Onde a aritmética exata é necessária, alguns endpoints também expõem `amountRaw`: o mesmo valor como um inteiro bruto serializado como uma string para evitar perda de precisão de ponto flutuante. A fórmula de conversão é:

`amount = parseInt(amountRaw) / 10**decimals`

| Endpoint                         | `amount` legível por humanos     | String bruta `amountRaw` |
| -------------------------------- | -------------------------------- | ------------------------ |
| **Saldos**                       | Campo `balance`                  | Não disponível           |
| **Balance-at**                   | Campo `balance` (string decimal) | Campo `balanceRaw`       |
| **Funded-by**                    | Campo `amount`                   | Campo `amountRaw`        |
| **Transferências**               | Campo `amount`                   | Campo `amountRaw`        |
| **Histórico** (`balanceChanges`) | Campo `amount`                   | Não disponível           |

Use `amount` para exibição. Use `amountRaw` ao passar valores para instruções on-chain ou outros sistemas que exigem aritmética exata de inteiros.

## Comece agora

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

  <Step title="Escolha seu endpoint">
    Use a tabela acima para escolher o endpoint que corresponde ao seu caso de uso.
  </Step>

  <Step title="Faça sua primeira solicitação">
    Comece com uma consulta de saldo simples:

    ```bash theme={"system"}
    curl "https://api.helius.xyz/v1/wallet/86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY/balances?api-key=YOUR_API_KEY"
    ```
  </Step>

  <Step title="Trate a resposta">
    Analise a resposta JSON e exiba os dados em sua aplicação.
  </Step>
</Steps>

## Próximos passos

<CardGroup cols={3}>
  <Card title="Obtendo Dados" icon="database" href="/docs/pt-BR/getting-data">
    Explore todas as formas de consultar dados do Solana no Helius.
  </Card>

  <Card title="Referência de API" icon="code" href="/docs/pt-BR/api-reference/wallet-api">
    Esquemas de solicitação e resposta para todos os endpoints da Wallet API.
  </Card>

  <Card title="Contato com Suporte" icon="headset" href="/docs/pt-BR/support/contact-support">
    Obtenha ajuda através do Discord, chat ou email.
  </Card>
</CardGroup>