web3_auth_client_sdk

React and TypeScript SDK for Web3 wallet authentication against the Web3 Identity backend.

What this package provides

• AuthProvider for auth state and session lifecycle
• useAuth for login, logout, refresh, and current user access
• useWallet for injected wallet connect and chain switching
• WalletButton and LoginButton helpers for quick integration

Requirements

• Node.js >=18
• React >=18
• React DOM >=18
• A browser wallet that exposes an EIP-1193 provider such as MetaMask
• A bundler/runtime that supports modern ESM packages such as Vite, Next.js, or a current React toolchain
• A compatible backend that serves these endpoints:
  • POST /auth/nonce
  • POST /auth/verify
  • GET /auth/me
  • POST /auth/refresh
  • POST /auth/logout if you want remote logout support

Before integrating

Developers should confirm these assumptions before using the package in an app:

• The backend returns the envelope { success, data | error }
• The backend sends a wallet signing message from /auth/nonce
• The frontend can reach the backend URL from the browser
• The target chain is one of the supported chain IDs
• The user has an injected wallet available in the browser

Supported chains

• Ethereum 1
• Polygon 137
• Base 8453
• Arbitrum 42161

Installation

From npm or a tarball:

npm install web3_auth_client_sdk

For local tarball testing:

npm run prepare:npm-package
cd npm-package
npm pack

Then install the generated tarball from another project:

npm install ../path-to/web3_auth_client_sdk-0.0.1.tgz

Quick start

import { AuthProvider, WalletButton, useAuth } from 'web3_auth_client_sdk';

function Profile() {
  const { user, isAuthenticated, logout } = useAuth();

  if (!isAuthenticated) {
    return <p>Not signed in</p>;
  }

  return (
    <div>
      <p>Wallet: {user?.wallet}</p>
      <button type="button" onClick={() => void logout()}>
        Log out
      </button>
    </div>
  );
}

export default function App() {
  return (
    <AuthProvider apiUrl={import.meta.env.VITE_API_URL}>
      <WalletButton />
      <Profile />
    </AuthProvider>
  );
}

Manual login example

If you want more control than WalletButton, use useWallet() and useAuth() directly:

import { BrowserProvider } from 'ethers';
import { useAuth, useWallet } from 'web3_auth_client_sdk';

export function ManualLogin() {
  const auth = useAuth();
  const wallet = useWallet();

  const handleLogin = async () => {
    if (!window.ethereum) {
      throw new Error('No browser wallet found');
    }

    const nextWallet = wallet.isConnected
      ? { address: wallet.address ?? '', chainId: wallet.chainId }
      : await wallet.connect();

    const provider = new BrowserProvider(window.ethereum);
    const signer = await provider.getSigner();

    await auth.login({
      walletAddress: nextWallet.address,
      chain: nextWallet.chainId?.toString(),
      signMessage: (message) => signer.signMessage(message),
    });
  };

  return (
    <button type="button" onClick={() => void handleLogin()} disabled={auth.isLoading || wallet.isConnecting}>
      Sign in manually
    </button>
  );
}

If you do not want to rely on WalletButton, this is the path to document in your application.

Environment

Your app should provide the backend base URL, for example:

VITE_API_URL=http://localhost:3000

Then pass it to the provider:

<AuthProvider apiUrl={import.meta.env.VITE_API_URL}>{/* app */}</AuthProvider>

Authentication flow

1. Connect a wallet with useWallet().connect() or WalletButton.
2. Request a nonce from POST /auth/nonce.
3. Sign the backend message with the connected wallet.
4. Exchange the signature at POST /auth/verify.
5. Store the access token in memory only.
6. Load the current user with GET /auth/me.

API surface

AuthProvider

Props:

• apiUrl: string
• children: React.ReactNode

useAuth()

Returns:

• user
• isAuthenticated
• isLoading
• error
• login({ walletAddress, signMessage, chain })
• logout()
• refreshSession()
• Throws if used outside AuthProvider

useWallet()

Returns:

• address
• chainId
• isConnected
• isConnecting
• error
• connect()
• disconnect()
• switchChain(chainId)

WalletButton

WalletButton combines wallet connection and auth login into one button. It:

• connects the wallet if needed
• requests a backend nonce
• signs the backend message
• logs out and clears local wallet state when already authenticated

LoginButton

LoginButton is a smaller sign-in helper that triggers wallet connect and auth.login() without the disconnect behavior used by WalletButton.

Security notes

• JWTs are kept in memory only.
• This package does not write tokens to localStorage or sessionStorage.
• Production backends should be served over HTTPS.
• Signature verification must happen on the backend.

Troubleshooting

useAuth must be used within an AuthProvider

Wrap your app or feature subtree with AuthProvider before calling useAuth() or rendering WalletButton.

No wallet found

Install MetaMask or another browser wallet that exposes window.ethereum.

Connected wallet is on an unsupported network

Switch the wallet to one of the supported chains before logging in.

Session expired

The backend likely returned 401, INVALID_TOKEN, or a failed refresh response. The SDK clears the in-memory session automatically.

Login fails after signing

Check that the backend message returned from /auth/nonce matches the message the backend expects to verify.