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

# All wallets
curl -s "$BASE/balances" -H "Authorization: Bearer $KEY"

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

{
  "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:

Custodial wallets

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.

External wallets

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.

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

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:

curl -s "$BASE/gas" -H "Authorization: Bearer $KEY"

{
  "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.

You rarely need to manage gas yourself: faucet funding tops up ETH automatically alongside stablecoin.

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.