Skip to content

Quick Start: Web3-React Apps

Already using Arcana Auth SDK?

Use the latest release: v1.0.9.

To upgrade Arcana Auth SDK v1.0.8 -> v1.0.9, see the Migration Guide. For versions older than Arcana Auth SDK v1.0.8, be aware of potential breaking changes that may require app reconfiguration and code updates. Check the Migration Guides and Release Notes for specifics.

Web3-React Apps

In addition to the latest Arcana Auth SDK, for Web3-React apps, you must also use the latest Arcana Auth Web3 React SDK release: v0.0.1


To implement Arcana Auth in a 'Web3-React' app, start by registering your app and configuring usage settings through Arcana Developer Dashboard. After that, install Arcana Auth SDK and Arcana Auth Web3 React SDK, integrate the app, and initialize the AuthProvider. You'll need to add code to initialize the ArcanaConnector and specify the AuthProvider. Next, use appropriate React hooks and call Arcana Auth SDK function to onboard users and allow authenticated users to sign blockchain transactions. Finally, deploy your app on the Testnet or Mainnet.

Auth Usage Overview Auth Usage Overview

Step 1: Register & Configure App

To register and configure your app, create a new entry for your app by logging into the Arcana Developer Dashboard:

Save the unique Client ID assigned to the app after registration. It will be required when you integrate the app with the Arcana Auth SDK. Also, configure the Arcana Auth product usage by specifying branding, setting up authentication providers, managing blockchains displayed in the wallet, and other settings as required.

See how to register and configure app using the Arcana Developer Dashboard for details.

After registering and configuring the app, install the requisite Arcana SDKs as per the app-type and use case.

Step 2: Install SDKs

For 'Web3-React' app, install the following packages:


npm install --save @arcana/auth-web3-react @arcana/auth


yarn add @arcana/auth-web3-react @arcana/auth


<script src=""></script>
<script src=""></script>
<script src=""></script>
<script src=""></script>

Watch Auth Releases

Get notified about newer auth releases by watching the auth GitHub repository.

Watch Auth-Web3-React SDK Releases

Get notified about newer auth-web3-react releases by [watching] ( the auth-web3-react GitHub repository.

Next, integrate the app with the installed SDKs.

Step 3: Integrate App

Begin app integration by importing AuthProvider from the auth package.

const { AuthProvider } = window.arcana.auth // From CDN
import { AuthProvider } from '@arcana/auth' //From npm

Create a new AuthProvider instance. Specify the unique Client ID obtained during the app registration.

const auth = new AuthProvider(
  "xar_test_445007f942xxxxxxxxxxxxxxxxxx484cAfd2", // App client ID
    position: 'left',         // default: right
    theme: 'light',           // default: dark
    alwaysVisible: false,     // default: true, wallet always visible
    setWindowProvider: true,  // default: false, window.ethereum not set
    connectOptions: {
      compact: true           // default: false, regular plug-and-play login UI
    chainConfig: {
      chainId: '137',                    // defaults to Ethereum
      rpcUrl: '', // defaults to ''
AuthProvider Optional Parameters

You can optionally customize the following settings in the AuthProvider constructor:

alwaysVisible: Arcana wallet visibility mode - always visible in the app context or only if a blockchain transaction is triggered by the app

chainConfig: use chainId to specify the chain identifier for the active chain in the wallet and rpcUrl for specifying the RPC Url for that chain identifier

position: wallet position within the app context - left|right

theme: wallet theme - light|dark

setWindowProvider: set window.ethereum in the app context with the standard EIP-1193 Ethereum provider value

connectOptions: built-in login UI compact mode - true|false

See AuthProvider constructor parameters for details.

Next, import the ArcanaConnector from the auth-web3-react package.

Initialize the ArcanaConnector by specifying the AuthProvider created earlier:

import { initializeConnector } from "@web3-react/core";
import { ArcanaConnector } from "@arcana/auth-web3-react";
import { AuthProvider } from "@arcana/auth";
import { URLS } from "../chains";

const auth = new AuthProvider(
export const [arcanaConnect, hooks] = initializeConnector<ArcanaConnector>(
  (actions) =>
    new ArcanaConnector(auth, {

The app is now integrated with the Arcana Auth SDK and the Arcana Auth Web3 React SDK. Next, add code to onboard users. You will need to use React hooks to enable AuthProvider functions via the ArcanaConnector.

import { useEffect, useState } from "react";

import { MAINNET_CHAINS } from "../../chains";
import { hooks, arcanaConnect } from "../../connectors/arcanaWallet";
import { Card } from "../Card";

const CHAIN_IDS = Object.keys(MAINNET_CHAINS).map(Number);

const {
} = hooks;

export default function ArcanaConnectCard() {
  const chainId = useChainId();
  const accounts = useAccounts();
  const isActivating = useIsActivating();

  const isActive = useIsActive();

  const provider = useProvider();
  const ENSNames = useENSNames(provider);

  const [error, setError] = useState(undefined);

  // attempt to connect eagerly on mount
  useEffect(() => {
    arcanaConnect.connectEagerly().catch((error) => {
      console.debug("Failed to connect eagerly to arcanaConnect", error);
  }, []);

  return (

Step 4: Onboard Users

import { initializeConnector } from "@web3-react/core";
import { ArcanaConnector } from "@arcana/auth-web3-react";
import { AuthProvider } from "@arcana/auth";
import { URLS } from "../chains";

const auth = new AuthProvider(
export const [arcanaConnect, hooks] = initializeConnector<ArcanaConnector>(
  (actions) =>
    new ArcanaConnector(auth, {

See sample Web3-React app for details.

Custom Login UI

You can onboard users through a custom login UI instead of the built-in plug-and-play one. See how to use custom login UI for onboarding users in a 'Web3-React' app for details.

Arcana JWT Token

Upon successful authentication, Arcana Auth SDK returns a unique JWT token to the app called the Arcana JWT Token. App developers can use this token to verify user login and subsequently generate another token for app use. Learn more about how to verify the Arcana JWT Token for apps deployed on Testnet and Mainnet.

That's all!!!

Your 'Web3-React' app is now powered by Arcana Auth.

Next Steps

After adding code to onboard users, you can optionally use the standard JSON RPC Web3 wallet operations supported by the AuthProvider. See how to enable Web3 operations using the Arcana wallet for details.

Manage the user experience for signing blockchain transactions by selecting the default, built-in Arcana wallet UI and tinkering with the wallet visibility or replacing the built-in wallet with a custom wallet UI.

To learn how to deploy the app on Testnet/Mainnet, see App Deployment Guide.


For a sample 'Web3-React' app that integrates with the Arcana Auth SDK, refer to 'sample-auth-web3-react' in the GitHub repo: Auth Examples.

See Also

SDK Release Details

Arcana Auth SDK

See the latest Arcana Auth SDK release notes, refer to the GitHub Repo changelog and download the auth.

Arcana Gasless (Standalone) SDK

See the latest Arcana Gasless (Standalone) SDK release notes, refer to the GitHub Repo changelog and download the Arcana Gasless (Standalone) SDK.

Last update: December 1, 2023 by shalz