Token balances and USD values
Keep token amounts precise, separate checking funds and show USD estimates without hiding missing prices.
Keep balances in token units#
For each asset, the balance is the sum of recovered unspent notes. Its contract address and decimals define the units. Use integer strings or bigint for selecting inputs, proving and reconciling transactions. Format decimal and USD values when displaying them.
A symbol alone cannot identify an asset. Two tokens with the same symbol can have different contracts, policies and redemption rules. Read the deployment's asset metadata and code checks, then use that token's decimals. In the app model, the zero address identifies native ETH. WETH uses its own contract address and remains a separate asset.
// USDC has 6 decimals in the reviewed asset metadata.
const amountAtomic = 12_345_678n;
const unit = 10n ** 6n;
const whole = amountAtomic / unit;
const fraction = (amountAtomic % unit).toString().padStart(6, '0');
const tokenText = `${whole}.${fraction} USDC`;
// Keep amountAtomic for transaction logic; tokenText is display only.Separate available and checking funds#
The app shows total, available and checking funds. A known note can still be waiting for deposit age, source-policy coverage or settlement. Checking funds count once in the total, but cannot yet be spent. Also respect the inputs reserved for saved operations when you choose a new spend.
A price update changes the USD total without changing token quantities. Finishing a check makes a note available without changing total holdings. Tell the user which happened. An excluded-source deposit needs its documented exit flow; knowing its amount does not make it spendable.
Where USD estimates come from#
The display assigns $1 to configured dollar-denominated symbols such as USDC. For ETH and WETH, it reads the configured Chainlink USD feed when that chain has a known feed entry. It rejects zero, negative or nonfinite prices, invalid timestamps and rounds older than two days. Completed display prices are cached for one minute.
On a chain without a configured feed, the client can use an eligible USD/WETH swap pair for a spot-price fallback. It will not replace a missing known Chainlink feed with a test pair's price. Yield shares can use convertToAssets when the underlying asset has a price. If the share-rate read fails, that share may remain unpriced.
Show missing prices as missing#
If a positive holding has no valid price, the aggregate USD total is unavailable. The token amount still appears. Otherwise a partial total could hide real money. A zero account with valid reads can show $0; a failed price or unreadable balance must have a different state.
Apply this rule in your dashboard: add USD values only when every positive holding included in the total has a price. Show the token or feed that needs attention and let the user refresh. Keep unknown shares in the asset list, preserve their atomic balance and avoid presenting the stablecoin subtotal as the whole account.
Name the asset the recipient will receive#
The interface can group ETH-family holdings for display. Transactions still use the selected native or wrapped asset and a supported route. Withdrawing WETH pays WETH unless the route unwraps it. An ETH-equivalent total cannot combine different assets into one spend on its own.
Earn shares, Term shares and ticket series are separate tokens with their own decimals and redemption rules. Sending shares gives the recipient shares. Show the venue and token address when needed, and explain how to redeem them, any liquidity requirement and the claim window before approval.
If the balance looks wrong#
Refresh the scan and check your Pool and earlier keys. Look at deposit status, pending actions and reserved inputs. A public action may have run before its settlement note is appended. A payment arriving after key rotation can belong to an earlier generation and need recovery or a move to the new key.
If only the USD value is missing, check price reads without changing token quantities. Relay fees use the published fee policy; swaps use the execution minimum you approved. Neither uses the dashboard's live display price. Show holdings, price availability and operation status separately.