Skip to main content
Trails works with virtually all wallets, including embedded wallets like Privy, smart contract wallets like Sequence, or injected EOAs like MetaMask. This enables complex transaction orchestration cross-chain in 1-click without requiring wallets to natively support ERC-7702.
Since 0xtrails@0.16.0, Trails uses its own built-in EVM runtime by default — wagmi is no longer required. Apps that already use wagmi can share that wallet session through @0xtrails/adapter-wagmi. See the 0.16 release notes for migration details.
For full copy-paste setup snippets, see Wallet Integration.

​
How it works

Trails can connect wallets in two ways:
  1. Use the built-in wallet runtime, which is the default and requires no wallet provider setup.
  2. Pass an explicit adapter when your app already manages wallets through wagmi, Privy, Sequence, or a custom EIP-1193 provider.

​
Pick an integration path

Wallet setupRecommended Trails integration
No existing wallet setupUse the built-in wallet runtime
Existing wagmi appUse wagmiAdapter with the same wagmiConfig
Sequence Embedded WalletUse Sequence’s wagmi config with wagmiAdapter
Privy embedded wallet with wagmiUse Privy’s wagmi config with wagmiAdapter
Privy embedded wallet without wagmiUse Privy’s EIP-1193 provider with evmAdapter
Custom EIP-1193 providerUse evmAdapter from 0xtrails

​
Built-in wallet runtime

This is the simplest path. If your app does not already use wagmi, Privy, Sequence, or another wallet system, render a Trails widget or focused component directly. 
import { Pay } from '0xtrails/widget'

export function Checkout() {
  return (
    <Pay
      apiKey="YOUR_API_KEY"
      to={{ recipient: '0x...', token: 'USDC', chain: 'base', amount: '25' }}
    />
  )
}

​
wagmi

Use wagmi only when your app already has a WagmiProvider and Trails should share that session. 
import { wagmiAdapter } from '@0xtrails/adapter-wagmi'

const adapters = [wagmiAdapter({ wagmiConfig })]
Checklist:
  • Install 0xtrails, @0xtrails/adapter-wagmi, wagmi, viem, and @tanstack/react-query.
  • Reuse the exact same wagmiConfig instance for WagmiProvider and wagmiAdapter(...).
  • Put adapters on either TrailsProvider config.adapters or a widget/focused component adapters prop, not both.

​
Sequence Embedded Wallet

Sequence’s current Embedded Wallet Web SDK is wagmi-based. Configure Sequence with @0xsequence/connect, then pass sequenceConfig.wagmiConfig to Trails. 
import { createConfig, SequenceConnect } from '@0xsequence/connect'
import { wagmiAdapter } from '@0xtrails/adapter-wagmi'
import { TrailsProvider } from '0xtrails'
import { Pay } from '0xtrails/widget'

const sequenceConfig = createConfig('waas', {
  projectAccessKey: 'YOUR_SEQUENCE_PROJECT_ACCESS_KEY',
  waasConfigKey: 'YOUR_SEQUENCE_WAAS_CONFIG_KEY',
  appName: 'Your App',
  chainIds: [8453],
  defaultChainId: 8453,
})

const adapters = [wagmiAdapter({ wagmiConfig: sequenceConfig.wagmiConfig })]

export function App() {
  return (
    <SequenceConnect config={sequenceConfig}>
      <TrailsProvider config={{ trailsApiKey: 'YOUR_API_KEY', adapters }}>
        <Pay to={{ recipient: '0x...', token: 'USDC', chain: 'base', amount: '25' }} />
      </TrailsProvider>
    </SequenceConnect>
  )
}
Do not pass the whole Sequence config object to Trails; pass sequenceConfig.wagmiConfig.

​
Privy embedded wallets

Integrate Privy for seamless embedded wallet experiences. You can try live demos below: Privy works with Trails either through wagmi or directly through Privy’s EIP-1193 provider.

​
Privy with wagmi

Use this when your app already uses wagmi hooks or wants Privy to manage the active wagmi wallet. 
import { PrivyProvider } from '@privy-io/react-auth'
import { createConfig, WagmiProvider } from '@privy-io/wagmi'
import { wagmiAdapter } from '@0xtrails/adapter-wagmi'
import { http } from 'wagmi'
import { base } from 'wagmi/chains'

const wagmiConfig = createConfig({
  chains: [base],
  transports: { [base.id]: http() },
})

const adapters = [wagmiAdapter({ wagmiConfig })]
Wrap PrivyProvider, QueryClientProvider, WagmiProvider, and TrailsProvider with that same config. See the full Privy with wagmi setup.

​
Privy without wagmi

Use this when your app wants Privy embedded wallets but does not want wagmi. Read the connected Privy wallet with useWallets(), get its EIP-1193 provider, then pass it to evmAdapter. 
import { useWallets } from '@privy-io/react-auth'
import { evmAdapter } from '0xtrails'

const { wallets } = useWallets()
const embeddedWallet = wallets.find((wallet) => wallet.walletClientType === 'privy')
const provider = await embeddedWallet?.getEthereumProvider()

const adapters = provider
  ? [
      evmAdapter({
        wallets: {
          id: 'privy-embedded-wallet',
          name: 'Privy Embedded Wallet',
          provider,
        },
      }),
    ]
  : undefined
Render Trails only after Privy is ready and the provider exists. See the full Privy without wagmi setup.

​
Custom EIP-1193 providers

Use evmAdapter for any non-wagmi wallet that exposes a standard EIP-1193 provider. 
import { evmAdapter } from '0xtrails'

const adapters = [
  evmAdapter({
    wallets: {
      id: 'custom-wallet',
      name: 'Custom Wallet',
      provider: customEip1193Provider,
      iconUrl: '/custom-wallet.svg',
    },
  }),
]

​
Supported wallet types

Trails supports common wallet setups including:
  • Built-in wallet runtime: no wallet provider setup required
  • Injected wallets: MetaMask, Coinbase Wallet, Brave Wallet
  • WalletConnect: any wallet supporting WalletConnect
  • Smart contract wallets: Sequence, Safe, Biconomy
  • Embedded wallets: Privy, Dynamic, Magic
  • Custom EIP-1193 providers: in-app wallets, embedded wallets, or custom signers

​
Key benefits

  • Universal compatibility: Works with the built-in runtime, wagmi, or standard EIP-1193 providers
  • No wallet modifications: Wallets don’t need ERC-7702, 4337, or other external dependencies
  • Cross-chain transactions: Complex multi-chain operations in 1-click
  • Flexible integration: Use Trails directly or share your existing wallet infrastructure
For more configuration options, see the Wallet Integration and Configuration Guide.