openfort-embedded-wallet

Openfort 嵌入式钱包设置

⚠️ 测试密钥与正式密钥——发布前请阅读。 Openfort 运行着两个完全隔离的环境：测试模式（pk_test_…，仅限测试网）和正式模式（pk_live_…，主网，真实资金）。一个环境中的钱包及其恢复（Shield）配置无法在另一个环境中访问。

• 使用测试（开发）可发布密钥创建的钱包仅在测试网上有效，绝不能用于存放真实用户资金。
• 要上线正式环境，请切换到正式可发布密钥（以及正式 Shield 密钥）——用户将获得全新钱包；测试钱包及其恢复份额不会迁移。
• 可发布密钥可在客户端安全使用；切勿将密钥（sk_…）发送到浏览器或应用中。 请参阅 https://openfort.io/docs/configuration/api-keys。

嵌入式钱包通过简化钱包管理，提供无缝体验。用户无需了解私钥、助记词或区块链概念，即可使用你的应用。

选择 SDK

Openfort 为多个平台提供嵌入式钱包 SDK：

平台	软件包	最适合
React / Next.js	@openfort/react	带有预构建 UI 模态框的 Web 应用
React Native / Expo	@openfort/react-native	移动应用（iOS + Android）
iOS / Swift	OpenfortSwift	原生 iOS 应用
Unity / C#	openfort-csharp-unity	游戏（Windows、macOS、Android、iOS、WebGL）
Vanilla JS / TS	@openfort/openfort-js	自定义 UI、任意 JS 框架、底层访问

我应该使用哪个 SDK？

• 如果你要构建 React 或 Next.js Web 应用 → 使用 @openfort/react（包含预构建的身份验证模态框和钱包 UI）
• 如果你要构建 React Native / Expo 移动应用 → 使用 @openfort/react-native
• 如果你要构建原生 iOS 应用 → 使用 OpenfortSwift
• 如果你要构建 Unity 游戏 → 使用 openfort-csharp-unity
• 如果你使用 Svelte、Vue、Angular、vanilla JS 构建，或需要自定义登录流程 → 使用 @openfort/openfort-js

如需各 SDK 的详细 API 参考，请参阅参考文件：

• references/openfort-react.md — React / Next.js
• references/openfort-react-native.md — React Native / Expo
• references/openfort-swift.md — iOS / Swift
• references/openfort-unity.md — Unity / C#
• references/openfort-js.md — Vanilla JS / TS

---

快速开始：搭建新项目

使用 Openfort CLI 是开始构建 Web 应用的最快方式：

npm create openfort@latest
# or
pnpm create openfort@latest
# or
yarn create openfort

此命令会搭建一个新项目，其中包含所有依赖项、配置和可用的嵌入式钱包集成。你可以选择：

• 框架：Vite 或 Next.js
• 身份验证提供方：Google、电子邮件、通行密钥等
• 嵌入式钱包：已预配置恢复功能
• UI 主题：从内置主题中选择

CLI 目前仅搭建 React Web 应用。其他平台请按照下面的手动设置步骤操作。

---

前提条件（所有平台）

集成任何 SDK 之前，请从 Openfort Dashboard 获取密钥：

1. 可发布密钥（pk_test_...）——用于标识你的项目
2. Shield 可发布密钥（your-shield-publishable-key）——用于嵌入式钱包加密
3. 恢复端点（推荐）——用于自动恢复钱包的后端 URL
4. 费用赞助 ID（pol_...，可选）——用于免 Gas 交易

---

React / Next.js — @openfort/react

预构建的身份验证模态框和钱包 UI。支持 Ethereum（EVM）和 Solana 链。

安装

# Ethereum (EVM) — with wagmi
npm install @openfort/react @tanstack/react-query wagmi viem

# Solana — no wagmi needed
npm install @openfort/react @tanstack/react-query @solana/kit

环境变量

VITE_OPENFORT_PUBLISHABLE_KEY=pk_test_...
VITE_SHIELD_PUBLISHABLE_KEY=your-shield-publishable-key
VITE_WALLET_CONNECT_PROJECT_ID=...               # Optional — enables external wallets (EVM only)
VITE_FEE_SPONSORSHIP_ID=pol_...                   # Optional — gasless transactions
VITE_CREATE_ENCRYPTED_SESSION_ENDPOINT=https://... # Backend endpoint for automatic recovery

对于 Next.js，请使用 NEXT_PUBLIC_ 前缀，而不是 VITE_。

