Swap

Overview

Swap mode provides a flexible interface for cross-chain token exchanges. Users control both input and output, with the widget handling optimal routing across bridges and DEXs. Trade types: EXACT_INPUT and EXACT_OUTPUT.

Quick start

import { Swap } from '0xtrails/widget'

<Swap
  apiKey="YOUR_API_KEY"
  from={{ token: "ETH", chain: "ethereum" }}
  to={{ token: "USDC", chain: "base" }}
/>

User picks the amount in the UI.

Props

Required

Prop	Type	Description
`apiKey`	`string`	Trails API key

Source (optional)

The from shape is a discriminated union on paymentMethod. For wallet, exchange, and crypto-transfer flows, source is crypto; for the fiat on-ramp arm, source is fiat. When paymentMethod is "CONNECTED_WALLET", "EXCHANGE", "CRYPTO_TRANSFER", or omitted (crypto source):

Prop	Type	Description
`from.token`	`string`	Pre-select source ERC-20 token — symbol (e.g. `"USDC"`) or contract address
`from.chain`	`ChainIdentifier`	Pre-select source chain — name, ID, or viem Chain
`from.amount`	`string \| number`	Pre-fill source amount
`from.walletAddress`	`string`	Source wallet address (defaults to connected wallet)
`from.exchange`	`string`	Mesh exchange key (e.g. `"coinbase"`). `EXCHANGE` arm only.

When paymentMethod is "CREDIT_DEBIT_CARD" (fiat source):

Prop	Type	Description
`from.currency`	`string`	ISO 4217 fiat code, e.g. `"USD"`, `"EUR"`, `"GBP"`
`from.amount`	`string \| number`	Pre-fill fiat amount

Destination (optional)

Prop	Type	Description
`to.token`	`string`	Pre-select or lock destination token — symbol or contract address
`to.chain`	`ChainIdentifier`	Pre-select or lock destination chain
`to.amount`	`string \| number`	Pre-fill destination amount
`to.defaultToken`	`string`	Default destination token — user can change
`to.defaultChain`	`ChainIdentifier`	Default destination chain — user can change
`to.calldata`	`string`	ABI-encoded calldata to execute after the swap lands
`to.supportedChains`	`ChainIdentifier[]`	Restrict destination chains the user can pick
`to.supportedTokensByChain`	`SupportedTokensByChainConfig[]`	Per-chain destination token allowlist

Payment method (optional)

paymentMethod controls the source funding method. Omit to default to the connected wallet.

Value	Method
`"CONNECTED_WALLET"`	Connected wallet (default)
`"CRYPTO_TRANSFER"`	QR code / address deposit
`"CREDIT_DEBIT_CARD"`	Fiat on-ramp
`"EXCHANGE"`	CEX transfer

Route options (optional)

Prop	Type	Description
`slippageTolerance`	`number \| string`	Slippage tolerance (e.g. `0.005` for 0.5%)
`swapProvider`	`RouteProvider`	Preferred same-chain swap provider
`bridgeProvider`	`RouteProvider`	Preferred bridge provider
`swapProviderFallback`	`boolean`	Fall back if preferred swap provider is unavailable
`bridgeProviderFallback`	`boolean`	Fall back if preferred bridge provider is unavailable

Lifecycle callbacks

Callback	Signature	When it fires
`onSwapStart`	`({ sessionId }) => void`	User begins the swap flow
`onSwapSuccess`	`({ sessionId }) => void`	Swap completes successfully
`onSwapError`	`({ sessionId, error }) => void`	Swap encounters an error

Examples

Basic swap — user picks everything

import { Swap } from '0xtrails/widget'

<Swap
  apiKey="YOUR_API_KEY"
  onSwapSuccess={({ sessionId }) => console.log("swapped", sessionId)}
>
  <button>Swap Tokens</button>
</Swap>

Pre-configured cross-chain swap

<Swap
  apiKey="YOUR_API_KEY"
  from={{ token: "ETH", chain: "ethereum" }}
  to={{ token: "USDC", chain: "base" }}
  onSwapSuccess={({ sessionId }) => console.log("swapped", sessionId)}
