> ## 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.

# Core SDK

> API reference for Aurum Core SDK

## Installation

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

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

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

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

## Configuration Options

The `Aurum` instance accepts three configuration parameters - `brand`, `wallets`, and `telemetry`.

<Accordion title="brand" icon="palette">
  Customize the look and feel of the modal.

  <ParamField body="appName" type="string">
    Your application's display name
  </ParamField>

  <ParamField body="logo" type="string">
    URL to your logo image (`https://...` or `data:image/...`)
  </ParamField>

  <ParamField body="theme" type="'light' | 'dark'">
    Color scheme for the modal
  </ParamField>

  <ParamField body="primaryColor" type="string">
    Hex color for buttons and accents
  </ParamField>

  <ParamField body="borderRadius" type="'none' | 'sm' | 'md' | 'lg' | 'xl'">
    Corner rounding for UI elements
  </ParamField>

  <ParamField body="font" type="string">
    Custom font family
  </ParamField>

  <ParamField body="hideFooter" type="boolean">
    Hides "powered by Aurum" footer
  </ParamField>

  <ParamField body="modalZIndex" type="number">
    z-index for modal
  </ParamField>

  <ParamField body="walletLayout" type="'stacked' | 'grid'">
    Wallet button arrangement
  </ParamField>
</Accordion>

<Accordion title="wallets" icon="wallet">
  Configure wallet providers and availability.

  <ParamField body="embedded.projectId" type="string">
    Project ID for email wallet functionality
  </ParamField>

  <ParamField body="walletConnect.projectId" type="string">
    Project ID for WalletConnect
  </ParamField>

  <ParamField body="exclude" type="WalletId[] | string[]">
    Wallet IDs to hide from the connection UI. Accepts the `WalletId` enum (recommended for IDE autocomplete and refactor safety) or the equivalent string literals — e.g. `[WalletId.Email, WalletId.Phantom]` or `['email', 'phantom']`.
  </ParamField>
</Accordion>

<Accordion title="telemetry" icon="chart-line">
  <ParamField body="telemetry" default="true" type="boolean">
    Allows Aurum to log unexpected SDK errors using Sentry.io. No PII is ever collected — including email address, IP address, user location, or other identifiable information. Also applies to analytics and error tracking for Email login, Coinbase Wallet, and WalletConnect (Reown).
  </ParamField>
</Accordion>

