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 Polygon Amoy 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:

npm install @keyban/sdk-react

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:

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,           // Polygon Amoy Testnet
    clientShareKeyProvider: async () => {      // Provide a unique shared key per client share
      // Implement your logic to retrieve or generate the shared key
      return "your-unique-shared-key";
    },
  },
};

export default config;

Key Points​

  • clientShareKeyProvider Integration: By including the clientShareKeyProvider in your config.ts, the KeybanProvider automatically utilizes it to cipher the client's share of the end user. This ensures that Keyban cannot sign operations on behalf of the end users.
  • Unique Key Recommendation: It's recommended to provide a unique key per client share to enhance security. This means generating a distinct key for each client or user, preventing key reuse and reducing the risk of compromise.
  • Secure Key Management: Ensure that the shared keys are retrieved from secure sources, such as environment variables or secure vaults, to prevent unauthorized access.

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 from 'react';
import { useAuth0 } from '@auth0/auth0-react';
import { KeybanProvider, useKeybanAccount, useKeybanAccountBalance, FormattedBalance } from '@keyban/sdk-react';
import config from './config';

// WalletContent component: Displays the user's address and balance
const WalletContent = () => {
  const [account] = useKeybanAccount();
  const [balance] = useKeybanAccountBalance(account);

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

// Wallet component: Initializes KeybanProvider and renders WalletContent
const Wallet = () => {
  const { getAccessTokenSilently } = useAuth0();

  return (
    <KeybanProvider
      {...config.keybanProvider}
      accessTokenProvider={getAccessTokenSilently} // Provides the JWT for API requests
    >
      <WalletContent />
    </KeybanProvider>
  );
};

export default Wallet;

Understanding the accessTokenProvider and JWT Audience​

The accessTokenProvider function supplies the Keyban SDK with a valid JWT for authenticating API requests. In the example provided, this is achieved using the getAccessTokenSilently function from Auth0, which fetches a token without prompting the user each time, ensuring a smoother experience.

However, it’s critical that the JWT includes a correctly configured audience field. The audience specifies which service the token is intended for. For the Keyban SDK, the audience should match the Keyban API URL, https://api.example.keyban.io. If the audience is incorrect or absent, the Keyban SDK will reject the token since it does not match the intended service.

In summary:

  • accessTokenProvider: Ensures a valid JWT is always available to the Keyban SDK.
  • Audience in JWT: This field specifies that the token is intended for the Keyban API. It must be set to https://api.example.keyban.io to ensure the SDK accepts the token and does not reject it.

If you’re using an authentication provider other than Auth0 (e.g., AWS Cognito or Okta), ensure that you configure the audience field in a similar manner so that the Keyban API accepts the token.

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 Polygon Amoy testnet. For further customization or to explore more features, refer to the Keyban React SDK Documentation.