Balances & token resolution - Inco Docs

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.

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

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