Ethereum Provider 设置

Provider 堆栈为：QueryClientProvider → WagmiProvider → OpenfortWagmiBridge → OpenfortProvider。

"use client" // Required in Next.js App Router

import { OpenfortProvider, AuthProvider } from '@openfort/react'
import { getDefaultConfig, OpenfortWagmiBridge } from '@openfort/react/wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { base, baseSepolia } from 'viem/chains'
import { createConfig, http, WagmiProvider } from 'wagmi'

const config = createConfig(
  getDefaultConfig({
    appName: 'My App',
    chains: [base, baseSepolia],
    walletConnectProjectId: import.meta.env.VITE_WALLET_CONNECT_PROJECT_ID,
    transports: {
      [base.id]: http('https://your-base-rpc.com'),
      [baseSepolia.id]: http(),
    },
  }),
)

const queryClient = new QueryClient()

const walletConfig = {
  shieldPublishableKey: import.meta.env.VITE_SHIELD_PUBLISHABLE_KEY!,
  ethereum: {
    ethereumFeeSponsorshipId: import.meta.env.VITE_FEE_SPONSORSHIP_ID,
  },
  createEncryptedSessionEndpoint: import.meta.env.VITE_CREATE_ENCRYPTED_SESSION_ENDPOINT,
  connectOnLogin: true,
}

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <WagmiProvider config={config}>
        <OpenfortWagmiBridge>
          <OpenfortProvider
            publishableKey={import.meta.env.VITE_OPENFORT_PUBLISHABLE_KEY!}
            walletConfig={walletConfig}
            uiConfig={{
              theme: 'midnight',
              mode: 'dark',
              authProviders: [AuthProvider.GOOGLE, AuthProvider.EMAIL_OTP, AuthProvider.WALLET],
            }}
          >
            {children}
          </OpenfortProvider>
        </OpenfortWagmiBridge>
      </WagmiProvider>
    </QueryClientProvider>
  )
}

Solana Provider 设置

无需 wagmi，也无需桥接层——只需 QueryClientProvider → OpenfortProvider。

"use client"

import { OpenfortProvider, AuthProvider, ChainTypeEnum } from '@openfort/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

const walletConfig = {
  shieldPublishableKey: import.meta.env.VITE_SHIELD_PUBLISHABLE_KEY!,
  chainType: ChainTypeEnum.SVM,
  solana: { cluster: 'mainnet-beta' },
  createEncryptedSessionEndpoint: import.meta.env.VITE_CREATE_ENCRYPTED_SESSION_ENDPOINT,
  connectOnLogin: true,
}

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <OpenfortProvider
        publishableKey={import.meta.env.VITE_OPENFORT_PUBLISHABLE_KEY!}
        walletConfig={walletConfig}
        uiConfig={{
          theme: 'midnight',
          mode: 'dark',
          authProviders: [AuthProvider.GOOGLE, AuthProvider.EMAIL_OTP],
        }}
      >
        {children}
      </OpenfortProvider>
    </QueryClientProvider>
  )
}

用法 — OpenfortButton

OpenfortButton 会根据用户状态自动调整：

• 未登录 → 显示“连接”按钮 → 打开身份验证模态框
• 已登录 + 有钱包 → 显示钱包地址 → 打开个人资料／钱包模态框
• 已登录，无钱包 → 创建钱包时显示加载状态

import { OpenfortButton } from '@openfort/react'

function App() {
  return <OpenfortButton />
}

关键钩子（React）

// Auth
import { useUser, useEmailAuth, useEmailOtpAuth, usePhoneOtpAuth, useOAuth, useGuestAuth, useSignOut } from '@openfort/react'

// Wallet
import { useEthereumEmbeddedWallet } from '@openfort/react/ethereum'
import { useSolanaEmbeddedWallet } from '@openfort/react/solana'

// UI control
import { useUI } from '@openfort/react' // open/close modal programmatically

// wagmi integration
import { useWalletAuth, useChainIsSupported } from '@openfort/react/wagmi'

uiConfig 选项

