> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitflare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# getBalance

> 返回提供的公钥对应账户的余额

## 参数

<ParamField query="pubkey" type="string" required>
  要查询的账户公钥（base-58 编码字符串）
</ParamField>

<ParamField query="config" type="object" optional>
  包含以下可选字段的配置对象：

  <Expandable title="config fields">
    <ParamField query="commitment" type="string" optional>
      使用的 commitment 级别：

      * `processed`：最新区块（未确认）
      * `confirmed`：超级多数确认
      * `finalized`：超级多数最终确认
    </ParamField>

    <ParamField query="minContextSlot" type="number" optional>
      请求可被评估的最小 slot
    </ParamField>
  </Expandable>
</ParamField>

## 响应

<ResponseField name="result" type="object">
  <Expandable title="result fields">
    <ResponseField name="context" type="object">
      <ResponseField name="slot" type="number">
        处理请求时的 slot
      </ResponseField>
    </ResponseField>

    <ResponseField name="value" type="number">
      分配给此账户的 lamports 数量
    </ResponseField>
  </Expandable>
</ResponseField>

## 代码示例

### 基本请求

```bash theme={null}
curl https://fra.rpc.orbitflare.com?api_key=YOUR-API-KEY -X POST -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBalance",
  "params": [
    "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri"
  ]
}'
```

### 带 Commitment 的请求

```bash theme={null}
curl https://fra.rpc.orbitflare.com?api_key=YOUR-API-KEY -X POST -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getBalance",
  "params": [
    "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri",
    {
      "commitment": "finalized"
    }
  ]
}'
```

### 使用 web3.js

```typescript theme={null}
import { Connection, PublicKey } from '@solana/web3.js';

const connection = new Connection('https://fra.rpc.orbitflare.com?api_key=YOUR-API-KEY');
const publicKey = new PublicKey('83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri');

const balance = await connection.getBalance(
  publicKey,
  'confirmed'
);

console.log(`Balance: ${balance / 1e9} SOL`);
```

## 注意事项

1. 余额以 lamports 返回（1 SOL = 1,000,000,000 lamports）
2. 对于新账户，余额为 0
3. 余额包括所有 SOL 代币，包括委托用于质押的代币
4. 响应是即时的，因为它从当前状态读取

## 最佳实践

1. 根据需求使用适当的 commitment 级别：
   * `processed` 用于 UI 更新
   * `confirmed` 用于大多数操作
   * `finalized` 用于关键操作
2. 向用户显示时，将 lamports 除以 1e9 转换为 SOL
3. 如果需要更多账户详情，请考虑使用 `getAccountInfo`

## 常见错误

| 错误码    | 消息                                       | 解决方案             |
| ------ | ---------------------------------------- | ---------------- |
| -32602 | Invalid param: WrongSize                 | 验证公钥是否有效         |
| -32602 | Invalid param: not base58 encoded string | 确保公钥是 base58 编码的 |
| -32007 | Account not found                        | 账户不存在（余额将为 0）    |