Civic Docs
Civic Auth
Civic Auth
  • 🔏Civic Auth
  • Integration
    • React
    • Next.JS
    • Node.JS
      • Express
      • Hono
      • Fastify
    • Other OIDC / OAuth 2.0-Compliant Environments
    • FAQs
    • Error Codes
    • Bring Your App to Production
  • Web3
    • Embedded Wallets
    • Ethereum / EVM
    • Solana
Powered by GitBook
On this page
  • Creating a Wallet
  • The useUser hook and UserContext Object
  • Using the Wallet
  • Using the Wallet with Wagmi
  • A Full Example
  • Using the Wallet with Viem
  • Configuration
  • Limiting to specific chains

Was this helpful?

  1. Web3

Ethereum / EVM

PreviousEmbedded WalletsNextSolana

Last updated 4 days ago

Was this helpful?

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. 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

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

  • 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

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.

A Full Example

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

const userContext  = useUser();

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

Using Viem without React

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

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:

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.

Vite + Wagmi
NextJS + Wagmi
Wagmi
Viem
Wagmi documentation
Wagmi docs
this GitHub repository
Viem
here
Contact us
above
user object