Wallet Data
Wallet Data

Read wallet state with user permission.

Access balances, transactions, and account info through permission-gated APIs. Users see a permission dialog and can revoke at any time.

Request permissions

JavaScript 
const { granted, denied } = await window.fire.requestPermissions([
  'balances:read',
  'transactions:read',
  'account:read',
  'subaddresses:read'
]);

Available scopes

Scope Description Method it unlocks
balances:read Token balances getBalances()
transactions:read Transaction history getTransactions()
account:read Account info and address getAccountInfo()
subaddresses:read Subaddress list getSubaddresses()

Read methods

JavaScript 
// Check what's currently granted
const permissions = await window.fire.getPermissions();

// Get balances (requires balances:read)
const balances = await window.fire.getBalances();
// → { 0: "1000000000000", 1: "5000000" }  (token ID → smallest unit)

// Get transactions (requires transactions:read)
const txs = await window.fire.getTransactions({ limit: 20, offset: 0 });

// Get account info (requires account:read)
const account = await window.fire.getAccountInfo();
// → { address: "3Fhv7x..." }

// Get subaddresses (requires subaddresses:read)
const subaddresses = await window.fire.getSubaddresses();

Permission revocation

Users can revoke permissions at any time from the wallet UI. Listen for revocations.

JavaScript 
const unsubscribe = window.fire.onPermissionRevoked((revokedScopes) => {
  console.log('Revoked:', revokedScopes);
  // e.g. ['balances:read', 'transactions:read']
});

// Stop listening
unsubscribe();

React hook: useFireWallet()

A React hook that manages wallet detection, connection state, and payment event subscriptions. Polls for window.fire on mount and exposes a reactive state object.

React / TypeScript 
import { useFireWallet } from '@fire/shared';

function WalletStatus() {
  const { installed, connected, address, state } = useFireWallet();

  if (!installed) return <p>Install Fire Wallet to continue</p>;
  if (state === 'locked') return <p>Unlock your wallet</p>;
  if (!connected) return <p>Connecting...</p>;

  return <p>Connected: {address}</p>;
}

Return value

Field Type Description
installed boolean true when the Fire Wallet extension is detected
connected boolean true when the wallet is connected and ready
address string | null The wallet's MobileCoin b58 address
state FireWalletState One of locked, syncing, ready, or unavailable

Payment event subscription

The hook also provides subscribeToPaymentUpdate() to listen for fire-payment-update DOM events in a React-safe way.

React / TypeScript 
const { subscribeToPaymentUpdate } = useFireWallet();

useEffect(() => {
  const unsubscribe = subscribeToPaymentUpdate((update) => {
    if (update.status === 'confirmed') {
      // Payment settled on-chain
    }
  });
  return unsubscribe;
}, []);

React hook: useFirePayment()

A React hook that manages the full payment lifecycle as a state machine. Handles requesting payment, tracking status transitions, timeouts, and cleanup.

React / TypeScript 
import { useFirePayment } from '@fire/shared';

function PayButton() {
  const { phase, requestPayment, txId, error } = useFirePayment({
    recipientB58: '3Fhv7x...',
    amount: '1000000',
    tokenId: 1,
    memo: 'Invoice INV-067',
    merchantRef: 'inv-067'
  });

  if (phase === 'confirmed') return <p>Paid. TX: {txId}</p>;
  if (phase === 'failed') return <p>Error: {error}</p>;

  return (
    <button
      onClick={requestPayment}
      disabled={phase !== 'idle'}
    >
      {phase === 'idle' && 'Pay $1.00'}
      {phase === 'requesting' && 'Opening wallet...'}
      {phase === 'confirming' && 'Waiting for confirmation...'}
    </button>
  );
}

Payment phases

Flow 
idle → requesting → confirming → confirmed
  │         │            │
  │         ▼            ▼
  │      rejected      failed
  │         │            │
  └─────────┴────────────┘
          (resets to idle)
Phase Meaning
idle Ready to initiate a payment
requesting Payment intent sent, waiting for wallet to open
confirming User approved, transaction submitted to network
confirmed Transaction settled on-chain. txId is available.
rejected User declined in the wallet UI. Resets to idle.
failed Transaction failed. error has the reason. Resets to idle.

Options

Field Type Description
recipientB58 string MobileCoin b58 address (or use resolveUrl)
amount string Amount in smallest unit
tokenId number 0 = MOB, 1 = eUSD
memo string Payment memo shown to the user
merchantRef string Your reference for correlating events
resolveUrl string Resolve endpoint (alternative to recipientB58)
intentToken string Token for your resolve endpoint
timeoutMs number Timeout in ms (default: 120000 — 2 minutes)

Return value

Field Type Description
phase FirePaymentPhase Current phase of the payment lifecycle
requestPayment () => void Call to initiate the payment
txId string | null Transaction ID, set when phase is confirmed
merchantRef string The merchant reference echoed back
error string | null Error message when phase is failed
reset () => void Manually reset to idle

React hook: useFire()

A typed React hook for the MobileCoin provider. Used internally by the Fire Swap Page.

React / TypeScript 
import { useFire, formatMob, formatEusd } from './use-fire';

function SwapWidget() {
  const {
    wallet,       // { installed, connected, address, state, balance }
    loading,      // true while detecting extension
    connect,      // () => Promise — connect to wallet
    getQuotes,    // (fromToken: 'MOB' | 'eUSD') => Promise<SwapQuote>
    requestSwap,  // (fromToken, amount) => Promise<{ tx_hash, status }>
    createOffer,  // (params) => Promise<{ offer_id }>
    cancelOffer,  // (offerId) => Promise<{ success }>
    getOffers,    // () => Promise<{ offers: Offer[] }>
  } = useFire();

  if (loading) return <p>Detecting wallet...</p>;
  if (!wallet.installed) return <p>Install Fire Wallet</p>;
  if (!wallet.connected) return <button onClick={connect}>Connect</button>;

  return (
    <div>
      <p>Address: {wallet.address}</p>
      <p>Balance: {formatMob(wallet.balance)} MOB</p>
      <p>State: {wallet.state}</p>
    </div>
  );
}

Wallet state shape

TypeScript 
interface WalletState {
  installed: boolean;
  connected: boolean;
  address: string | null;
  state: 'locked' | 'syncing' | 'ready' | 'unavailable';
  balance: string;  // picoMOB
}

Format helpers

TypeScript 
formatMob('1000000000000')  // → '1.0000'
formatEusd('1000000')       // → '1.00'

Swap quote shape

TypeScript 
interface SwapQuote {
  rate: number;
  depth: string;
  quoteCount: number;
  online: boolean;
}
← MobileCoin Reference →