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


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.


<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',
    },
    social: {
      enabled: true,
      providers: [
        // Configured automatically by default
      ],
    },
    network: {
      chainId: 994873017,  // Lumia Mainnet
      forceChain: false,
    },
    preferedColorMode: 'dark',
  }}
>
  {children}
</Provider>

`callbacks`

Type: CallbacksConfig

Event callbacks for wallet lifecycle events.


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:

Section	Description
`passkey`	Configure passkey (WebAuthn) authentication
`email`	Configure email-based authentication
`social`	Configure social login providers (Google, Telegram, etc.)
`wallet`	Configure external wallet connection (RainbowKit/WalletConnect)
`network`	Set default chain and force-chain behavior
`ui`	UI customization options
`services`	Override service URLs (advanced)
`features`	Feature flags (e.g., `mpcSecurity`)
`translations`	Custom i18n translations
`watchTokens`	Custom ERC-20 tokens to track per chain
`kyc`	KYC integration settings
`preferedColorMode`	`'light'`, `'dark'`, or omit for auto

External Wallet Mode

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


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

Mode	Description
`linked`	External wallet is linked to a smart account (account abstraction). Default.
`direct`	External wallet signs transactions directly (no AA).
`both`	User chooses between linked and direct mode.

Lifecycle

When the Provider mounts:

Config merge — initialConfig is deep-merged with defaults.
Iframe initialization — A secure iframe is loaded for MPC key operations (DKG, signing).
Session hydration — Previous session is restored from localStorage if available.
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 { updateConfig, updateCallbacks } = useProviderConfig()
 
  const switchToMainnet = () => {
    updateConfig({
      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>
  )
}