- Civic Auth Client Web3 SDK
- Embedded Wallets
- Quick Start
- Installation
- npm
- yarn
- pnpm
- bun
- Integration
- Deep Linking
- Ethereum / EVM
- Creating and retrieving existing wallets
- client-side
- server-side
- The useUser hook and UserContext Object
- Using the Wallet
- Using the Wallet with Wagmi
- 1. Add the Embedded Wallet to Wagmi Config
- Call connect
- Use Wagmi Hooks
- A Full Example
- Using the Wallet with Viem
- Using Viem without React

Civic Auth Client Web3 SDK

Civic Auth Web3 offers a simple, flexible, and fast way to integrate authentication with Web3 features into your applications.

You can find the full, official documentation here, with a quick-start version in this README.

Embedded Wallets

The Civic Auth Web3 SDK (@civic/auth-web3) extends the functionality of the base Civic Auth SDK by including the ability to provision a Web3 wallet for users. This allows Civic Auth apps to provide their users with access to the world of Cryptocurrencies and Web3 without any hassle or prior knowledge.

Quick Start

Sign up for Civic Auth at auth.civic.com and make sure to select the "web3 wallet" option.

If you already have an account, just log in and select the web3 wallet option in the configuration to enable web3 wallets.

Installation

Install the Civic Auth Web3 SDK:

$3

``bash
npm install @civic/auth-web3
`

$3

`bash
yarn add @civic/auth-web3
`

$3

`bash
pnpm install @civic/auth-web3
`

$3

`bash
bun add @civic/auth-web3
`

Integration

You need to set up a CivicAuthProvider in your application with the integration for the web3 library being identical to the setup for @civic/auth), except that you import from @civic/auth-web3 instead of @civic/auth i.e:

`typescript
import { CivicAuthProvider, UserButton } from "@civic/auth-web3/react";
`

Once the basic setup is done, you can access Web3 features by following the Embedded Wallet Web3 integration instructions below.

Deep Linking

Deep linking allows users to be redirected back to their original destination (including query parameters) after completing authentication. This is configured via the deepLinkHandling option in createCivicAuthPlugin:

`typescript
import { createCivicAuthPlugin } from "@civic/auth-web3/nextjs";

const withCivicAuth = createCivicAuthPlugin({
clientId: 'YOUR_CLIENT_ID',
deepLinkHandling: 'fullUrl' // or 'queryParamsOnly' or 'disabled'
});

export default withCivicAuth(nextConfig);
`

| Value | Description |
|-------|-------------|
| "fullUrl" | Preserves the full URL including path and query parameters |
| "queryParamsOnly" (default) | Preserves only query parameters, redirects to loginSuccessUrl after login |
| "disabled" | Disables deep linking entirely |

For Express/Fastify integration, use the handleDeepLinking method on CivicAuth:

`typescript
import { CivicAuth, CookieStorage } from '@civic/auth-web3/server';

// In your protected route middleware
if (!(await req.civicAuth.isLoggedIn())) {
const requestUrl = ${req.protocol}://${req.get("host")}${req.originalUrl};
const originUrl = ${req.protocol}://${req.get("host")};

await req.civicAuth.handleDeepLinking(requestUrl, originUrl);

const loginUrl = await req.civicAuth.buildLoginUrl();
return res.redirect(loginUrl.toString());
}
`

Ethereum / EVM

Creating and retrieving existing wallets

$3

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 from the user context. Here’s a basic example:

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

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

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

export const afterWalletCreation = async () => {
const wallets = await getWallets();

}
`

$3


When a user is available, the createWallet function can be called in a server call:
`
import { getUser, createWallet, getWallets } from '@civic/auth-web3/nextjs;

const user = await getUser({
endpoints: { wallet: WALLET_API_BASE_URL },
});

if (user && !userHasWallet(user)) {
await 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,

`typescript
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:

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

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

Using the Wallet

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

$3

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

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:

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

const wagmiConfig = createConfig({
chains: supportedChains,
transports: transports,
connectors: [
embeddedWallet(),
],
});
`

#### Call connect

Initiate the connection to the embedded wallet using Wagmi’s connect method.

`typescript
const { connectors, connect } = useConnect();

// connect to the "civic" connector
const connector = connectors[0];
connect(connector);
`

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

$3

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.

`typescript
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WagmiProvider, createConfig, useAccount, useConnect, useBalance, http } from 'wagmi';
import { embeddedWallet, userHasWallet } from '@civic/auth-web3';
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
const App = () => {
return (







);
};

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

// Add the wagmi hooks
const { connect, connectors } = useConnect();
const { isConnected } = useAccount();
const balance = useBalance({
address: userHasWallet(userContext) ? userContext.ethereum.address: undefined,
});

// A function to connect to an existing civic embedded wallet
const connectExistingWallet = () => connect({
connector: connectors[0],
});

// 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 it straight away
return userContext.createWallet().then(connectExistingWallet)
}
}

return (
<>

{userContext.user &&


}

);
};

export default App;
`

$3

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

`typescript
const userContext = useUser();

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

Full documentation for Viem can be found here.

#### Using Viem without React

While our SDK is 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.