createWalletKit

createWalletKit is the all-in-one convenience entry point from @xrpl-wallet-kit/client. It creates a WalletManager, a WalletModal, a WalletButton, and a WalletToast in a single call with sensible defaults.

If you need more control, use createWalletClient instead — it only creates the WalletManager.

Installation

npm install @xrpl-wallet-kit/client

Usage

import { createWalletKit } from "@xrpl-wallet-kit/client";

const { manager, modal, button, toast, openModal } = createWalletKit({
  metadata: {
    name: "My XRPL dApp",
    description: "Wallet connection for My XRPL dApp",
    url: window.location.origin,
    icons: [`${window.location.origin}/icon.png`],
  },
  wallets: "all",
  walletConnectProjectId: import.meta.env.VITE_WALLETCONNECT_PROJECT_ID,
  xamanClientId: import.meta.env.VITE_XAMAN_CLIENT_ID,
  connectButton: "#connect-btn",
});

await manager.recoverSession();

<!-- index.html -->
<button id="connect-btn"></button>

That's all you need. The connect button renders itself, the modal opens on click, toasts appear for transactions, and sessions are restored on reload.

Options

CreateWalletKitOptions

Extends all CreateWalletClientOptions (see below) with UI-specific fields.

interface CreateWalletKitOptions extends CreateWalletClientOptions {
  // Wallet modal — set to false to disable, or pass WalletUiConfig to customize
  modal?: boolean | (WalletUiConfig & { autoOpen?: boolean });

  // Connect button — CSS selector, DOM element, or button config object
  connectButton?: string | HTMLElement | WalletKitConnectButtonConfig;

  // Identity resolver for on-chain display names (XRP Domains, etc.)
  identity?: {
    resolve: WalletIdentityResolver;
    cacheMs?: number;
  };
}

interface WalletKitConnectButtonConfig {
  target?: string | HTMLElement;
  label?: string;
  icon?: false
    | { type: "default" }
    | { type: "image"; src: string; alt?: string }
    | { type: "html"; html: string; ariaLabel?: string };
  size?: "sm" | "md" | "lg";
  variant?: "default" | "pill" | "minimal" | "outline";
  showAdapterIcon?: boolean;
  showChevron?: boolean;
}

CreateWalletClientOptions

interface CreateWalletClientOptions {
  // dApp identity shown in WalletConnect/AppKit and future auth prompts
  metadata?: {
    name: string;
    description?: string;
    url?: string;
    icons?: string[];
  };

  // Legacy aliases. Prefer metadata for new integrations.
  appName?: string;
  appDescription?: string;
  appUrl?: string;
  appIcons?: string[];

  // Adapters to register — defaults to all installed adapters when "all" is used
  wallets?: "all" | WalletKitAdapterId[];

  // Provide pre-built adapter instances instead of auto-creation
  adapters?: WalletAdapter[];

  // Session storage — "localStorage" (default), "memory", or a custom StorageAdapter
  storage?: "localStorage" | "memory" | StorageAdapter;

  // WalletConnect Project ID (required for WalletConnect adapter)
  walletConnectProjectId?: string;

  // Xaman OAuth client ID (required for Xaman adapter)
  xamanClientId?: string;

  // Network config
  network?: WalletNetwork;

  // Auto-reconnect on page load (default: true)
  autoReconnect?: boolean;

  // UI config — shared theme/locale applied to modal, button, and toast
  ui?: WalletUiConfig;
}

App Metadata

Use metadata to identify your dApp to wallets. XRPL Wallet Kit forwards it to WalletConnect/AppKit and will reuse it for app-context UI such as connection loading and Sign-In with XRPL prompts.

createWalletKit({
  metadata: {
    name: "XRP Domains",
    description: "XRPL domains and wallet tools",
    url: "https://xrpdomains.xyz",
    icons: ["https://xrpdomains.xyz/icon.png"],
  },
  walletConnectProjectId: import.meta.env.VITE_WALLETCONNECT_PROJECT_ID,
});

metadata takes precedence over the older appName, appDescription, appUrl, and appIcons fields. Those aliases remain supported for existing integrations.

Return Value

const kit = createWalletKit(options);

