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";
const connector = capsuleConnector({
capsule: capsuleClient,
chains: [sepolia],
appName: "Your App Name",
options: {},
nameOverride: "Capsule",
idOverride: "capsule",
oAuthMethods: Object.values(OAuthMethod),
disableEmailLogin: false,
disablePhoneLogin: false,
onRampTestMode: true,
});
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";
const { chains, provider } = configureChains([mainnet, sepolia], [publicProvider()]);
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
