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

Two fields are required: `apiKey` and a `routes` object containing at minimum `toChain` and `toToken`. Everything else is optional and falls back to a sensible default.

## Complete config shape

```ts theme={null}
type TrustwareConfigOptions = {
  apiKey: string;
  routes: {
    toChain: string;
    toToken: string;
    fromToken?: string;
    fromAddress?: string;
    toAddress?: string;
    defaultSlippage?: number;
    options?: {
      routeRefreshMs?: number;
      fixedFromAmount?: string | number;
      minAmountOut?: string | number;
      maxAmountOut?: string | number;
    };
  };
  autoDetectProvider?: boolean;
  theme?: TrustwareWidgetTheme;
  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>

<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 address. Use the standard ERC-20 contract address for
  the token on the destination chain. 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                                                                                                                                                                                                                                                                                              |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `routes`             | Controls the destination chain, token, slippage, route type, and amount constraints. See [route configuration](/configuration/routes).                                                                                                                                                                   |
| `theme`              | Overrides widget colors and border radius. 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`              | Controls automatic retry behavior on rate-limited requests. 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>