web3auth

MetaMask Embedded Wallets (Web3Auth)

编写代码前，请使用 MCP 工具查阅实时文档和示例。请勿猜测包名、API 签名或配置。

控制台：https://developer.metamask.io
文档：https://docs.metamask.io/embedded-wallets/
社区：https://builder.metamask.io/c/embedded-wallets/5

MCP 工具（按顺序使用）

示例和 SDK 源码通过 GitHub 实时发现。references/examples.md 仅包含筛选方法。生成代码前务必先调用 get_example。MCP 实时服务：https://mcp.web3auth.io

1. search_docs — 搜索文档（Algolia）和示例项目。
   • query（必填）
   • platform?：react | vue | js | react-native | android | ios | flutter | unity | unreal | node
   • chain?：evm | solana | other
   • category?：quick-start | custom-auth | blockchain | feature | playground
2. get_doc — 按 URL 获取完整文档页面（docs.metamask.io）。生成代码前先阅读对应平台的 SDK 文档。
3. get_example — 从 GitHub 获取完整示例源码（主要集成参考）。
   • name?、platform?、chain?、category?、auth_method?（例如 firebase、auth0、grouped）
   • 开始新的集成时，务必先获取 quick-start；使用自定义身份验证时，获取对应的身份验证示例。
   • 查看筛选方法和 eval 锚点名称references/examples.md
4. search_community — Builder Hub。使用 query? 搜索，或使用 topic_id? 获取完整讨论串。
5. get_sdk_reference — 仅用于调试类型/签名的 SDK 源码（不可用于发现功能）。
   • platform（必填）、module?（首次省略以列出模块）、focus?：types | hooks | main-class | errors | all（默认值为 types）

MCP 不可用时： https://docs.metamask.io/llms-embedded-wallets-full.txt（完整文档），https://docs.metamask.io/llms-embedded-wallets.txt（索引）。

前提条件 - 控制台设置流程

1. 在 developer.metamask.io 创建项目 → 获取 Client ID。
2. 选择 Sapphire Devnet（本地）或 Mainnet（生产环境）。
3. 将域名（Web）或 bundle ID + 深度链接方案（移动端）加入允许列表。
4. 在控制台配置链（Web/Node），或在代码中配置（RN、Android、iOS、Flutter、Unity、Unreal）。
5. 身份验证：使用默认社交登录或自定义连接。
6. 可选项：会话时长、测试账号、密钥导出、白标。

阅读 https://docs.metamask.io/embedded-wallets/dashboard/

密钥派生规则（重要）

要获得相同的钱包地址，必须满足以下所有条件：

• Client ID 相同
• Sapphire 网络相同（devnet 或 mainnet，绝不可混用）
• 连接配置相同（auth connection ID 相同）
• 集成中的 useSFAKey 布尔值相同。

更改其中任意一项 → 地址将永久不同。

• 在生产环境中，绝不可更改 Client ID 或 Sapphire 网络。
• Sapphire 并非区块链 devnet/mainnet。Devnet 允许 localhost；Mainnet 不允许。
• 本地开发和预发布环境：使用 Sapphire Devnet。生产环境：仅使用 Sapphire Mainnet。请勿在生产环境中使用 Devnet。
• 避免随意添加 useSFAKey / useCoreKitKey 等标志——除非用户已经在使用，或希望使用钱包预生成。钱包预生成仅在 useSFAKey / useCoreKitKey 为 true 时有效。

SDK 选择

选择	适用场景
React (@web3auth/modal/react)	React、Next.js — Hooks
Vue (@web3auth/modal/vue)	Vue、Nuxt — Composables
JavaScript (@web3auth/modal)	Angular、Svelte、原生 JavaScript
React Native (@web3auth/react-native-sdk)	Expo 或 Bare RN - Hooks
Android / iOS / Flutter	原生移动 SDK — 导出密钥 + 平台库（不内置 provider）
Unity / Unreal	游戏 SDK — 导出密钥 + 平台库（不内置 provider）
Node.js (@web3auth/node-sdk)	后端、AI Agent — 仅自定义 JWT，无状态

各平台详情和注意事项：references/platforms.md

场景

按任务查找 fetch / tripwire / verify 工作流：references/scenarios.md

示例目录【最重要】

示例托管在 GitHub 上；编写集成代码前，请调用 get_example 或 search_docs。MCP 筛选配方和评估锚点名称：references/examples.md

身份验证

连接、隐式流程与 JWT 流程、分组连接、JWT iat 规则：references/authentication.md

迁移

升级现有集成——版本表、工作流、旧版 PnP/CoreKit/SFA：references/migration.md

摘要： 每个平台都有一份升级到当前主版本的指南（Web v11、RN v9、Android v9、iOS v10、Flutter v6）。请使用各指南中的 AI 辅助提示词。除非有意为之，否则切勿更改 Client ID 或 Sapphire 网络。

• 迁移索引：https://docs.metamask.io/embedded-wallets/migration-guides/