Integrating with Rainbowkit

A step-by-step guide to integrating the Okto-Rainbowkit adapter into Rainbowkit-based dApps, enabling smooth wallet connectivity and streamlined user onboarding.

Quick Start Template Available!

Skip the manual setup and get started in minutes with our template repository. Please note that this template is for development and testing purposes only. Be sure to customize and secure it before using in production.

View Template Run Template

Note that this repository includes multiple branches, each corresponding to a different adapter integration. For integrating Okto with RainbowKit, refer to the bmac-react-rainbowkit-okto branch.

Rainbowkit is a React library that makes it easy to add wallet connection to your dapp. It's intuitive, responsive and customizable.

This guide shows how to add Okto wallet support to an existing Rainbowkit application, enabling social login options for your users.

If you're starting from scratch, you have two options:

Build with an Okto SDK directly
Follow the Rainbowkit quickstart guide first, then return here to add Okto support

Video Tutorial

Installation

Install the Okto wagmi adapter package, Rainbowkit and other dependencies:

npm i @okto_web3/wagmi-adapter @rainbow-me/rainbowkit wagmi [email protected] @tanstack/react-query

Essential Vite Configuration for Rainbowkit + Okto

When integrating Okto with Rainbowkit in a Vite project, you'll need to add Node.js polyfills to resolve browser buffer issues. Update your vite.config.ts file with this configuration:

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { nodePolyfills } from "vite-plugin-node-polyfills";
 
// https://vite.dev/config/
export default defineConfig({
  plugins: [react(), nodePolyfills()],
  server: {
    port: 3000, // will always start the service on port 3000
  },
});

Don't forget to install the required package:

npm i -D vite-plugin-node-polyfills

Without this package, your app will fail to build or run properly.

Configure Okto

Warning:Essential Setup Required

Show

Set up your Okto Developer Dashboard by making sure you have :

Created your Okto Developer Dashboard account
Get your Okto credits from the dashboard
Obtained your API keys from the dashboard
Enabled the specific Chains and Tokens you plan to use in your application
Optional: Enabled Sponsorship for the desired chains

If you need help, reach out to us on our troubleshooting form and we will contact you.

Before getting started, ensure you have the following:

Okto API Keys: You need your clientPrivateKey and clientSWA. Obtain these from the Okto Developer Dashboard.
Okto Account Setup: Ensure you have sufficient Okto Credits, enable the required Chains and Tokens , and optionally Activate Sponsorship.
Google OAuth Credentials (if using Google authentication): Create OAuth 2.0 credentials in the Google Cloud Console to get your googleClientId.

Configure Rainbowkit

Create a configuration file to set up rainbowkit with the Okto connector. You can choose between two authentication methods:

This method provides a streamlined Google sign-in experience directly in the wallet connection flow.

rainbowkit.config.ts

import { connectorsForWallets } from '@rainbow-me/rainbowkit';
import { createConfig, http } from 'wagmi';
import { mainnet, optimism, baseSepolia } from 'wagmi/chains';
import { getOktoSdkConnector, OktoParameters } from '@okto_web3/wagmi-adapter';
 
const oktoParams: OktoParameters = {
    environment: 'sandbox',
    clientPrivateKey: '0xprivatekey',
    clientSWA: '0xswa',
    googleClientId: 'xxx',
} as OktoParameters;
 
// create a 'Social Login' group in rainbowkit config connectors list
const connectors = connectorsForWallets(
[
  {
    groupName: 'Social Login',
    wallets: [
      getOktoSdkConnector({
        type: 'google',
        params: oktoParams,
      }),
    ],
  }
],
{
  appName: 'My Okto Rainbowkit App',
  projectId: 'xxx', // Replace with your WalletConnect project ID if using WalletConnect
},
);
 
// Wagmi config
export const config = createConfig({
  connectors,
  chains: [mainnet, optimism, baseSepolia],
  transports: {
    [mainnet.id]: http(),
    [optimism.id]: http(),
    [baseSepolia.id]: http(),
  },
});

This method shows a comprehensive onboarding modal with multiple authentication options (Google, email, phone, etc.).

rainbowkit.config.ts

import { connectorsForWallets } from '@rainbow-me/rainbowkit';
import { createConfig, http } from 'wagmi';
import { mainnet, optimism, baseSepolia } from 'wagmi/chains';
import { getOktoSdkConnector, OktoParameters } from '@okto_web3/wagmi-adapter';
 
const oktoParams: OktoParameters = {
    environment: 'sandbox',
    clientPrivateKey: '0xprivatekey',
    clientSWA: '0xswa',
} as OktoParameters;
 
