Skip to main content

Integrate Keyban SDK into Your React App

This guide walks you through integrating the Keyban SDK into an existing React app to display a user's wallet and native balance.

What You’ll Learn​

By the end of this tutorial, you'll have a wallet component that shows a user's public address and native token balance using the Keyban SDK.

Prerequisites​

  • Familiarity with React
  • Node.js and npm installed
  • An existing React project
  • A Keyban App ID
  • A client share provider endpoint or use of the KeybanClientShareProvider

Step 1: Install the Keyban SDK​

In your project directory, run the following command to install the SDK:

npm install @keyban/sdk-react

Step 2: Set Up the Configuration​

Create a config.ts file in your src/ directory and configure the Keyban SDK:

src/config.ts
import { KeybanChain } from '@keyban/sdk-react';

const config = {
  keybanProvider: {
    appId: "your-keyban-app-id",  // Replace with your own App ID
    chain: KeybanChain.PolygonAmoy, // Use the desired chain
  },
};

export default config;
info

If you need more information about KeybanProvider and its configuration options, you can refer to the KeybanProvider documentation.

Step 3: Choose a Client Share Provider​

Option A: Use KeybanClientShareProvider​

The easiest option is to use the built-in KeybanClientShareProvider.

src/config.ts
import { KeybanClientShareProvider } from '@keyban/sdk-react';

const clientShareProvider = new KeybanClientShareProvider();

Option B: Create a Custom Client Share Provider​

If you need custom handling of client shares, implement your own ClientShareProvider:

src/ClientShareProvider.ts
import { ClientShareProvider } from '@keyban/sdk-base';

export class MyClientShareProvider implements ClientShareProvider {
  async get(): Promise<string | null> {
    // Replace with your API endpoint or secure storage
    return fetch("/api/clientShare").then((res) => res.json());
  }

  async set(clientShare: string): Promise<void> {
    // Save the client share securely
    await fetch("/api/clientShare", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ clientShare }),
    });
  }
}
note

The /api/clientShare endpoint (or any custom endpoint you define) is mandatory. This endpoint is responsible for securely saving and restoring client shares for end users. Make sure you implement proper security and authentication.

info

Refer to the ClientShareProvider documentation for more details.

Step 4: Create the Wallet Component with Authentication​

In this step, you'll create a new component Wallet.tsx to display wallet details. We'll use the built-in KeybanClientShareProvider to simplify the setup.

Component Example​

src/Wallet.tsx
import React from 'react';
import {
  KeybanProvider,
  useKeybanAccount,
  useKeybanAccountBalance,
  useKeybanAuth,
  KeybanClientShareProvider,
  KeybanChain
} from '@keyban/sdk-react';

const WalletContent = () => {
  const { login, logout, isAuthenticated } = useKeybanAuth();
  const [account] = useKeybanAccount();
  const [balance] = useKeybanAccountBalance(account);

  if (!isAuthenticated) {
    return (
      <div>
        <p>You are not logged in.</p>
        <button onClick={login}>Log in</button>
      </div>
    );
  }

  return (
    <div>
      <button onClick={logout}>Log out</button>
      <p>Address: {account?.address}</p>
      <p>Balance: {balance}</p>
    </div>
  );
};

const Wallet = () => {
  return (
    <KeybanProvider
      appId="your-keyban-app-id"
      chain={KeybanChain.PolygonAmoy}
      clientShareProvider={React.useMemo(() => new KeybanClientShareProvider(), [])}
    >
      <WalletContent />
    </KeybanProvider>
  );
};

export default Wallet;

Explanation​

  • The component now uses KeybanClientShareProvider, which handles client share storage automatically via Keyban’s API, reducing the need for custom logic.
  • The hooks useKeybanAccount, useKeybanAccountBalance, and useKeybanAuth provide wallet and authentication state.
  • The component renders the user's wallet address and balance once authenticated.

Step 5: Add the Wallet Component to Your App​

Integrate the Wallet component into your App.tsx:

src/App.tsx
import React from 'react';
import Wallet from './Wallet';

const App = () => (
  <div>
    <h1>My Wallet</h1>
    <Wallet />
  </div>
);

export default App;

Step 6: Run the Application​

Start your development server:

npm run dev

Visit http://localhost:5173/ to see your wallet and balances displayed.

Conclusion​

Congratulations! You’ve successfully integrated the Keyban SDK into your React app. For advanced features such as transferring tokens or interacting with NFTs, explore the Keyban React SDK Documentation.