@0xtrails/adapter-wagmi

Use Trails with wagmi.

This adapter lets Trails use the wagmi setup your app already has. Use it when your app owns WagmiProvider, chains, transports, and connectors, and you want the Trails widget or hooks to share that wallet state. The primary integration target is wagmi 3, with wagmi 2 kept as a compatibility target.

The adapter auto-detects a surrounding WagmiProvider by default:

• surrounding WagmiProvider and no wagmiConfig option → bridge into the host-owned wagmi runtime
• same wagmiConfig instance as the surrounding WagmiProvider → bridge into the host-owned wagmi runtime
• no matching surrounding WagmiProvider and a wagmiConfig option → mount an adapter-owned wagmi runtime with the provided config

For a truly separate Trails-owned runtime, create and pass a separate wagmi config instance.

Install

npm install 0xtrails @0xtrails/adapter-wagmi wagmi viem @tanstack/react-query

Supported wagmi versions:

• Primary: wagmi@^3.2.0
• Compatibility: wagmi@^2.19.0

The package peer range remains wagmi@^2.19.0 || ^3.2.0 so existing wagmi 2 hosts can keep using the same adapter.

Quick start: widget with your wagmi provider

import { TrailsWidget } from '0xtrails'
import { wagmiAdapter } from '@0xtrails/adapter-wagmi'
import { WagmiProvider } from 'wagmi'

const apiKey = 'YOUR_TRAILS_API_KEY'

// Automatically uses the surrounding WagmiProvider.
const adapters = [wagmiAdapter()]

export function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <TrailsWidget apiKey={apiKey} adapters={adapters} renderInline />
    </WagmiProvider>
  )
}

You only need to pass wagmiConfig when Trails should be able to mount an adapter-owned wagmi runtime fallback.

App-level setup with TrailsProvider

Use this when Trails hooks and the widget should share the same adapter.

import { TrailsProvider, TrailsWidget } from '0xtrails'
import { wagmiAdapter } from '@0xtrails/adapter-wagmi'
import { WagmiProvider } from 'wagmi'

const apiKey = 'YOUR_TRAILS_API_KEY'
const adapters = [wagmiAdapter()]

export function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <TrailsProvider config={{ trailsApiKey: apiKey, adapters }}>
        <TrailsWidget renderInline />
      </TrailsProvider>
    </WagmiProvider>
  )
}

Runtime ownership

managedBy is only needed when you pass multiple adapters as wrapped entries. It controls wallet lifecycle ownership in Trails, not whether the wagmi adapter bridges to a parent provider.

const hostAdapter = wagmiAdapter({ wagmiConfig: hostWagmiConfig })
const trailsAdapter = wagmiAdapter({ wagmiConfig: trailsWagmiConfig })

const adapters = [
  { adapter: hostAdapter, managedBy: 'host' },
  { adapter: trailsAdapter, managedBy: 'trails' },
]

Use managedBy: 'host' when Trails can use the wallet but should not own its lifecycle, for example hiding disconnect actions for a host-controlled wallet. Use managedBy: 'trails' for wallet options that Trails should own.

Optional: custom wallet labels

Pass wallets if you want to control how a host wallet appears in Trails. name and icon replace the catalog's label and logo everywhere Trails shows the wallet: the connect list, the connected chip, the funding selector and the recipient rows.

const adapters = [
  wagmiAdapter({
    wagmiConfig,
    wallets: [
      {
        id: 'host-wallet',
        name: 'My Wallet',
        icon: 'https://my.app/wallet.png',
        flow: 'direct',
        placement: 'featured',
      },
    ],
  }),
]

Branding an embedded wallet as your own

Embedded wallets (Privy, Sequence) are host-login identities, so Trails never lists them on its own; a host opts one in with a featured descriptor. The same descriptor is where you rename it. Users of an app built on Privy should see the app's wallet, not Privy's:

wagmiAdapter({
  wagmiConfig: privyWagmiConfig,
  wallets: [
    {
      id: 'privy',
      name: 'XYZ Wallet',
      icon: 'https://xyz.app/wallet.png',
      flow: 'embedded',
      placement: 'featured',
      connect: connectPrivyEmbedded,
    },
  ],
})

Trails resolves any @privy-io/wagmi connector to the id privy, so the descriptor matches the connection whether the user connected through Trails or was already signed in. Privy's own login modal and its "Protected by Privy" footer are configured in the Privy dashboard, outside Trails.

Tips

• Put adapters on TrailsProvider config.adapters for app-level setup.
• Put adapters on TrailsWidget adapters for widget-only setup.
• Do not pass adapters in both places at the same time.
• Use wagmiAdapter() when Trails should auto-detect and share your existing wagmi runtime.
• Pass the same wagmiConfig instance when Trails should share that runtime but still have an adapter-owned fallback.
• Use a separate wagmiConfig instance when Trails should mount a separate adapter-owned runtime.
• managedBy controls lifecycle ownership in composite adapter lists; it does not override wagmi runtime matching.

License

Apache-2.0