> ## 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 getBalance
> Aprenda sobre casos de uso do getBalance, exemplos de código, parâmetros de requisição, estrutura de resposta e dicas.
O método RPC [`getBalance`](https://www.helius.dev/docs/api-reference/rpc/http/getbalance) é uma forma simples de descobrir o saldo SOL nativo de qualquer conta na blockchain Solana. Ele retorna o saldo em lamports (1 SOL = 1.000.000.000 lamports).
Este método é mais leve do que `getAccountInfo` se você *somente* precisar do saldo em SOL e nenhum outro detalhe da conta.
## Caso de Uso Principal
* **Verificar Rapidamente o Saldo de SOL de uma Conta:** O uso principal é determinar quanto SOL uma conta (carteira, programa, etc.) possui.
## Parâmetros
1. `publicKey` (string, obrigatório): A chave pública codificada em base-58 da conta a ser consultada.
2. `config` (objeto, opcional): Um objeto de configuração com os seguintes campos:
* `commitment` (string, opcional): Especifica o [nível de compromisso](https://www.helius.dev/blog/solana-commitment-levels) a ser usado para a consulta. O padrão é `finalized`.
* `finalized`: O nó consultará o bloco mais recente confirmado pela supermaioria do cluster como tendo atingido o bloqueio máximo.
* `confirmed`: O nó consultará o bloco mais recente que foi votado por uma supermaioria do cluster.
* `processed`: O nó consultará seu bloco mais recente. Note que o bloco pode não estar completo.
* `minContextSlot` (número, opcional): O slot mínimo que a solicitação pode ser avaliada.
## Resposta
O campo `result` da resposta JSON-RPC será um objeto contendo:
* `context` (objeto):
* `slot` (número): O slot em que o saldo foi recuperado.
* `apiVersion` (string, opcional): A versão da API RPC (pode não estar presente em todos os nós).
* `value` (número): O saldo da conta em lamports (inteiro sem sinal de 64 bits).
Se a conta não existir on-chain, `getBalance` geralmente retornará um valor de `0` lamports.
## Exemplo: Obtendo o Saldo de uma Conta
Vamos verificar o saldo SOL do ID do Programa Serum V3 (`9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin`) na mainnet. Esta conta de programa em si possui SOL para isenção de aluguel.
**Nota:** Substitua `YOUR_API_KEY` pela sua chave de API Helius real nos exemplos abaixo.
```bash curl theme={"system"}
curl https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY -X POST -H "Content-Type: application/json" -d \
'{
"jsonrpc": "2.0",
"id": 1,
"method": "getBalance",
"params": [
"9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"
]
}'
```
```javascript JavaScript (using @solana/web3.js) theme={"system"}
const { Connection, PublicKey, LAMPORTS_PER_SOL } = require('@solana/web3.js');
async function checkBalance() {
const rpcUrl = 'https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY'; // Replace YOUR_API_KEY
const connection = new Connection(rpcUrl, 'confirmed');
const accountPubKey = new PublicKey('9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin');
try {
const lamports = await connection.getBalance(accountPubKey);
const sol = lamports / LAMPORTS_PER_SOL;
console.log(`Account PubKey: ${accountPubKey.toBase58()}`);
console.log(`Balance (Lamports): ${lamports}`);
console.log(`Balance (SOL): ${sol}`);
} catch (error) {
console.error('Error fetching balance:', error);
}
}
checkBalance();
```
```typescript Kit theme={"system"}
import { address, createSolanaRpc } from "@solana/kit";
const rpc_url = "https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY";
const rpc = createSolanaRpc(rpc_url);
const publicKey = address("83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri");
const balance = await rpc.getBalance(publicKey).send();
console.log("Account Balance:", balance);
```
```rust Rust theme={"system"}
use anyhow::Result;
use solana_client::nonblocking::rpc_client::RpcClient;
use solana_sdk::{
commitment_config::CommitmentConfig, native_token::LAMPORTS_PER_SOL, pubkey::Pubkey,
};
use std::str::FromStr;
#[tokio::main]
async fn main() -> Result<()> {
let client = RpcClient::new_with_commitment(
String::from("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY"),
CommitmentConfig::confirmed(),
);
let pubkey = Pubkey::from_str("83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri")?;
let balance = client.get_balance(&pubkey).await?;
println!("{:#?} SOL", balance / LAMPORTS_PER_SOL);
Ok(())
}
```
## Dicas para Desenvolvedores
* **Simplicidade para Saldo SOL:** Se você precisa apenas do saldo SOL de uma conta e nenhum outro dado on-chain (como proprietário, dados ou status executável), `getBalance` é mais eficiente do que `getAccountInfo` pois busca menos dados.
* **Contas Inexistentes:** Se uma conta não existe on-chain (nunca foi inicializada ou teve SOL), `getBalance` retornará `0`. Esta pode ser uma maneira rápida de verificar a existência da conta se você só se importa com seu saldo SOL.
* **Lamports vs. SOL:** Lembre-se de que o saldo é retornado em lamports. Você precisará dividir por `LAMPORTS_PER_SOL` (1.000.000.000) para convertê-lo para SOL.
* **Níveis de Compromisso:** A escolha de `commitment` pode afetar a rapidez com que você obtém o saldo e quão confirmado esse saldo está. Para a maioria dos propósitos de exibição em UI, `confirmed` oferece um bom equilíbrio. Para transações financeiras críticas, `finalized` fornece a maior garantia. Veja [Níveis de Compromisso do Solana](https://www.helius.dev/blog/solana-commitment-levels) para informações detalhadas.
* **Agrupamento com `getMultipleAccounts`:** Enquanto `getBalance` é para uma única conta, se você precisar de saldos para muitas contas, usar `getMultipleAccounts` e então extrair o saldo lamport das informações de cada conta pode ser mais eficiente do que muitas chamadas individuais `getBalance`.
## Métodos Relacionados
Obtenha detalhes completos da conta, incluindo dados, proprietário e status executável
Busque várias contas em uma única solicitação