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

# Balances

> The balance triple (normal, confidential, total) plus per-wallet gas, and how decryption works for each wallet type.

Every wallet's holdings are reported as a **triple**, plus the ETH the wallet
holds for gas:

| Field          | What it is                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `normal`       | Public ERC-20 balance of the test stablecoin; what any block explorer shows.                                                          |
| `confidential` | cAROUSD (ERC-7984) balance. On-chain this is an encrypted handle; the sandbox decrypts it server-side **for custodial wallets only**. |
| `total`        | `normal + confidential` in human units, when the confidential side is known.                                                          |
| `eth`          | Sepolia ETH held by the wallet; the gas that pays for its transactions.                                                               |

Both rails are 1:1 with USD in the sandbox, so `total` reads as a dollar
figure.

## Reading balances

```bash theme={null}
# All wallets
curl -s "$BASE/balances" -H "Authorization: Bearer $KEY"

# One wallet
curl -s "$BASE/balances?walletId=$WALLET" -H "Authorization: Bearer $KEY"
```

```json theme={null}
{
  "ok": true,
  "data": {
    "balances": [
      {
        "wallet": {
          "id": "ckwlt0001…",
          "address": "0x8Ba1…BA72",
          "type": "CUSTODIAL",
          "label": "Payouts",
          "isPrimary": true,
          "createdAt": "2026-08-13T09:30:00.000Z"
        },
        "eth": { "amount": "0.05" },
        "normal": { "token": "AROUSD", "amount": "890.00" },
        "confidential": {
          "token": "cAROUSD",
          "amount": "65.00",
          "encrypted": false,
          "handle": "0x1f8e…"
        },
        "total": { "amount": "955.00", "currency": "USD" }
      }
    ]
  }
}
```

## Confidential balances and wallet type

The cAROUSD contract stores balances as encrypted handles. Whether AroPay can
show you the plaintext depends on who controls the key:

<Columns cols={2}>
  <Card title="Custodial wallets" icon="lock-open" iconType="duotone">
    The sandbox holds the wallet key, so it can sign the decryption request and
    return the plaintext amount. `confidential.amount` is a decimal string and
    `encrypted` is `false`.
  </Card>

  <Card title="External wallets" icon="lock" iconType="duotone">
    The sandbox cannot decrypt a balance it doesn't own. `confidential.amount`
    is `null`, `encrypted` is `true`, and only the raw `handle` is reported;
    `total.amount` is `null` too.
  </Card>
</Columns>

<Note>
  A zero confidential balance is detectable without decryption (the handle is
  the zero handle), so brand-new wallets show `"amount": "0"` immediately.
</Note>

## Gas balances

Confidential reads are comparatively heavy; they involve FHE decryption
through the relayer. When all you need is gas visibility (dashboards, health
checks, alerts), use the dedicated endpoint instead of `/balances`:

```bash theme={null}
curl -s "$BASE/gas" -H "Authorization: Bearer $KEY"
```

```json theme={null}
{
  "ok": true,
  "data": {
    "wallets": [
      {
        "walletId": "ckwlt0001…",
        "address": "0x8Ba1…BA72",
        "label": "Payouts",
        "type": "CUSTODIAL",
        "isPrimary": true,
        "eth": "0.05",
        "wei": "50000000000000000"
      }
    ],
    "total": "0.05"
  }
}
```

`GET /gas` performs no token or FHE reads, making it **safe to poll**; it's
what backs the dashboard's gas indicator and Gas Station page. If a wallet's
RPC read fails, its balance is reported as zero rather than failing the whole
request.

<Tip>
  You rarely need to manage gas yourself: [faucet funding](/guides/fund-a-wallet)
  tops up ETH automatically alongside stablecoin.
</Tip>

## Amount format

Everywhere in the API, amounts are **decimal strings in human units**:
`"125.50"` means 125.5 tokens (or ETH). You never deal in wei or base units,
with one exception: `GET /gas` also returns a `wei` string for precision-
sensitive tooling.