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 balance on the Ethereum Sepolia testnet.

What You’ll Learn​

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

Prerequisites​

  • Basic knowledge of React
  • Node.js and npm installed
  • An existing React project

Step 1: Install the Keyban SDK​

In your project directory, run the following command to install the SDK and a library for handling errors:

npm install @keyban/sdk-react react-error-boundary

Checkpoint​

At this point, the Keyban SDK is installed in your project.

Step 2: Set Up the Configuration​

Now let's set up the Keyban SDK configuration. Create a config.ts file in your src/ directory and add the following configuration:

import { KeybanChain, KeybanLocalStorage, KeybanSigner } from '@keyban/sdk-react';

const config = {
  keybanProvider: {
    apiUrl: "https://api.example.keyban.io",  // Replace with your Keyban API URL
    appId: "your-keyban-app-id",  // Replace with your own App ID
    chain: KeybanChain.Sepolia,  // Ethereum Sepolia Testnet
    signer: KeybanSigner.ECDSA,  // Signature mechanism
    storage: new KeybanLocalStorage(),  // Storage solution (development only)
  },
};

export default config;

Note: The KeybanLocalStorage is only for development purposes. For production, ensure you use a more secure storage solution.

Audience Field Explanation (JWTs)​

When integrating authentication with the Keyban SDK, you need to ensure that the JWT tokens issued by your Identity Provider (e.g., Auth0, AWS Cognito) include a valid audience field. This audience field should correspond to the Keyban API URL, as it tells Keyban which service the token is intended for.

For example, if you’re using Auth0, you would configure the audience like this in your Auth0 settings:

  • Audience: https://api.example.keyban.io

If the audience is not set correctly, Keyban will reject the JWT token during authentication.

Important: If you use another identity provider, such as AWS Cognito or Okta, ensure that the JWT tokens they generate include the correct audience value that matches the Keyban API URL.

Step 3: Create the Wallet Component​

Now, create a new file called Wallet.tsx in the src/ directory. This component will display the user's wallet and balance.

src/Wallet.tsx
import React, { Suspense } from 'react';
import { useAuth0 } from '@auth0/auth0-react';
import { ErrorBoundary, useErrorBoundary } from 'react-error-boundary';
import { FormattedBalance, KeybanProvider, useKeybanAccount, useKeybanAccountBalance } from '@keyban/sdk-react';
import config from './config';

// Error handling component
function ErrorFallback({ error }) {
  const { resetBoundary } = useErrorBoundary();
  return (
    <div role="alert">
      <p>Something went wrong:</p>
      <pre>{error.message}</pre>
      <button onClick={resetBoundary}>Try again</button>
    </div>
  );
}

const WalletContent = () => {
  const [account] = useKeybanAccount({ suspense: true });
  const [balance, , { refresh: refreshBalance }] = useKeybanAccountBalance(account, { suspense: true });

  return (
    <div>
      <div>Address: {account?.address || "No address found"}</div>
      <div>
        <FormattedBalance balance={balance} />
        <button onClick={refreshBalance}>Refresh Balance</button>
      </div>
    </div>
  );
};

// Wallet component: retrieves the access token and initializes KeybanProvider
const Wallet = () => {
  const { getAccessTokenSilently } = useAuth0();

  return (
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <KeybanProvider
        {...config.keybanProvider}
        accessTokenProvider={getAccessTokenSilently} // Provides the JWT for API requests
      >
        <Suspense fallback={<div>Loading...</div>}>
          <WalletContent />
        </Suspense>
      </KeybanProvider>
    </ErrorBoundary>
  );
};

export default Wallet;

Additional explanation of accessTokenProvider​

Important: The accessTokenProvider function provides the Keyban SDK with a JWT, which is required to authenticate API requests. In this example, we use the getAccessTokenSilently function from Auth0 to retrieve the token without prompting the user each time. This ensures that API interactions are securely authenticated.

Note: Make sure that the JWT includes the correct audience field. The audience should match the Keyban API URL, e.g., https://api.example.keyban.io. You can replace getAccessTokenSilently with any function that retrieves a valid JWT from your Identity Provider (such as AWS Cognito, Okta, etc.) as long as the token includes the correct audience.

Checkpoint​

After adding this code, you’ve created the basic wallet component. It will show the user's Ethereum address and their balance on the Sepolia testnet.

Step 4: Add the Wallet Component to Your App​

Finally, let’s integrate the Wallet component into your existing app. Open your App.tsx file and add the Wallet component:

import React from 'react';
import Wallet from './Wallet';

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

export default App;

Step 5: Run the Application​

Now that everything is set up, run your development server:

npm run dev

Go to http://localhost:5173/ in your browser, and you should see your wallet's public address and balance.

Conclusion​

Congratulations! You've successfully integrated the Keyban SDK into your React app. You now have a working wallet component that displays a user's balance on the Ethereum Sepolia testnet. For further customization or to explore more features, refer to the Keyban SDK Documentation.