> ## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.