payToken.balanceUsd is a one-time snapshot and can read 0 while the wallet is funded

[abretonc7s]

We hit this in Perps and fixed it on our side. The same pattern shows up in Predict and in a couple of shared confirmations hooks, so flagging it rather than sitting on it.

What we saw

User picks ETH as the payment method for a trade. The token picker lists it at $9.37. The trade screen then tells them they can't afford a $10 order at 2x leverage — where the margin required is $5.01.

Probing both balance sources on device at the same moment:

snapshot balanceUsd: "0"                     <- what the trade screen read
live balanceUsd:     "9.3670768275998875…"   <- what the picker showed
symbol: ETH · chainId: 0xa4b1

Why

updatePaymentToken → getPaymentToken → getTokenBalance computes balanceUsd once, when the token is selected, and stores it on transactionData.paymentToken. It's never recomputed. If the balance hasn't been polled yet — or the balance call fails — it stays frozen at 0 for the life of that selection.

usePayTokenAccountBalance already exists for exactly this, and its comment says so:

payToken.balanceUsd is a one-time snapshot that can be stale (race with AccountTracker polling). Read from the same reactive asset source the token selector uses so the balance stays in sync.

The picker's preferred-token row uses it. Most other call sites don't.

Other places reading the snapshot

We have not reproduced any of these — it's from reading the code after finding our own. They may well be fine in your flows. Worth a look:

Where	What it feeds	Possible impact
useTransactionCustomAmount.ts:574 (useTokenBalance)	Max / percentage in the custom-amount keypad	Max could produce $0
usePredictBuyAvailableBalance.ts:16	"Available: $X" on Predict buy	Could show $0.00 while funded — looked display-only to us, not gating the order
useDepositPrefillAmount.ts:128	Deposit prefill (!balanceUsd short-circuits)	Prefill may silently not happen
usePayWithSelectedToken.ts:47	Selected-token row in the pay-with sheet	Selected row and preferred row could disagree in the same sheet

That last one is what made us think this is systemic rather than a one-off: someone already hit the race, wrote the hook to fix the preferred row, and the other call sites were never migrated.

Repro (Perps, but the shape should transfer)

1. Wallet with a small non-zero token balance on a chain that isn't actively polled yet.
2. Open a flow with "Pay with", switch from the default to that token.
3. Read payToken.balanceUsd vs usePayTokenAccountBalance() in the same render.

The window is timing-dependent — it reproduces reliably right after switching payment method, before the balance lands. Anything that caches or fails the balance read makes it stick.

What we did in Perps

Swapped payToken.balanceUsd for usePayTokenAccountBalance(), and collapsed the screen down to a single balance source so the affordability banner couldn't contradict the slider and validation. Fix is going out with the Perps 8.8.0 pay-with-token work.

Suggestion

The per-consumer swap works but doesn't scale — every new call site has to independently know not to trust a field that looks authoritative. The durable fix is probably in @metamask/transaction-pay-controller: either make balanceUsd reactive, or drop it from the payload so consumers can't read a stale number at all.

Happy to help with the mobile-side migration if useful.

cc @MetaMask/confirmations @MetaMask/predict

[metamask-ci]

Triage Agent -- Classification

Severity: Sev2-normal (confidence: 0.82) ⚠️ Advisory

The bug causes a stale balance snapshot to show insufficient funds when the user actually has funds, blocking the user from completing a transaction flow (Perps/Predict confirmations). However, it only manifests after switching payment tokens and likely affects a subset of users on specific chains. A workaround may exist (switching back and forth, or waiting for polling to catch up). It does not cause fund loss or a crash, but it does block a flow with a misleading error banner.
Not auto-applied -- confidence below threshold.

Size: size-M (confidence: 0.75) ⚠️ Advisory

The fix likely involves ensuring that when the payment token is switched, the balance is re-fetched reactively rather than relying on a one-time snapshot. This probably touches the TransactionPayController (or equivalent), the hook that provides payToken.balanceUsd, and possibly the AccountTrackerController polling logic for the new token's chain. Multiple files across controller and UI layers, but the scope is well-defined.
Not auto-applied -- confidence below threshold.

Team: team-confirmations ✅

Matched via CODEOWNERS: @MetaMask/confirmations

---

Root Cause Analysis

Affected component: TransactionPayController / payment token balance resolution

When the user switches the payment token in a 'Pay with' selector, the transactionData.paymentToken object is updated with a new token reference, but its balanceUsd field is populated from a snapshot taken at the time the token list was initially loaded or when the transaction data was first constructed. If the new token's chain has not been actively polled by AccountTrackerController, the cached balance may be stale or zero. The reactive hook usePayTokenAccountBalance() correctly fetches/subscribes to the live balance, but the payToken.balanceUsd field used by affordability checks and UI banners is not re-derived from the live source after the switch. This creates a divergence: the hook shows the real balance, but the controller-level snapshot remains at 0, causing the insufficient funds banner to appear incorrectly.

Evidence:

• Reporter observes payToken.balanceUsd = 0 while usePayTokenAccountBalance() returns a non-zero funded amount in the same render
• Issue manifests specifically after switching payment method, suggesting the snapshot is taken once and not refreshed
• Chains not actively polled are more likely to have stale/zero cached balances in AccountTrackerController
• The bug is described as a 'one-time snapshot rather than a reactive value'

Suggested Fix

Confidence: medium: likely but needs investigation — no direct code context was provided, so the exact file paths and function names are inferred from the issue description and controller names. The pattern (stale snapshot vs. reactive hook) is a common class of bug in state management.

Ensure that when the payment token is switched, the balanceUsd on the transactionData.paymentToken object is either (a) re-fetched from AccountTrackerController with a forced poll for the new token's chain, or (b) the affordability check and UI banner derive their balance from the same reactive source as usePayTokenAccountBalance() rather than from the snapshot field.

Target files: @metamask/transaction-pay-controller (source files for TransactionPayController), UI component or hook that reads transactionData.paymentToken.balanceUsd for affordability checks
Target functions: setPaymentToken or equivalent method in TransactionPayController that handles payment token switching, affordability check logic that reads payToken.balanceUsd, usePayTokenAccountBalance hook

Approach:

1. In the TransactionPayController (or wherever the payment token switch is handled), add a call to AccountTrackerController to refresh/poll the balance for the newly selected token's chain and account before setting the balanceUsd field. 2. Alternatively (and more robustly), refactor the affordability check and the insufficient-funds banner to derive the balance from the same reactive state source that usePayTokenAccountBalance() uses, rather than from the static snapshot on transactionData.paymentToken.balanceUsd. 3. Add a useEffect or subscription in the confirmation UI that listens for payment token changes and triggers a balance refresh if the cached value is stale or zero. 4. Add a test case: switch payment token to a token on a chain not yet polled, verify balanceUsd updates to the correct non-zero value.

---

Confidence threshold: 0.85. Labels marked ✅ were auto-applied. Labels marked ⚠️ are advisory only (below threshold).
To re-triage, remove the ta-bot-triage label and re-apply ta-needs-triage.
⚠️ Some dimensions could not be confidently classified. An engineer should review this issue.