wallet-integration

钱包集成（Para）

本技能介绍如何使用 Para 和 para CLI（@getpara/cli）为 Monad 项目的前端添加钱包和身份验证。

Para 为用户提供嵌入式 MPC 钱包——用户通过电子邮件、手机号、通行密钥或社交服务提供商（Google、Apple、Twitter、Discord、Facebook、Farcaster）登录后，即可立即获得钱包，无需浏览器扩展。Para 还支持连接外部钱包（MetaMask、Coinbase、WalletConnect、Rainbow、Zerion、Rabby），供已有钱包的用户使用。这两种流程都由同一个 ParaProvider 处理。

本技能假设前端已存在（通常由 scaffold/ 技能在 web/ 中搭建）。本技能不会搭建新应用——Para 的 para create 模板有意不在此范围内，因为项目脚手架由其他地方处理。

何时获取此技能

• 用户希望在前端添加任何钱包连接或登录流程，适用于 Monad 主网或测试网。
• 用户希望添加嵌入式钱包、社交登录、电子邮件／短信登录或通行密钥登录。
• 用户已有前端（Next.js 或 Vite），并希望将 Para 集成其中（para init + ParaProvider + para doctor）。
• 用户希望通过 CLI 管理 Para API 密钥、环境、Webhook、品牌设置或身份验证方式。
• 用户希望排查无法正常工作的钱包集成问题（para doctor）。

Para 上的 Monad

Para 的 --networks 标志支持 evm。Monad 主网和 Monad 测试网都是 EVM 链，因此适用 EVM 模板——但 Para 并未将 Monad 作为内置链对象提供。执行 para init 后，从 wagmi/chains 导入 monad 和 monadTestnet，并通过 ParaProvider 上的 externalWalletConfig.evmConnector.config.{chains,transports} 传入（v2 将链列表存放在此处——没有单独的 wagmi.ts createConfig，也没有 defaultChain 属性）。确切的代码修改请参阅 references/para-monad-wiring.md。

v2 SDK 结构——修改 Provider 前请先阅读

如果你要更新现有的 Para 集成，请注意，ParaProvider 的属性不是扁平的 apiKey={...}。v2 将其拆分为四个配置对象：

• paraClientConfig={{ apiKey, env: Environment.BETA }} — 凭据和环境（BETA / PRODUCTION）。
• config={{ appName }} — 应用元数据。
• paraModalConfig={{ oAuthMethods, disablePhoneLogin, recoverySecretStepEnabled, ... }} — 客户端侧模态框控件（显示哪些 IDP 按钮、手机号登录开关、恢复步骤）。oAuthMethods: [] 会隐藏所有社交登录选项。
• externalWalletConfig={{ evmConnector: { config: { chains, transports } }, wallets: ['METAMASK', ...] }} — 链列表、RPC 传输方式，以及要显示的外部钱包选项。

默认链 = externalWalletConfig.evmConnector.config.chains 中的第一项。没有顶层 defaultChain 属性。完整示例请参阅 references/para-workflows.md → 步骤 7。

前置条件

要运行任何 para 命令，用户必须具备以下所有条件：

1. 已全局安装 @getpara/cli：npm install -g @getpara/cli（或 pnpm add -g @getpara/cli，也可以通过 npx @getpara/cli@latest 运行）。
2. 已登录 para：para login（浏览器 OAuth 流程——只有用户本人可以完成）。
3. 已选择 Para 组织和项目作为活动上下文。执行 para login 后，CLI 会自动选择第一个组织和项目；如有需要，可通过 para orgs switch / para projects switch 切换。

monskills hook 会在安装并登录后才允许运行 para 命令。如果缺少前置条件，hook 会拒绝工具调用，并指出确切的缺失项——将该消息告知用户并等待。

不要做的事

• 不要替用户安装 CLI。 如果缺少 @getpara/cli，请告知用户准确的命令并等待。
• 不要替用户运行 para login。 该命令会打开浏览器标签页，只有用户才能完成 OAuth 流程。（无头环境可使用 --no-browser，但 monskills 面向交互式使用——让用户自行选择。）
• 不要通过 Web 门户替用户创建 Para 账户或 API 密钥。 CLI 会处理项目和密钥的创建——引导用户完成即可。
• 不要运行 para create。 项目脚手架由 scaffold/ 技能处理；此技能只将 Para 集成到已有的前端中。

将 Para 集成到现有前端

cd web   # or wherever the frontend lives
para init

para init 会写入 .pararc（组织、项目和环境上下文），然后安装 SDK 包、用 ParaProvider 封装应用，并导入 Para 的 CSS。接线完成后，运行 para doctor 验证是否有遗漏。

在沙盒或无头终端（没有真实 TTY）中，para init 会因 TTY initialization failed: uv_tty_init returned EINVAL 而退出——重新运行 para init --no-input，它便会使用全局配置中的当前组织、项目和环境，而不再提示输入。

有关具体代码修改、包列表和 para doctor 调试流程，请参阅 references/para-workflows.md →“将 Para 集成到现有前端”。

后续查阅

参考文件——按需获取：

• 工作流方案 — 针对以下任务的推荐步骤：将 Para 集成到现有前端、轮换 API 密钥，以及通过 para keys config 配置身份验证方式、品牌信息和 Webhook，还有使用 para doctor 调试。
• CLI 参考 — 按类别（身份验证、配置、组织/项目、密钥、诊断）归纳的所有 para 命令，并附有标志和注意事项。
• Monad 接线 — para init 后的具体修改，用于将 Monad 主网和测试网添加到 Para 提供程序使用的 wagmi 配置中。每次集成 Para 后都要执行这些修改。

从符合用户目标的工作流方案开始。只有在需要查找其中未涵盖的标志或子命令时，才查阅 CLI 参考。

退出码约定

每条 para 命令都遵循相同的约定——检查退出码，而不只是标准输出：

退出码	含义	应对方式
0	成功	继续
1	用户错误（参数错误、未登录、未知项目、para doctor 使用 --json 时发现错误）	查看标准错误，修正输入，然后重试
2	API/服务端错误	并非用户的问题。重试一次；如果问题仍然存在，告知用户并停止。

para doctor --json 发现错误时会以 1 退出——这是预期行为，不是 CLI 缺陷。将此作为集成存在问题的信号。

密钥安全

• para keys get --show-secret 和 para keys get --copy-secret 会打印或复制秘密 API 密钥。切勿在回复中向用户透露该值，也不要将其粘贴到会提交的文件中。公开密钥（不带标志）可安全写入 .env.local，变量名前缀为 NEXT_PUBLIC_PARA_API_KEY（或框架对应的前缀）。
• 写入密钥前，务必检查环境变量前缀是否与框架匹配：Next.js 使用 NEXT_PUBLIC_，Vite 使用 VITE_。para doctor 会标记不匹配的情况。
• .pararc 可以安全提交（其中只存储组织/项目 ID 和环境，不含密钥）。.env/.env.local 应列入 .gitignore。

官方文档

• CLI 概览：https://docs.getpara.com/v2/cli/overview
• 安装：https://docs.getpara.com/v2/cli/installation
• 命令参考：https://docs.getpara.com/v2/cli/commands