Skip to main content

​
Configuration Options

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

​
Core Props

PropTypeRequiredDefaultDescription
projectAccessKeystringNo—Your project access key provided by Sequence
mode"pay" | "fund" | "earn" | "swap" | "receive"No"pay"Widget operation mode
toAddressstringNo—Destination address for payments
toAmountstringNo—Exact amount for payments (used in pay mode)
toChainIdnumber | stringNo—Destination chain ID
toTokenstringNo—Destination token symbol or contract address
toCalldatastringNo—Custom calldata for contract interactions

​
UI & Rendering Options

PropTypeRequiredDefaultDescription
renderInlinebooleanNofalseRender widget inline instead of as a modal
childrenReact.ReactNodeNo—Custom button content (when not renderInline)
buttonTextstringNoAuto-generatedCustom text for the trigger button
theme"light" | "dark" | "auto"No"auto"Color theme; auto follows system preference
customCssstring | Record<string, string>No—Custom CSS styles to apply to the component

​
Wallet & Connection Options

PropTypeRequiredDefaultDescription
walletConnectProjectIdstringNo—WalletConnect project ID for WalletConnect integration

​
Transaction Options

PropTypeRequiredDefaultDescription
gaslessbooleanNofalseEnable gasless transactions
paymasterUrlsArray<{ chainId: number; url: string }>No—Configure per-chain paymaster endpoints for gasless transactions
quoteProviderstringNo"auto"Preferred quote provider (“lifi”, “auto”, etc.)
slippageTolerancenumber | stringNo—Slippage tolerance for swaps

​
Sequence Configuration

PropTypeRequiredDefaultDescription
sequenceUseV3RelayersbooleanNo—Use Sequence v3 relayers
sequenceIndexerUrlstringNo—Custom Sequence indexer URL
sequenceApiUrlstringNo—Custom Sequence API URL
sequenceEnv"local" | "cors-anywhere" | "dev" | "prod"No—Sequence environment configuration

​
Event Handlers

PropTypeRequiredDefaultDescription
onOriginConfirmation(data: { txHash: string; chainId: number; sessionId: string }) => voidNo—Called when origin transaction is confirmed
onDestinationConfirmation(data: { txHash: string; chainId: number; sessionId: string }) => voidNo—Called when destination transaction is confirmed
onCheckoutStart(data: { sessionId: string }) => voidNo—Called when checkout process starts
onCheckoutQuote(data: { sessionId: string; quote: any }) => voidNo—Called when quote is received
onCheckoutComplete(data: { sessionId: string }) => voidNo—Called when checkout completes successfully
onCheckoutError(data: { sessionId: string; error: string }) => voidNo—Called when checkout encounters an error
onCheckoutStatusUpdate(data: { sessionId: string; transactionStates: TransactionState[] }) => voidNo—Called when transaction status updates

​
Mode Configurations

​
Pay Mode

Used for exact output payments (e.g., NFT purchases, bills): 
<TrailsWidget
  mode="pay"
  toAddress="0x..."
  toAmount="1"
  toChainId={8453}
  toToken="USDC"
  onCheckoutComplete={(result) => console.log('Payment completed')}
/>

​
Fund Mode

Used for deposits where user chooses amount: 
<TrailsWidget
  mode="fund"
  toAddress="0x..."
  toChainId={8453}
  toToken="USDC"
  onCheckoutComplete={(result) => console.log('Funding completed')}
/>

​
Swap Mode

Used for open-ended token swapping: 
<TrailsWidget
  mode="swap"
  onCheckoutComplete={(result) => console.log('Swap completed')}
/>

​
Earn Mode

Used for yield farming and staking: 
<TrailsWidget
  mode="earn"
  toAddress="0x..." // Staking contract
  toChainId={1}
  toToken="ETH"
  onCheckoutComplete={(result) => console.log('Staking completed')}
/>

​
Receive Mode

Used for requesting payments: 
<TrailsWidget
  mode="receive"
  toAddress="0x..." // Your address
  toAmount="10"
  toChainId={8453}
  toToken="USDC"
/>

​
Gasless Configuration

Enable gasless transactions by providing paymaster URLs: 
<TrailsWidget
  mode="pay"
  gasless={true}
  paymasterUrls={[
    { chainId: 8453, url: "https://paymaster.base.org" },
    { chainId: 42161, url: "https://paymaster.arbitrum.org" }
  ]}
  // ... other props
/>

​
Custom Theming

​
Theme Selection

<TrailsWidget
  theme="dark" // or "light" or "auto"
  // ... other props
/>

​
Custom CSS

<TrailsWidget
  customCss={`
    .trails-widget {
      border-radius: 12px;
      box-shadow: 0 4px 12px rgba(0,0,0,0.1);
    }
    .trails-button {
      background: linear-gradient(45deg, #ff6b6b, #4ecdc4);
    }
  `}
  // ... other props
/>

​
Custom CSS as Object

<TrailsWidget
  customCss={{
    '--trails-primary-color': '#ff6b6b',
    '--trails-secondary-color': '#4ecdc4',
    '--trails-border-radius': '12px'
  }}
  // ... other props
/>

​
Smart Contract Interactions

Execute custom contract calls with payments: 
import { encodeFunctionData } from 'viem'

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

<TrailsWidget
  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

<TrailsWidget
  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)
    // Handle error (show notification, retry logic, etc.)
  }}
/>

​
Quote Provider Configuration

<TrailsWidget
  quoteProvider="auto" // Automatically selects best provider
  // ... other props
/>

​
Specific Provider

<TrailsWidget
  quoteProvider="lifi" // Use LiFi for cross-chain swaps
  // ... other props
/>

​
Advanced Configuration

​
Slippage Configuration

<TrailsWidget
  mode="swap"
  slippageTolerance={0.5} // 0.5% slippage tolerance
  // ... other props
/>

​
Rendering Options

<TrailsWidget
  renderInline={false} // Default - shows as modal
  buttonText="Pay with Trails"
  // ... other props
/>

​
Inline

<TrailsWidget
  renderInline={true} // Renders directly in page
  // ... other props
/>

​
Custom Button

<TrailsWidget
  renderInline={false}
  // ... other props
>
  <button className="custom-pay-button">
    💳 Pay with Crypto
  </button>
</TrailsWidget>

​
Type Definitions

export type TransactionState = {
  chainId: number
  transactionHash: string
  state: 'pending' | 'confirmed' | 'failed'
  explorerUrl: string
  label: string
  blockNumber?: number
}

export type Mode = "pay" | "fund" | "earn" | "swap" | "receive"

export type Theme = "light" | "dark" | "auto"

export type RelayerEnv = "local" | "cors-anywhere" | "dev" | "prod"

export interface TrailsWidgetRef {
  openModal: () => void
  closeModal: () => void
  isModalOpen: boolean
}