Wagmi is a collection of React Hooks for Ethereum, making it easier to build Web3 applications. This guide will show you how to integrate Capsule’s wallet and signing capabilities with both Wagmi v2 (recommended) and v1.

​
Prerequisites

Before integrating Capsule with Wagmi, ensure you have:

  • Set up authentication with Capsule. See our Getting Started guides for details.
  • Configured the Capsule client in your application
  • A React application set up with React 18 or higher

If you haven’t set up Capsule authentication yet, complete one of our authentication tutorials first and return to this guide when you’re ready to implement Wagmi integration.

​
Wagmi v2

​
Installation

Choose your preferred package manager to install the required dependencies:

​
Usage

First, set up the required providers and configurations:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { capsuleConnector } from "@usecapsule/wagmi-v2-integration";
import { OAuthMethod } from "@usecapsule/web-sdk";
import { createConfig, WagmiProvider, type CreateConfigParameters } from "wagmi";
import { http } from "wagmi";
import { sepolia } from "wagmi/chains";
import { capsuleClient } from "./capsuleClient"; // Your Capsule client initialization

// Create Capsule connector
const connector = capsuleConnector({
  capsule: capsuleClient,
  chains: [sepolia], // Add your supported chains
  appName: "Your App Name",
  options: {},
  nameOverride: "Capsule",
  idOverride: "capsule",
  oAuthMethods: Object.values(OAuthMethod),
  disableEmailLogin: false,
  disablePhoneLogin: false,
  onRampTestMode: true,
});

// Configure Wagmi
const config: CreateConfigParameters = {
  chains: [sepolia],
  connectors: [connector],
  transports: {
    [sepolia.id]: http(),
  },
};

const wagmiConfig = createConfig(config);
const queryClient = new QueryClient();

Then, implement your components using Wagmi hooks:

import { useAccount, useConnect, useDisconnect } from "wagmi";

function AuthContent() {
  const { connect, connectors } = useConnect();
  const { address, isConnected } = useAccount();
  const { disconnect } = useDisconnect();

  if (isConnected) {
    return (
      <div>
        <p>Connected as {address}</p>
        <button onClick={() => disconnect()}>Disconnect</button>
      </div>
    );
  }

  return (
    <div>
      {connectors
        .filter((connector) => connector.id === "capsule")
        .map((connector) => (
          <button
            key={connector.id}
            onClick={() => connect({ connector })}>
            Connect with {connector.name}
          </button>
        ))}
    </div>
  );
}

Always ensure your components using Wagmi hooks are wrapped with both WagmiProvider and QueryClientProvider.

​
Wagmi v1 (Legacy)

​
Installation

Install the v1-specific integration package:

​
Usage

Set up the Wagmi v1 provider:

import { capsuleConnector } from "@usecapsule/wagmi-v1-integration";
import { configureChains, createClient, WagmiConfig } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";
import { publicProvider } from "wagmi/providers/public";
import { capsuleClient } from "./capsuleClient";

// Configure chains and providers
const { chains, provider } = configureChains([mainnet, sepolia], [publicProvider()]);

// Create Wagmi client
const client = createClient({
  autoConnect: true,
  connectors: [
    capsuleConnector({
      capsule: capsuleClient,
      chains,
      options: {},
      appName: "Your App Name",
      nameOverride: "Capsule",
      idOverride: "capsule",
      oAuthMethods: Object.values(OAuthMethod),
      disableEmailLogin: false,
      disablePhoneLogin: false,
      onRampTestMode: true,
    }),
  ],
  provider,
});

Example component using v1 hooks:

import { useAccount, useConnect, useDisconnect } from "wagmi";

function Profile() {
  const { address, isConnected } = useAccount();
  const { connect, connectors } = useConnect();
  const { disconnect } = useDisconnect();

  if (isConnected) {
    return (
      <div>
        Connected to {address}
        <button onClick={() => disconnect()}>Disconnect</button>
      </div>
    );
  }

  return <button onClick={() => connect({ connector: connectors[0] })}>Connect Wallet</button>;
}

​
Server-Side Usage

Wagmi is designed for client-side usage. For server-side signing with Capsule, please refer to our Server-Side Signing Guide for specific instructions.

Wagmi hooks should only be used in client-side components. For server-side signing operations, use our dedicated server-side SDKs.

​
Additional Resources

Was this page helpful?

ViemBlocknative Web3-Onboard