​
Creating a Wallet

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.

Currently, we don’t support connecting users’ existing self-custodial wallets. This is coming soon.

Right now, we only support embedded wallets, which are generated on behalf of the user by our non-custodial wallet partner.

You could use Civic’s embeddedWallet() wagmi connector alongside other connectors like Metamask, so your code can switch between Civic embedded wallets and the user’s other installed wallets. Currently those wallets cannot be linked to the Civic account, they are separate.

Neither Civic nor your app ever has access to the wallets’ private keys.

Here’s a basic example:

Complete examples can be found on github:

import { userHasWallet } from "@civic/auth-web3";
import { useUser } from "@civic/auth-web3/react";

export const afterLogin = async () => {
  const userContext = await useUser();

  if (userContext.user && !userHasWallet(userContext)) {
    await userContext.createWallet();
  }
};

​
The useUser hook and UserContext Object

The useUser hook returns a user context object that provides access to the base library’s user object 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 the user does not yet have a wallet:

type NewWeb3UserContext = UserContext & {
  createWallet: () => Promise<void>;
  walletCreationInProgress: boolean;
}

An easy way to distinguish between the two is to use the userHasWallet type guard.

if (userHasWallet(userContext)) {
  user.ethereum.wallet; // user has a wallet
} else {
  user.createWallet();// user does not have a wallet
}

​
Using the Wallet

The Civic Auth Web3 SDK uses Wagmi and Viem to expose the embedded wallet to your app, simplifying wallet interactions on both the front end and back end.

  • React Apps: Civic Auth is optimized for React, with easy access to Wagmi hooks for a seamless experience.

  • Non-React Apps: For non-React frameworks, use Viem directly to interact with the wallet.

​
Using the Wallet with Wagmi

To use the embedded wallet with Wagmi, follow these steps:

Prerequisites

Follow the Wagmi documentation to learn how to set up your app with Wagmi.

Ensure you have created the user’s wallet first as described above.

​
1. Add the Embedded Wallet to Wagmi Config

Include embeddedWallet() in your Wagmi configuration as shown below:

import { embeddedWallet } from "@civic/auth-web3/wagmi";

import { mainnet } from "viem/chains";
import { Chain, http } from "viem";
import { createConfig, WagmiProvider } from "wagmi";

const wagmiConfig = createConfig({
  chains: [mainnet],
  transports: {
      [mainnet.id]: http()
  },
  connectors: [
    embeddedWallet(),
  ],
});

​
2. Connect the wallet

​
Autoconnect

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.

const { connectors, connect } = useConnect();

const connectWallet = () => connect({
// connect to the "civic" connector
  connector: connectors[0],
});

​
3. Use Wagmi Hooks

Once connected, you can use Wagmi hooks to interact with the embedded wallet. Common hooks include:

  • useBalance: Retrieve the wallet balance.

  • useAccount: Access account details.

  • useSendTransaction: Send transactions from the wallet.

  • useSignMessage: Sign messages with the wallet.

For more detailed documentation on how to use these hooks, see the Wagmi docs.

​
A Full Example

See below for a full minimal example of a Wagmi app using Civic Auth for an embedded wallet. This is based on this GitHub repository that contains a sample implementation.

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WagmiProvider, createConfig, useAccount, useConnect, useBalance, http } from "wagmi";
import { userHasWallet } from "@civic/auth-web3";
import { embeddedWallet } from "@civic/auth-web3/wagmi";
import { CivicAuthProvider, UserButton, useUser } from "@civic/auth-web3/react";
import { mainnet, sepolia } from "wagmi/chains";

const wagmiConfig = createConfig({
  chains: [ mainnet, sepolia ],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
  connectors: [
    embeddedWallet(),
  ],
});

// Wagmi requires react-query
const queryClient = new QueryClient();

// Wrap the content with the necessary providers to give access to hooks: react-query, wagmi & civic auth provider
// initialChain is passed into <CivicAuthProvider /> to indicate the first chain you want to use.
// The chain can be switched later using wagmi's useSwitchChain() hook.
const App = () => {
  return (
    <QueryClientProvider client={queryClient}>
      <WagmiProvider config={wagmiConfig}>
        <CivicAuthProvider clientId="< YOUR CLIENT ID >" initialChain={mainnet}>
          <AppContent />
        </CivicAuthProvider>
      </WagmiProvider>
    </QueryClientProvider>
  );
};

// Separate component for the app content that needs access to hooks
const AppContent = () => {
  // Add the civic hooks
  const userContext = useUser();
  useAutoConnect();

  // Add the wagmi hooks
  const { isConnected, address } = useAccount();
  const balance = useBalance({ address });

  return (
    <>
      <UserButton />
      {userContext.user &&
        <div>
          {!userHasWallet(userContext) &&
            <p><button onClick={createWallet}>Create Wallet</button></p>
          }
          {userHasWallet(userContext) &&
            <>
              <p>Wallet address: {userContext.eth.address}</p>
              <p>Balance: {
                balance?.data
                  ? `${(BigInt(balance.data.value) / BigInt(1e18)).toString()} ${balance.data.symbol}`
                  : "Loading..."
              }</p>
              {isConnected ? <p>Wallet is connected</p> : (
                <button onClick={connectExistingWallet}>Connect Wallet</button>
              )}
            </>
          }
        </div>
      }
    </>
  );
};

export default App;

​
Using the Wallet with Viem

If you are not using Wagmi, you may also use Viem directly to access the same wallet capabilities:

const userContext  = useUser();

if (userContext.user && userHasWallet(userContext)) {
  const { wallet } = userContext.ethereum;
  const hash = await wallet.sendTransaction({
    to: "0x...",
    value: 1000n
  })
}

Full documentation for Viem can be found here.

​
Using Viem without React

Our SDK is currently being adapted to support other frontend frameworks beyond React.

Contact us if you have questions about integrating Civic Auth Web3 with a different framework.

​
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. Pass the initialChain property to define the chain you want to start using.

​
Example 1. Using viem chain objects

import { mainnet, polygon } from "viem/chains";
<CivicAuthProvider chains={[mainnet, polygon]} initialChain={mainnet}>

​
The chain can be switched using wagmi’s useSwitchChain hook:

import { useSwitchChain } from "wagmi";

// Switch chain to polygon
switchChain({
   chainId: polygon.id,
});

​
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
        }
    }
}}>