Integration Patterns

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.

Delora Widget

Basic Setup

Advanced Setup

Integration Patterns

1. `TradeWidget`

2. `TradeWidget` with auto wallet management

3. `TradeWidget` with manual external wallet management

Receiver handling

​1. TradeWidget

​2. TradeWidget with auto wallet management

​3. TradeWidget with manual external wallet management

​Receiver handling

1. `TradeWidget`

2. `TradeWidget` with auto wallet management

3. `TradeWidget` with manual external wallet management

Receiver handling