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

# TrustwareConfigOptions configuration reference

> TrustwareConfigOptions is the root config for TrustwareProvider. Controls routing, theming, wallet detection, retry behavior, and lifecycle callbacks.

`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](/api-reference/types#trustwareconfigoptions).

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

<ParamField path="apiKey" type="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.
</ParamField>

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](/guides/swap-mode).

<ParamField path="routes.toChain" type="string" required>
  The destination chain ID as a string (for example, `"8453"` for Base). See
  the [route configuration](/configuration/routes) page for the full list of
  supported values.
</ParamField>

<ParamField path="routes.toToken" type="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](/configuration/routes) for details.
</ParamField>

## 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](/guides/swap-mode). |
| `routes` | Controls the destination chain and token, preferred source chain and token, slippage, and amount constraints. See [route configuration](/configuration/routes). |
| `theme` | Sets the widget color scheme to `"light"`, `"dark"`, or `"system"`. See [appearance customization](/configuration/theme). |
| `messages` | Overrides the widget title and description copy. See [appearance customization](/configuration/theme). |
| `walletConnect` | Configures or disables the WalletConnect connector. See [WalletConnect configuration](/configuration/walletconnect). |
| `retry` | Callbacks for monitoring your key's rate limit. Retry timing itself is server-directed and not configurable. See [retry configuration](/configuration/retry). |
| `features` | Controls optional SDK behaviours and modes: `tokensPagination`, `balanceStreaming`, `shouldAllowGA4`, and swap mode (`swapMode`, `swapDefaultDestToken`, `swapLockDestToken`, `swapAllowedDestTokens`). See [swap mode](/guides/swap-mode) and the [types reference](/api-reference/types#featureflags). |
| `autoDetectProvider` | For headless usage; when `true`, the core API auto-picks up `window.ethereum` when called directly. Defaults to `false`. See note below. |

<Note>
  **`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](/integration/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`.
</Note>

## Lifecycle callbacks

<ParamField path="onError" type="(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.
</ParamField>

<ParamField path="onSuccess" type="(transaction: Transaction) => void">
  Called after a transaction is successfully submitted and confirmed. Receives
  the completed `Transaction` object.
</ParamField>

<ParamField path="onEvent" type="(event: TrustwareEvent) => void">
  Called for widget lifecycle events such as step transitions. Use this for
  analytics or custom instrumentation.
</ParamField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.