Skip to main content

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

type TrustwareConfigOptions = {
  apiKey: string;
  routes: {
    toChain: string;
    toToken: string;
    fromToken?: string;
    fromAddress?: string;
    toAddress?: string;
    defaultSlippage?: number;
    routeType?: string;
    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

​
apiKey
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.
​
routes.toChain
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.
​
routes.toToken
string
required
The destination token address. Use the standard ERC-20 contract address for the token on the destination chain. See route configuration for details.

​
Config groups

Each top-level key beyond apiKey and routes is documented on its own page.
KeyDescription
routesControls the destination chain, token, slippage, route type, and amount constraints. See route configuration.
themeOverrides widget colors and border radius. See appearance customization.
messagesOverrides the widget title and description copy. See appearance customization.
walletConnectConfigures or disables the WalletConnect connector. See WalletConnect configuration.
retryControls automatic retry behavior on rate-limited requests. See retry configuration.
featuresControls optional SDK behaviours: tokensPagination, balanceStreaming, and shouldAllowGA4. See the types reference.
autoDetectProviderWhen true, the SDK attempts to discover an injected wallet provider automatically. Defaults to false. Distinct from the provider-level autoDetect prop — see note below.
autoDetectProvider vs autoDetect — these are two separate controls:
  • autoDetectProvider is a field inside TrustwareConfigOptions (the config object you pass to the provider). Defaults to false.
  • autoDetect is a prop on <TrustwareProvider> itself. Defaults to true. Set autoDetect={false} when you pass your own wallet (see host wallet) so the SDK doesn’t run wallet discovery alongside your wallet state.
Most integrations only need to think about the provider prop.

​
Lifecycle callbacks

​
onError
(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.
​
onSuccess
(transaction: Transaction) => void
Called after a transaction is successfully submitted and confirmed. Receives the completed Transaction object.
​
onEvent
(event: TrustwareEvent) => void
Called for widget lifecycle events such as step transitions. Use this for analytics or custom instrumentation.

​
Type-safe config with satisfies

Use the satisfies operator to get full TypeScript inference without widening the type: 
import {
  TrustwareProvider,
  TrustwareWidget,
  type TrustwareConfigOptions,
} from "@trustware/sdk";

const config = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  routes: {
    toChain: "8453",
    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  },
} satisfies TrustwareConfigOptions;

export function App() {
  return (
    <TrustwareProvider config={config}>
      <TrustwareWidget />
    </TrustwareProvider>
  );
}
Using satisfies instead of a type annotation preserves the literal types of your values, which is useful when you spread the config object across multiple files.