Configuration - Trails

Configuration Options

Trails is easy to get started, however we have deep configuration options to address most use cases.

Core Props

Prop	Type	Required	Description
`apiKey`	`string`	Yes	Your project access key provided by Trails
`mode`	`"pay" \| "fund" \| "earn" \| "swap"`	Yes	Widget operation mode
`toAddress`	`string`	No	Destination address for payments
`toAmount`	`string`	No	Exact amount for payments (used in pay mode)
`toChainId`	`number \| string`	No	Destination chain ID
`toToken`	`string`	No	Destination token symbol or contract address
`toCalldata`	`string`	No	Custom calldata for contract interactions

UI & Rendering Options

Prop	Type	Required	Description
`renderInline`	`boolean`	No	Render widget inline instead of as a modal (default: `false`)
`children`	`React.ReactNode`	No	Custom button content (when not renderInline)
`buttonText`	`string`	No	Custom text for the trigger button (auto-generated if not provided)
`theme`	`"light" \| "dark" \| "auto"`	No	Color theme; `auto` follows system preference (default: `"auto"`)
`customCss`	`string \| Record<string, string>`	No	Custom CSS styles to apply to the component
`disableCss`	`boolean`	No	Disable default CSS injection (for custom styling)
`toast`	`boolean`	No	Show toast notifications for transaction updates
`hideDisconnect`	`boolean`	No	Hide the disconnect button in the widget
`payMessage`	`string`	No	Custom message to display during payment flow

Wallet & Connection Options

Prop	Type	Required	Description
`walletConnectProjectId`	`string`	No	WalletConnect project ID for WalletConnect integration
`walletOptions`	`string[]`	No	Array of wallet connector IDs to show (e.g., `["metamask", "walletconnect"]`)
`isSmartWallet`	`boolean`	No	Indicate if the connected wallet is a smart wallet (for ERC-4337 support)
`decoupleWagmi`	`boolean`	No	Decouple from wagmi provider (use external wagmi config)
`wagmiConnectors`	`Connector[]`	No	Custom wagmi connectors to use

Transaction Options

Prop	Type	Required	Description
`paymasterUrls`	`Array<{ chainId: number; url: string }>`	No	Configure per-chain paymaster endpoints for gasless transactions
`swapProvider`	`RouteProvider`	No	Preferred swap provider: `"AUTO"`, `"LIFI"`, `"RELAY"`, `"SUSHI"`, `"ZEROX"`, or `"CCTP"`. Default: `"AUTO"` automatically selects best provider
`bridgeProvider`	`RouteProvider`	No	Preferred bridge provider: `"AUTO"`, `"LIFI"`, `"RELAY"`, `"CCTP"`. Default: `"AUTO"` automatically selects best provider for cross-chain transfers
`slippageTolerance`	`number \| string`	No	Slippage tolerance for swaps (e.g., `0.005` for 0.5%)
`priceImpactWarningThresholdBps`	`number`	No	Price impact threshold in basis points before showing a warning (e.g., `500` for 5%)
`priceImpactWarningMessage`	`string`	No	Custom message to display when price impact exceeds threshold
`priceImpactFallbackBridgeUrl`	`string`	No	URL to redirect users when price impact is too high

App Metadata (for WalletConnect)

Prop	Type	Required	Description
`appName`	`string`	No	Your app’s name (shown in wallet connect dialogs)
`appUrl`	`string`	No	Your app’s URL
`appImageUrl`	`string`	No	Your app’s logo URL
`appDescription`	`string`	No	Short description of your app

Onramp Integration

Prop	Type	Required	Description
`onramp`	`OnrampFactory`	No	Onramp factory function from `@0xtrails/onramp` for fiat-to-crypto funding

import { trailsOnramp } from "@0xtrails/onramp"

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="fund"
  onramp={trailsOnramp({ 
    config: { 
      exchanges: ['coinbase', 'moonpay'] 
    } 
  })}
/>

Event Handlers

