feat: useAccountStream — real-time account balance updates via Horizon SSE

[gloriaelishahabu]

Overview

Currently useAssetBalances fetches balances once on mount and exposes a manual refetch(). This issue tracks adding a useAccountStream hook that subscribes to Horizon's Server-Sent Events (SSE) stream so balances update in real time when payments are received.

What needs to be built

• New hook useAccountStream(publicKey?) in packages/ui/src/hooks/
• Subscribe to server.accounts().accountId(publicKey).stream()
• Parse incoming account record and update balance state
• Auto-unsubscribe on component unmount
• Export from barrel src/index.ts

API shape

const {
  balances,   // AssetBalanceType[]
  loading,    // boolean
  error,      // string | null
  streaming,  // boolean — true while SSE is active
  stop,       // () => void — manually close the stream
} = useAccountStream();

Example usage

import { useAccountStream } from "@stellar-pay/ui";

function LiveBalances() {
  const { balances, streaming } = useAccountStream();
  return (
    <div>
      {streaming && <span>● Live</span>}
      {balances.map(b => <div key={b.asset.code}>{b.balance}</div>)}
    </div>
  );
}

Acceptance criteria

• Balance updates within 1–2 seconds of an incoming payment
• Stream closes cleanly on unmount (no memory leaks)
• Falls back to polling if SSE connection drops

Why this matters

This is a core SDP use case — disbursement recipients need to see their balance update the moment funds arrive without manually refreshing.