> ## Documentation Index
> Fetch the complete documentation index at: https://docs.delora.build/llms.txt
> Use this file to discover all available pages before exploring further.

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

```tsx theme={null}
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.

```tsx theme={null}
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.

```tsx theme={null}
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](../advanced-setup/wallet-management).