Core SDK

Installation

pnpm add @aurum-sdk/core

npm install @aurum-sdk/core

yarn add @aurum-sdk/core

bun add @aurum-sdk/core

Configuration Options

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

brand

Customize the look and feel of the modal.

string

Your application’s display name

string

URL to your logo image (https://... or data:image/...)

'light' | 'dark'

Color scheme for the modal

string

Hex color for buttons and accents

'none' | 'sm' | 'md' | 'lg' | 'xl'

Corner rounding for UI elements

string

Custom font family

boolean

Hides “powered by Aurum” footer

z-index for modal

'stacked' | 'grid'

Wallet button arrangement

wallets

Configure wallet providers and availability.

string

Project ID for email wallet functionality

string

Project ID for WalletConnect

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'].

telemetry

boolean

default:"true"

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

Embedded: Get your project ID at Coinbase CDPWalletConnect: Get your project ID at Reown Dashboard

Example

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.

const accounts = await aurum.rpcProvider.request({ method: 'eth_accounts' });

import { createWalletClient, custom } from 'viem';

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

import { ethers } from 'ethers';

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

import { BrowserProvider } from 'ethers';

const provider = new BrowserProvider(aurum.rpcProvider);

Show EIP-1193 Event listeners

The provider emits standard EIP-1193 events. We recommend registering them on the Aurum instance directly (see Event Listeners below) so they survive provider swaps on connect/disconnect.

  aurum.rpcProvider.on?.('connect', (info: { chainId: string }) => { ... });
  aurum.rpcProvider.on?.('accountsChanged', (accounts: string[]) => { ... });
  aurum.rpcProvider.on?.('chainChanged', (chainId: string) => { ... });
  aurum.rpcProvider.on?.('disconnect', () => { ... });

See full integration guides for Viem, Ethers v5 and Ethers v6.

`ready`

Returns boolean true once the SDK has finished initializing and restored any persisted connection. Synchronous companion to whenReady() — useful for conditional render in components.

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.

await aurum.whenReady();

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

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

`connect(walletId?: WalletId)`

Returns Promise<`0x${string}`> Opens the wallet connection modal. Optionally, pass a walletId to connect directly without showing the modal.

// 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);

For WalletId.Email and custom WalletConnect QR Code flows, see the Headless API. connect('email') will throw an error. connect('walletconnect') will open the WalletConnect modal.

Throws an error if the user closes the modal without connecting.

`disconnect()`

Returns Promise<void> Disconnects the currently connected wallet.

await aurum.disconnect();

`isConnected()`

Returns Promise<boolean> Returns whether a wallet is currently connected.

const connected = await aurum.isConnected();

`getUserInfo()`

Returns Promise<UserInfo | undefined> Returns info about the connected user, or undefined if not connected.

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

Show UserInfo type

  interface UserInfo {
    publicAddress: string;
    walletName: WalletName;
    walletId: WalletId;
    email?: string;
  }

`getChainId()`

Returns Promise<number> Returns the current chain ID.

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.

import { polygon } from 'viem/chains';

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

Throws an error if the user rejects the request

`updateBrandConfig(newConfig)`

**Returns **void Updates the brand configuration at runtime (theme, font, walletLayout, etc).

aurum.updateBrandConfig({ theme: 'light' });

`updateWalletsConfig(newConfig)`

Returns void Updates the wallets configuration at runtime. Currently only supports exclude.

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.

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.

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.

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.

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);
  }
}

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

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

import { normalizeError, UserRejectedError } from '@aurum-sdk/core';

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

API reference

UI Modes

Integrations

Installation

Configuration Options

Example

Aurum Properties

`rpcProvider`

`ready`

Aurum Methods

`whenReady()`

`connect(walletId?: WalletId)`

`disconnect()`

`isConnected()`

`getUserInfo()`

`getChainId()`

`switchChain(chainId, chain?)`

`updateBrandConfig(newConfig)`

`updateWalletsConfig(newConfig)`

Event Listeners

`on(event, listener)`

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

Errors

`normalizeError(err, context?)`

​Installation

​Configuration Options

​Example

​Aurum Properties

​rpcProvider

​ready

​Aurum Methods

​whenReady()

​connect(walletId?: WalletId)

​disconnect()

​isConnected()

​getUserInfo()

​getChainId()

​switchChain(chainId, chain?)

​updateBrandConfig(newConfig)

​updateWalletsConfig(newConfig)

​Event Listeners

​on(event, listener)

​off(event, listener) / removeListener(event, listener)

​Errors

​normalizeError(err, context?)

Installation

Configuration Options

Example

Aurum Properties

`rpcProvider`

`ready`

Aurum Methods

`whenReady()`

`connect(walletId?: WalletId)`

`disconnect()`

`isConnected()`

`getUserInfo()`

`getChainId()`

`switchChain(chainId, chain?)`

`updateBrandConfig(newConfig)`

`updateWalletsConfig(newConfig)`

Event Listeners

`on(event, listener)`

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

Errors

`normalizeError(err, context?)`