> ## 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.
# Run the widget in swap mode
> Enable swapMode to turn the Trustware widget into a standalone swap experience where users swap any asset on any chain into their own wallet, with optional control over the output token.
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 routing engine and the quote, route, sign, broadcast, receipt, and status lifecycle are identical; only the configuration and where funds settle change.
## Enable swap mode
Set `swapMode: true` under `features`. With no destination flags set, the user selects the output token themselves. This is the open, Uniswap-style configuration.
```ts theme={null}
import { type TrustwareConfigOptions } from "@trustware/sdk";
const swapConfig = {
apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
features: {
swapMode: true,
},
} satisfies TrustwareConfigOptions;
```
Pass the config to `TrustwareProvider`:
```tsx theme={null}
```
`swapMode` defaults to `false`, 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.
## 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.
```ts theme={null}
const lockedSwapConfig = {
apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
features: {
swapMode: true,
// 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.
```ts theme={null}
const allowlistSwapConfig = {
apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
features: {
swapMode: true,
// 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 |
| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------ |
| `swapMode` | `boolean` | Enables swap mode. Defaults to `false`. |
| `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. |
All four fields live under `features` in `TrustwareConfigOptions`. See the [configuration overview](/configuration/overview) for the full config reference.
## 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.
```ts theme={null}
const swapConfig = {
apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
features: {
swapMode: true,
},
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](/events-errors/lifecycle-events) for the full event reference.
## Works with every integration style
Swap mode is a configuration flag, so it works with all four integration paths without code changes.
The fastest path: render `TrustwareWidget` with swap mode enabled in your config.
Pass your app's existing Wagmi or viem wallet and run it in swap mode.
Open and close the swap widget programmatically from your own UI.
Build a custom swap interface on top of the routing and transaction APIs.