TrustwareConfigOptions configuration reference

TrustwareConfigOptions is the single object you pass to TrustwareProvider. Every aspect of the SDK (which chain and token to route to, how the widget looks, how retries are handled, and which wallet connectors are available) is controlled through this shape. apiKey is always required. In deposit mode, which is the default, a routes object containing at minimum toChain and toToken is required as well. In swap mode the user chooses both sides of the trade in the widget, so routes is optional. Everything else falls back to a sensible default.

Complete config shape

Shown for deposit mode, the default. In swap mode set mode: "swap" and routes becomes optional; everything else is identical. The SDK types this as a discriminated union on mode, shown in the types reference.

type TrustwareConfigOptions = {
  apiKey: string;
  mode?: "deposit" | "swap"; // defaults to "deposit"
  routes: { // optional when mode is "swap"
    toChain: string;
    toToken: string;
    fromToken?: string;
    fromChain?: string;
    fromAddress?: string;
    toAddress?: string;
    defaultSlippage?: number;
    options?: {
      routeRefreshMs?: number;
      fixedFromAmount?: string | number;
      minAmountOut?: string | number;
      maxAmountOut?: string | number;
    };
  };
  autoDetectProvider?: boolean;
  theme?: TrustwareTheme;
  messages?: Partial<TrustwareWidgetMessages>;
  retry?: RetryConfig;
  walletConnect?: WalletConnectConfig;
  features?: FeatureFlags;
  onError?: (error: TrustwareError) => void;
  onSuccess?: (transaction: Transaction) => void;
  onEvent?: (event: TrustwareEvent) => void;
};

Required fields

string

required

Your Trustware API key. Used for all requests the SDK makes to the Trustware backend. Store this in an environment variable and avoid committing it to source control.

The two routes fields below are required in deposit mode, which is the default. In swap mode they are optional, because the user selects both the source and the destination in the widget. See swap mode.

string

required

The destination chain ID as a string (for example, "8453" for Base). See the route configuration page for the full list of supported values.

string

required

The destination token identifier: the contract address on EVM, the mint address on Solana, or the native denom string (for example "unibi") on Cosmos. See route configuration for details.

Config groups

Each top-level key beyond apiKey and routes is documented on its own page.

Key	Description
`mode`	`"deposit"` (default) or `"swap"`. Selects which widget experience runs. Requires SDK 1.1.9 or later. See swap mode.
`routes`	Controls the destination chain and token, preferred source chain and token, slippage, and amount constraints. See route configuration.
`theme`	Sets the widget color scheme to `"light"`, `"dark"`, or `"system"`. See appearance customization.
`messages`	Overrides the widget title and description copy. See appearance customization.
`walletConnect`	Configures or disables the WalletConnect connector. See WalletConnect configuration.
`retry`	Controls automatic retry behavior on rate-limited requests. See retry configuration.
`features`	Controls optional SDK behaviours and modes: `tokensPagination`, `balanceStreaming`, `shouldAllowGA4`, and swap mode (`swapMode`, `swapDefaultDestToken`, `swapLockDestToken`, `swapAllowedDestTokens`). See swap mode and the types reference.
`autoDetectProvider`	For headless usage; when `true`, the core API auto-picks up `window.ethereum` when called directly. Defaults to `false`. See note below.

autoDetectProvider vs autoDetect: two related but distinct controls.

autoDetect is a prop on <TrustwareProvider> that triggers wallet detection on mount. Defaults to true. Set autoDetect={false} when passing your own wallet (see host wallet) to avoid duplicate discovery.
autoDetectProvider is a field inside TrustwareConfigOptions for headless usage. When true, the core API auto-picks up window.ethereum when called directly. Defaults to false.

Lifecycle callbacks

(error: TrustwareError) => void

Called whenever a TrustwareError is thrown during a route or transaction operation. Use this to surface errors to your own UI or logging pipeline.

(transaction: Transaction) => void

Called after a transaction is successfully submitted and confirmed. Receives the completed Transaction object.

(event: TrustwareEvent) => void

Called for widget lifecycle events such as step transitions. Use this for analytics or custom instrumentation.

Get Started

Integration

Configuration

Events & Errors

Guides

SDK Reference

TrustwareConfigOptions configuration reference

Complete config shape

Required fields

Config groups

Lifecycle callbacks

​Complete config shape

​Required fields

​Config groups

​Lifecycle callbacks

Complete config shape

Required fields

Config groups

Lifecycle callbacks