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

# Balances & token resolution

> Read public and confidential balances without losing precision.

## Public and confidential balances

| Method               | Arguments               | Result                           | Notes                                                                                                                      |
| -------------------- | ----------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `publicBalanceExact` | `{ token }`             | `ExactBalance`                   | Public ERC-20 balance of wallet owner; no signature.                                                                       |
| `publicBalanceOf`    | `{ token }`             | `number`                         | Display compatibility; may lose precision.                                                                                 |
| `publicBalances`     | `{ tokens: Address[] }` | `Record<Address, number>`        | Batched public balances; deduplicates token addresses; any failed row rejects.                                             |
| `balanceExact`       | `{ token }`             | `ExactBalance`                   | Confidential balance; may request a session signature.                                                                     |
| `balanceOf`          | `{ token }`             | `number`                         | Display compatibility; failed/pending reads throw.                                                                         |
| `balances`           | `{ tokens }`            | `Record<Address, number>`        | Batch confidential values; any failed/pending row rejects.                                                                 |
| `balancesSettled`    | `{ tokens }`            | `Record<Address, BalanceResult>` | Per-token read errors and transient pending states; global session/authorization failures can still reject the whole call. |
| `preflightHandles`   | `{ tokens }`            | `TokenHandle[]`                  | Read metadata, wrapper and balance handles without decrypting or signing. Preserve input order.                            |

All methods return promises. Empty batches return empty results; record keys preserve caller casing.

```ts theme={null}
type ExactBalance = {
  raw: bigint;
  formatted: string;
  decimals: number;
};

type BalanceResult = {
  value: number | null;       // display only
  raw: bigint | null;
  formatted: string | null;
  decimals: number | null;
  pending: boolean;
  error?: CTokenError;
};

type TokenHandle = {
  token: Address;             // underlying ERC-20
  cToken: Address | null;
  handle: Hex | null;
  decimals: number;
  error?: CTokenError;
};
```

Treat failed or pending reads as unavailable, never zero. Ignore placeholder metadata on `TokenHandle` rows with `error`.

## Exact Max

```ts theme={null}
const balance = await ctoken.publicBalanceExact({ token: USDC });
if (balance.raw > 0n) {
  await ctoken.deposit({ token: USDC, amount: balance.raw });
}

const rows = await ctoken.balancesSettled({ tokens: [USDC, USDT] });
for (const [token, row] of Object.entries(rows)) {
  if (row.error) console.log(token, row.error.message);
  else if (row.pending) console.log(token, "Processing ciphertext");
  else console.log(token, row.formatted);
}
```

Use exact `raw` or `formatted` values for writes. Converting a display number back to a string can lose precision or produce unsupported exponent notation.

## Token resolution

| Method           | Arguments    | Result                     | Meaning                                                        |
| ---------------- | ------------ | -------------------------- | -------------------------------------------------------------- |
| `wrapperOf`      | `{ token }`  | `Promise<Address or null>` | Registered cToken address; null if absent.                     |
| `confidentialOf` | `{ token }`  | `Promise<Address>`         | Registered address, otherwise deterministic predicted address. |
| `underlyingOf`   | `{ cToken }` | `Promise<Address>`         | Underlying ERC-20 of a deployed cToken.                        |

Use `wrapperOf` to check registration and [ensureWrapper](/ctoken/transactions) to deploy. A predicted address does not establish deployment.

## Shared helpers and types

| Export                | Signature / purpose                                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `toBaseUnits`         | `(amount: Amount, decimals: number): bigint`; validates positive uint256 amounts.                                            |
| `fromBaseUnits`       | `(value: bigint, decimals: number): number`; display conversion only.                                                        |
| `sanitizeAmountInput` | `(raw: string): string`; currently preserves text exactly so signs/exponents cannot silently change intent.                  |
| `isRealHandle`        | Nonzero 32-byte hex check.                                                                                                   |
| `getTokenMeta`        | `(network, erc20): TokenMeta or undefined`; built-in symbol/name/icon/decimals.                                              |
| `enrichToken`         | `(network, token): TokenConfig`; fills missing metadata from the registry.                                                   |
| `DEFAULT_TOKEN_META`  | Metadata lookup keyed by network and lowercase ERC-20 address.                                                               |
| `Address`, `Hex`      | Template string types starting with `0x`; not a substitute for runtime validation.                                           |
| `Amount`              | Decimal string or bigint base units.                                                                                         |
| `NetworkName`         | `base` or `baseSepolia`.                                                                                                     |
| `DepositStep`         | `creating`, `approving`, `wrapping`.                                                                                         |
| `TokenConfig`         | Required `erc20`, `symbol`; optional `name`, `decimals`, `icon`. Tokens appear in array order; there is no numeric priority. |
| `TokenMeta`           | Optional `symbol`, `name`, `icon`, `decimals`.                                                                               |

Amounts must be positive uint256 values: no signs, whitespace, exponents, or excess nonzero fractional digits. Trailing fractional zeros are accepted. Decimals: integer 0–255; amount strings: at most 335 characters.