Starting from scratch? Create a new React app first
:::code-group ```sh [pnpm] pnpm create vite my-openfort-app --template react-ts ``` ```sh [npm] npm create vite@latest my-openfort-app -- --template react-ts ``` ```sh [yarn] yarn create vite my-openfort-app --template react-ts ``` :::Ethereum: Need WalletConnect support?
Add `walletConnectProjectId` to `getDefaultConfig`. Get a project ID from the [WalletConnect dashboard](https://cloud.reown.com/sign-in).My Profile
This is a custom profile page.
setEmail(e.target.value)} placeholder="Email" />
{otpSent && (
setOtp(e.target.value)} placeholder="Enter OTP" />
)}
{!otpSent ? (
) : (
)}
)
}
```
[View full documentation →](/docs/products/embedded-wallet/react/hooks/useEmailOtpAuth)
## Using Phone OTP Authentication
Use [`usePhoneOtpAuth`](/docs/products/embedded-wallet/react/hooks/usePhoneOtpAuth) for passwordless SMS authentication with one-time passwords.
```tsx
import { usePhoneOtpAuth } from "@openfort/react"
import { useState } from "react"
function PhoneOtpLogin() {
const { requestPhoneOtp, logInWithPhoneOtp, isRequesting, isLoading } = usePhoneOtpAuth()
const [phoneNumber, setPhoneNumber] = useState("")
const [otp, setOtp] = useState("")
const [otpSent, setOtpSent] = useState(false)
const handleRequestOtp = async () => {
const { error } = await requestPhoneOtp({ phoneNumber })
if (!error) setOtpSent(true)
}
const handleSignIn = async () => {
const { user, error } = await logInWithPhoneOtp({ phoneNumber, otp })
if (user) console.log("Signed in:", user.id)
}
return (
setPhoneNumber(e.target.value)}
placeholder="+1234567890"
/>
{otpSent && (
setOtp(e.target.value)} placeholder="Enter OTP" />
)}
{!otpSent ? (
) : (
)}
)
}
```
[View full documentation →](/docs/products/embedded-wallet/react/hooks/usePhoneOtpAuth)
## Using Social Authentication
Use [`useOAuth`](/docs/products/embedded-wallet/react/hooks/useOAuth) for social login (Google, Facebook, Twitter, etc.) and account linking.
`useOAuth` only authenticates. The wallet appears reactively on [`useEthereumEmbeddedWallet`](/docs/products/embedded-wallet/react/hooks/useEthereumEmbeddedWallet) or [`useSolanaEmbeddedWallet`](/docs/products/embedded-wallet/react/hooks/useSolanaEmbeddedWallet) once `isConnected` flips true. Both hooks expose the same connection-state shape (`isConnected`, `isConnecting`, `isDisconnected`, `isReconnecting`). Recovery is automatic via the `recoverWalletAutomatically` option (default `true`) and uses the `walletConfig.chainType` set on `OpenfortProvider` — set it to `ChainTypeEnum.SVM` for Solana, otherwise EVM is used.
:::code-group
```tsx [Prebuilt]
import { useUI } from "@openfort/react"
function SocialLogin() {
const { open } = useUI()
return
}
```
```tsx [Ethereum (custom)]
import { OAuthProvider, useOAuth } from "@openfort/react"
import { useEthereumEmbeddedWallet } from "@openfort/react/ethereum"
function SocialLogin() {
const { initOAuth, isLoading } = useOAuth()
const { isConnected, address } = useEthereumEmbeddedWallet()
if (isConnected) return Wallet: {address}
return ( ) } ``` ```tsx [Solana (custom)] import { OAuthProvider, useOAuth } from "@openfort/react" import { useSolanaEmbeddedWallet } from "@openfort/react/solana" function SocialLogin() { const { initOAuth, isLoading } = useOAuth() const { isConnected, address } = useSolanaEmbeddedWallet() if (isConnected) returnWallet: {address}
return ( ) } ``` ::: :::warning One `chainType` per provider. An app cannot headlessly OAuth into both EVM and Solana from the same `OpenfortProvider` instance. ::: Working examples: * [Headless EVM quickstart](https://github.com/openfort-xyz/openfort-react/tree/main/examples/quickstarts/headless) – minimal headless EVM setup * [Headless Solana quickstart](https://github.com/openfort-xyz/openfort-react/tree/main/examples/quickstarts/solana-headless) – minimal headless Solana setup with `chainType: SVM` [View full documentation →](/docs/products/embedded-wallet/react/hooks/useOAuth) ## Using Wallet Authentication (Ethereum only) Wallet authentication (Sign-In with Ethereum, SIWE) with external wallets (MetaMask, WalletConnect, etc.) is **Ethereum-only** and requires wagmi provider setup. Full setup, provider config, and API are in [useWalletAuth](/docs/products/embedded-wallet/react/hooks/useWalletAuth). :::code-group ```tsx [Prebuilt] import { useUI } from "@openfort/react" function WalletLogin() { const { open } = useUI() return } ``` ```tsx [Custom] import { useWalletAuth } from "@openfort/react/wagmi" import { useState } from "react" function WalletLogin() { const { availableWallets, connectWallet } = useWalletAuth() const [loading, setLoading] = useState(false) const handleConnect = async (walletId: string) => { setLoading(true) try { await connectWallet(walletId, { onConnect: () => console.log("Connected"), onError: (err) => console.error(err), }) } finally { setLoading(false) } } return ( <> {availableWallets.map((w) => ( ))} ) } ``` ::: [View full documentation →](/docs/products/embedded-wallet/react/hooks/useWalletAuth#usewalletauth-siwe-connection-flow) ## Using Guest Authentication Use [`useGuestAuth`](/docs/products/embedded-wallet/react/hooks/useGuestAuth) for anonymous users and instant onboarding. ```tsx import { useGuestAuth } from "@openfort/react" function GuestLogin() { const { signUpGuest, isLoading } = useGuestAuth() return ( ) } ``` [View full documentation →](/docs/products/embedded-wallet/react/hooks/useGuestAuth) ## Using Your Own Authentication Openfort integrates with external authentication providers like Firebase, Supabase, Auth0, and custom auth systems so you can keep your existing login flow while issuing embedded wallets for users. [View full documentation →](/docs/products/embedded-wallet/react/auth/third-party) # Using Your Own Authentication Openfort integrates with external authentication providers so you can keep your existing login while still issuing embedded wallets for users. :::warning[No UI Components with Third-Party Auth] When using third-party authentication (Firebase, Supabase, etc.), you must handle your own login UI. Openfort's built-in UI components (like `OpenfortButton`) and the `uiConfig` settings in `OpenfortProvider` do not apply—they are designed for Openfort's native authentication methods only. ::: ## Ready-Made Quickstarts Get started quickly with complete working examples that integrate third-party authentication: * [Quickstart w/ Firebase](https://github.com/openfort-xyz/openfort-react/tree/main/examples/quickstarts/firebase#firebase-quickstart) – Complete Firebase integration example * [Quickstart w/ Supabase](https://github.com/openfort-xyz/openfort-react/tree/main/examples/quickstarts/supabase#supabase-quickstart) – Complete Supabase integration example * [Quickstart w/ Better Auth](https://github.com/openfort-xyz/openfort-react/tree/main/examples/quickstarts/betterauth#better-auth-quickstart) – Complete Better Auth integration example ## Supported Providers Openfort has built-in support for these third-party authentication platforms: | Provider | Configuration | |----------|---------------| | [**Firebase**](/docs/configuration/external-auth/firebase) | `ThirdPartyOAuthProvider.FIREBASE` | | [**Better-Auth**](/docs/configuration/external-auth/better-auth) | `ThirdPartyOAuthProvider.BETTER_AUTH` | | [**Supabase**](/docs/configuration/external-auth/supabase) | `ThirdPartyOAuthProvider.SUPABASE` | | [**PlayFab**](/docs/configuration/external-auth/playfab) | `ThirdPartyOAuthProvider.PLAYFAB` | | [**AccelByte**](/docs/configuration/external-auth/accelbyte) | `ThirdPartyOAuthProvider.ACCELBYTE` | | [**LootLocker**](/docs/configuration/external-auth/lootlocker) | `ThirdPartyOAuthProvider.LOOTLOCKER` | | [**Custom OIDC**](/docs/configuration/custom-auth/oidc-token) | `ThirdPartyOAuthProvider.OIDC` | | [**Custom Auth**](/docs/configuration/custom-auth/auth-token) | `ThirdPartyOAuthProvider.CUSTOM` | ## Setup Steps ### 1. Configure Your Provider in the Dashboard Before integrating, configure your authentication provider in the [Openfort Dashboard → Providers](https://dashboard.openfort.io/providers): * **For built-in providers** (Firebase, Supabase, etc.): Add your provider's Project ID or credentials * **For OIDC providers** (Auth0, Cognito, etc.): Provide your JWKS URL and audience (`aud`) value * **For custom auth servers**: Set up a verification endpoint and authentication headers [View detailed provider setup guides →](/docs/configuration/external-auth) ### 2. Set up the `thirdPartyAuth` prop in `OpenfortProvider` Wrap your React app with `OpenfortProvider` and specify your authentication provider's `getAccessToken` function. Here's an example using Firebase: ```tsx [Providers.tsx] import React from "react" import { OpenfortProvider, RecoveryMethod, ThirdPartyOAuthProvider } from "@openfort/react" import { auth as firebaseAuth } from "./lib/firebase" export function Providers({ children }: { children: React.ReactNode }) { const firebaseGetAccessToken = async () => { const token = await firebaseAuth.currentUser?.getIdToken(false) return token ?? null } return (Not connected
return (
Address: {activeWallet.address}
Chain: Ethereum
-
{wallets.map((w) => (
- {w.address} {w.id === activeWallet?.id && "(active)"} ))}
Ethereum wallet
Address: {activeWallet?.address}
Account ID: {activeWallet?.accountId}
Created at: {activeWallet?.createdAt}
All wallets
-
{wallets.map((wallet) => (
- {wallet.address} — {wallet.isActive ? "Active" : "Inactive"} ))}
Not connected
return (
Address: {activeWallet.address}
Cluster: {cluster}
-
{wallets.map((w) => (
- {w.address} {w.id === activeWallet?.id && "(active)"} ))}
Solana wallet
Address: {activeWallet?.address}
All wallets
-
{wallets.map((wallet) => (
- {wallet.address} — {wallet.id === activeWallet?.id ? "Active" : "Inactive"} ))}
{isConfirmed &&
)
}
```
## Send a contract call
Use wagmi's `useWriteContract` for ERC-20 transfers or any contract interaction:
:::info
This example uses a testnet USDC token address for demonstration purposes. This is not the real mainnet USDC token.
:::
:::code-group
```tsx [useSendUsdc.ts]
import { useCallback } from 'react'
import { parseUnits } from 'viem'
import { useAccount, useWriteContract, useWaitForTransactionReceipt } from 'wagmi'
const usdcAddress = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' // replace with your token
const usdcAbi = [{
name: 'transfer',
type: 'function',
stateMutability: 'nonpayable',
inputs: [
{ name: 'to', type: 'address' },
{ name: 'amount', type: 'uint256' },
],
outputs: [{ name: 'success', type: 'bool' }],
}] as const
export function useSendUsdc() {
const { address } = useAccount()
const { writeContract, data: hash, isPending, error } = useWriteContract()
const { isLoading: isConfirming, isSuccess: isConfirmed } =
useWaitForTransactionReceipt({ hash })
const sendUsdc = useCallback(async (to: `0x${string}`, amount: string) => {
if (!address) throw new Error('Wallet not connected')
const units = parseUnits(amount, 6)
writeContract({
address: usdcAddress,
abi: usdcAbi,
functionName: 'transfer',
args: [to, units],
})
}, [address, writeContract])
return {
sendUsdc,
hash,
isPending,
isConfirming,
isConfirmed,
error,
}
}
```
```tsx [TransferButton.tsx]
import { useSendUsdc } from './useSendUsdc'
export function TransferButton() {
const { sendUsdc, isPending, isConfirming, isConfirmed, error } = useSendUsdc()
const handleTransfer = () => {
sendUsdc('0x742d35Cc6634C0532925a3b844Bc454e4438f44e', '10.5')
}
return (
Transfer confirmed!
} {error &&Error: {error.message}
}
{isConfirmed &&
)
}
```
:::
## Gas sponsorship
:::warning
Gas sponsorship requires a **Smart Account** or **Delegated Account**. EOA wallets pay their own gas and cannot use gas sponsorship policies. Make sure `accountType` is set to `AccountTypeEnum.SMART_ACCOUNT` or `AccountTypeEnum.DELEGATED_ACCOUNT` in your [wallet configuration](/docs/products/embedded-wallet/react/wallet/ethereum#setting-the-account-type).
:::
:::info
For full details on gas sponsorship policies, see [Gas sponsorship](/docs/configuration/gas-sponsorship).
:::
Keep the experience gasless by attaching a gas policy created in the Openfort dashboard:
1. Navigate to [**Dashboard → Gas sponsorship**](https://dashboard.openfort.io/policies), add a gas sponsorship, and copy the generated `pol_...` identifier.
2. Configure match rules (chain, method, contract) so only the intended `wallet_sendCalls` bundles qualify.
3. Pick a **Sponsorship mode**: **App pays** covers gas so users transact for free, or **User pays** lets users pay gas in a token you choose. On EVM you select a network and a gas-payment token — supported stablecoins (USDC, USDT, DAI, WETH) are priced automatically, or you set a fixed amount per transaction.
:::info
This applies to Ethereum wallets. For Solana, see [Send transaction (Solana)](/docs/products/embedded-wallet/react/wallet/actions/send-transaction/solana#gasless-solana-transactions).
:::
Wire the policy into `ethereumFeeSponsorshipId` inside `walletConfig.ethereum` so the SDK appends it automatically:
```tsx [Providers.tsx]
const config = createConfig(
getDefaultConfig({
appName: "Openfort demo",
chains: [polygonAmoy],
ssr: true,
})
)
export function Providers({ children }: { children: React.ReactNode }) {
return (
Transfer confirmed!
} {error &&Error: {error.message}
}
{signature &&
)
}
```
:::info
Smart and Delegated accounts use [EIP-1271](https://eips.ethereum.org/EIPS/eip-1271) for
signature verification. The wagmi hooks are identical — the SDK handles the difference under the hood.
:::
## Typed data — EIP-712
Use `useSignTypedData` for structured, domain-separated signatures:
```tsx [SignTypedData.tsx]
import { useSignTypedData } from 'wagmi'
function SignTypedData() {
const { signTypedData, data: signature, isPending, error } = useSignTypedData()
const handleSign = () => {
signTypedData({
domain: {
chainId: 1,
name: 'Example DApp',
verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC',
version: '1',
},
types: {
Mail: [
{ name: 'from', type: 'Person' },
{ name: 'to', type: 'Person' },
{ name: 'content', type: 'string' },
],
Person: [
{ name: 'name', type: 'string' },
{ name: 'wallet', type: 'address' },
],
},
message: {
from: { name: 'Alice', wallet: '0x2111111111111111111111111111111111111111' },
to: { name: 'Bob', wallet: '0x3111111111111111111111111111111111111111' },
content: 'Hello!',
},
primaryType: 'Mail',
})
}
return (
Signature: {signature}
} {error &&Error: {error.message}
}
{signature &&
)
}
```
# Switch chain
Switch the active chain for the user's embedded wallet.
:::info
When using *Smart accounts*, the address is at first pre-computed off-chain.
The account will be deployed when doing the first transaction with it.
Only [supported chains](/docs/configuration/chains) can be used with Smart Accounts.
:::
:::warning
ERC-7702 delegation must be **set per chain**.
When switching to a new chain, the delegation authorization needs to be re-established on that chain. See [EIP-7702 authorization](/docs/products/embedded-wallet/react/wallet/actions/eip-7702-authorization) for details.
:::
Use wagmi's `useSwitchChain` hook to change the active chain:
```tsx [SwitchChainButton.tsx]
import { useSwitchChain } from 'wagmi'
import { polygonAmoy, baseSepolia } from 'wagmi/chains'
function SwitchChainButton() {
const { switchChain, isPending, error } = useSwitchChain()
return (
Signature: {signature}
} {error &&Error: {error.message}
}
{error &&
)
}
```
# Sign EIP-7702 authorization
[EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) allows an externally owned accounts (EOA) to delegate their execution to smart contract code
This allows EOA wallets to gain account abstraction capabilities such as transaction bundling, gas sponsorship, and custom permissions.
:::warning
This page applies to **Delegated Accounts only**. EOA and Smart Account types do not require EIP-7702 authorization.
:::
Openfort provides methods to sign EIP-7702 authorizations, which allows your embedded wallets to be upgraded into any smart contract.
Despite you can sign an authorization for any smart account, when using openfort to send transactions from `delegated accounts`, only a limited list of smart account implementations is supported.
[Learn more](/docs/configuration/addresses) about the supported list of smart accounts.
When sending a transaction from a Delegated Account through Openfort, you must sign a one-time EIP-7702 authorization.
This authorization tells the network which smart account implementation contract the EOA is delegating to.
* The authorization is **signed once per chain** — after the first transaction is submitted with the authorization, subsequent transactions on the same chain do not need it again.
* When switching to a **new chain**, a new authorization must be signed for that chain.
:::info[Supported chains vs. other chains]
On a [supported EVM chain](/docs/configuration/chains), Openfort delegates automatically to the **Calibur** implementation (the default unless you configure another) — nothing else to do. On a chain Openfort does not natively support, you can still delegate to any 7702 implementation deployed on that chain by signing the authorization yourself with viem — see [Delegate to a different implementation](#delegate-to-a-different-implementation).
:::
## Recommended: native delegation to Calibur
The simplest path is to configure the embedded wallet as a Delegated Account and let the SDK attach the authorization for you. Set `accountType` to `DELEGATED_ACCOUNT` in [`walletConfig.ethereum`](/docs/products/embedded-wallet/react/wallet/ethereum#setting-the-account-type):
```tsx [Providers.tsx]
Error: {error.message}
}
Loading assets...
if (error) return Error: {error.message}
return (
Wallet Assets
-
{assets?.map((asset) => (
- {asset.address}: {formatUnits(asset.balance, asset.metadata?.decimals ?? 18)} {asset.metadata?.symbol} ))}
Status: {status}
Send to: {session.paymentMethod.receiverAddress}
{/* render session.paymentMethod.addressUri as a QR, or session.paymentMethod.deeplinks */}
setEmail(e.target.value)} placeholder="Email" />
{otpSent && (
setOtp(e.target.value)} placeholder="Enter OTP" />
)}
{!otpSent ? (
) : (
)}
);
}
```
## Return type
```ts
type EmailOtpAuthReturn = {
requestEmailOtp(options: RequestEmailOtpOptions): Promise
setPhoneNumber(e.target.value)} placeholder="+1234567890" />
{otpSent && (
setOtp(e.target.value)} placeholder="Enter OTP" />
)}
{!otpSent ? (
) : (
)}
);
}
```
## Return type
```ts
type PhoneOtpAuthReturn = {
requestPhoneOtp(options: RequestPhoneOtpOptions): PromisePlease sign in first
; const handleRequestOtp = async () => { const { error } = await requestPhoneOtp({ phoneNumber }); if (!error) setOtpSent(true); }; const handleLinkPhone = async () => { const { user, error } = await linkPhoneOtp({ phoneNumber, otp }); if (user) console.log('Phone linked successfully'); }; return (
setPhoneNumber(e.target.value)} placeholder="+1234567890" />
{otpSent && (
setOtp(e.target.value)} placeholder="Enter OTP" />
)}
{!otpSent ? (
) : (
)}
);
}
```
## Related
* [useEmailOtpAuth](/docs/products/embedded-wallet/react/hooks/useEmailOtpAuth) - Email OTP authentication
* [useEmailAuth](/docs/products/embedded-wallet/react/hooks/useEmailAuth) - Email/password authentication
# `useOAuth`
Authenticate with third-party providers like Google, Apple, Facebook, Discord, and Twitter.
## Usage
```tsx
import { OAuthProvider, useOAuth } from '@openfort/react';
function SocialLogin() {
const { initOAuth, linkOauth, isLoading } = useOAuth();
const loginWithGoogle = () => initOAuth({ provider: OAuthProvider.GOOGLE });
const linkDiscord = () => linkOauth({ provider: OAuthProvider.DISCORD });
return null;
}
```
## Reading the wallet after sign-in
`useOAuth` is fire-and-forget — it authenticates the user, then returns. The wallet appears reactively on the chain hook a moment later, once the SDK has recovered or created it.
* **Ethereum:** read `address` / `isConnected` from [`useEthereumEmbeddedWallet`](/docs/products/embedded-wallet/react/hooks/useEthereumEmbeddedWallet).
* **Solana:** read `address` / `isConnected` from [`useSolanaEmbeddedWallet`](/docs/products/embedded-wallet/react/hooks/useSolanaEmbeddedWallet).
* Both hooks share the same connection-state shape (`isConnected`, `isConnecting`, `isDisconnected`, `isReconnecting`); use the `status` discriminated union when you need granular states like `'fetching-wallets'`, `'creating'`, or `'needs-recovery'`.
* Recovery is controlled by `recoverWalletAutomatically` (default `true`) and uses the `walletConfig.chainType` set on `OpenfortProvider`. **The default `chainType` is `EVM`** — Solana apps must set `chainType: ChainTypeEnum.SVM`, or the wallet hook will stay disconnected after OAuth.
See the [social authentication overview](/docs/products/embedded-wallet/react/auth#using-social-authentication) for end-to-end snippets, or the [headless EVM](https://github.com/openfort-xyz/openfort-react/tree/main/examples/quickstarts/headless) and [headless Solana](https://github.com/openfort-xyz/openfort-react/tree/main/examples/quickstarts/solana-headless) quickstart apps for runnable references.
## Return type
```ts
type UseOAuthReturn = {
initOAuth(options: InitOAuthOptions): PromiseWalletConnect support
If using WalletConnect, add a project ID from the [WalletConnect dashboard](https://cloud.walletconnect.com): ```tsx const config = createConfig( getDefaultConfig({ appName: "Openfort demo", chains: [baseSepolia], ssr: true, walletConnectProjectId: "YOUR_WALLET_CONNECT_PROJECT_ID", }) ) ```useWalletAuth — SIWE connection flow
`useWalletAuth` from `@openfort/react/wagmi` is the recommended way to connect external wallets with Sign-In with Ethereum. It handles connect + SIWE sign-in in one flow. ```tsx import { useWalletAuth } from "@openfort/react/wagmi" function WalletConnectList() { const { availableWallets, connectWallet, linkWallet, walletConnectingTo, isLoading, isError, error, } = useWalletAuth({ onSuccess: () => console.log("Connected"), onError: (err) => console.error(err), }) return (
{walletConnectingTo &&
)
}
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `hookOptions` | `OpenfortHookOptions?` | Optional. `onSuccess`, `onError`, `throwOnError`. Default `{}`. |
| Return | Type | Description |
|--------|------|-------------|
| `availableWallets` | `AvailableWallet[]` | List of connectable wallets (excludes Openfort embedded). See [AvailableWallet](#availablewallet-type) below. |
| `connectWallet(connectorId, callbacks?)` | `(string, WalletAuthCallbacks?) => PromiseConnecting to {walletConnectingTo}…
} {availableWallets.map((w) => ( ))}AvailableWallet type
```ts type AvailableWallet = { id: string name: string icon?: string connector: OpenfortEthereumBridgeConnector // Openfort bridge connector for the external wallet } ``` `connectWallet` creates a new session; `linkWallet` links the external wallet to the current user's account. ### Using wagmi hooks for transactions When using `OpenfortWagmiBridge`, wagmi's native hooks work with the Openfort embedded wallet. Example with `useWriteContract` for an ERC-20 transfer: ```tsx import { useWriteContract } from "wagmi" import { parseUnits } from "viem" const usdcAbi = [ { name: "transfer", type: "function", stateMutability: "nonpayable", inputs: [{ name: "to", type: "address" }, { name: "amount", type: "uint256" }], outputs: [{ name: "success", type: "bool" }] }, ] as const function TransferButton() { const { writeContract, data: hash, isPending } = useWriteContract() return ( ) } ``` `useSendTransaction`, `useAccount`, `useBalance`, `useSignMessage`, and `useWalletClient` also work through the bridge. ### Using wallet\_sendCalls directly Use `useWalletClient` from wagmi for direct `wallet_sendCalls` RPC: ```tsx import { useWalletClient } from "wagmi" import { encodeFunctionData, parseUnits } from "viem" const usdcAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" const usdcAbi = [ { name: "transfer", type: "function", stateMutability: "nonpayable", inputs: [{ name: "to", type: "address" }, { name: "amount", type: "uint256" }], outputs: [{ name: "success", type: "bool" }] }, ] as const function useSendUsdc() { const { data: walletClient } = useWalletClient() return async (to: `0x${string}`, amount: string) => { if (!walletClient?.chain || !walletClient.account) throw new Error("Wallet client not ready") const data = encodeFunctionData({ abi: usdcAbi, functionName: "transfer", args: [to, parseUnits(amount, 6)] }) return walletClient.request({ method: "wallet_sendCalls", params: [{ version: "1.0", chainId: `0x${walletClient.chain.id.toString(16)}`, from: walletClient.account.address, calls: [{ to: usdcAddress, value: "0x0", data }], }], }) } } ``` ### Gas sponsorship Wire `ethereumFeeSponsorshipId` into `walletConfig.ethereum`. Create policies at [Dashboard → Gas sponsorship](https://dashboard.openfort.io/policies): ```tsx walletConfig={{ shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY", ethereum: { chainId: 84532, ethereumFeeSponsorshipId: "pol_...", }, }} ``` ### EOA wallets on a custom chain For EOA wallets on a custom chain, define the chain with `defineChain` and pass it to `getDefaultConfig`. Set `accountType: AccountTypeEnum.EOA` in `walletConfig.ethereum` and `enforceSupportedChains: false` in `uiConfig`: ```tsx [Providers.tsx] import { defineChain } from "viem" import { WagmiProvider, createConfig, http } from "wagmi" import { AccountTypeEnum, AuthProvider, OpenfortProvider, RecoveryMethod } from "@openfort/react" import { getDefaultConfig, OpenfortWagmiBridge } from "@openfort/react/wagmi" import { QueryClient, QueryClientProvider } from "@tanstack/react-query" const customMainnet = defineChain({ id: 12345, name: "Custom Mainnet", network: "custom", nativeCurrency: { name: "Cust", symbol: "CUST", decimals: 18 }, rpcUrls: { default: { http: ["https://rpc.custom.xyz"] }, }, blockExplorers: { default: { name: "customscan", url: "https://customscan.io" }, }, testnet: true, }) const wagmiConfig = createConfig( getDefaultConfig({ appName: "Your App Name", chains: [customMainnet], transports: { [customMainnet.id]: http() }, walletConnectProjectId: "YOUR_WALLETCONNECT_PROJECT_ID", }) ) const queryClient = new QueryClient() export function Providers({ children }: { children: React.ReactNode }) { return (Processing...
;
if (isSuccess) return Success!
;
return null;
}
```
## Return type
```ts
type UseAuthCallbackReturn = {
// Detected auth provider from URL.
provider: UIAuthProvider | null
// Email from verification URL.
email: string | null
verifyEmail(options: VerifyEmailOptions): PromiseUser ID: {user?.id}
Email: {user?.email}
Linked accounts: {linkedAccounts?.length}
Not connected
return {address} on chain {chainId}
}
```
**Manage wallets** (create, list, switch):
```tsx
import { useEthereumEmbeddedWallet } from "@openfort/react/ethereum"
function WalletList() {
const { wallets, activeWallet, setActive } = useEthereumEmbeddedWallet()
return (
{wallets.map((w) => (
))}
)
}
```
## Return type
The hook returns `EthereumWalletState` (`EthereumWalletStateBase & WalletDerived & ConnectedWalletState`). All status variants include the actions and the derived/connected fields; the status-specific fields below vary by `status`.
```ts
type EthereumWalletState = {
// --- Actions (all statuses) ---
create(options?: CreateEmbeddedWalletOptions): PromiseWallet: {address}
} ``` For granular UI states (loading, recovery prompts, errors) read the `status` discriminated union instead — see [Return type](#return-type). **List and switch wallets** (cluster from provider/context): ```tsx import { useSolanaEmbeddedWallet } from "@openfort/react/solana" function WalletList() { const { wallets, activeWallet, setActive, create } = useSolanaEmbeddedWallet() return (
{wallets.map((w) => (
))}
)
}
```
**With options** (parity with Ethereum’s `useEthereumEmbeddedWallet({ chainId: 1 })`): pass `cluster` to override the cluster from context, and optionally `recoveryParams` for wallet access:
```tsx
const { cluster, rpcUrl, activeWallet } = useSolanaEmbeddedWallet({ cluster: 'mainnet-beta' })
// Or with recovery params
const { cluster, rpcUrl } = useSolanaEmbeddedWallet({ cluster: 'devnet', recoveryParams: { ... } })
```
## Return type
The hook returns `SolanaWalletState` (`SolanaWalletStateBase & SolanaWalletDerived & ConnectedWalletState`). All status variants include the actions and the derived/connected fields; the status-specific fields below vary by `status`.
```ts
type SolanaCluster = 'mainnet-beta' | 'devnet' | 'testnet'
type SolanaWalletState = {
// --- Actions (all statuses) ---
create(options?: CreateEmbeddedWalletOptions): PromiseLoading...
;
if (error) return Error: {error.message}
;
return (
-
{assets?.map((asset) => (
- {formatUnits(asset.balance, asset.metadata?.decimals ?? 18)} {asset.metadata?.symbol} ))}
Loading...
;
return (
Embedded state: {embeddedState}
User ID: {user?.id}
{getStateMessage()}
; } ``` # `useGrantPermissions` Grant permissions to session keys using EIP-7715 for scoped, time-limited transactions. Both `useGrantPermissions` and `useRevokePermissions` use the Ethereum bridge directly (no SIWE dependency). External wallets (e.g. MetaMask) connected via wagmi work for session key grant/revoke. ## Usage ```tsx import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'; import { useGrantPermissions } from '@openfort/react'; function CreateSessionKey() { const { grantPermissions, isLoading } = useGrantPermissions(); const handleCreate = async () => { const sessionKey = generatePrivateKey(); const sessionAccount = privateKeyToAccount(sessionKey); // Store the session key. You need it later to sign transactions. localStorage.setItem('sessionKey', sessionKey); const result = await grantPermissions({ sessionKey: sessionKey, request: { signer: { type: 'account', data: { id: sessionAccount.address }, }, expiry: 60 * 60 * 24, // 24 hours permissions: [ { type: 'contract-call', data: { address: '0x2522f4fc9af2e1954a3d13f7a5b2683a00a4543a', calls: [], }, policies: [], }, ], }, }); console.log('Permissions granted:', result.address); }; return ; } ``` ## Return type ```ts type UseGrantPermissionsReturn = { grantPermissions(params: GrantPermissionsParams, options?: GrantPermissionsHookOptions): PromiseEndpoint examples for you to copy
Expose a GET endpoint `/api/protected-create-encryption-session` that returns `{ "session": "" }`. Use one of the examples below.
:::code-group
```ts [Express.js]
import express, { Request, Response } from 'express';
// Initialize the Openfort client // [!code focus]
import Openfort from "@openfort/openfort-node"; // [!code focus]
const openfort = new Openfort(process.env.OPENFORT_SECRET_KEY); // [!code focus]
// 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.get('/api/protected-create-encryption-session', authenticateUser, async (req: Request, res: Response) => { // [!code focus]
try { // [!code focus]
const session = await openfort.createEncryptionSession( // [!code focus]
process.env.OPENFORT_SHIELD_PUBLISHABLE_KEY as string, // [!code focus]
process.env.OPENFORT_SHIELD_SECRET_KEY as string, // [!code focus]
process.env.OPENFORT_SHIELD_ENCRYPTION_SHARE as string // [!code focus]
); // [!code focus]
res.status(200).json({ session }); // [!code focus]
} catch (e) { // [!code focus]
console.error(e); // [!code focus]
res.status(500).json({ error: 'Internal server error' }); // [!code focus]
} // [!code focus]
}); // [!code focus]
export default router;
```
```ts [Next.js (/api/protected-create-encryption-session.ts)]
import type { NextApiRequest, NextApiResponse } from 'next';
// Initialize the Openfort client // [!code focus]
import Openfort from "@openfort/openfort-node"; // [!code focus]
const openfort = new Openfort(process.env.OPENFORT_SECRET_KEY); // [!code focus]
// Use your own authentication middleware (JWT, sessions, API key, etc.) to authenticate the user here
function authenticateUser(req: NextApiRequest): boolean {
// Example: req.user = { id: 'user_123', email: 'user@example.com' };
return true;
}
export default async function handler(req: NextApiRequest, res: NextApiResponse) { // [!code focus]
// Authenticate user // [!code focus]
if (!authenticateUser(req)) { // [!code focus]
return res.status(401).json({ error: 'Unauthorized' }); // [!code focus]
} // [!code focus]
// [!code focus]
try { // [!code focus]
const session = await openfort.createEncryptionSession( // [!code focus]
process.env.OPENFORT_SHIELD_PUBLISHABLE_KEY as string, // [!code focus]
process.env.OPENFORT_SHIELD_SECRET_KEY as string, // [!code focus]
process.env.OPENFORT_SHIELD_ENCRYPTION_SHARE as string // [!code focus]
); // [!code focus]
res.status(200).json({ session }); // [!code focus]
} catch (e) { // [!code focus]
console.error(e); // [!code focus]
res.status(500).json({ error: 'Internal server error' }); // [!code focus]
} // [!code focus]
} // [!code focus]
```
:::