kit.manager        // WalletManager instance
kit.modal          // WalletModal instance (undefined if modal: false)
kit.button         // WalletButton instance (undefined if no connectButton)
kit.toast          // WalletToast instance (undefined if no modal)
kit.openModal()    // () => void — open the modal programmatically
kit.closeModal()   // () => void — close the modal
kit.disconnect()   // () => void — disconnect the active wallet
kit.getSession()   // () => WalletSession | null — current session
kit.signAndSubmit  // manager.signAndSubmit (bound)
kit.signTransaction// manager.signTransaction (bound)
kit.signMessage    // manager.signMessage (bound)
kit.refreshAccount()    // force-refresh account data shown in button
kit.refreshBalance()    // force-refresh balance in button
kit.refreshIdentity()   // force-refresh identity (name/avatar) in button

Customizing the Modal

Pass a WalletUiConfig object to the modal option:

createWalletKit({
  wallets: "all",
  walletConnectProjectId: import.meta.env.VITE_WALLETCONNECT_PROJECT_ID,
  modal: {
    mode: "dark",
    themeName: "midnight",
    customTheme: { accent: "#7c3aed" },
    modal: { title: "Connect to MyApp", width: "default" },
    autoOpen: true,   // open the modal immediately on page load
  },
});

See WalletUiConfig for the full interface.

For app-wide UI settings, prefer the top-level ui option. It is shared by the modal, connect button, account panel, and toast:

createWalletKit({
  wallets: "all",
  walletConnectProjectId: import.meta.env.VITE_WALLETCONNECT_PROJECT_ID,
  connectButton: "#connect-btn",
  ui: {
    mode: "dark",
    themeName: "glass",
    customTheme: {
      accent: "#10b981",
      accentText: "#ffffff",
    },
    accountPanel: {
      showRecentTransactions: true,
      maxVisibleTransactions: 5,
    },
    connectButton: {
      icon: {
        type: "image",
        src: "/brand-wallet.svg",
        alt: "MyApp wallet",
      },
    },
    toast: true,
  },
});

Recent Transactions in the Account Panel

Recent transactions are opt-in. Enable them through the shared ui.accountPanel config when using the all-in-one kit:

const kit = createWalletKit({
  wallets: "all",
  walletConnectProjectId: import.meta.env.VITE_WALLETCONNECT_PROJECT_ID,
  connectButton: "#connect-btn",
  ui: {
    accountPanel: {
      showRecentTransactions: true,
      maxVisibleTransactions: 5,
    },
  },
});

When showRecentTransactions is enabled, manager.signAndSubmit() records submitted transactions with a hash and the account panel shows compact rows with status, shortened hash, relative time, and an explorer link. The section only appears when there are transactions for the active account/network.

For custom flows, add entries manually:

kit.manager.addTransaction({
  hash: "A1B2...",
  status: "submitted",
  submittedAt: Date.now(),
  account: kit.getSession()?.account,
});

Selecting Specific Wallets

createWalletKit({
  wallets: ["xaman", "gemwallet", "ledger", "walletconnect"],
  walletConnectProjectId: import.meta.env.VITE_WALLETCONNECT_PROJECT_ID,
});

Available IDs: "xaman", "gemwallet", "walletconnect", "crossmark", "ledger", "dropfi", "xrpl-snap", "otsu".

ledger is included in wallets: "all" by default. It uses WebHID/WebUSB and never silently restores after a reload; users must reconnect the device and open the XRP app.

Custom Adapters

To mix built-in adapters with your own:

import { createWalletKit, createXamanAdapter } from "@xrpl-wallet-kit/client";
import { createMyCustomAdapter } from "./adapters/my-adapter";

createWalletKit({
  adapters: [
    createXamanAdapter({ apiKey: import.meta.env.VITE_XAMAN_CLIENT_ID }),
    createMyCustomAdapter(),
  ],
});

When adapters is provided, the wallets and walletConnectProjectId fields are ignored.

Session Restore

Call recoverSession() once on startup:

const { manager } = createWalletKit({ wallets: "all", ... });
await manager.recoverSession();

createWalletClient

A lighter variant that returns only a WalletManager with no UI:

import { createWalletClient } from "@xrpl-wallet-kit/client";

const manager = createWalletClient({
  wallets: "all",
  walletConnectProjectId: import.meta.env.VITE_WALLETCONNECT_PROJECT_ID,
});

Use this when you're building your own UI or using a framework integration.

TypeScript

All option types are exported from @xrpl-wallet-kit/client:

import type {
  CreateWalletKitOptions,
  CreateWalletClientOptions,
  WalletKitAdapterId,
  WalletKitUiConfig,
} from "@xrpl-wallet-kit/client";