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

# Drop-in widget with Trustware wallet detection

> The zero-config integration path: wrap your component with TrustwareProvider and drop in TrustwareWidget. Trustware handles wallet selection for you.

The drop-in widget is the fastest way to add a deposit flow to your app. You provide a config, Trustware handles wallet discovery, and users move through the full hosted flow without any wallet state management on your side.

## When to use this pattern

Choose this pattern when:

* your app does not already have a connected wallet state
* you want the complete built-in UX: wallet selection, token picker, amount entry, and confirmation
* you want to reach production with the shortest integration path

If you already own wallet connection through Wagmi, RainbowKit, or a custom adapter, use the [host wallet pattern](/integration/host-wallet) instead.

## Setup

<Steps>
  <Step title="Install the SDK">
    ```bash theme={null}
    npm install @trustware/sdk
    # or
    pnpm add @trustware/sdk
    ```

    The SDK requires React `18.2+` or `19`.
  </Step>

  <Step title="Define your config">
    Create a `TrustwareConfigOptions` object. At minimum you need `apiKey` and `routes.toChain` / `routes.toToken`.

    ```tsx theme={null}
    import { type TrustwareConfigOptions } from "@trustware/sdk";

    const trustwareConfig = {
      apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
      routes: {
        toChain: "8453",
        toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        defaultSlippage: 1,
        options: {
          routeRefreshMs: 15000,
        },
      },
      autoDetectProvider: true,
      messages: {
        title: "Deposit",
        description: "Move funds into the destination asset and chain.",
      },
    } satisfies TrustwareConfigOptions;
    ```

    <Note>
      `autoDetectProvider: true` tells Trustware to manage wallet discovery on its own. Leave this enabled when using the drop-in pattern.
    </Note>
  </Step>

  <Step title="Render the provider and widget">
    Wrap a component with `TrustwareProvider` and place `TrustwareWidget` anywhere inside it.

    ```tsx theme={null}
    import { TrustwareProvider, TrustwareWidget } from "@trustware/sdk";

    export function DepositPanel() {
      return (
        <TrustwareProvider config={trustwareConfig}>
          <TrustwareWidget />
        </TrustwareProvider>
      );
    }
    ```

    `TrustwareProvider` initializes the SDK, runs wallet detection, and makes configuration available to the widget. You do not need to pass anything else.
  </Step>
</Steps>

## Widget flow

Once rendered, the widget walks users through these steps in order:

1. **Home**: entry point; users choose to pay with crypto or fiat
2. **Select Token**: all routable assets in the connected wallet are displayed for the transaction
3. **Confirm Deposit**: amount entry with slider, token carousel, and fee summary
4. **Processing**: transaction submitted; the widget waits for confirmation
5. **Success / Error**: final result screen

## When to prefer this pattern

<Tip>
  The drop-in widget is the right default for most new integrations. If you find yourself needing to control the wallet, open the widget programmatically, or build custom deposit UI, look at the other integration patterns.
</Tip>

| Scenario                           | Recommended pattern                                 |
| ---------------------------------- | --------------------------------------------------- |
| No existing wallet                 | Drop-in widget (this page)                          |
| Already using Wagmi / RainbowKit   | [Host wallet](/integration/host-wallet)             |
| Open/close widget programmatically | [Controlled widget](/integration/controlled-widget) |
| Custom deposit UI, no widget       | [Headless core](/integration/headless-core)         |