When a new user logs in, they do not yet have a Web3 wallet by default. You can create a wallet for them by calling the createWallet function on the user object. Here’s a basic example:
The useUser hook returns a user context object that provides access to the base library's in the 'user' field, and adds some Web3 specific fields. The returned object has different types depending on these cases:
If the user has a wallet,
type ExistingWeb3UserContext = UserContext & {
ethereum: {
address: string // the address of the embedded wallet
wallet: WalletClient // a Viem WalletClient
}
}
If you want to automatically connect the civic wallet as soon as the user has logged in, you can use the useAutoConnect() hook:
import { useAutoConnect } from "@civic/auth-web3/wagmi";
useAutoConnect();
This hook also creates the wallet, if it is a new user.
Manual
If you want a little more control, first create the wallet,
import { userHasWallet } from "@civic/auth-web3";
import { embeddedWallet } from "@civic/auth-web3/wagmi";
import { CivicAuthProvider, UserButton, useUser } from "@civic/auth-web3/react";
// A function that creates the wallet if the user doesn't have one already
const createWallet = () => {
if (userContext.user && !userHasWallet(userContext)) {
// Once the wallet is created, we can connect to it
return userContext.createWallet().then(connectWallet)
}
}
then initiate the connection to the embedded wallet using Wagmi’s connect method.
Our SDK is currently being adapted to support other frontend frameworks beyond React.
Configuration
The library works out of the box without additional configuration.
If you need to customize the library's behavior, you can pass additional configuration options to the CivicAuthProvider component. Here is an example:
Limiting to specific chains
By default, Civic Auth supports all chains supported by viem. If you want to restrict wallet usage to specific chains, you can pass an array of chains to the CivicAuthProvider.
Example 1. Using viem chain objects
import { mainnet, polygon } from "viem/chains";
<CivicAuthProvider chains={[mainnet, polygon]}>
Example 2. Specifying custom RPCs
import { mainnet, polygon } from "viem/chains";
<CivicAuthProvider endpoints={{
rpcs: {
[mainnet.id]: {
http: [<your mainnet HTTP RPC URL>],
webSocket: [<your mainnet WS RPC URL>], // or omit if not available
},
[polygon.id]: {
http: [<your polygon HTTP RPC URL>],
webSocket: [<your polygon WS RPC URL>], // or omit if not available
}
}
}}>
The Civic Auth Web3 SDK uses and to expose the embedded wallet to your app, simplifying wallet interactions on both the front end and back end.
Follow the to learn how to set up your app with Wagmi.
Ensure you have created the user's wallet first as described .
For more detailed documentation on how to use these hooks, see the .
See below for a full minimal example of a Wagmi app using Civic Auth for an embedded wallet. This is based on that contains a sample implementation.
If you are not using Wagmi, you may also use directly to access the same wallet capabilities:
Full documentation for Viem can be found .
if you have questions about integrating Civic Auth Web3 with a different framework.