Configuration

Complete configuration reference for the Trails SDK

Focused components

Shared props

All focused components accept these optional props in addition to their mode-specific props.

Appearance

Prop	Type	Default	Description
theme	"light" | "dark" | "auto"	"auto"	Color theme; auto follows system preference
customCss	string | Record<string, string>	—	Custom CSS to inject into the widget
disableCss	boolean	false	Disable default CSS injection
renderInline	boolean	false	Render inline instead of as a modal
buttonText	string	—	Custom CTA button text

App metadata

Used in wallet connection dialogs (WalletConnect, etc.):

appMetadata={{
  name: "My App",
  url: "https://myapp.com",
  imageUrl: "https://myapp.com/logo.png",
  description: "Short description",
}}

Wallet options

Prop	Type	Description
walletConnectProjectId	string	WalletConnect project ID
walletOptions	string[]	Wallet connector IDs to show (e.g. ["metamask", "walletconnect"])
adapters	TrailsAdapterEntry[]	Explicit wallet runtime adapters. Use wagmiAdapter from @0xtrails/adapter-wagmi to share an existing wagmi session, or build your own with evmAdapter.
hideAddWallet	boolean	Hide “Add wallet” option
isSmartWallet	boolean	Signal that the connected wallet is a smart wallet

The wagmiConnectors and decoupleWagmi props were removed in 0xtrails@0.16.0. Wagmi is no longer required by default — pass adapters via the adapters prop instead.

Route options

Prop	Type	Description
slippageTolerance	number | string	Slippage tolerance (e.g. 0.005 for 0.5%)
swapProvider	RouteProvider	Preferred same-chain swap provider
swapProviderFallback	boolean	Fall back if preferred swap provider is unavailable
bridgeProvider	RouteProvider	Preferred bridge provider
bridgeProviderFallback	boolean	Fall back if preferred bridge provider is unavailable
priceImpactWarningThresholdBps	number	Basis points before showing a price impact warning
priceImpactWarningMessage	string	Custom price impact warning message
priceImpactFallbackBridgeUrl	string	URL to redirect when price impact is too high
intentProtocolVersion	IntentProtocolVersion	Force a specific intent protocol version

Debug / dev

dev={{
  debug: true,
  sequenceIndexerUrl: "https://...",
  trailsApiUrl: "https://...",
}}

General callbacks

These callbacks are available on all focused components (in addition to mode-specific lifecycle callbacks):

Callback	When it fires
onOpen	Widget modal opens
onClose	Widget modal closes
onOriginConfirmation	Origin-chain transaction confirmed
onDestinationConfirmation	Destination-chain transaction confirmed
onQuote	Quote is received
onSignRequest	Wallet signature requested
onSign	Wallet signature obtained
onSignReject	User rejected the signature
onApproveRequest	ERC-20 approval requested
onApprove	ERC-20 approval confirmed
onApproveReject	User rejected the approval
onStatus	Transaction status update

ChainIdentifier

All chain fields accept a ChainIdentifier, which can be:

• A chain name string: "base", "ethereum", "polygon", "arbitrum", "optimism", "avalanche", "bsc", "katana", etc.
• A numeric chain ID: 8453, 1, 137, etc.
• A viem Chain object

PaymentMethod

The paymentMethod prop on focused components accepts:

Value	Method
"CONNECTED_WALLET"	Connected wallet (default when omitted)
"CRYPTO_TRANSFER"	QR code / address deposit
"CREDIT_DEBIT_CARD"	Fiat on-ramp (credit/debit card)
"EXCHANGE"	CEX transfer (Coinbase, Binance, etc.)

Mode-specific props

See the individual mode pages for full prop details:

• Pay — to.recipient, to.currency, to.chain, to.amount, payMessage, onPaymentStart/Success/Error
• Fund — to, fundMethodsList, hideUnlistedFundMethods, hideSwap, onFundingStart/Success/Error
• Swap — from, to, onSwapStart/Success/Error
• Withdraw — from, to, onWithdrawStart/Success/Error
• Earn — to with calldata, onEarnStart/Success/Error