Design System

Balance Detection Guard

Prevent destructive operations on funded accounts by checking balances first.

Why This Matters

A wallet UX failure allowed deleting a seed phrase without checking if the address had funds. The result: ~$10,000 in assets became permanently inaccessible because there was:

  • No balance check before the destructive action
  • No warning about assets at risk
  • No way to recover the funds

Select Address to Check

Connect your wallet to check its balances, or switch to "Custom Address" mode.

Blocking Behavior

Choose how the guard should handle non-zero balances:

Live Balance Detection (Hook)

Direct hook usage shows raw balance data:

Select or enter an address above to check balances.

Implementation

Using the Hook

import { useBalanceDetection } from './hooks/useBalanceDetection';

const {
  hasBalance,
  summary,
  isLoading
} = useBalanceDetection({
  address: walletToDelete,
});

if (hasBalance) {
  // Block the operation!
  return <BalanceWarning summary={summary} />;
}

Using the Guard Component

import { BalanceAwareGuard } from './components/BalanceAwareGuard';

<BalanceAwareGuard
  address={addressToAffect}
  blockingBehavior="require_acknowledgment"
  confirmationPhrase="I ACCEPT THE LOSS"
  onClear={() => {
    // User has acknowledged or address is empty
    proceedWithDangerousOperation();
  }}
>
  <DangerousActionButton />
</BalanceAwareGuard>

Balance Guard Checklist

  • Check SOL balance before destructive operations
  • Check all SPL token balances
  • Check for NFT holdings
  • Show total value at risk (when price data available)
  • Block by default, require explicit acknowledgment
  • Integrate with NuclearWarningDialog for acknowledgment