External Wallet

Connect and interact with external wallets (MetaMask, WalletConnect) alongside EmbarkAI smart accounts.

EmbarkAI supports two wallet modes: linked (external wallet controls a smart account) and direct (use the external wallet directly). These hooks let you manage both modes.

Import


import {
  useWalletMode,
  useDirectWallet,
  useSendDirectTransaction,
  useTransferToLinkedWallet,
} from '@embarkai/ui-kit'

useWalletMode

Returns the current wallet mode. In 'linked' mode, the external wallet is paired with an EmbarkAI smart account. In 'direct' mode, the external wallet is used as-is without account abstraction.


import { useWalletMode } from '@embarkai/ui-kit'
 
function WalletModeIndicator() {
  const mode = useWalletMode()
 
  return (
    <span>
      {mode === 'linked' ? 'Smart Account (AA)' : 'Direct Wallet'}
    </span>
  )
}

Return Value

Value	Description
`'linked'`	External wallet is linked to an EmbarkAI smart account. Transactions go through the bundler.
`'direct'`	External wallet is used directly. No account abstraction.
`null`	No external wallet connected.

useDirectWallet

Access the connected external wallet provider and address when in direct mode. Returns null if no external wallet is connected.


import { useDirectWallet } from '@embarkai/ui-kit'
 
function DirectWalletInfo() {
  const wallet = useDirectWallet()
 
  if (!wallet) return <p>No external wallet connected.</p>
 
  return (
    <div>
      <p>External address: {wallet.address}</p>
      <p>Connector: {wallet.connectorName}</p>
    </div>
  )
}

Return Value

Property	Type	Description
`address`	`0x${string}`	The external wallet address.
`connectorName`	`string`	Name of the wallet connector (e.g., `'MetaMask'`, `'WalletConnect'`).
`provider`	`EIP1193Provider`	The raw EIP-1193 provider instance.

useSendDirectTransaction

Send a transaction directly from the external wallet, bypassing account abstraction. Useful when the user needs to interact with contracts that don’t support smart accounts.


import { useSendDirectTransaction } from '@embarkai/ui-kit'
 
function DirectSend() {
  const { sendTransaction, isLoading, error, txHash } = useSendDirectTransaction()
 
  const handleSend = async () => {
    await sendTransaction({
      to: '0xRecipientAddress...',
      value: '0.01',
    })
  }
 
  return (
    <div>
      <button onClick={handleSend} disabled={isLoading}>
        {isLoading ? 'Sending...' : 'Send (Direct)'}
      </button>
      {error && <p className="error">{error}</p>}
      {txHash && <p>Tx: {txHash}</p>}
    </div>
  )
}

Return Value

Property	Type	Description
`sendTransaction`	`(params: { to: string; value: string; data?: string }) => Promise<string \| null>`	Submit a direct transaction. Returns the tx hash.
`isLoading`	`boolean`	`true` while the transaction is pending.
`error`	`string \| null`	Error message if the transaction failed.
`txHash`	`string \| null`	The transaction hash after submission.

useTransferToLinkedWallet

Transfer assets from the external wallet to the linked smart account. Only available in 'linked' mode.


import { useTransferToLinkedWallet } from '@embarkai/ui-kit'
 
function FundSmartAccount() {
  const { transfer, isLoading, error, txHash } = useTransferToLinkedWallet()
 
  const handleTransfer = async () => {
    await transfer({
      value: '0.5',
    })
  }
 
  return (
    <div>
      <button onClick={handleTransfer} disabled={isLoading}>
        {isLoading ? 'Transferring...' : 'Fund Smart Account'}
      </button>
      {error && <p className="error">{error}</p>}
      {txHash && <p>Funded! Tx: {txHash}</p>}
    </div>
  )
}

Parameters

Parameter	Type	Required	Description
`value`	`string`	Yes	Amount of native token to transfer (human-readable).
`tokenAddress`	`0x${string}`	No	ERC-20 token address. Omit for native token.
`decimals`	`number`	No	Token decimals (required for ERC-20).

Return Value

Property	Type	Description
`transfer`	`(params) => Promise<string \| null>`	Execute the transfer. Returns the tx hash.
`isLoading`	`boolean`	`true` while the transfer is pending.
`error`	`string \| null`	Error message if the transfer failed.
`txHash`	`string \| null`	The transaction hash after submission.

Full Example


import {
  useWalletMode,
  useDirectWallet,
  useTransferToLinkedWallet,
} from '@embarkai/ui-kit'
 
function ExternalWalletPanel() {
  const mode = useWalletMode()
  const wallet = useDirectWallet()
  const { transfer, isLoading } = useTransferToLinkedWallet()
 
  if (!wallet) return <p>Connect an external wallet to use these features.</p>
 
  return (
    <div>
      <p>Mode: {mode}</p>
      <p>External: {wallet.address}</p>
      {mode === 'linked' && (
        <button
          onClick={() => transfer({ value: '0.1' })}
          disabled={isLoading}
        >
          Fund Smart Account (0.1)
        </button>
      )}
    </div>
  )
}

Next Steps

Hooks Overview — all available hooks
useSendTransaction — send transactions via account abstraction
Provider — configure external wallet connectors