Route configuration: chains, tokens, and amounts

The routes field in TrustwareConfigOptions defines the destination for every transaction the widget processes. At a minimum you must tell the SDK which chain and token to route to. Everything else (source chain and token preference, slippage, amount constraints) is optional and can be configured incrementally.

This page describes deposit mode, the default. In swap mode the user selects both sides of the trade in the widget, so routes is optional and the fields below are ignored as a destination. The swap destination is set through the swap fields under features.

Required fields (deposit mode)

string

required

The destination chain ID as a string. Numeric on EVM chains, so "8453" targets Base mainnet; a named identifier on Cosmos chains, so "cataclysm-1" targets Nibiru. This must be a chain the Trustware backend supports.

string

required

The destination token identifier on the destination chain. On EVM this is the token contract address, on Solana the mint address, and "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" is the conventional address used for the native gas token on EVM chains. On Cosmos chains it is the native denom string, for example "unibi" for NIBI on Nibiru.

Optional fields

string

A preferred source token. When set, the widget pre-selects this token on the source side. The user can still change it.

string

A preferred source chain. When set, the widget pre-selects this chain on the source side. The user can still change it. This is also the chain that routes.fromAddress is validated against; when omitted, routes.toChain is used for that validation.

string

Override the source wallet address used when building routes. Useful when you want to pre-specify the sending address independently of the connected wallet.

string

Override the destination wallet address. You can also set this at runtime using Trustware.setDestinationAddress(address) without rebuilding the provider.

number

default:"1"

Slippage tolerance as a percentage. Defaults to 1 (1%). Increase this for volatile pairs or routes with low liquidity.

routes.options

The nested options object controls route refresh behavior and amount constraints.

number

How often (in milliseconds) the widget automatically re-fetches a fresh route preview while the user is on the amount entry screen. If omitted, routes are not automatically refreshed.

options: {
  routeRefreshMs: 15000, // refresh every 15 seconds
}

string | number

Locks the widget’s amount input to a specific USD amount. When set, the user cannot change the amount; the widget behaves as a fixed-price checkout.

options: {
  fixedFromAmount: "25", // USD amount, cannot be changed by the user
}

string | number

The minimum USD amount the user is allowed to enter. Amounts below this threshold are rejected by the widget before a route is requested.

string | number

The maximum USD amount the user is allowed to enter. Amounts above this threshold are rejected by the widget before a route is requested.

Setting the destination address at runtime

If you only know the destination address after the provider has mounted (for example, after a user logs in), use Trustware.setDestinationAddress instead of rebuilding the config:

import { Trustware } from "@trustware/sdk";

Trustware.setDestinationAddress("0xYourDestinationAddress");

Trustware.setDestinationAddress overwrites routes.toAddress for the current session. You do not need to unmount and remount the provider.

routes.toAddress and Trustware.setDestinationAddress() set a recipient address. They do not configure a contract call on the destination chain. To run a contract call once funds arrive, pass hooks.postHook on the individual route-build request. See vault destinations.

Examples

Minimal required config

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

Cosmos destination

Cosmos destinations use the chain’s named identifier and the token’s native denom string rather than the 0xEeee... sentinel used on EVM chains. This example settles into native NIBI on Nibiru.

const config = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  routes: {
    toChain: "cataclysm-1",
    toToken: "unibi",
  },
} satisfies TrustwareConfigOptions;

When routes.toAddress is set on a Cosmos destination, it must be a bech32 address with that chain’s prefix, so nibi1... for Nibiru. Sei is a special case: address validation accepts either a sei1... bech32 address or a 0x EVM address, and Sei is discoverable as EVM chain ID 1329. Its Cosmos identifier pacific-1 is not currently returned by chain discovery. See supported chains and assets for what is available.

Full route config with all options

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

Fixed-amount checkout

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

Min/max amount guardrails

const config = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  routes: {
    toChain: "8453",
    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    options: {
      minAmountOut: "10",
      maxAmountOut: "250",
      routeRefreshMs: 10000,
    },
  },
} satisfies TrustwareConfigOptions;

Get Started

Integration

Configuration

Events & Errors

Guides

SDK Reference

Route configuration: chains, tokens, and amounts

Required fields (deposit mode)

Optional fields

routes.options

Setting the destination address at runtime

Examples

Minimal required config

Cosmos destination

Full route config with all options

Fixed-amount checkout

Min/max amount guardrails

​Required fields (deposit mode)

​Optional fields

​routes.options

​Setting the destination address at runtime

​Examples

​Minimal required config

​Cosmos destination

​Full route config with all options

​Fixed-amount checkout

​Min/max amount guardrails

Required fields (deposit mode)

Optional fields

routes.options

Setting the destination address at runtime

Examples

Minimal required config

Cosmos destination

Full route config with all options

Fixed-amount checkout

Min/max amount guardrails