Integration Patterns

Choose between the built-in wallet flow and host-managed wallet integration.

The widget exposes one main trading UI and three practical integration patterns.

These patterns do not change the widget layout. They change who owns wallet state and provider access.

• TradeWidget
• DeloraAutoWalletManagementProvider from @deloraprotocol/widget-wallet-management
• TradeWidgetWalletProvider

Pattern	Use when	Notes
TradeWidget	You want the full trading widget with the built-in wallet flow	Best default for standalone embeds
TradeWidget + DeloraAutoWalletManagementProvider	Your app already uses Wagmi and/or Solana Wallet Adapter	Auto-detected adapter layer for common wallet stacks
TradeWidget + TradeWidgetWalletProvider	Your app has custom wallet state or custom providers	Low-level adapter API from the core widget package

1. TradeWidget

Use TradeWidget when you want the complete Delora trading experience, including token selection, network selection, quote loading, slippage control, wallet connection, and transaction execution.

import "@deloraprotocol/widget/styles.css";
import { TradeWidget } from "@deloraprotocol/widget";

<TradeWidget
  theme="dark"
  config={{}}
/>;

2. TradeWidget with auto wallet management

Use this pattern when the host app already wraps the widget with Wagmi and/or Solana Wallet Adapter providers.

import "@deloraprotocol/widget/styles.css";
import { TradeWidget } from "@deloraprotocol/widget";
import { DeloraAutoWalletManagementProvider } from "@deloraprotocol/widget-wallet-management/auto";

<DeloraAutoWalletManagementProvider
  evm={{
    walletOptions: [],
    openConnectModal: () => {
      // Open RainbowKit, Reown, Dynamic, or another Wagmi-based modal.
    },
  }}
  solana={{
    walletOptions: [],
    openConnectModal: () => {
      // Open your Solana Wallet Adapter modal.
    },
  }}
>
  <TradeWidget config={{}} />
</DeloraAutoWalletManagementProvider>;

By default, this provider uses partial wallet management. If only EVM is externally managed, Solana can still fall back to the widget’s built-in wallet flow, and vice versa.

Use forceInternalWalletManagement when you want to ignore detected host wallet contexts and use only the widget’s built-in wallet flow.

The /auto import loads both the Wagmi and Solana Wallet Adapter adapters, so install both optional peer stacks when you use this pattern. Use the /wagmi or /solana subpath hooks for single-stack integrations.

3. TradeWidget with manual external wallet management

Use this pattern when the host app already manages wallet state and providers.

import "@deloraprotocol/widget/styles.css";
import {
  TradeWidget,
  TradeWidgetWalletProvider,
} from "@deloraprotocol/widget";

<TradeWidgetWalletProvider
  value={{
    origin: {
      namespace: connected ? "EVM" : null,
      address: connectedAddress ?? null,
      walletName: "My App Wallet",
      evmProvider,
      connect: async ({ namespace }) => {
        await openWalletModal(namespace);
        return true;
      },
      disconnect: async () => {
        await disconnectWallet();
      },
    },
  }}
>
  <TradeWidget config={{}} />
</TradeWidgetWalletProvider>;

You can manage origin, destination, or both sides. If one side is omitted, that side falls back to the widget’s built-in wallet flow.

In the widget UI, origin maps to the sell-side wallet and destination maps to the receiver-side wallet.

Receiver handling

The widget also supports receiver-side selection at runtime:

• reuse the origin wallet when the buy-side namespace matches
• connect a separate destination wallet
• paste a receiver address directly in the UI

If you need more control over those flows, continue with Wallet & Receiver Management.