Skip to main content

Integrate Keyban SDK into an Existing React Application

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
  • React 18+ with a Suspense boundary (required by the SDK hooks)
  • Node.js and npm installed
  • An existing React project
  • A Keyban App ID
  • A client share provider endpoint (optional)

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 { KeybanNetwork } from '@keyban/sdk-react';

const config = {
  keybanProvider: {
    appId: "your-keyban-app-id",  // Replace with your own App ID
    network: KeybanNetwork.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 the built-in ClientShareProvider​

The easiest option is to use the built-in ClientShareProvider. To do so, simply do not specify any clientShareProvider option.

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 ClientShareProvider to simplify the setup.

Add a Suspense boundary​

Keyban React hooks use React Suspense to manage async data. Wrap components that consume the SDK hooks (or your app layout/route) in a <Suspense> boundary.

Component Example​

src/Wallet.tsx
import React, { Suspense } from 'react';
import {
  KeybanProvider,
  useKeybanAccount,
  useKeybanAccountBalance,
  useKeybanAuth,
  KeybanNetwork
} 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 = () => (
  <Suspense fallback={<div>Loading wallet…</div>}>
    <KeybanProvider
      appId="your-keyban-app-id"
      network={KeybanNetwork.PolygonAmoy}
    >
      <WalletContent />
    </KeybanProvider>
  </Suspense>
);

export default Wallet;

Explanation​

  • The component now uses the built-in ClientShareProvider, 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.
tip

You can place the <Suspense> boundary higher in your app (e.g., around your router or layout) to cover multiple SDK-powered components.

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.