uiConfig={{
  theme: 'midnight',              // 'auto' | 'web95' | 'retro' | 'soft' | 'midnight' | 'minimal' | 'rounded' | 'nouns'
  mode: 'dark',                   // 'light' | 'dark' | 'auto'
  authProviders: [AuthProvider.GOOGLE, AuthProvider.EMAIL_OTP, AuthProvider.WALLET],
  authProvidersLength: 4,         // How many to show before "More options"
  walletRecovery: {
    allowedMethods: [RecoveryMethod.AUTOMATIC, RecoveryMethod.PASSKEY],
    defaultMethod: RecoveryMethod.AUTOMATIC,
  },
  // termsOfServiceUrl, privacyPolicyUrl, disclaimer, customTheme, logo, etc.
}}

---

React Native / Expo — @openfort/react-native

原生移动端 SDK。支持 Ethereum 和 Solana 嵌入式钱包。

安装

npx --yes expo install expo-apple-authentication expo-application expo-crypto expo-secure-store expo-constants
npm install react-native-get-random-values @openfort/react-native

# Optional:
npm install react-native-passkeys          # For passkey recovery
npx expo install expo-web-browser expo-linking  # For OAuth

入口点

必须首先导入 react-native-get-random-values：

// entrypoint.ts
import "react-native-get-random-values";
import "expo-router/entry";

更新 package.json：{ "main": "entrypoint.ts" }

设置 Provider

import { OpenfortProvider, RecoveryMethod } from "@openfort/react-native";
import Constants from "expo-constants";

export default function RootLayout() {
  return (
    <OpenfortProvider
      publishableKey={Constants.expoConfig?.extra?.openfortPublishableKey}
      walletConfig={{
        shieldPublishableKey: Constants.expoConfig?.extra?.openfortShieldPublishableKey,
        recoveryMethod: RecoveryMethod.AUTOMATIC,
        feeSponsorshipId: Constants.expoConfig?.extra?.openfortPolicyId,
        createEncryptedSessionEndpoint: Constants.expoConfig?.extra?.openfortShieldRecoveryEndpoint,
      }}
      supportedChains={[{
        id: 84532,
        name: 'Base Sepolia',
        nativeCurrency: { name: 'Base Sepolia Ether', symbol: 'ETH', decimals: 18 },
        rpcUrls: { default: { http: ['https://sepolia.base.org'] } },
      }]}
      verbose={__DEV__}
    >
      {/* Your app */}
    </OpenfortProvider>
  );
}

无需 wagmi、桥接层、QueryClientProvider 或手动配置 WebView——只需使用 OpenfortProvider。

关键钩子（React Native）

import { useEmbeddedEthereumWallet } from '@openfort/react-native'  // EVM
import { useEmbeddedSolanaWallet } from '@openfort/react-native'    // Solana
import { AuthBoundary } from '@openfort/react-native'                // Auth state boundary
import { useUser, useEmailAuth, useEmailAuthOtp, useOAuth, useGuestAuth, useSignOut } from '@openfort/react-native'

AuthBoundary

<AuthBoundary
  loading={<LoadingScreen />}
  unauthenticated={<LoginScreen />}
  error={(error) => <ErrorScreen error={error} />}
>
  <MainApp />
</AuthBoundary>

---

iOS / Swift — OpenfortSwift

适用于 iOS 应用的原生 Swift SDK。仅支持 Ethereum（EVM）。

安装

通过 Swift Package Manager 添加：https://github.com/openfort-xyz/swift-sdk.git

配置

将 OFConfig.plist 添加到 Xcode 项目：

• openfortPublishableKey（必需）
• shieldPublishableKey（必需）
• shieldEncryptionKey 或 shieldEncryptionEndpoint（用于恢复）

初始化

import OpenfortSwift

// In AppDelegate or App init:
try OFSDK.initialize()

// With third-party auth:
try OFSDK.initialize(thirdPartyAuth: .init(
    provider: .firebase,
    getAccessToken: { try await Auth.auth().currentUser?.getIDToken() ?? "" }
))

钱包与身份验证

let sdk = OFSDK.shared

// Authenticate
try await sdk.logInWithEmailPassword(email: "[email protected]", password: "pass")
try await sdk.initOAuth(provider: .google, redirectTo: "myapp://callback")

// Configure embedded wallet (auto create or recover)
let account = try await sdk.configureEmbeddedWallet(
    chainId: 80002,
    recoveryMethod: .automatic(encryptionSession: session)
)

// Get EIP-1193 provider
let provider = try sdk.getEthereumProvider(policy: "pol_...")

// Send transaction
let txHash = try await provider.request(method: "eth_sendTransaction", params: [...])

---

Unity / C# — openfort-csharp-unity

支持 Windows、macOS、Android、iOS 和 WebGL 的游戏 SDK。