/>

Lock destination, let user pick source

<Swap
  apiKey="YOUR_API_KEY"
  to={{ token: "USDC", chain: "base" }}
  onSwapSuccess={({ sessionId }) => console.log("swapped", sessionId)}
/>

Cross-chain swap with a fixed output amount

<Swap
  apiKey="YOUR_API_KEY"
  from={{ token: "USDC", chain: "ethereum" }}
  to={{ token: "USDC", chain: "base", amount: "100" }}
  onSwapSuccess={({ sessionId }) => console.log("bridged", sessionId)}
/>

Custom bridge provider

<Swap
  apiKey="YOUR_API_KEY"
  bridgeProvider="CCTP"
  from={{ token: "USDC", chain: "ethereum" }}
  to={{ token: "USDC", chain: "base" }}
/>

Headless implementation

For custom UI, use the useQuote hook directly:

This example reads walletClient and address from wagmi hooks. Since 0xtrails@0.16.0, wagmi is opt-in — install @0xtrails/adapter-wagmi and configure wagmiAdapter to keep using wagmi alongside Trails. See SDK Hooks.

import { useQuote } from '0xtrails'
import { useWalletClient, useAccount } from 'wagmi'

export const CustomSwap = () => {
  const { data: walletClient } = useWalletClient()
  const { address } = useAccount()
  
  const { quote, send, isLoadingQuote, quoteError, refetchQuote } = useQuote({
    walletClient,
    from: {
      token: 'USDC',
      chain: 'ethereum',
      amount: '1', // human-readable USDC amount
    },
    to: {
      token: 'USDC',
      chain: 'base',
      recipient: address,
    },
    slippageTolerance: '0.005', // 0.5%
    onStatusUpdate: (states) => {
      console.log('Transaction status:', states)
    },
  })
  
  // Refresh quotes every 30 seconds
  useEffect(() => {
    const interval = setInterval(() => {
      refetchQuote?.()
    }, 30000)
    return () => clearInterval(interval)
  }, [refetchQuote])
  
  const handleSwap = async () => {
    if (!send) return
    
    try {
      const result = await send()
      console.log('Swap result:', result)
    } catch (error) {
      console.error('Swap failed:', error)
    }
  }
  
  if (isLoadingQuote) return <div>Loading quote...</div>
  if (!quote) return null

  return (
    <div>
      <p>From: {quote.originAmountFormatted} {quote.originToken.symbol}</p>
      <p>To: {quote.destinationAmountFormatted} {quote.destinationToken.symbol}</p>
      <button onClick={() => send?.()}>Execute Swap</button>
    </div>
  )
}

Trade Types

EXACT_INPUT

User specifies exact input amount; output amount varies:

const { quote } = useQuote({
  // ... other props
  from: { token: 'USDC', chain: 'base', amount: '100' },
})
// User sends exactly 100 USDC, receives ~0.039 ETH (varies with price)

EXACT_OUTPUT

User specifies exact output amount; input amount varies:

const { quote } = useQuote({
  // ... other props
  to: { token: 'ETH', chain: 'arbitrum', amount: '0.1' },
})
// User receives exactly 0.1 ETH, sends ~256 USDC (varies with price)

Quote Types

type UseQuoteProps = {
  walletClient?: WalletClient
  walletAddress?: string | null
  from: {
    token: string
    chain: ChainIdentifier
    amount?: string // human-readable; EXACT_INPUT when set
    decimals?: number
  }
  to: {
    token: string
    chain: ChainIdentifier
    recipient?: string | null
    amount?: string // human-readable; EXACT_OUTPUT when set
    decimals?: number
  }
  slippageTolerance?: string | number | null
  onStatusUpdate?: (txs: TransactionState[]) => void | null
}

type UseQuoteReturn = {
  quote: Quote | null
  send: (() => Promise<SwapReturn | null>) | null
  isLoadingQuote: boolean
  quoteError: unknown
  refetchQuote: (() => Promise<void>) | null
}