// Custom connector for Okto onboarding modal
const connectors = connectorsForWallets(
[
  {
    groupName: 'Social Login',
    wallets: [
      getOktoSdkConnector({
        type: 'generic',
        params: oktoParams,
      }),
    ],
  }
],
{
  appName: 'My Okto Rainbowkit App',
  projectId: 'xxx', // Replace with your WalletConnect project ID if using WalletConnect
},
);
 
// Wagmi config
export const config = createConfig({
  connectors,
  chains: [mainnet, optimism, baseSepolia],
  transports: {
    [mainnet.id]: http(),
    [optimism.id]: http(),
    [baseSepolia.id]: http(),
  },
});

📝 Connector Types Explained

Google OAuth (type: 'google'): Shows only Google sign-in button in the wallet connection flow
Okto Onboarding Modal (type: 'generic'): Opens a full onboarding modal with multiple authentication options (Google, email, phone, etc.)

You can also include both connectors for maximum flexibility!

Okto Configuration Parameters

Parameter	Description	Type	Required
`environment`	Environment to use for the SDK	`'sandbox'` \| `'production'`	Yes
`clientPrivateKey`	Your client private key	`string`	Yes
`clientSWA`	Your client SWA	`string`	Yes
`googleClientId`	Your Google client ID	`string`	Yes*

*Required only for type: 'google', optional for type: 'generic'

Set Up Providers

Update your app's root component to include the necessary providers:

layout.tsx

"use client"
 
import React from 'react';
import { config } from './rainbowkit.config.ts';
import { RainbowKitProvider } from '@rainbow-me/rainbowkit';
import '@rainbow-me/rainbowkit/styles.css';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import Script from 'next/script';
import { WagmiProvider } from 'wagmi';
 
const queryClient = new QueryClient();
 
export default function Layout({ children }: { children: React.ReactNode }) {
 
  return (
    <html lang="en">
      <head>
        <Script src="https://accounts.google.com/gsi/client" async defer /> // Not needed if using Onboarding Modal
      </head>
      <body>
        <WagmiProvider config={config}>
          <QueryClientProvider client={queryClient}>
             <RainbowKitProvider>{children}</RainbowKitProvider>
          </QueryClientProvider>
        </WagmiProvider>
       </body>
    </html>
  );
}

main.tsx

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App.tsx';
import '@rainbow-me/rainbowkit/styles.css';
import { RainbowKitProvider } from '@rainbow-me/rainbowkit';
import { WagmiProvider } from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { config } from './rainbowkit.config.ts';
 
(window as any).Buffer = Buffer;
 
const queryClient = new QueryClient();
 
createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider >
          <App />
        </RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  </StrictMode>
);

Note

For Vite project, add this script tag to your index.html file in the project root directory. The script must be placed inside the <head> tag.

<script src="https://accounts.google.com/gsi/client" async defer></script>

This is necessary for Google OAuth to work properly with RainbowKit. If using Onboarding Modal, this script is not required.

Add the ConnectButton to your App

Once configured, you can use to offer Okto social login to your users:

page.tsx

'use client';
 
import { ConnectButton } from '@rainbow-me/rainbowkit';
 
export default function Home() {
return (
    <div>
      <p>Connect your wallet</p>
      <ConnectButton />
    </div>
);
}

App.tsx

import { ConnectButton } from "@rainbow-me/rainbowkit";
 
export default function App() {
return (
    <div>
      <p>Connect your wallet</p>
      <ConnectButton />
    </div>
);
}

Important Notes & Troubleshooting

Chain Switching

When using traditional wallets like MetaMask with RainbowKit, users can change networks directly in their wallet interface, and your application code automatically picks up the current selected chain. However, Okto users don't have a separate wallet UI to change networks manually.

This means your application code must handle network switching programmatically when using Okto. If your dApp requires a specific chain (like Base Sepolia for transactions), you need to implement chain switching logic.

🔗 Network Switching: Traditional Wallets vs Okto

Traditional Wallets (MetaMask, etc.): User changes network in wallet → Code automatically detects the change
Okto: No external wallet UI → Your app must programmatically switch networks when needed

Implementation Example Here's how to implement automatic chain switching when a user tries to perform an action requiring a specific network:

import { useChainId, useSwitchChain } from 'wagmi';
 
const chainId = useChainId();
const { switchChain } = useSwitchChain();
 
const handleTransaction = async () => {
  // Check if user is on the required chain (Base Sepolia = 84532)
  if (chainId !== 84532) {
    try {
      console.log("Current chainId:", chainId);
      await switchChain({ chainId: 84532 }); // Switch to Base Sepolia
    } catch (error) {
      alert("Network switch to Base Sepolia failed or was rejected.");
      return;
    }
  }
  
  // Proceed with transaction now that we're on the correct network
  // ... your transaction logic here
};

This pattern ensures your dApp works seamlessly with Okto by automatically switching to the required network before executing transactions.

Integrating with Rainbowkit

Quick Start Template Available!

On this page