> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://www.openfort.io/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

# `useEthereumEmbeddedWallet`

:::info
If using Next.js App Router, add `"use client"` at the top of the file.
:::

`useEthereumEmbeddedWallet` is your Ethereum wallet hook — it combines wallet state, connection status, and provider access with wallet management. If you're coming from wagmi, think of it as `useAccount` + `useWalletClient` + wallet CRUD in one hook. It accepts an optional `options` argument with `chainId` and `recoveryParams`. For parity, the Solana hook `useSolanaEmbeddedWallet(options?)` uses `options.cluster` (network override) and `options.recoveryParams`.

## Day-to-day properties

Properties you read on every render: address, chain, connection status, and provider.

| Property | Type | Description |
|----------|------|-------------|
| `address` | `string \| undefined` | Current wallet address (hex). |
| `chainId` | `number \| undefined` | Current chain ID. |
| `embeddedWalletId` | `string \| undefined` | Set when connected; use for connector checks (e.g. vs wagmi `connector?.id`). |
| `isConnected` | `boolean` | Whether a wallet is connected. |
| `isConnecting` | `boolean` | True while connecting or transitioning. |
| `isDisconnected` | `boolean` | True when disconnected. |
| `isReconnecting` | `boolean` | True when reconnecting after loss of connection. |
| `provider` | `OpenfortEmbeddedEthereumWalletProvider \| undefined` | EIP-1193 provider for signing. Use with viem's `custom(provider)` when not using wagmi. |

### Connected wallet state properties

The hook exposes this connection-state shape (subset of the full return type). Shared with `useSolanaEmbeddedWallet`:

```ts
export type ConnectedWalletState = {
  /** embeddedWalletId when connected. */
  embeddedWalletId?: string
  /** True when currently connected. */
  isConnected: boolean
  /** True when actively connecting or transitioning. */
  isConnecting: boolean
  /** True when disconnected. */
  isDisconnected: boolean
  /** True when reconnecting after loss of connection. */
  isReconnecting: boolean
}
```

## Wallet management operations

Operations used during onboarding or when switching wallets.

| Property | Type | Description |
|----------|------|-------------|
| `create` | `(options?) => Promise<CreateEmbeddedWalletResult>` | Create a new embedded wallet. |
| `import` | `(options) => Promise<CreateEmbeddedWalletResult>` | Import an embedded wallet from a private key. |
| `setActive` | `(options) => Promise<SetActiveEmbeddedWalletResult>` | Switch the active wallet. |
| `wallets` | `ConnectedEmbeddedEthereumWallet[]` | List of user's embedded wallets. |
| `activeWallet` | `ConnectedEmbeddedEthereumWallet \| null` | Currently active wallet. |
| `exportPrivateKey` | `(options?) => Promise<ExportPrivateKeyResult>` | Export the active wallet's private key. |
| `setRecovery` | `(options) => Promise<SetRecoveryResult>` | Change recovery method. |

## Usage

**Read address and connection status** (like `useAccount`):

```tsx
import { useEthereumEmbeddedWallet } from "@openfort/react/ethereum"

function AccountInfo() {
  const { address, chainId, isConnected } = useEthereumEmbeddedWallet()
  if (!isConnected) return <div>Not connected</div>
  return <div>{address} on chain {chainId}</div>
}
```

**Manage wallets** (create, list, switch):

```tsx
import { useEthereumEmbeddedWallet } from "@openfort/react/ethereum"

function WalletList() {
  const { wallets, activeWallet, setActive } = useEthereumEmbeddedWallet()

  const activate = async (address: `0x${string}`) => {
    const result = await setActive({ address })
    if (result.error) return console.error(result.error.shortMessage)
    if (result.needsRecovery) console.log('Recovery required')
  }

  return (
    <div>
      {wallets.map((w) => (
        <button key={w.id} onClick={() => void activate(w.address)}>
          {w.address}
        </button>
      ))}
    </div>
  )
}
```

## Return type

The hook returns `EthereumWalletState` (`EthereumWalletStateBase & WalletDerived & ConnectedWalletState`). All status variants include the actions and the derived/connected fields; the status-specific fields below vary by `status`.

