Hooks

React hooks for interacting with smart wallets, reading state, and submitting transactions.

All hooks must be called inside a Provider component. They access shared wallet state and return reactive values that update automatically.

Hooks by Category

Session & Authentication

Hook	Description
`useSession`	Raw store selector for session state.
`useAccountSession`	Returns the current session object or `null`. Recommended for most use cases.
`useLoadingStatus`	Returns `{ isSessionLoading, sessionStatus }` for loading indicators.
`useAddress`	Returns the connected wallet address.
`useLogout`	Returns `{ logout }` function to end the session.
`useHydrated`	Returns `true` once the session has been restored from storage.
`useRecoveryUserId`	Returns the user ID used for key recovery.
`useHasServerVault`	Returns whether the user has a server-side key vault.
`useLinkedProfiles`	Returns linked social/email profiles for the account.
`requireActiveChainId`	Non-hook helper: reads the active `chainId` from the session store synchronously or throws. Useful in event handlers.
`waitForStoreHydration`	Non-hook helper: returns a `Promise<void>` that resolves once the session store has rehydrated from storage. Useful before calling imperative APIs on page load.

Balance & Assets

Hook	Description
`useBalance`	Native wallet balance, fiat conversion, and rate info.
`useAssets`	Native balance plus tracked ERC-20 assets, with refresh.
`useTokenInfo`	`{ isLoading, tokenInfo }` for a token address.
`useTokenBalance`	`{ balance, formattedBalance, refetch }` for one ERC-20 token.
`useBlockscoutAssets`	Full token + NFT portfolio from Blockscout indexer (richer than `useAssets`).

Transactions

Hook	Description
`useSendTransaction`	Build and send a UserOperation (native, ERC-20, NFT).
`useUserOpStatus`	Poll a UserOperation hash for confirmation state.
`useTransactions`	Helper functions for reading transactions and history via viem.
`useSmartAccountTransactions`	Helper functions for reading a smart account’s UserOperations.
`useErc3643Compliance`	Check ERC-3643 compliance status for regulated tokens.

External Wallet

Hook	Description
`useWalletMode`	`{ configMode, activeMode, switchMode, isDirect }`.
`useDirectWallet`	Access the direct (non-AA) external wallet.
`useSendDirectTransaction`	Send a transaction directly from the external wallet.
`useTransferToLinkedWallet`	Transfer assets from external wallet to the linked smart account.

UI & Utilities

Hook	Description
`useColorMode`	Get and set the current color mode (`'light'` / `'dark'`).
`useIsMobileView`	Returns `true` when the viewport is mobile-sized.
`useActiveChainId`	Returns the currently active chain ID.
`useOpenPage`	`{ open, close, isOpen }` for the built-in UI pages (`PageKey`).
`useIFrameReady`	Returns `true` when the secure MPC iframe is loaded.
`useError`	Latest SDK error message as a string.
`useNicknameResolve`	Resolve a nickname to a wallet on a chain.
`useProviderConfig`	Read and update the Provider configuration at runtime.
`looksLikeNickname`	Non-hook helper: returns `true` if a string looks like a nickname (vs. an address). Handy for input validation before calling `useNicknameResolve`.
`wagmiConfig`	Pre-built wagmi config used internally by `Provider`. Exported for apps that need to share the same wagmi instance.
`getExplorerUrl`	Non-hook helper: returns the block explorer URL for the active chain.

Quick Example


import {
  useAccountSession,
  useAddress,
  useBalance,
  useLoadingStatus,
} from '@embarkai/ui-kit'
 
function WalletInfo() {
  const session = useAccountSession()
  const address = useAddress()
  const { walletBalance, fiatBalance, fiatSymbol } = useBalance()
  const { isSessionLoading } = useLoadingStatus()
 
  if (isSessionLoading) return <p>Loading...</p>
  if (!session) return <p>Not connected</p>
 
  return (
    <div>
      <p>Address: {address}</p>
      <p>Balance: {walletBalance.formatted} {walletBalance.symbol}</p>
      <p>Value: {fiatSymbol}{fiatBalance.toFixed(2)}</p>
    </div>
  )
}

Next Steps

Session & Auth — session state, authentication, address, logout, key recovery
Balance & Assets — native balances, fiat conversion, ERC-20 tokens
Transactions — sending UserOperations, tracking status, history
External Wallet — MetaMask/WalletConnect integration, direct transactions
UI & Utilities — color mode, viewport, chain selection, error handling
Components — pre-built UI components that use these hooks internally