> ## 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 Saldo Histórico de Token de uma Carteira Solana > Consulte o saldo de uma carteira de qualquer token ou SOL nativo em um ponto passado no tempo, data ou slot. Ideal para PnL, base de custo, relatórios fiscais e reconstrução do estado da carteira. A Wallet API está em Beta. Os endpoints e formatos de resposta podem mudar. ## Visão Geral O endpoint de Saldo Histórico responde: **qual era o saldo desta carteira de um token específico (ou SOL nativo) em um ponto específico no passado?** Enquanto o endpoint [Balances](/docs/pt-BR/wallet-api/balances) reporta as *posições atuais*, `balance-at` reporta as posições de acordo com qualquer timestamp, data ou slot. Ele encontra a **única transação mais recente no ou antes do ponto no tempo solicitado** que envolveu a carteira e o token, em seguida, lê o **saldo pós-transação** da carteira a partir dessa transação. O saldo pós-transação de uma transação é o saldo mantido a partir dessa transação até a próxima, então "saldo a partir do tempo T" é o saldo pós-transação da última transação relevante com um tempo de bloco (ou slot) no ou antes de T. Para a carteira típica, isso é um valor exato, não uma estimativa. * **Tokens (SPL / Token-2022)**: lido dos saldos de tokens pós-transação, somados nas contas de token da carteira para essa emissão. * **SOL nativo**: lido dos saldos pós-transação de lamports. Enderece o SOL nativo com o pseudo-mint `So11111111111111111111111111111111111111111`. ## Quando usar isso Use a API de Saldo Histórico para: * **Cálculo de PnL**: determine as posições no início e no final de um período. * **Base de custo e lotes fiscais**: reconstrua saldos em eventos de aquisição ou disposição. * **Resolução de disputas**: comprove o que uma carteira possuía em um momento específico. * **Verificação de instantâneos**: verifique o saldo de uma carteira em um lançamento aéreo ou instantâneo de governança. * **Contabilidade e auditorias**: reconstrua o estado da carteira em limites de período. ## Início Rápido ### Saldo de token em um timestamp Obtenha o saldo de USDC de uma carteira em um timestamp Unix: ```javascript theme={"system"} const getBalanceAt = async (wallet, mint, time) => { const url = `https://api.helius.xyz/v1/wallet/${wallet}/balance-at?mint=${mint}&time=${time}&api-key=YOUR_API_KEY`; const response = await fetch(url); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const result = await response.json(); if (result.asOf === null) { console.log('Wallet had no activity for this token by that time — balance is 0'); return result; } console.log(`Balance: ${result.balance}`); console.log(`Raw amount: ${result.balanceRaw} (${result.decimals} decimals)`); console.log(`As of slot ${result.asOf.slot}, signature ${result.asOf.signature}`); return result; }; // USDC balance on 2025-01-10 19:20:00 UTC getBalanceAt( "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 1736536800 ); ``` ```python theme={"system"} import requests def get_balance_at(wallet: str, mint: str, time: int): url = f"https://api.helius.xyz/v1/wallet/{wallet}/balance-at" headers = {"X-Api-Key": "YOUR_API_KEY"} params = {"mint": mint, "time": time} response = requests.get(url, headers=headers, params=params) response.raise_for_status() result = response.json() if result["asOf"] is None: print("Wallet had no activity for this token by that time — balance is 0") return result print(f"Balance: {result['balance']}") print(f"Raw amount: {result['balanceRaw']} ({result['decimals']} decimals)") print(f"As of slot {result['asOf']['slot']}, signature {result['asOf']['signature']}") return result # USDC balance on 2025-01-10 19:20:00 UTC get_balance_at( "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 1736536800 ) ``` ```bash theme={"system"} curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&time=1736536800&api-key=YOUR_API_KEY" ``` ### Saldo de token em uma data e hora Passe uma data e hora legíveis em vez de um timestamp. Lembre-se de codificar o espaço em URL como `%20`: ```bash theme={"system"} curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&datetime=2025-01-10%2019:20:00&api-key=YOUR_API_KEY" ``` ### Saldo de SOL nativo em um slot Para o SOL nativo, use o pseudo-mint `So11111111111111111111111111111111111111111`. Consultas baseadas em slots são exatas e determinísticas: ```bash theme={"system"} curl "https://api.helius.xyz/v1/wallet/5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9/balance-at?mint=So11111111111111111111111111111111111111111&slot=313000000&api-key=YOUR_API_KEY" ``` ## Parâmetros de consulta | Param | Obrigatório | Tipo | Descrição | | ---------- | ----------- | ------ | ------------------------------------------------------------------------------------------------- | | `mint` | Sim | string | Endereço de emissão do token. Para SOL nativo, use `So11111111111111111111111111111111111111111`. | | `time` | Um dos | int | Timestamp Unix em **segundos**. Saldo a partir deste tempo. | | `datetime` | Um dos | string | String de data e hora, por exemplo, `2025-01-10 19:20:00`. UTC por padrão. | | `slot` | Um dos | int | Número do slot. Saldo a partir deste slot. Exato e determinístico. | Exatamente **um** de INLINE\_CODE\_PLACEHOLDER\_bac8af8ba1420fb1\_END, `datetime`, ou `slot` deve ser fornecido. Fornecer zero ou mais de um retorna um erro `400`. ### Formatos de data e hora Formatos aceitos: * Apenas data: `2025-01-10` → meia-noite UTC * Data + hora: `2025-01-10 19:20:00` ou `2025-01-10T19:20:00` (segundos opcionais) → UTC * Com fuso horário explícito: `2025-01-10T19:20:00Z`, `2025-01-10T19:20:00+02:00`, `2025-01-10T19:20:00-05:00` → respeitado como fornecido Formatos inválidos ou não suportados (`01/10/2025`, `2025-13-10`, `2025-02-30`) retornam um erro `400`. Datas e horas são interpretadas como UTC por padrão. Uma data e hora simples como `2025-01-10 19:20:00` é tratada como UTC, não no seu horário local. Inclua um deslocamento de fuso horário explícito se quiser dizer outra coisa. O campo `requested.time` da resposta mostra os segundos de época resolvidos para que você possa verificar a interpretação. ## Formato de resposta ```json theme={"system"} { "wallet": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "isNative": false, "balance": "284961463.392936", "balanceRaw": "284961463392936", "decimals": 6, "requested": { "time": 1736536800, "slot": null, "datetime": null }, "asOf": { "slot": 313000000, "blockTime": 1736536794, "signature": "5Cyy7Mh9nVgFq3T8wJp2sKxR4dE6bA1uZoNcLrXmYqUpon" } } ``` ### Anotações de campo * **`wallet`**: eco do endereço da carteira consultada. * **`mint`**: eco da emissão consultada (o pseudo-mint SOL quando nativo). * **`isNative`**: `true` quando o resultado é SOL nativo. * **`balance`**: quantidade legível em formato decimal **string** — uma string, não um número, para que saldos grandes não percam precisão. Zeros à direita são aparados (`"1.5"`, não `"1.500000"`). * **`balanceRaw`**: quantidade exata na menor unidade (lamports para SOL), como uma string. * **`decimals`**: decimais do token (9 para SOL). * **`requested`**: eco da consulta. Quando `datetime` é usado, INLINE\_CODE\_PLACEHOLDER\_bac8af8ba1420fb1\_END também é populado com os segundos de época resolvidos, tornando a interpretação UTC visível. * **`asOf`**: a transação da qual o saldo foi lido (`slot`, `blockTime`, `signature`). `asOf: null` significa zero, não um erro. Quando a carteira não teve transações correspondentes no ou antes do ponto no tempo solicitado, o endpoint retorna `200` com `balance: "0"` e `asOf: null` — a carteira simplesmente não detinha o token até então. ## Casos de uso ### Mudança de saldo ao longo de um período Compare as posições em dois pontos no tempo: ```javascript theme={"system"} const getBalanceChange = async (wallet, mint, startTime, endTime) => { const fetchBalance = (time) => fetch( `https://api.helius.xyz/v1/wallet/${wallet}/balance-at?mint=${mint}&time=${time}&api-key=YOUR_API_KEY` ).then(r => r.json()); const [start, end] = await Promise.all([ fetchBalance(startTime), fetchBalance(endTime) ]); // balanceRaw is an exact integer string — use BigInt for precise arithmetic const delta = BigInt(end.balanceRaw) - BigInt(start.balanceRaw); const human = Number(delta) / 10 ** end.decimals; console.log(`Start: ${start.balance}`); console.log(`End: ${end.balance}`); console.log(`Change: ${human > 0 ? '+' : ''}${human}`); return { start, end, delta }; }; ``` ### Verificação de elegibilidade para instantâneo Verifique se uma carteira possuía um token em um slot de instantâneo: ```javascript theme={"system"} const heldAtSnapshot = async (wallet, mint, snapshotSlot, minimumRaw) => { const result = await fetch( `https://api.helius.xyz/v1/wallet/${wallet}/balance-at?mint=${mint}&slot=${snapshotSlot}&api-key=YOUR_API_KEY` ).then(r => r.json()); const eligible = BigInt(result.balanceRaw) >= BigInt(minimumRaw); console.log(`${wallet}: ${result.balance} at slot ${snapshotSlot} — ${eligible ? 'eligible' : 'not eligible'}`); return eligible; }; ``` ## Melhores práticas * **Use `slot` para resultados determinísticos.** INLINE\_CODE\_PLACEHOLDER\_bac8af8ba1420fb1\_END e `datetime` são resolvidos via tempos de bloco relatados por validadores, que podem ter um desvio de alguns segundos. Quando a reprodutibilidade exata é importante (instantâneos, auditorias), consulte por `slot`. * **Analise saldos como strings.** `balance` e `balanceRaw` são strings para preservar a precisão. Use `BigInt(balanceRaw)` (ou os inteiros de precisão arbitrária da sua linguagem) para aritmética — não converta para float. * **Trate `asOf: null` como zero.** Um `null` `asOf` é uma resposta bem-sucedida, significando que a carteira não teve atividade para aquele token no ponto solicitado. Não trate isso como um erro. * **Armazene em cache os resultados históricos.** Um saldo em um ponto passado no tempo nunca muda. Armazene os resultados permanentemente para evitar chamadas de API repetidas. ## Erros comuns \| Código de Erro | Descrição | Solução | \|----------------||-------------|----------| \| 400 | Faltando `mint`, emissão inválida, zero ou múltiplos de INLINE\_CODE\_PLACEHOLDER\_bac8af8ba1420fb1\_END/`datetime`/`slot`, ou `datetime` não analisável | Forneça uma emissão válida e exatamente um parâmetro ponto-no-tempo | \| 401 | Chave de API ausente ou inválida | Verifique se sua chave de API está incluída na solicitação | \| 404 | Endereço de carteira inválido no caminho | Verifique se o endereço é um endereço base58 Solana válido | \| 429 | Limite de taxa excedido | Reduza a frequência de solicitações ou atualize seu plano | \| 502 | Erro de RPC a montante ou tempo limite | Tente novamente com backoff exponencial | ## Limitações * **Carteiras com várias contas de token podem subcontar.** O saldo é lido da transação única mais recente correspondente. O caso comum — uma conta de token associada por emissão — é exato. Uma carteira que possui a mesma emissão em várias contas de token, onde a última transação tocou apenas algumas delas, pode ser subcontada. * **Precisão de SOL nativo para saldos muito grandes.** Para saldos de SOL além de \~ 9.007.199 SOL (2⁵³ lamports), a precisão pode ser perdida a montante. Quantidades de token não são afetadas. * **Precisão de INLINE\_CODE\_PLACEHOLDER\_bac8af8ba1420fb1\_END/`datetime` depende dos tempos de bloco relatados pelos validadores**, que podem ter um desvio de alguns segundos. Use `slot` para resultados exatos e determinísticos. * **Um token por solicitação.** Não há forma de múltiplas emissões ou "todos os saldos no tempo T" em lote. ## Próximos passos Obtenha as atuais posses de token e NFT de uma carteira com valores em USD. Todos os endpoints da Wallet API e convenções compartilhadas. Esquemas de solicitação e resposta para saldo histórico.