Drop-in widget with Trustware wallet detection

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

The widget does not accept a hooks field, so destination contract calls are not available through it. To deposit into a contract on the destination chain, use the headless core or the REST API. See vault destinations.

Setup

Install the SDK

npm install @trustware/sdk
# or
pnpm add @trustware/sdk

The SDK requires React 18.2+ or 19.

Define your config

Create a TrustwareConfigOptions object. At minimum you need apiKey and routes.toChain / routes.toToken.

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;

autoDetectProvider: true tells Trustware to manage wallet discovery on its own. Leave this enabled when using the drop-in pattern.

Render the provider and widget

Wrap a component with TrustwareProvider and place TrustwareWidget anywhere inside it.

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.

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

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

When to prefer this pattern

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.

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

Get Started

Integration

Configuration

Events & Errors

Guides

SDK Reference

Drop-in widget with Trustware wallet detection

When to use this pattern

Setup

Widget flow

When to prefer this pattern

​When to use this pattern

​Setup

​Widget flow

​When to prefer this pattern

When to use this pattern

Setup

Widget flow

When to prefer this pattern