```ts
type EthereumWalletState = {
  // --- Actions (all statuses) ---
  create(options?: CreateEmbeddedWalletOptions): Promise<CreateEmbeddedWalletResult>
  import(options: ImportEmbeddedWalletOptions): Promise<CreateEmbeddedWalletResult>
  wallets: ConnectedEmbeddedEthereumWallet[]
  setActive(options: SetActiveEthereumWalletOptions): Promise<SetActiveEmbeddedWalletResult>
  setRecovery(options: SetRecoveryOptions): Promise<SetRecoveryResult>
  exportPrivateKey(options?: ExportPrivateKeyOptions): Promise<ExportPrivateKeyResult>

  // --- WalletDerived ---
  isLoading: boolean
  isError: boolean
  isSuccess: boolean

  // --- ConnectedWalletState ---
  embeddedWalletId?: string
  isConnected: boolean
  isConnecting: boolean
  isDisconnected: boolean
  isReconnecting: boolean

  // --- Discriminated by status (union) ---
  status: 'disconnected' | 'fetching-wallets' | 'connecting' | 'reconnecting' | 'creating' | 'needs-recovery' | 'connected' | 'error'
  activeWallet: ConnectedEmbeddedEthereumWallet | null
  address?: `0x${string}`
  chainId?: number
  displayAddress?: string
  provider?: OpenfortEmbeddedEthereumWalletProvider
  error?: string
}
```

Status-specific shape:

* **`disconnected`** | **`fetching-wallets`** | **`creating`**: `activeWallet: null`; no `address`, `chainId`, `displayAddress`, `provider`, `error`.
* **`connecting`** | **`reconnecting`**: `activeWallet` set; `address`, `displayAddress`; `chainId` optional.
* **`needs-recovery`**: `activeWallet` set; `address`, `chainId`, `displayAddress` optional.
* **`connected`**: `activeWallet` set; `address`, `chainId`, `displayAddress`, `provider` all set.
* **`error`**: `activeWallet` set or null; `error: string`; `address`, `chainId`, `displayAddress` optional.

`ConnectedEmbeddedEthereumWallet` (items in `wallets` / `activeWallet`):

```ts
type SimpleAccount = { id: string; chainId?: number }

type ConnectedEmbeddedEthereumWallet = {
  id: string
  address: `0x${string}`
  ownerAddress?: string
  implementationType?: string
  chainType: typeof ChainTypeEnum.EVM
  walletIndex: number
  recoveryMethod?: RecoveryMethod
  getProvider(): Promise<OpenfortEmbeddedEthereumWalletProvider>
  isAvailable: boolean
  isActive: boolean
  isConnecting: boolean
  accounts: SimpleAccount[]
  connectorType?: string
  walletClientType?: string
  accountId?: string
  accountType?: AccountTypeEnum
  createdAt?: number
  salt?: string
}
```

`WalletDerived` adds `isLoading`, `isError`, `isSuccess`; `ConnectedWalletState` adds `embeddedWalletId`, `isConnected`, `isConnecting`, `isDisconnected`, `isReconnecting`.

## Hook options

```ts
export type UseEmbeddedEthereumWalletOptions = {
  chainId?: number
  recoveryParams?: RecoveryParams
}
```

## Parameters

### create

```ts
export type CreateEmbeddedWalletOptions = {
  chainId?: number
  recoveryMethod?: RecoveryMethod
  passkeyId?: string
  password?: string
  otpCode?: string
  accountType?: AccountTypeEnum
  feeSponsorshipId?: string
} & OpenfortHookOptions<CreateEmbeddedWalletResult>
```

`CreateEmbeddedWalletOptions` and `CreateEmbeddedWalletResult` are shared types from `@openfort/react`. `OpenfortHookOptions` adds `onSuccess` and `onError` callbacks. Expected SDK failures still resolve as `{ error }`.

### setActive

```ts
export type SetActiveEmbeddedWalletOptionsBase = {
  recoveryParams?: RecoveryParams
  recoveryMethod?: RecoveryMethod
  passkeyId?: string
  password?: string
  otpCode?: string
}

export type SetActiveEthereumWalletOptions = SetActiveEmbeddedWalletOptionsBase & {
  address: `0x${string}`
  chainId?: number
}
```

### setRecovery

```ts
export type SetRecoveryOptions = {
  previousRecovery: RecoveryParams
  newRecovery: RecoveryParams
}
```

## Embedded only / external wallet

`useEthereumEmbeddedWallet` is for Openfort embedded wallets only. External wallet state comes from wagmi — use `useAccount()`, `useConnect()`, and `useDisconnect()`, and check the connector (e.g. `connector?.id !== embeddedWalletId`) to detect or switch to an external wallet. Apps that want a single active account (embedded or external) or “prefer Openfort” should implement that in the app using `setActive` / `setActiveEmbeddedAddress`, wagmi’s disconnect/connect, and connector checks; the SDK does not auto-disconnect external wallets.

## Related

* [Wallet actions](https://www.openfort.io/docs/products/embedded-wallet/react/wallet/actions) — Send transactions with wagmi
* [Create wallet](https://www.openfort.io/docs/products/embedded-wallet/react/wallet/create)
* [Active wallet](https://www.openfort.io/docs/products/embedded-wallet/react/wallet/active-wallet/ethereum)