Run the widget in swap mode

Swap mode turns the Trustware widget into a standalone swap experience, the same flow users expect from a frontend like Uniswap. Users swap from any supported asset on any supported chain and receive the output directly in their own connected wallet, with no destination address to configure. It is an alternative to deposit mode: instead of routing funds to a destination you set, the output settles back to the user.

In deposit mode, funds route to a destination you configure in routes. In swap mode, funds settle to the user’s own connected wallet. The Route Handler and the quote, route, sign, broadcast, receipt, and status lifecycle are identical; only the configuration and where funds settle change.

Enable swap mode

Set mode: "swap" on the top-level config. Because the user picks both sides of the trade in the widget, routes is not required in swap mode. With no destination flags set, the user selects the output token themselves. This is the open, Uniswap-style configuration.

import { type TrustwareConfigOptions } from "@trustware/sdk";

const swapConfig = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  mode: "swap",
} satisfies TrustwareConfigOptions;

Pass the config to TrustwareProvider:

<TrustwareProvider config={swapConfig}>
  <TrustwareWidget />
</TrustwareProvider>

mode defaults to "deposit", which keeps the widget in deposit mode. Inputs are never restricted: users can always pay in from any supported asset on any supported chain. Only the output can be restricted, using the fields below.

mode requires @trustware/sdk 1.1.9 or later.In 1.1.8, enable swap mode with features.swapMode: true and include a routes object with toChain and toToken. That version requires both fields in every mode, so a config without routes throws TrustwareConfig: 'routes.toChain' and 'routes.toToken' are required. before the widget renders. The values are not used as the swap destination, which is governed by the swap fields below.Swap mode does not exist before 1.1.8. Versions up to and including 1.1.7 ship no swapMode flag and no swap destination fields, so upgrade rather than trying to configure it there.

// @trustware/sdk 1.1.8
const swapConfig = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  routes: {
    toChain: "8453",
    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  },
  features: {
    swapMode: true,
  },
} satisfies TrustwareConfigOptions;

features.swapMode still works in 1.1.9 and is treated as equivalent to mode: "swap", but it is deprecated and logs a deprecation warning to the console. Prefer mode in new integrations.

Lock the destination token

To settle every swap into one token, set swapDefaultDestToken and lock it with swapLockDestToken: true. For example, a client on Base can lock the output so users only ever receive USDC on Base, paying in from any asset on any chain.

const lockedSwapConfig = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  mode: "swap",
  features: {
    // Pre-select USDC on Base as the destination
    swapDefaultDestToken: {
      address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
      chainId: 8453,
    },
    // Lock it so the user cannot change the destination
    swapLockDestToken: true,
  },
} satisfies TrustwareConfigOptions;

Restrict outputs to an allowlist

To allow a small set of output tokens, list them in swapAllowedDestTokens. The destination-token picker is limited to this list; everything else is locked out. This restricts outputs only. Users can still pay in with any supported asset on any chain.

const allowlistSwapConfig = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  mode: "swap",
  features: {
    // Users may only swap into USDC or USDT on Base
    swapAllowedDestTokens: [
      { address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", chainId: 8453 }, // USDC on Base
      { address: "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2", chainId: 8453 }, // USDT on Base
    ],
  },
} satisfies TrustwareConfigOptions;

Config reference

Field	Type	Description
`mode`	`"deposit" \| "swap"`	Top-level field. Set to `"swap"` to enable swap mode. Defaults to `"deposit"`. Requires SDK 1.1.9 or later.
`swapDefaultDestToken`	`{ address: string; chainId: number }`	Pre-selects the destination token shown when the widget opens.
`swapLockDestToken`	`boolean`	Locks the destination so the user cannot change it. Use with `swapDefaultDestToken`.
`swapAllowedDestTokens`	`Array<{ address: string; chainId: number }>`	Restricts the destination-token picker to this list. Everything else is locked out.
`swapMode`	`boolean`	Deprecated. Equivalent to `mode: "swap"`. Use `mode` instead.

mode is a top-level field on TrustwareConfigOptions. The three swap destination fields and the deprecated swapMode flag live under features. See the configuration overview for the full config reference.

Destination locking supports EVM chains only. SwapTokenRef.chainId is numeric, and Cosmos chains are identified by named strings such as cataclysm-1, so Cosmos destinations cannot be set through swapDefaultDestToken or swapAllowedDestTokens.

React to route changes

In swap mode, the SDK emits a swap_route_changed event whenever the resolved route updates, for example when the user changes the source or destination chain, token, or amount. Subscribe with onEvent to keep your own UI in sync.

const swapConfig = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  mode: "swap",
  onEvent: (event) => {
    if (event.type === "swap_route_changed") {
      console.log("Route updated:", event.fromToken, "to", event.toToken);
    }
  },
} satisfies TrustwareConfigOptions;

The event carries fromChain, fromToken, toChain, toToken, and an optional amount. See lifecycle events for the full event reference.

Swap with an embedded wallet

Swap mode also works when the host wallet is an embedded wallet your app provisions, for example through Privy. Adapt the wallet’s EIP-1193 provider with useEIP1193, pass it to TrustwareProvider through the wallet prop, and set autoDetect={false} so the SDK does not run its own wallet discovery alongside it.

<TrustwareProvider config={swapConfig} wallet={wallet} autoDetect={false}>
  <TrustwareWidget />
</TrustwareProvider>

The embedded wallet signs the swap and receives the output. See use Trustware with embedded wallets for the full adapter pattern.

Works with every integration style

Swap mode is a configuration flag, so it works with all four integration paths without code changes.

Drop-in widget

The fastest path: render TrustwareWidget with swap mode enabled in your config.

Host wallet

Pass your app’s existing Wagmi or viem wallet and run it in swap mode.

Controlled widget

Open and close the swap widget programmatically from your own UI.

Headless core

Build a custom swap interface on top of the routing and transaction APIs.

Get Started

Integration

Configuration

Events & Errors

Guides

SDK Reference

Run the widget in swap mode

Enable swap mode

Lock the destination token

Restrict outputs to an allowlist

Config reference

React to route changes

Swap with an embedded wallet

Works with every integration style

Drop-in widget

Host wallet

Controlled widget

Headless core

​Enable swap mode

​Lock the destination token

​Restrict outputs to an allowlist

​Config reference

​React to route changes

​Swap with an embedded wallet

​Works with every integration style

Drop-in widget

Host wallet

Controlled widget

Headless core

Enable swap mode

Lock the destination token

Restrict outputs to an allowlist

Config reference

React to route changes

Swap with an embedded wallet

Works with every integration style