Data service for Money account balances. For presentation, prefer fetchBalanceWithFallback, which selects between the Money Account API and on-chain Multicall3 RPC according to the moneyAccountBalanceSource remote feature flag.

Also provides lower-level RPC helpers (mUSD / vmUSD / exchange rate), plus vault APY from Veda's REST API.

const result = await service.fetchBalanceWithFallback(accountAddress);
// {
//   musdBalance, vmusdValueInMusd, totalBalance,
//   source: 'api' | 'rpc',
//   usedFallback: boolean,
//   // when source === 'api':
//   asOfBlock?, asOfTimestamp?, dataFreshness?, indexerLagSeconds?,
//   musdBalanceUpdatedAt?,
// }

Post-transaction refreshes may pass additive options so a lagging Money API result falls back to pending-tag RPC once, without changing the steady-state api policy:

await service.fetchBalanceWithFallback(accountAddress, {
  fresh: true,
  minBlock: confirmedTxBlockNumber,
});

Callers must not select a source. Provenance (source, usedFallback) is always returned so fallback is never silent. When both eligible sources fail, the service throws MoneyAccountBalanceFetchError (with causes) and never invents a zero balance.

Malformed or unavailable source balances (MoneyAccountBalanceValidationError / MoneyAccountBalanceUnavailableError) are reported via the messenger's captureException before fallback.

The facade calls MoneyAccountApiDataService:fetchPositions. Client composition must permit that action on the balance-service messenger (same pattern as NetworkController / RemoteFeatureFlagController actions).

Balance RPC and third-party vault APY currently share one BaseDataService retry / circuit-breaker policy. A Veda APY outage can affect RPC balance availability (including facade fallback). Splitting those failure domains is planned before production reliance on the facade. Source equivalence between Money API and RPC totals is also not yet proven — keep the default rpc policy until shadow comparison and rollout gates from the ADR are met.

yarn add @metamask/money-account-balance-service

or

npm install @metamask/money-account-balance-service

This package is part of a monorepo. Instructions for contributing can be found in the monorepo README.