mini-apps

Nimiq Mini Apps

Mini App 是一种在移动版 WebView 中运行于 Nimiq Pay 内的 Web 应用。它通过注入的 Provider 与钱包通信。应用在沙箱中运行，无法访问私钥。每项敏感操作都需要用户通过原生对话框批准。

如何继续

如果开发者的请求已经表明了方向，请直接前往相应步骤：

• 想要构建、创建、启动或搭建新项目 → 阅读并遵循 references/scaffold.md
• 有现有代码需要转换、移植、迁移或适配 → 阅读并遵循 references/convert.md
• 想在发布前检查、审核、验证或审计 → 阅读并遵循 references/checklist.md
• 已经在开发，并提出了具体问题 → 根据需要继续遵循以下规则并查阅 API 参考

如果请求没有上下文或意图不明确，请展示以下选项并让开发者选择：

1. 从头开始 — 我有一个想法，但还没有项目
2. 转换现有应用 — 我想让一个 Web 应用在 Nimiq Pay 内运行
3. 检查应用是否已准备就绪 — 我想在发布前验证我的 Mini App
4. 直接开发 — 我已经在开发，只需要了解规则和 API

不要猜测。在弄清楚开发者的需求之前，不要加载参考文档。

完成搭建或转换流程后，始终在最后一步运行检查清单（references/checklist.md）。在任何流程中，只要开发者表示应用已完成、准备就绪或已开发完毕，就运行检查清单。

Providers

有两种 Provider 可供使用。根据应用的需求选择其中一种或同时使用。

Nimiq provider

用于 NIM 支付、消息签名、质押和区块链状态查询。只能通过 Mini App SDK 的 init() 助手访问。绝不能通过其他方式访问。

import { init } from '@nimiq/mini-app-sdk'

const nimiq = await init()

可用能力：

• 账户访问：列出用户的 Nimiq 地址。需要用户确认。
• 消息签名：使用用户的 Nimiq 密钥为任意消息签名。需要用户确认。
• 共识和区块状态：检查钱包是否已达成网络共识，获取当前区块高度。无需确认。
• NIM 支付：发送基本 NIM 交易，可附带文本数据，也可不附带。金额单位为 Luna（1 NIM = 100,000 Luna）。方法：sendBasicTransaction、sendBasicTransactionWithData。
• 质押：所有操作都需要用户确认。能力对应方法：创建新的质押者（sendNewStakerTransaction）、增加质押（sendStakeTransaction）、设置活跃质押（sendSetActiveStakeTransaction）、更新委托（sendUpdateStakerTransaction）、退出质押（sendRetireStakeTransaction）、移除质押（sendRemoveStakeTransaction）。

关于准确的方法签名、参数和返回类型，请参阅 references/nimiq-provider-api.md。

Ethereum 提供方

用于 EVM 链交互、ERC-20 代币、消息签名和合约调用。通过 window.ethereum 访问。这是标准的 EIP-1193 提供方。无需 SDK。

可用功能：

• 账户访问：请求用户的 Ethereum 地址。同一地址可用于所有 EVM 链。需要用户确认。
• 消息签名：对于类型化结构化数据（许可、订单批准、登录质询），优先使用 eth_signTypedData_v4（EIP-712）。它会向用户展示所签名内容的可读明细，而不是不透明的哈希值。仅当纯文本消息没有值得展示的结构时，才使用 personal_sign。两者都需要用户确认。
• 交易：发送原生代币转账或合约调用（eth_sendTransaction）。需要用户确认。
• 链管理：切换当前 EVM 链（wallet_switchEthereumChain）或添加新链（wallet_addEthereumChain）。需要用户确认。
• 只读查询：获取余额、调用合约、估算 Gas、读取区块和日志、获取交易回执。无需确认。通过 RPC 路由。
• 任意 RPC：对于标准列表中未包含的方法，rpcCall 会通过宿主代理 JSON-RPC 请求。请谨慎使用；优先使用上述类型化方法。
• 发现：Nimiq Pay 实现了 EIP-6963，因此钱包发现库（wagmi、RainbowKit 等）会自动检测到它。你无需手动广播该提供方。

有关确切的方法签名、参数和返回类型，请参阅 references/ethereum-provider-api.md。

支持的 EVM 链

这些是 Nimiq Pay 当前提供的链。可以使用 wallet_addEthereumChain 添加自定义链。Sepolia 仅用于开发和测试。请勿发布会在 Sepolia 上进行交易、面向真实用户的迷你应用。

有关链 ID、代币地址和小数位数，请参阅 references/chains-and-tokens.md。

ERC-20 代币规则

任何受支持链上的 ERC-20 代币都可以通过 window.ethereum 访问。无需自定义提供方或额外设置。

操作流程始终如下：

1. 使用 wallet_switchEthereumChain 切换到正确的链
2. 使用 eth_call 调用代币合约（用于读取 balanceOf 等数据），或使用 eth_sendTransaction（用于 transfer 等写入操作）

