# `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<EmbeddedAccount>` | Create a new embedded wallet. |
| `setActive` | `(options) => Promise<void>` | Switch the active wallet. |
| `wallets` | `ConnectedEmbeddedEthereumWallet[]` | List of user's embedded wallets. |
| `activeWallet` | `ConnectedEmbeddedEthereumWallet \| null` | Currently active wallet. |
| `exportPrivateKey` | `() => Promise<string>` | Export the active wallet's private key. |
| `setRecovery` | `(options) => Promise<void>` | 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()

  return (
    <div>
      {wallets.map((w) => (
        <button key={w.id} onClick={() => setActive({ address: 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<EmbeddedAccount>
  wallets: ConnectedEmbeddedEthereumWallet[]
  setActive(options: SetActiveEthereumWalletOptions): Promise<void>
  setRecovery(options: SetRecoveryOptions): Promise<void>
  exportPrivateKey(): Promise<string>

  // --- 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 from `@openfort/react` shared types; `OpenfortHookOptions` adds `onSuccess`, `onError`, `throwOnError`.

### 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](/docs/products/embedded-wallet/react/wallet/actions) — Send transactions with wagmi
* [Create wallet](/docs/products/embedded-wallet/react/wallet/create)
* [Active wallet](/docs/products/embedded-wallet/react/wallet/active-wallet/ethereum)