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. Fires before quoting, so no `intentId` yet
`onSwapSuccess`	`({ sessionId, intentId }) => void`	Swap completes successfully
`onSwapError`	`({ sessionId, intentId, error }) => void`	Swap encounters an error

intentId identifies the intent behind this flow and is what you pass to the Trails API or Trailscan to look it up. It is null for passthrough quotes. See Callback payloads.

Examples

Basic swap — user picks everything

import { Swap } from '0xtrails/widget'

<Swap
  apiKey="YOUR_API_KEY"
  onSwapSuccess={({ intentId }) => console.log("swapped", intentId)}
>
  <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={({ intentId }) => console.log("swapped", intentId)}
/>

Lock destination, let user pick source

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

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={({ intentId }) => console.log("bridged", intentId)}
/>

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={({ intentId }) => {
    console.log('Swap completed:', intentId)
  }}
  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