Integrating with wagmi

wagmi is a set of React hooks for working with Ethereum wallets, allowing you do things like read addresses, request signatures, call smart contracts, and more.

Privy's wallet connectors and embedded wallets are fully compatible with wagmi; Privy even sponsors the project! In this guide, you'll find:

• steps to integrate wagmi alongside Privy
• a list of supported hooks from wagmi
• a demo app of wagmi's hooks with Privy

Integration steps

At a high-level, to use wagmi, you'll need to configure your chains and providers for wagmi, and then pass your configuration into the PrivyWagmiConnector component as shown below:

1. Install the necessary dependencies

To get started, install the wagmi and the latest version of @privy-io/wagmi-connector packages in your app:

npm i wagmi @privy-io/wagmi-connector

tip

Depending on your wagmi version, you should use a specific version of @privy-io/wagmi-connector:

• If your wagmi version is 1.0.0 or higher, you should use the latest version of @privy-io/wagmi-connector. At minimum, you must use version 0.1.0.
• If your wagmi version is 0.x.x, you should use version 0.0.12 of @privy-io/wagmi-connector. These versions are no longer actively maintained, but you can find docs for them here.

2. Build your wagmi chain configuration

At the root-level of your application (_app.jsx in NextJS or index.js in create-react-app), add the following imports and build your chain configuration object with wagmi's configureChains method:

import {PrivyWagmiConnector} from '@privy-io/wagmi-connector';
// You can import additional chains from 'wagmi/chains'
// https://wagmi.sh/react/chains
import {mainnet, goerli} from '@wagmi/chains';
import {configureChains} from 'wagmi';
// You may replace this with your preferred providers
// https://wagmi.sh/react/providers/configuring-chains#multiple-providers
import {publicProvider} from 'wagmi/providers/public';

// Replace the chains and providers with the ones used by your app.
// https://wagmi.sh/react/providers/configuring-chains
const configureChainsConfig = configureChains([mainnet, goerli], [publicProvider()]);

3. Add the PrivyWagmiConnector to your app

Lastly, wrap your components with the PrivyWagmiConnector, passing in the chain configuration object you just created into wagmiChainConfig property. Make sure that the PrivyWagmiConnector is nested inside the PrivyProvider component.

export default function App({Component, pageProps}: AppProps) {
  return (
    <PrivyProvider appId="your-privy-app-ID">
      <PrivyWagmiConnector wagmiChainsConfig={configureChainsConfig}>
        <Component {...pageProps} />
      </PrivyWagmiConnector>
    </PrivyProvider>
  );
}

4. Set the user's active wallet

Privy allows users to use multiple different wallets with your app, while wagmi allows your app to request signatures or transactions from a single wallet. To manage this difference, Privy introduces the concept of a wagmi active wallet to configure which wallet your wagmi hooks should apply to.

To get the user's current active wallet, simply use activeWallet returned by the usePrivyWagmi hook. All wagmi methods will apply to the user's active wallet. By default, when your app loads:

• If a user has an embedded wallet, that will be the activeWallet.
• If a user does not have an embedded wallet, the most recently used external wallet will be the activeWallet.
• If a user connects, links, or creates a new wallet, the new wallet will become the activeWallet.

To configure wagmi hooks to apply to a particular connected wallet, you should update the user's active wallet via the setActiveWallet method from the usePrivyWagmi hook. Simply find your desired wallet in the useWallets array, and pass the corresponding ConnectedWallet object to setActiveWallet.

You can see an example of getting and updating the active wallet below:

import {usePrivy, useWallets} from '@privy-io/react-auth';
import {usePrivyWagmi} from '@privy-io/wagmi-connector';

export default function MyComponent() {
  const {login, ready, authenticated} = usePrivy();
  const {wallets} = useWallets();
  const {wallet: activeWallet, setActiveWallet} = usePrivyWagmi();

  if (!ready) return null;

  if (!authenticated) {
    // Use Privy login instead of wagmi's connect
    return <button onClick={() => login()}>login</button>;
  }

  return (
    <div>
      <h2>Active Wallet {activeWallet?.address}</h2>
      <ul>
        {wallets.map((wallet) => (
          <li key={wallet.address}>
            <button onClick={() => setActiveWallet(wallet)}>Activate {wallet.address}</button>
          </li>
        ))}
      </ul>
    </div>
  );
}

That's it! Throughout your app, you can now import and use hooks from wagmi.

You can see the code examples all together here.

Supported hooks

Below is a list of wagmi hooks that Privy officially supports.

Full list of WAGMI hooks and their compatibility with Privy

Hook	Supported	Notes
useAccount	✅
useBalance	✅
useBlockNumber	✅
useConnect	❌	Instead of this, use login from Privy.
useContract	✅
useContractEvent	✅
useContractInfiniteReads	✅
useContractRead	✅
useContractReads	✅
useContractWrite	✅
useDisconnect	✅
useEnsAddress	✅
useEnsAvatar	✅
useEnsName	✅
useEnsResolver	✅
useFeeData	✅
useNetwork	✅
useProvider	✅
useSendTransaction	✅
useSigner	✅
useSignMessage	✅
useSignTypedData	✅
useSwitchNetwork	❌	Import wrapped hook of the same name from @privi-io/wagmi-connector.
useToken	✅
useTransaction	✅
useWaitForTransaction	✅
useWatchPendingTransactions	✅
useWebSocketProvider	❌	We are working on useWebSocketProvider support. Please reach out if you need this hook.

Demo app

Check out our wagmi demo app to see the hooks listed above in action.

Feel free to take a look at the app's source code to see an end-to-end implementation of Privy with wagmi.