Configuration - Trails

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"`	`"light"`	Color theme. Defaults to `"light"` when omitted and the user has no stored preference; pass `"auto"` to follow the OS 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
`defaultDisplayCurrency`	`string`	`"USD"`	ISO 4217 code (e.g. `"NZD"`) of the fiat currency used to display amounts. Unsupported codes fall back to USD; a currency the user picks in preferences takes precedence
`merchantCheckout`	`boolean`	—	Render the merchant checkout presentation. Implied by the `stripe` and `settlement` props; set to `false` to keep the standalone presentation with a settlement

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
`adapters`	`TrailsAdapterEntry[]`	Explicit wallet runtime adapters. Use `wagmiAdapter` from `@0xtrails/adapter-wagmi` to share an existing wagmi session, or build your own with `evmAdapter`. See Adapters.
`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 [email protected]. Wagmi is no longer required by default — pass adapters on the widget’s adapters prop instead. See Adapters.

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
`disablePassthrough`	`boolean`	Always route through the intent flow, even when a quote is passthrough-eligible (same token, same chain, wallet funding). Default: `false`
`settlement`	`QuoteSettlementParams`	Advanced: fully-specified settlement quote params forwarded to `QuoteIntent`. Set automatically by the `stripe` prop; only set directly when managing the checkout reference lifecycle yourself
`stripe`	`TrailsStripeCheckoutProps`	Arm a Stripe checkout that settles USDC. See Stripe Onramp

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	Payload	When it fires
`onOpen`	—	Widget modal opens
`onClose`	—	Widget modal closes
`onQuote`	`{ sessionId, intentId, quote }`	Quote is received
`onSignRequest`	`{ sessionId, intentId }`	Wallet signature requested
`onSign`	`{ sessionId, intentId }`	Wallet signature obtained
`onSignReject`	`{ sessionId, intentId, error }`	User rejected the signature
`onApproveRequest`	`{ sessionId, intentId }`	ERC-20 approval requested
`onApprove`	`{ sessionId, intentId, transactionHash }`	ERC-20 approval confirmed
`onApproveReject`	`{ sessionId, intentId, error }`	User rejected the approval
`onStatus`	`{ sessionId, intentId, transactionStates }`	Transaction status update
`onOriginConfirmation`	`{ sessionId, intentId, txHash, chainId }`	Origin-chain transaction confirmed
`onDestinationConfirmation`	`{ sessionId, intentId, txHash, chainId }`	Destination-chain transaction confirmed
`onPaymentCreated`	`{ sessionId, settlement }`	A quote armed an external payment (Stripe PaymentIntent). Fires once per payment reference, before execution; carries no `intentId`. `settlement` is a `QuoteSettlementInfo`

When a settlement is armed (via the stripe or settlement props), onSuccess/onPaymentSuccess carries an optional settlement field of type IntentSettlement, and the widget holds the success event until the processor confirms settlement.

Callback payloads

Every callback that fires after a quote exists carries two identifiers:

Field	Type	Description
`sessionId`	`string`	Analytics session id for the current widget session. Stable across every callback in one session, but not known to the Trails API.
`intentId`	`string \| null`	Id of the intent created for the active quote. Use it to look the payment up server-side (`GetIntentReceipt`, `GetIntentStatus`) or on Trailscan. `null` for passthrough quotes (same-chain, same-token transfers that need no intent).

The *Start callbacks (onPaymentStart, onFundingStart, …) fire before quoting, so they carry only sessionId. onOpen and onClose have no payload.

<Pay
  apiKey="YOUR_API_KEY"
  to={{ recipient: "0xMerchant", currency: "USDC", chain: "base", amount: "25" }}
  onQuote={({ intentId }) => console.log("intent created", intentId)}
  onPaymentSuccess={({ intentId }) => {
    // Verify server-side with the Trails API before fulfilling
    fetch("/api/verify-payment", { method: "POST", body: JSON.stringify({ intentId }) })
  }}
>
  <button>Pay $25</button>
</Pay>

The payload types are exported from 0xtrails:

CheckoutEventBase — { sessionId: string; intentId: string | null }
TransactionConfirmationEvent — { txHash: string; chainId: number; sessionId: string; intentId: string | null }

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). Opens the card provider picker — Stripe or Meld, chosen by country, with a chooser only when both are available
`"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

​Focused components

​Shared props

​Appearance

​App metadata

​Wallet options

​Route options

​Debug / dev

​General callbacks

​Callback payloads

​ChainIdentifier

​PaymentMethod

​Mode-specific props

Focused components

Shared props

Appearance

App metadata

Wallet options

Route options

Debug / dev

General callbacks

Callback payloads

ChainIdentifier

PaymentMethod

Mode-specific props