> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aurumsdk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React Hooks

> API reference for Aurum React Hooks

The React Hooks package provides hooks for accessing user state, connecting to and disconnecting from wallets.

## Installation

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm add @aurum-sdk/core @aurum-sdk/hooks
  ```

  ```bash npm theme={null}
  npm install @aurum-sdk/core @aurum-sdk/hooks
  ```

  ```bash yarn theme={null}
  yarn add @aurum-sdk/core @aurum-sdk/hooks
  ```

  ```bash bun theme={null}
  bun add @aurum-sdk/core @aurum-sdk/hooks
  ```
</CodeGroup>

## Provider Setup

Wrap your application root in `AurumProvider` with an initialized `Aurum` instance:

```typescript theme={null}
import { Aurum } from '@aurum-sdk/core';
import { AurumProvider } from '@aurum-sdk/hooks';

const aurum = new Aurum({
  brand: { appName: 'Your App Name' },
  wallets: {
    embedded: { projectId: 'cdp-project-id' },
    walletConnect: { projectId: 'reown-project-id' },
  },
});

function App() {
  return (
    <AurumProvider aurum={aurum}>
      <YourApp />
    </AurumProvider>
  );
}
```

See [Core SDK Configuration](/api-reference/core#configuration-options) for all available `Aurum` options.

## Available Hooks

### `useAurum()`

Access the raw Aurum SDK instance for advanced use cases.

```typescript theme={null}
const { aurum, isReady } = useAurum();
```

<Expandable title="Return values">
  <ParamField body="aurum" type="Aurum">
    The Aurum SDK instance passed to `AurumProvider`.
  </ParamField>

  <ParamField body="isReady" type="boolean">
    `true` once the SDK has finished initializing and restored any persisted connection.
  </ParamField>
</Expandable>

### `useAccount()`

Access connected user information. Updates automatically when the connection state changes.

```typescript theme={null}
const {
  publicAddress,
  walletName,
  walletId,
  email,
  isConnected,
  isInitializing,
} = useAccount();
```

<Expandable title="Return values">
  <ParamField body="publicAddress" type="string | undefined">
    The connected wallet address
  </ParamField>

  <ParamField body="walletName" type="WalletName | undefined">
    Display name of the connected wallet
  </ParamField>

  <ParamField body="walletId" type="WalletId | undefined">
    Identifier of the connected wallet
  </ParamField>

  <ParamField body="email" type="string | undefined">
    User's email (only present for email wallets)
  </ParamField>

  <ParamField body="isConnected" type="boolean">
    `true` if a wallet is currently connected
  </ParamField>

  <ParamField body="isInitializing" type="boolean">
    `true` while the SDK is checking for / restoring a persisted connection
  </ParamField>
</Expandable>

### `useConnect()`

Connect to a wallet via the modal or directly by wallet ID.

```typescript theme={null}
const {
  connect,
  emailAuthStart,
  emailAuthVerify,
  getWalletConnectSession,
  isPending,
  error,
} = useConnect();

// Open wallet selection modal
await connect();

// Or connect directly to a specific wallet (skips modal)
import { WalletId } from '@aurum-sdk/types';

await connect(WalletId.MetaMask);
```

<Expandable title="Return values">
  <ParamField body="connect" type="(walletId?: WalletId) => Promise<`0x${string}`>">
    Opens the modal or connects directly if `walletId` is provided. Returns the connected address.
  </ParamField>

  <ParamField body="emailAuthStart" type="(email: string) => Promise<{ flowId: string }>">
    Starts the [headless email OTP flow](/api-reference/ui-modes/headless#email-authentication). Returns a `flowId` for `emailAuthVerify`.
  </ParamField>

  <ParamField body="emailAuthVerify" type="(flowId: string, otp: string) => Promise<{ address: string, email: string, isNewUser: boolean }>">
    Verifies the OTP and completes the email connection.
  </ParamField>

  <ParamField body="getWalletConnectSession" type="() => Promise<{ uri: string, waitForConnection: () => Promise<`0x${string}`> }>">
    Initiates a [headless WalletConnect session](/api-reference/ui-modes/headless#walletconnect-uri) for rendering your own QR code.
  </ParamField>

  <ParamField body="isPending" type="boolean">
    `true` while a connection attempt is in progress (covers all four methods above).
  </ParamField>

  <ParamField body="error" type="Error | null">
    The error if the last connection attempt failed.
  </ParamField>
</Expandable>

<Info>
  `WalletId.Email` cannot be used with `connect(walletId)` — use `emailAuthStart` / `emailAuthVerify` instead. See the [Headless API](/api-reference/ui-modes/headless) for full examples.
</Info>

<Warning>
  Do not use `useConnect()` with `<ConnectWidget>`. Instead use `useAccount()` to react to connection state changes when using the widget.
</Warning>

### `useDisconnect()`

Disconnect the current wallet.

```typescript theme={null}
const { disconnect } = useDisconnect();

await disconnect();
```

### `useChain()`

Access current chain information and switch networks.

```typescript theme={null}
import { sepolia } from 'viem/chains';

const { chainId, switchChain, error } = useChain();

await switchChain(sepolia.id, sepolia);
```

<Expandable title="Return values">
  <ParamField body="chainId" type="number | null">
    The current chain ID as a decimal number, or `null` if no wallet is connected.
  </ParamField>

  <ParamField body="switchChain" type="(chainId: number | string, chain?: Chain) => Promise<void>">
    Switches to the specified chain. Pass the chain definition to prompt the user to add it if it's not yet configured.
  </ParamField>

  <ParamField body="error" type="Error | null">
    The error if the user rejected the request.
  </ParamField>
</Expandable>

***

<CardGroup cols={2}>
  <Card title="Core SDK" icon="dice-d6" href="/api-reference/core">
    Framework-agnostic API
  </Card>

  <Card title="Headless Mode" icon="code-simple" href="/api-reference/ui-modes/headless">
    Build custom connection UIs
  </Card>
</CardGroup>