安装

通过 UPM git URL 安装：https://github.com/openfort-xyz/openfort-csharp-unity.git?path=/src/Packages/OpenfortSDK

需要 UniTask v2.3.3。

初始化与身份验证

using Openfort;

var sdk = await OpenfortSDK.Init("pk_test_...", "your-shield-publishable-key");

// Authenticate
await sdk.LogInWithEmailPassword("[email protected]", "pass");

// Configure embedded wallet
var account = await sdk.ConfigureEmbeddedWallet(
    chainId: 80002,
    recoveryMethod: RecoveryMethod.Automatic,
    encryptionSession: session
);

// Get provider and send transaction
var provider = sdk.GetEthereumProvider(policy: "pol_...");
var txHash = await provider.Request("eth_sendTransaction", new object[] { txParams });

---

Vanilla JavaScript / TypeScript — @openfort/openfort-js

用于自定义登录流程和直接访问底层 API 的低级 SDK。可与任何框架（Svelte、Vue、Angular 等）配合使用，也可完全不依赖框架。

安装

npm install @openfort/openfort-js@latest

初始化

import { Openfort } from '@openfort/openfort-js'

const openfort = new Openfort({
  baseConfiguration: { publishableKey: 'pk_test_...' },
  shieldConfiguration: { shieldPublishableKey: 'your-shield-publishable-key' },
})

await openfort.waitForInitialization()

身份验证与钱包

// Authenticate
await openfort.auth.logInWithEmailPassword({ email: '[email protected]', password: 'pass' })

// Or OAuth
const url = await openfort.auth.initOAuth({ provider: OAuthProvider.GOOGLE, redirectTo: '...' })

// Configure embedded wallet (auto create or recover)
const account = await openfort.embeddedWallet.configure({
  chainId: 80002,
  recoveryParams: {
    recoveryMethod: RecoveryMethod.AUTOMATIC,
    encryptionSession: await fetchEncryptionSession(),
  },
})

// Get EIP-1193 provider
const provider = await openfort.embeddedWallet.getEthereumProvider({ policy: 'pol_...' })

// Send transaction
const txHash = await provider.request({
  method: 'eth_sendTransaction',
  params: [{ from: account.address, to: '0x...', value: '0x...', data: '0x' }],
})

Web3 库集成

// Viem
import { createWalletClient, custom } from 'viem'
const walletClient = createWalletClient({ chain: sepolia, transport: custom(provider) })

// Ethers.js v6
import { ethers } from 'ethers'
const ethersProvider = new ethers.BrowserProvider(provider)
const signer = await ethersProvider.getSigner()

---

通用概念（适用于所有平台）

身份验证提供商

所有 SDK 都支持相同的身份验证方式：

• 电子邮件 + 密码 — 传统注册／登录
• 电子邮件 OTP — 无密码魔法链接
• 手机 OTP — 短信验证
• OAuth — Google、Apple、Twitter、Discord、Facebook、LINE、Epic Games
• 访客 — 匿名身份，之后可升级
• SIWE — 使用 Ethereum 登录（外部钱包）
• 第三方身份验证 — Firebase、Supabase、Auth0 等

恢复方式

嵌入式钱包使用客户端加密。用户更换设备时需要进行恢复：

• 自动（推荐）— 后端加密会话，无缝完成
• 密码 — 用户提供的密码
• 通行密钥 — 生物识别（Face ID、指纹）— iOS 18+ / Android 14+

无 Gas 交易（费用赞助）

在控制台的 Policies 和 Fee Sponsorship 下设置 Gas 赞助，然后将 pol_... ID 传入 SDK 配置。

支持的链

Openfort 嵌入式钱包支持任意 EVM 链和 Solana。在 SDK 设置中配置链 ID 和 RPC URL。

---

文档与资源

• 完整文档：https://www.openfort.io/docs/products/embedded-wallet
• React 快速入门：https://www.openfort.io/docs/products/embedded-wallet/react
• React Native 快速入门：https://www.openfort.io/docs/products/embedded-wallet/react-native
• Swift 快速入门：https://www.openfort.io/docs/products/embedded-wallet/swift
• Unity 快速入门：https://www.openfort.io/docs/products/embedded-wallet/unity/quickstart
• JS 快速入门：https://www.openfort.io/docs/products/embedded-wallet/javascript/quickstart
• 控制台：https://dashboard.openfort.io
• GitHub 示例：https://github.com/openfort-xyz