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

# Wallet RPC: Check XFG Balances and Node Status

> Use getBalance and getStatus to retrieve available balance, locked amounts, deposit balances, and wallet sync status from walletd.

Before sending transactions or creating deposits, you need to know your spendable balance and confirm that the wallet is fully synced with the chain. The `getBalance` method provides a breakdown of available, locked, and deposit-related funds for any address in your wallet. The `getStatus` method gives you the wallet's sync state, peer count, and internal counters — use it to verify that `walletd` is up to date before relying on balance data. All calls go to `POST http://127.0.0.1:8070/json_rpc`.

<Note>
  All balance values are in **atomic units**. Divide by `10,000,000` to convert to XFG. For example, `10000000` atomic units = `1.0000000 XFG`.
</Note>

***

## getBalance

Returns the balance breakdown for a specific address, or the aggregate balance across all addresses in the wallet if `address` is omitted.

### Request

<ParamField body="params.address" type="string">
  A specific Fuego address to query. Omit this field to get the combined balance across all addresses in the wallet.
</ParamField>

<CodeGroup>
  ```bash curl (single address) theme={null}
  curl -s http://127.0.0.1:8070/json_rpc \
    -H 'Content-Type: application/json' \
    -d '{
      "jsonrpc": "2.0",
      "method": "getBalance",
      "params": {
        "address": "fireXfGYourAddress..."
      },
      "id": "1"
    }'
  ```

  ```bash curl (all addresses) theme={null}
  curl -s http://127.0.0.1:8070/json_rpc \
    -H 'Content-Type: application/json' \
    -d '{
      "jsonrpc": "2.0",
      "method": "getBalance",
      "params": {},
      "id": "1"
    }'
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "availableBalance": 50000000000,
    "lockedAmount": 10000000000,
    "lockedDepositBalance": 80000000000,
    "unlockedDepositBalance": 8000000000
  }
}
```

<ResponseField name="availableBalance" type="integer" required>
  Funds that are confirmed and immediately spendable. In atomic units.

  **Example:** `50000000000` = 5,000.0000000 XFG
</ResponseField>

<ResponseField name="lockedAmount" type="integer" required>
  Funds that are confirmed on chain but temporarily unspendable — typically outputs from recent transactions that have not yet reached the required 10-block confirmation depth. In atomic units.
</ResponseField>

<ResponseField name="lockedDepositBalance" type="integer" required>
  The total principal amount of XFG currently locked in active time deposits that have not yet matured. These funds cannot be accessed until the deposit term completes. In atomic units.

  **Example:** `80000000000` = 8,000.0000000 XFG locked in one or more deposits.
</ResponseField>

<ResponseField name="unlockedDepositBalance" type="integer" required>
  The total value (principal + interest) of matured deposits that can now be withdrawn via `withdrawDeposit`. In atomic units.

  **Example:** `8000000000` = 800.0000000 XFG ready to withdraw.
</ResponseField>

### Understanding locked vs. unlocked deposits

`lockedDepositBalance` holds XFG that is currently locked inside active deposits — these are funds committed to a time-lock term (currently 16,440 blocks, approximately 3 months). You cannot spend them until the term ends.

`unlockedDepositBalance` represents deposits that have completed their term. The wallet has scanned the chain and found these deposits are past their `unlockHeight`. You can retrieve these funds — principal plus accrued interest — by calling `withdrawDeposit` with the corresponding `depositId`.

***

## getStatus

Returns the wallet's current synchronization state and internal statistics. Always check `blockCount` vs `knownBlockCount` to verify the wallet is synced before reading balance data.

### Request

<CodeGroup>
  ```bash curl theme={null}
  curl -s http://127.0.0.1:8070/json_rpc \
    -H 'Content-Type: application/json' \
    -d '{
      "jsonrpc": "2.0",
      "method": "getStatus",
      "params": {},
      "id": "1"
    }'
  ```

  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "getStatus",
    "params": {},
    "id": "1"
  }
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "blockCount": 900000,
    "knownBlockCount": 900000,
    "lastBlockHash": "a1b2c3d4e5f6...",
    "peerCount": 8,
    "depositCount": 3,
    "transactionCount": 142,
    "addressCount": 2
  }
}
```

<ResponseField name="blockCount" type="integer" required>
  The height the wallet has synced up to. When `blockCount` equals `knownBlockCount`, the wallet is fully synchronized and balance data is current.
</ResponseField>

<ResponseField name="knownBlockCount" type="integer" required>
  The highest block height the wallet is aware of from its connected daemon. If `knownBlockCount` is greater than `blockCount`, the wallet is still syncing.
</ResponseField>

<ResponseField name="lastBlockHash" type="string" required>
  Hash of the most recently processed block. Use this to confirm chain continuity across calls.
</ResponseField>

<ResponseField name="peerCount" type="integer" required>
  Number of peers the underlying daemon connection sees. A value of `0` means the node may be offline or not connected.
</ResponseField>

<ResponseField name="depositCount" type="integer" required>
  Total number of deposit records (both active and matured) tracked by this wallet.
</ResponseField>

<ResponseField name="transactionCount" type="integer" required>
  Total number of transactions (sent and received) tracked by this wallet.
</ResponseField>

<ResponseField name="addressCount" type="integer" required>
  Number of addresses currently managed by the wallet service.
</ResponseField>