Prop	Type	Required	Description
`onOriginConfirmation`	`(data: { txHash: string; chainId: number; sessionId: string }) => void`	No	Called when origin transaction is confirmed
`onDestinationConfirmation`	`(data: { txHash: string; chainId: number; sessionId: string }) => void`	No	Called when destination transaction is confirmed
`onCheckoutStart`	`(data: { sessionId: string }) => void`	No	Called when checkout process starts
`onCheckoutQuote`	`(data: { sessionId: string; quote: any }) => void`	No	Called when quote is received
`onCheckoutSignatureRequest`	`(data: { sessionId: string }) => void`	No	Called when signature is requested from wallet
`onCheckoutSignatureConfirmed`	`(data: { sessionId: string }) => void`	No	Called when user confirms signature
`onCheckoutSignatureRejected`	`(data: { sessionId: string; error: unknown }) => void`	No	Called when user rejects signature
`onCheckoutComplete`	`(data: { sessionId: string }) => void`	No	Called when checkout completes successfully
`onCheckoutError`	`(data: { sessionId: string; error: unknown }) => void`	No	Called when checkout encounters an error (including user rejection)
`onCheckoutStatusUpdate`	`(data: { sessionId: string; transactionStates: TransactionState[] }) => void`	No	Called when transaction status updates
`onCheckoutApprovalRequest`	`(data: { sessionId: string }) => void`	No	Called when token approval is requested
`onCheckoutApprovalConfirmed`	`(data: { sessionId: string; transactionHash: string }) => void`	No	Called when token approval is confirmed
`onCheckoutApprovalRejected`	`(data: { sessionId: string; error: unknown }) => void`	No	Called when token approval is rejected
`onOpen`	`() => void`	No	Called when the widget modal opens
`onClose`	`() => void`	No	Called when the widget modal closes

Smart Contract Interactions

Execute custom contract calls with payments:

import { encodeFunctionData } from 'viem'

const calldata = encodeFunctionData({
  abi: contractABI,
  functionName: 'mintNFT',
  args: [recipient, tokenId]
})

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="pay"
  toAddress="0x..." // Contract address
  toAmount="0.1"
  toChainId={1}
  toToken="ETH"
  toCalldata={calldata}
  onCheckoutComplete={(result) => {
    console.log('NFT minted:', result)
  }}
/>

Event Handling Examples

Complete Event Handling

import { getIsUserRejectionError } from '0xtrails'

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="pay"
  toAddress="0x..."
  toAmount="1"
  toChainId={8453}
  toToken="USDC"
  onOriginConfirmation={({ txHash, chainId, sessionId }) => {
    console.log('Origin tx confirmed:', { txHash, chainId, sessionId })
  }}
  onDestinationConfirmation={({ txHash, chainId, sessionId }) => {
    console.log('Destination tx confirmed:', { txHash, chainId, sessionId })
  }}
  onCheckoutStatusUpdate={({ sessionId, transactionStates }) => {
    transactionStates.forEach((state, index) => {
      console.log(`Step ${index + 1}: ${state.label} - ${state.state}`)
      if (state.state === 'confirmed') {
        console.log('Transaction confirmed:', state.transactionHash)
      }
    })
  }}
  onCheckoutComplete={({ sessionId }) => {
    console.log('Transaction completed successfully:', sessionId)
  }}
  onCheckoutError={({ sessionId, error }) => {
    console.error('Transaction failed:', sessionId, error)
    
    // Check if user rejected the transaction
    if (getIsUserRejectionError(error)) {
      console.log('User rejected the transaction')
      // Handle user rejection (e.g., show "Transaction cancelled" message)
    } else {
      // Handle other errors (show error notification, retry logic, etc.)
    }
  }}
/>

Handling User Rejection

User rejection occurs when a user declines to sign a transaction in their wallet. This is handled through the onCheckoutError callback:

import { getIsUserRejectionError, TrailsWidget } from '0xtrails'

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="pay"
  toAddress="0x..."
  onCheckoutError={({ sessionId, error }) => {
    if (getIsUserRejectionError(error)) {
      // User cancelled the transaction
      showNotification('Transaction cancelled by user')
    } else {
      // Other error occurred
      showNotification('Transaction failed: ' + error)
    }
  }}
/>

SDK Documentation

​Configuration Options

​Core Props

​UI & Rendering Options

​Wallet & Connection Options

​Transaction Options

​App Metadata (for WalletConnect)

​Onramp Integration

​Event Handlers

​Smart Contract Interactions

​Event Handling Examples

​Complete Event Handling

​Handling User Rejection