使用 EVM 库（viem、ethers.js 或 wagmi）进行 ABI 编码。请勿手动编码合约调用。

USDT 和 USDC 使用 6 位小数，而不是大多数 ERC-20 代币使用的 18 位。解析或格式化金额时，始终使用代币实际的 decimals 值。若将 1 USDT 余额按 18 位小数显示，就会显示为 0.000000000001，而不是 1.0。

移动端优先

迷你应用在移动设备上的 Nimiq Pay 内运行。每项 UI 决策都必须考虑这一点：

• 优先针对小屏幕设计。不要仅适配桌面端的布局。
• 使用适合触控的点击区域（最小 44px）。
• 避免水平滚动。
• 在实际设备或设备模拟环境中测试，不要只在桌面浏览器中测试。

用户语言

Nimiq Pay 会通过 window.nimiqPay.language 提供用户选择的语言。该值是 ISO 639-1 双字母代码（例如，'en'、'de'），会在页面脚本运行前注入，只读，且在每个会话中保持不变。构建带有本地化或国际化功能的内容时，请使用此值，以匹配用户的 Nimiq Pay 语言设置。

Nimiq 网络

Nimiq Pay 会通过 window.nimiqPay.network（'mainnet' 或 'testnet'）提供其运行的 Nimiq 网络；也可通过 @nimiq/mini-app-sdk 0.2.4+ 中的 getHostNetwork() 获取。该值会在页面脚本运行前注入，只读，且在每个会话中保持不变。在 Nimiq Pay 外部以及较旧版本的 Nimiq Pay 中，该值为 undefined，因此请回退到 'mainnet'。当迷你应用使用特定于网络的端点、区块浏览器链接或地址时，请根据此值进行选择。

全屏

如果 Mini App 需要全屏，请提供明确的用户控件，例如 进入全屏，并在用户选择后调用 window.nimiqPay.requestFullscreen()。@nimiq/mini-app-sdk 0.2.3 及更高版本会导出与之对应的 requestFullscreen()、exitFullscreen()、getFullscreen() 和 onFullscreenChange() 辅助函数。Nimiq Pay 不会添加审批提示。请跟踪原生退出操作、检查宿主是否可用，并处理被拒绝的调用。

外部 API 和后端

Mini App 可以也应该调用外部 API 并使用服务端后端。这能让 Mini App 功能更丰富。唯一的限制是，钱包操作（付款、签名、账户访问）必须通过注入的提供程序进行。

当 Mini App 调用由开发者控制的后端时，后端必须在 Access-Control-Allow-Origin 响应头中包含 Mini App 的来源。来源是 Nimiq Pay 加载 Mini App 时使用的网址。

在开发环境中，Mini App 在手机上的 Nimiq Pay 中运行，因此从 WebView 内部访问 localhost 时，解析到的是手机，而非开发机器。如果后端在开发期间也在本地运行，请将 fetch URL 指向开发机器的局域网 IP（例如 http://192.168.x.x:3000），而不是 localhost。

审批对话框体验

不要快速连续发起多个需要用户确认的提供程序调用。每次确认都会触发一个需要用户响应的原生对话框。排队发起多个调用会造成令人困惑的体验。只读调用可以自由批量处理，但需要确认的调用应依照清晰的用户意图依次进行。

在测试网上测试

Nimiq Pay 有一个隐藏的开发菜单，可切换网络。长按设置按钮 10 秒即可显示。选项：Default、Mainnet、Testnet。

测试网开关只影响 Nimiq 提供程序操作。EVM 操作仍会在主网链上运行。对于 EVM 测试，开发者可以使用 wallet_addEthereumChain 添加自定义链（例如 Sepolia）。

建议支付或质押测试流程时，请推荐使用测试网，以避免使用真实资金。

在测试网上，点击“获取免费 NIM”按钮，每次请求都会为账户充值 110'000 NIM。该按钮会显示在首页空状态和充值弹窗中。

反模式

请勿进行以下操作：

• 请勿访问私钥。 应用在沙盒中运行。密钥绝不会离开钱包。所有签名都通过审批对话框进行。
• 请勿绕过审批对话框。 每项敏感操作（账户访问、签名、交易）都必须通过 Nimiq Pay 原生对话框获得用户的明确确认。
• 请勿使用第三方支付提供商（Stripe、PayPal 等）处理付款。请仅使用 Nimiq 和 Ethereum 提供程序。

参考

文档：

• Mini App 概览
• 构建你的第一个 Mini App
• 构建双链 Mini App
• 加载本地 Mini App
• 在 Mini App 中使用 EVM 代币
• Mini App 全屏
• Nimiq 提供程序 API
• Ethereum 提供程序 API

参考实现：

• evm-mini-wallet — 功能完整的 EVM 钱包 Mini App，支持在所有受支持的链上发送和接收代币，以及跟踪余额
• nimiq-mini-app-demo — 展示所有受支持的 Nimiq 和 Ethereum 提供程序方法

Nimiq 视觉素材：

• Nimiq 设计套件