Configuration

This page describes all available configuration options for initializeLedgerProvider. See Get started for usage and API reference for the function signature.

Configuration options

{
  // Core options
  apiKey?: string;                                    // Your Ledger API key
  dAppIdentifier?: string;                            // Your dApp identifier
  loggerLevel?: 'fatal' | 'error' | 'warn' | 'info' | 'debug';  // Log verbosity (default: 'info')
  environment?: 'staging' | 'production';             // Target Ledger backend environment
  dmkConfig?: DeviceModuleOptions;                    // Device Management Kit configuration (optional)
 
  // UI options
  target?: HTMLElement;                               // Where to mount the UI (default: document.body)
  floatingButtonPosition?: 'bottom-right' | 'bottom-left' | 'bottom-center' | 'top-right' | 'top-left' | 'top-center' | 'middle-right';  // Position of the floating button (default: 'bottom-right')
  floatingButtonTarget?: HTMLElement | string;        // Element or CSS selector to anchor the floating button to
  walletTransactionFeatures?: Array<'send' | 'receive' | 'swap' | 'buy' | 'earn' | 'sell'>;  // Wallet action CTAs to display
 
  // Development options
  devConfig?: {
    stub?: {
      base?: boolean;              // Enable base stub mode (default: false)
      account?: boolean;           // Stub account operations (default: false)
      balance?: boolean;           // Stub account balances (default: false)
      device?: boolean;            // Stub signer interactions (default: false)
      web3Provider?: boolean;      // Stub Web3 provider responses (default: false)
      dAppConfig?: boolean;        // Stub dApp configuration (default: false)
      transactionHistory?: boolean; // Stub transaction history (default: false)
    };
  };
}

All options are optional.

Parameter details

`apiKey`

Your Ledger API key. Required for production use.

`dAppIdentifier`

Your dApp identifier. This lets Ledger validate the integration and enable remote services.

`loggerLevel`

Log verbosity. Accepted values: 'fatal', 'error', 'warn', 'info', 'debug'. Default is 'info'.

`environment`

Target Ledger backend environment. Accepted values: 'staging', 'production'.

`target`

Target element to mount the Ledger Wallet Provider UI. Defaults to document.body.

`floatingButtonPosition`

Controls where the floating Ledger button appears on screen. Default is 'bottom-right'.

Available positions: 'bottom-right', 'bottom-left', 'bottom-center', 'top-right', 'top-left', 'top-center', 'middle-right'.

initializeLedgerProvider({
  floatingButtonPosition: "bottom-left",
  // ...
});

`floatingButtonTarget`

An HTMLElement or CSS selector string. When provided, the floating button renders as a compact button inside the target element instead of being positioned on screen.

Use this to integrate the Ledger button into your own navigation bar, wallet panel, or sidebar.

// CSS selector
initializeLedgerProvider({
  floatingButtonTarget: "#my-wallet-button-slot",
  // ...
});
 
// HTMLElement reference
initializeLedgerProvider({
  floatingButtonTarget: document.querySelector("#my-wallet-button-slot"),
  // ...
});

When floatingButtonTarget is set, floatingButtonPosition has no effect. The button is placed inside your target element instead.

`walletTransactionFeatures`

An optional array of wallet transaction features to display as action buttons in the side panel.

Available features:

'send' — Send crypto
'receive' — Receive crypto
'swap' — Swap tokens
'buy' — Buy crypto
'earn' — Earn rewards
'sell' — Sell crypto

If not specified, the action buttons section is not displayed.

`dmkConfig`

Device Management Kit configuration (optional). Passes custom device policies to the underlying Device Management Kit.

`devConfig.stub`

Toggles local stub modes so you can simulate accounts, balances, devices, and Web3 flows during development without a physical signer.

Field	Default	Stubs
`base`	`false`	Base stub mode
`account`	`false`	Account operations
`balance`	`false`	Account balances
`device`	`false`	Signer interactions
`web3Provider`	`false`	Web3 provider responses
`dAppConfig`	`false`	dApp configuration
`transactionHistory`	`false`	Transaction history

const cleanup = initializeLedgerProvider({
  devConfig: {
    stub: {
      base: true,
      account: true,
      balance: true,
      device: true,
      web3Provider: true,
      dAppConfig: true,
    },
  },
  dAppIdentifier: "my-dapp",
  apiKey: "your-api-key",
});

Return value

initializeLedgerProvider returns a cleanup function. Call it to remove the provider and UI components from the DOM.

const cleanup = initializeLedgerProvider({ /* options */ })
 
// Later, when unmounting:
cleanup()

The cleanup function removes the UI, deregisters the eip6963:requestProvider listener, and resets the internal provider state so a new configuration can be applied on the next call.

Configuration

Configuration options

Parameter details

apiKey

dAppIdentifier

loggerLevel

environment

target

floatingButtonPosition

floatingButtonTarget

walletTransactionFeatures

dmkConfig

devConfig.stub