<Info>
  **Embedded:** Get your project ID at [Coinbase CDP](https://portal.cdp.coinbase.com)

  **WalletConnect:** Get your project ID at [Reown Dashboard](https://dashboard.reown.com/)
</Info>

### Example

```typescript theme={null}
const aurum = new Aurum({
  brand: { 
    appName: 'Aurum Demo',
    theme: 'dark',
  },
  wallets: {
    embedded: { projectId: 'cdp-project-id' },
    walletConnect: { projectId: 'reown-project-id' },
  },
});
```

## Aurum Properties

### `rpcProvider`

**Returns** `AurumRpcProvider`

EIP-1193 compatible provider. Works with viem, ethers.js, and other web3 libraries.

<CodeGroup>
  ```typescript Direct Usage theme={null}
  const accounts = await aurum.rpcProvider.request({ method: 'eth_accounts' });
  ```

  ```typescript Viem theme={null}
  import { createWalletClient, custom } from 'viem';

  const walletClient = createWalletClient({
    transport: custom(aurum.rpcProvider),
  });
  ```

  ```typescript Ethers v5 theme={null}
  import { ethers } from 'ethers';

  const provider = new ethers.providers.Web3Provider(aurum.rpcProvider);
  ```

  ```typescript Ethers v6 theme={null}
  import { BrowserProvider } from 'ethers';

  const provider = new BrowserProvider(aurum.rpcProvider);
  ```
</CodeGroup>

<Expandable title="EIP-1193 Event listeners">
  The provider emits standard EIP-1193 events. We recommend registering them on the `Aurum` instance directly (see [Event Listeners](#event-listeners) below) so they survive provider swaps on connect/disconnect.

  ```typescript theme={null}
    aurum.rpcProvider.on?.('connect', (info: { chainId: string }) => { ... });
    aurum.rpcProvider.on?.('accountsChanged', (accounts: string[]) => { ... });
    aurum.rpcProvider.on?.('chainChanged', (chainId: string) => { ... });
    aurum.rpcProvider.on?.('disconnect', () => { ... });
  ```
</Expandable>

See full integration guides for [Viem](/api-reference/integrations/viem), [Ethers v5](/api-reference/integrations/ethers-v5) and [Ethers v6](/api-reference/integrations/ethers-v6).

### `ready`

**Returns** `boolean`

`true` once the SDK has finished initializing and restored any persisted connection. Synchronous companion to [`whenReady()`](#whenready) — useful for conditional render in components.

```typescript theme={null}
if (aurum.ready) {
  // safe to call rpcProvider, isConnected, getUserInfo, etc.
}
```

## Aurum Methods

### `whenReady()`

**Returns** `Promise<void>`

Waits for the SDK to finish initializing, such as restoring any previous connection after a page refresh.

```typescript theme={null}
await aurum.whenReady();

// Safe to use the provider
const balance = await aurum.rpcProvider.request({
  method: 'eth_getBalance',
  params: [address, 'latest'],
});
```

<Info>
  await `whenReady()` before making calls to the `rpcProvider` to ensure persisted connections are restored and request is routed to the correct provider.
</Info>

### `connect(walletId?: WalletId)`

**Returns** ``Promise<`0x${string}`>``

Opens the wallet connection modal. Optionally, pass a `walletId` to connect directly without showing the modal.

```typescript theme={null}
// Show modal
const address = await aurum.connect();

// Connect directly to a specific wallet
import { WalletId } from '@aurum-sdk/types';

const address = await aurum.connect(WalletId.MetaMask);
```

<Info>
  For `WalletId.Email` and custom WalletConnect QR Code flows, see the [Headless API](/api-reference/ui-modes/headless). `connect('email')` will throw an error. `connect('walletconnect')` will open the WalletConnect modal.
</Info>

<Warning>
  Throws an error if the user closes the modal without connecting.
</Warning>

### `disconnect()`

**Returns** `Promise<void>`

Disconnects the currently connected wallet.

```typescript theme={null}
await aurum.disconnect();
```

### `isConnected()`

**Returns** `Promise<boolean>`

Returns whether a wallet is currently connected.

```typescript theme={null}
const connected = await aurum.isConnected();
```

### `getUserInfo()`

**Returns** `Promise<UserInfo | undefined>`

Returns info about the connected user, or `undefined` if not connected.

```typescript theme={null}
const user = await aurum.getUserInfo();
if (user) {
  console.log(`Connected: ${user.walletName}`);
}
```

<Expandable title="UserInfo type">
  ```typescript theme={null}
    interface UserInfo {
      publicAddress: string;
      walletName: WalletName;
      walletId: WalletId;
      email?: string;
    }
  ```
</Expandable>

### `getChainId()`

**Returns** `Promise<number>`

Returns the current chain ID.

```typescript theme={null}
const chainId = await aurum.getChainId();
```

### `switchChain(chainId, chain?)`

**Returns** `Promise<void>`

Switches to a different network. If the chain isn't added to the wallet, it will prompt the user to accept the new network and switch to it.

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

await aurum.switchChain(polygon.id, polygon);
```

<Warning>
  Throws an error if the user rejects the request
</Warning>

### `updateBrandConfig(newConfig)`

\*\*Returns \*\*`void`

Updates the brand configuration at runtime (`theme`, `font`, `walletLayout`, etc).

```typescript theme={null}
aurum.updateBrandConfig({ theme: 'light' });
```

### `updateWalletsConfig(newConfig)`

**Returns** `void`

Updates the wallets configuration at runtime. Currently only supports `exclude`.

```typescript theme={null}
import { WalletId } from '@aurum-sdk/types';

aurum.updateWalletsConfig({ exclude: [WalletId.Phantom] });
```

## Event Listeners

Subscribe to EIP-1193 events directly on the `Aurum` instance. Listeners registered here **survive provider swaps** when users connect, disconnect, or switch wallets — register once and they keep firing.

```typescript theme={null}
const handleAccounts = (accounts: string[]) => {
  console.log('accounts changed:', accounts);
};

aurum.on('accountsChanged', handleAccounts);
aurum.on('chainChanged', (chainId: string) => { /* ... */ });
aurum.on('connect', (info: { chainId: string }) => { /* ... */ });
aurum.on('disconnect', () => { /* ... */ });

// Remove a listener (off and removeListener are aliases)
aurum.off('accountsChanged', handleAccounts);
```

### `on(event, listener)`

**Returns** `void`

Registers an EIP-1193 event listener. Supported events: `accountsChanged`, `chainChanged`, `connect`, `disconnect`.

### `off(event, listener)` / `removeListener(event, listener)`

**Returns** `void`

Removes a previously registered listener. The two methods are aliases — use whichever fits your style.

<Tip>
  Prefer `aurum.on()` over `aurum.rpcProvider.on()`. The provider proxy is replaced on connect/disconnect, so listeners attached to it will silently stop firing after the user reconnects.
</Tip>

## Errors

All public methods on `Aurum` throw typed errors that extend `AurumError`. Discriminate failures via `instanceof` or the stable `code` field instead of parsing message strings.

```typescript theme={null}
import {
  UserRejectedError,
  ChainSwitchRejectedError,
  WalletNotInstalledError,
  WalletNotConfiguredError,
  WalletExcludedError,
  ChainNotSupportedError,
  InvalidConfigError,
  ConnectionError,
  AdapterLoadError,
  AurumError,
} from '@aurum-sdk/core';

try {
  await aurum.connect();
} catch (err) {
  if (err instanceof UserRejectedError) {
    // user closed the modal or denied the request
  } else if (err instanceof WalletNotInstalledError) {
    console.log(`${err.walletId} is not installed`);
  } else if (err instanceof AurumError) {
    console.log(err.code, err.message);
  }
}
```

<Expandable title="Error classes and codes">
  | Class                      | `code`                  | Thrown when                                                                                                                                                                    |
  | -------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `UserRejectedError`        | `USER_REJECTED`         | User cancels a connection or signing request.                                                                                                                                  |
  | `ChainSwitchRejectedError` | `CHAIN_SWITCH_REJECTED` | User rejects a `switchChain` request.                                                                                                                                          |
  | `WalletNotInstalledError`  | `WALLET_NOT_INSTALLED`  | Direct connect to a wallet whose extension isn't installed. Carries `.walletId`.                                                                                               |
  | `WalletNotConfiguredError` | `WALLET_NOT_CONFIGURED` | Wallet selected but missing required config (e.g. `walletConnect.projectId`). Carries `.walletId`.                                                                             |
  | `WalletExcludedError`      | `WALLET_EXCLUDED`       | Direct connect to a wallet listed in `wallets.exclude`. Carries `.walletId`.                                                                                                   |
  | `ChainNotSupportedError`   | `CHAIN_NOT_SUPPORTED`   | Target chain isn't supported by the connected wallet.                                                                                                                          |
  | `InvalidConfigError`       | `INVALID_CONFIG`        | Misuse of the API — e.g. `connect('email')` instead of `emailAuthStart()`.                                                                                                     |
  | `ConnectionError`          | `CONNECTION_FAILED`     | Generic connection failure not covered above.                                                                                                                                  |
  | `AdapterLoadError`         | `ADAPTER_LOAD_FAILED`   | A wallet adapter chunk failed to load (e.g. network drop, stale chunk after redeploy). Carries `.walletId` and `.cause`. The cache evicts on failure so the next call retries. |
  | `AurumError`               | *(abstract)*            | Base class — use for catch-all branches.                                                                                                                                       |
</Expandable>

### `normalizeError(err, context?)`

**Returns** `AurumError`

Wraps an unknown thrown value into the typed hierarchy. Useful if you're catching errors from a wrapper layer where the original wallet error has already been re-thrown as a generic `Error`.

```typescript theme={null}
import { normalizeError, UserRejectedError } from '@aurum-sdk/core';

try {
  await someWrapper();
} catch (err) {
  const aurumErr = normalizeError(err, { operation: 'switchChain' });
  if (aurumErr instanceof UserRejectedError) { /* ... */ }
}
```