Skip to Content
🌐 Frontend SDKProvider Setup

Provider Setup

Wrap your app with the embarkAI Provider to enable wallet functionality.

The Provider component is the root of every embarkAI integration. It initializes the wagmi client, sets up the secure MPC iframe for key operations, manages session state, and provides configuration to all child components and hooks.

Import

import { Provider } from "@embarkai/ui-kit";

Basic Usage

import { Provider, ConnectWalletButton } from "@embarkai/ui-kit";
 
function App() {
  return (
    <Provider projectId="your-project-id">
      <ConnectWalletButton />
      {/* Your application */}
    </Provider>
  );
}

Props

import type { ReactNode } from "react";
import type { ProviderConfig, CallbacksConfig } from "@embarkai/ui-kit";
 
interface ProviderProps {
  children: ReactNode;
  projectId?: string;
  initialConfig?: Partial<ProviderConfig>;
  callbacks?: CallbacksConfig;
}

projectId

Type: string

Your project identifier from the embarkAI Dashboard . This is required for the Provider to connect to embarkAI services.

initialConfig

Type: Partial<ProviderConfig>

Optional configuration object to customize authentication methods, network settings, UI behavior, and more.

import { Provider } from "@embarkai/ui-kit";
 
function App({ children }: { children: React.ReactNode }) {
  return (
    <Provider
      projectId="your-project-id"
      initialConfig={{
        passkey: {
          enabled: true,
          showCreateButton: true,
          primaryButtonText: "Sign in with Passkey",
        },
        email: {
          enabled: true,
          placeholder: "Enter your email",
          buttonText: "Continue with Email",
          verificationTitle: "Verify your email",
        },
        network: {
          name: "Lumia Prism",
          symbol: "LUMIA",
          chainId: 994873017,
          rpcUrl: "https://mainnet-rpc.lumia.org",
          forceChain: false,
        },
        preferedColorMode: "dark",
      }}
    >
      {children}
    </Provider>
  );
}

initialConfig is deep-merged with the defaults at runtime. The prop is typed as a shallow Partial<ProviderConfig>, so a section you touch must be complete (network needs name, symbol, chainId, rpcUrl; passkey needs enabled, showCreateButton, primaryButtonText; and so on).

callbacks

Type: CallbacksConfig

Event callbacks for wallet lifecycle events.

import type { WalletReadyStatus } from "@embarkai/ui-kit";
 
interface CallbacksConfig {
  onConnecting?: (payload: {
    method: "passkey" | "email" | "social" | "wallet";
    provider?: string;
  }) => void;
 
  onConnect?: (payload: { address: `0x${string}`; session: any }) => void;
 
  onAccount?: (payload: {
    userId?: string | null;
    address?: `0x${string}` | null;
    session?: any;
    hasKeyshare?: boolean;
  }) => void;
 
  onAccountUpdate?: (payload: { providers?: Array<any> }) => void;
 
  onDisconnect?: (payload: {
    address?: `0x${string}` | null;
    userId?: string | null;
  }) => void;
 
  onError?: (payload: { error: Error; code?: string; message: string }) => void;
 
  onChainChange?: (payload: {
    chainId: number;
    previousChainId: number;
  }) => void;
 
  onWalletReady?: (status: WalletReadyStatus) => void;
}

Configuration Reference

The ProviderConfig object supports these top-level sections:

SectionDescription
passkeyConfigure passkey (WebAuthn) authentication
emailConfigure email-based authentication
socialConfigure social login providers (Google, Telegram, etc.)
walletConfigure external wallet connection (RainbowKit/WalletConnect)
networkSet default chain and force-chain behavior
uiUI customization options
servicesOverride service URLs (advanced)
featuresFeature flags (e.g., mpcSecurity)
translationsCustom i18n translations
watchTokensCustom ERC-20 tokens to track per chain
kycKYC integration settings
preferedColorMode'light', 'dark', or omit for auto

External Wallet Mode

To enable WalletConnect / RainbowKit alongside embarkAI wallets, set wallet.enabled: true:

import { Provider } from "@embarkai/ui-kit";
 
function App({ children }: { children: React.ReactNode }) {
  return (
    <Provider
      projectId="your-project-id"
      initialConfig={{
        wallet: {
          enabled: true,
          walletConnectProjectId: "your-wc-project-id",
          mode: "both", // 'linked' | 'direct' | 'both'
        },
      }}
    >
      {children}
    </Provider>
  );
}

When wallet.enabled is true, the Provider wraps children with RainbowKitProvider instead of the default WagmiProvider, enabling users to connect MetaMask, WalletConnect, and other external wallets.

ModeDescription
linkedExternal wallet is linked to a smart account (account abstraction). Default.
directExternal wallet signs transactions directly (no AA).
bothUser chooses between linked and direct mode.

Lifecycle

When the Provider mounts:

  1. Config merge — initialConfig is deep-merged with defaults.
  2. Iframe initialization — A secure iframe is loaded for MPC key operations (DKG, signing).
  3. Session hydration — Previous session is restored from localStorage if available.
  4. Chain setup — If network.forceChain is set, the active chain is locked to the configured chainId.

When the Provider unmounts, the iframe manager is destroyed and resources are cleaned up.

Programmatic Config Updates

Use the useProviderConfig hook to update configuration at runtime without causing re-renders:

import { useProviderConfig } from "@embarkai/ui-kit";
 
function Settings() {
  const { config, updateConfig } = useProviderConfig();
 
  const switchToMainnet = () => {
    updateConfig({
      network: { ...config.current.network, chainId: 994873017 },
    });
  };
 
  return <button onClick={switchToMainnet}>Switch to Mainnet</button>;
}

Full Example

import { Provider, ConnectWalletButton } from "@embarkai/ui-kit";
 
function App() {
  return (
    <Provider
      projectId={process.env.NEXT_PUBLIC_EMBARK_PROJECT_ID!}
      initialConfig={{
        passkey: { enabled: true, showCreateButton: true },
        email: { enabled: true },
        social: { enabled: true },
        network: { chainId: 2030232745 }, // Lumia Testnet
        preferedColorMode: "dark",
      }}
      callbacks={{
        onConnect: ({ address }) => {
          console.log("Connected:", address);
        },
        onError: ({ error, message }) => {
          console.error("Wallet error:", message, error);
        },
        onWalletReady: (status) => {
          console.log("Wallet ready:", status.address, status.ready);
        },
      }}
    >
      <header>
        <ConnectWalletButton />
      </header>
      <main>{/* Your app */}</main>
    </Provider>
  );
}
Last updated on
OverviewConnect Wallet