Quote Refresh Strategy

Quotes can become stale. Implement refresh logic:

// Refresh every 30 seconds
useEffect(() => {
  const interval = setInterval(() => {
    refetchQuote?.()
  }, 30000)
  return () => clearInterval(interval)
}, [refetchQuote])

// Refresh on window focus
useEffect(() => {
  const handleFocus = () => refetchQuote?.()
  window.addEventListener('focus', handleFocus)
  return () => window.removeEventListener('focus', handleFocus)
}, [refetchQuote])

Event Handling

<Swap
  apiKey="YOUR_API_KEY"
  onSwapStart={({ sessionId }) => {
    console.log('Swap started:', sessionId)
  }}
  onSwapSuccess={({ sessionId }) => {
    console.log('Swap completed:', sessionId)
  }}
  onSwapError={({ sessionId, error }) => {
    console.error('Swap failed:', error)
  }}
/>

useQuote Transaction Status

const { quote, send } = useQuote({
  // ... other props
  onStatusUpdate: (states) => {
    states.forEach(state => {
      console.log(`${state.chainId}: ${state.status}`)
      // States: 'pending', 'executing', 'completed', 'failed'
    })
  },
})

Error Handling

import { getIsUserRejectionError, InsufficientBalanceError } from '0xtrails'

const handleSwap = async () => {
  try {
    await send?.()
  } catch (error) {
    if (getIsUserRejectionError(error)) {
      console.log('User rejected transaction')
    } else if (error instanceof InsufficientBalanceError) {
      console.error('Insufficient balance')
    } else {
      console.error('Swap failed:', error)
    }
  }
}

Use Cases

Cross-chain Token Exchange: Swap any token to any other token across chains
Portfolio Rebalancing: Shift holdings between chains and tokens
Yield Optimization: Move assets to chains with better yields
Gas Token Acquisition: Get native tokens for new chains
Arbitrage: Take advantage of price differences across chains

Technical Notes

Quotes automatically factor in gas costs and fees
Multiple liquidity sources are queried for optimal routing
Supports both same-chain and cross-chain swaps
Native token wrapping/unwrapping is handled automatically
Slippage protection is built-in

SDK Documentation

Overview

Quick start

Props

Required

Source (optional)

Destination (optional)

Payment method (optional)

Route options (optional)

Lifecycle callbacks

Examples

Basic swap — user picks everything

Pre-configured cross-chain swap

Lock destination, let user pick source

Cross-chain swap with a fixed output amount

Custom bridge provider

Headless implementation

Trade Types

EXACT_INPUT

EXACT_OUTPUT

Quote Types

Quote Refresh Strategy

Event Handling

Widget Events

useQuote Transaction Status

Error Handling

Use Cases

Technical Notes

See Also

​Overview

​Quick start

​Props

​Required

​Source (optional)

​Destination (optional)

​Payment method (optional)

​Route options (optional)

​Lifecycle callbacks

​Examples

​Basic swap — user picks everything

​Pre-configured cross-chain swap

​Lock destination, let user pick source

​Cross-chain swap with a fixed output amount

​Custom bridge provider

​Headless implementation

​Trade Types

​EXACT_INPUT

​EXACT_OUTPUT

​Quote Types

​Quote Refresh Strategy

​Event Handling

​Widget Events

​useQuote Transaction Status

​Error Handling

​Use Cases

​Technical Notes

​See Also

Overview

Quick start

Props

Required

Source (optional)

Destination (optional)

Payment method (optional)

Route options (optional)

Lifecycle callbacks

Examples

Basic swap — user picks everything

Pre-configured cross-chain swap

Lock destination, let user pick source

Cross-chain swap with a fixed output amount

Custom bridge provider

Headless implementation

Trade Types

EXACT_INPUT

EXACT_OUTPUT

Quote Types

Quote Refresh Strategy

Event Handling

Widget Events

useQuote Transaction Status

Error Handling

Use Cases

Technical Notes

See Also