Quickstart React

Start by installing @openfort/react and its peer dependencies using your package manager of choice:

npm install @openfort/react wagmi viem@^2.22.0 @tanstack/react-query

In the API keys section of Openfort dashboard, you will find:

• Publishable Key: Safe to expose in client-side environment
• Secret Key: Must be kept secure and used only server-side

To generate non-custodial wallets:

1. Scroll to the Shield section and click Create Shield keys
2. Store the encryption share safely when it appears (you'll only see it once)
3. You'll receive:
   • Shield Publishable Key: Safe for client-side use
   • Shield Secret Key: Keep secure, server-side only

If you use the default Wagmi configuration (which includes WalletConnect support) you will also need a WalletConnect project ID. You can get one by creating a project on the WalletConnect dashboard. The connection flow will fail if you supply a placeholder value.

Decide which wallet recovery experience you want to ship:

• Automatic recovery — no action from the user required.
• Passkey recovery — biometric or device authentication with no backend endpoint.
• Password recovery — user sets their own password with no backend endpoint.

Create a backend endpoint that issues a Shield encryption session used to recover wallets. Learn more about setting up the recovery endpoint.

Option 1: One‑click deploy

Use our prebuilt endpoint and deploy in one click on Cloudflare or Vercel as a function.

Option 2: Implement your own backend

Use this option if you have your backend set up and can add an extra endpoint.

import express, { Request, Response } from 'express';
 
// Initialize the Openfort client  
const openfort = require("@openfort/openfort-node")(process.env.OPENFORT_SECRET_KEY);  
 
// Use your own middleware (JWT, sessions, API key, etc.) to authenticate the user here
export const authenticateUser = (req: Request, res: Response, next: NextFunction) => {
  // Example: req.user = { id: 'user_123', email: 'user@example.com' };
  return next();
};
 
const router = express.Router();
 
router.post('/api/shield-session', authenticateUser, async (req: Request, res: Response) => {  
  try {  
    const session = await openfort.registerRecoverySession(  
      process.env.OPENFORT_SHIELD_PUBLISHABLE_KEY as string,  
      process.env.OPENFORT_SHIELD_SECRET_KEY as string,  
      process.env.OPENFORT_SHIELD_ENCRYPTION_SHARE as string
    );  
    res.status(200).json({ session });  
  } catch (e) {  
    console.error(e);  
    res.status(500).json({ error: 'Internal server error' });  
  }  
});  
 
export default router;

After setting up the /api/shield-session endpoint, save your endpoint URL (https://your-domain.com/api/shield-session) for the next step.

Set up providers for Wagmi, TanStack Query, and Openfort.

To set up a config for Wagmi, we will use Wagmi's createConfig function with @openfort/react's getDefaultConfig function. This automatically sets up the Wagmi instance to support all chains and transports supported by Openfort. If you need more configuration go to the Wagmi configuration guide.

To set up OpenfortProvider we will need the publishable key from the Openfort dashboard, and the wallet configuration. More information on the wallet configuration can be found here.

import React from "react";
import {
  AuthProvider,
  OpenfortProvider,
  getDefaultConfig,
  RecoveryMethod,
} from "@openfort/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WagmiProvider, createConfig } from "wagmi";
import { polygonAmoy } from "viem/chains";
 
const config = createConfig(
  getDefaultConfig({
    appName: "Openfort demo",
    chains: [polygonAmoy],
    ssr: true,
  })
);
 
const queryClient = new QueryClient();
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <OpenfortProvider
          // Set the publishable key of your Openfort account. This field is required.
          publishableKey={"YOUR_OPENFORT_PUBLISHABLE_KEY"}
 
          // Set the wallet configuration.
          walletConfig={{
            shieldPublishableKey: "YOUR_OPENFORT_SHIELD_PUBLISHABLE_KEY",
            // If you want to use AUTOMATIC embedded wallet recovery, an encryption session is required.
            // Set this to your recovery endpoint URL from step "3. Set up the recovery endpoint" (e.g., "https://your-domain.com/api/shield-session").
            createEncryptedSessionEndpoint: "YOUR_OPENFORT_BACKEND_ENDPOINT",
          }}
        >
          {children}
        </OpenfortProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

const config = createConfig(
  getDefaultConfig({
    appName: "Openfort demo",
    chains: [polygonAmoy],
    ssr: true,
    walletConnectProjectId: "YOUR_WALLET_CONNECT_PROJECT_ID",
  })
);

Once you've configured your app, wrap it in the Providers component and drop in Openfort UI elements where you need them.

import React from "react";
import { Providers } from "./Providers";
import { OpenfortButton } from "@openfort/react";
 
export default function App() {
  return (
    <Providers>
      {/* Your app content */}
      <OpenfortButton />
    </Providers>
  );
}