Wallet Compatibility

Comprehensive wallet integration support and compatibility across different blockchain ecosystems

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. The patterns below still work for apps that share an existing wagmi session, via the @0xtrails/adapter-wagmi package. See the 0.16 release notes for the migration.

How It Works

Trails detects and uses connected wallets through its built-in runtime, or through wagmi connectors when you install the wagmi adapter. For apps that already use wagmi, wrap your app with a wagmi provider, include the desired wallet connectors in your config, and pass wagmiAdapter({ wagmiConfig }) to TrailsProvider.

Basic Wagmi Setup

import { createConfig, http, WagmiProvider } from 'wagmi'
import { mainnet, base, arbitrum } from 'wagmi/chains'
import { injected, walletConnect } from 'wagmi/connectors'
import { Pay } from '0xtrails/widget'

const config = createConfig({
  chains: [mainnet, base, arbitrum],
  connectors: [
    injected(),
    walletConnect({ projectId: 'your-walletconnect-project-id' })
  ],
  transports: {
    [mainnet.id]: http(),
    [base.id]: http(),
    [arbitrum.id]: http(),
  },
})

export function App() {
  return (
    <WagmiProvider config={config}>
      <Pay
        apiKey="YOUR_API_KEY"
        to={{
          recipient: "0x...",
          currency: "USDC",
          chain: "arbitrum",
          amount: "1000",
        }}
      />
    </WagmiProvider>
  )
}

Sequence Wallet Integration

Integrate Sequence smart contract wallets for enhanced security and user experience:

import { createConfig, http, WagmiProvider } from 'wagmi'
import { mainnet, base, arbitrum } from 'wagmi/chains'
import { sequenceWallet } from '@0xsequence/wagmi-connector'
import { Pay } from '0xtrails/widget'

// Create Sequence connector
const sequenceConnector = sequenceWallet({
  connectOptions: {
    app: "Your App Name",
    apiKey: "your-sequence-project-key",
  },
  defaultNetwork: 1, // Mainnet
  walletAppURL: "https://sequence.app",
})

const config = createConfig({
  chains: [mainnet, base, arbitrum],
  connectors: [sequenceConnector],
  transports: {
    [mainnet.id]: http(),
    [base.id]: http(),
    [arbitrum.id]: http(),
  },
})

export function AppWithSequence() {
  return (
    <WagmiProvider config={config}>
      <Pay
        apiKey="YOUR_API_KEY"
        to={{
          recipient: "0x...",
          currency: "USDC",
          chain: "arbitrum",
          amount: "1000",
        }}
      />
    </WagmiProvider>
  )
}

Privy Embedded Wallets

Integrate Privy for seamless embedded wallet experiences. You can try live demos below:

• Headless SDK demo
• Widget demo

import React from 'react';
import { PrivyProvider } from '@privy-io/react-auth';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { mainnet } from 'wagmi/chains';
import { createConfig, WagmiProvider } from '@privy-io/wagmi';
import { http } from 'wagmi';
import { Pay } from '0xtrails/widget';

const config = createConfig({
  chains: [mainnet],
  transports: {
    [mainnet.id]: http(),
  },
});

const queryClient = new QueryClient();

export function AppWithPrivy() {
  return (
    <PrivyProvider
      appId="your-privy-app-id"
      config={{
        embeddedWallets: {
          ethereum: {
            createOnLogin: 'users-without-wallets',
          },
        },
      }}
    >
      <QueryClientProvider client={queryClient}>
        <WagmiProvider config={config}>
          <Pay
            apiKey="YOUR_API_KEY"
            to={{
              recipient: "0x...",
              currency: "USDC",
              chain: "arbitrum",
              amount: "1000",
            }}
          />
        </WagmiProvider>
      </QueryClientProvider>
    </PrivyProvider>
  )
}

Multiple Wallet Support

Combine multiple wallet connectors to give users choice:

import { createConfig, http, WagmiProvider } from 'wagmi'
import { mainnet, base, arbitrum } from 'wagmi/chains'
import { injected, walletConnect } from 'wagmi/connectors'
import { sequenceWallet } from '@0xsequence/wagmi-connector'
import { createPrivyWalletConnector } from '@privy-io/wagmi-connector'
import { PrivyProvider } from '@privy-io/react-auth'
import { Pay } from '0xtrails/widget'

// Create all connectors
const sequenceConnector = sequenceWallet({
  connectOptions: {
    app: "Your App",
    apiKey: "your-sequence-key",
  },
  defaultNetwork: 1,
})

const privyConnector = createPrivyWalletConnector({
  appId: "your-privy-app-id",
  name: "Privy",
})

const config = createConfig({
  chains: [mainnet, base, arbitrum],
  connectors: [
    injected(),
    walletConnect({ projectId: 'your-walletconnect-project-id' }),
    sequenceConnector,
    privyConnector,
  ],
  transports: {
    [mainnet.id]: http(),
    [base.id]: http(),
    [arbitrum.id]: http(),
  },
})

export function MultiWalletApp() {
  return (
    <PrivyProvider
      appId="your-privy-app-id"
      config={{
        loginMethods: ["email", "google"],
        embeddedWallets: { createOnLogin: "all-users" },
      }}
    >
      <WagmiProvider config={config}>
        <Pay
          apiKey="YOUR_API_KEY"
          to={{
            recipient: "0x...",
            currency: "USDC",
            chain: "arbitrum",
            amount: "1000",
          }}
        />
      </WagmiProvider>
    </PrivyProvider>
  )
}

Supported Wallet Types

Trails works with all wagmi-compatible wallets including:

• Injected Wallets: MetaMask, Coinbase Wallet, Brave Wallet
• WalletConnect: Any wallet supporting WalletConnect protocol
• Smart Contract Wallets: Sequence, Safe, Biconomy
• Embedded Wallets: Privy, Dynamic, Magic
• Mobile Wallets: Rainbow, Trust Wallet, Phantom
• Hardware Wallets: Ledger, Trezor (via connectors)

Key Benefits

• Universal Compatibility: Works with any wagmi connector
• 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 existing wallet infrastructure
• Future-Proof: Automatically supports new wagmi connectors

For more configuration options, see our Configuration Guide.