mini-apps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nimiq Mini Apps

Nimiq 迷你应用（Mini Apps）

A mini app is a web application that runs inside Nimiq Pay in a mobile WebView. It communicates with the wallet through injected providers. The app runs in a sandbox with no access to private keys. Every sensitive action requires user approval through native dialogs.

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

How to proceed

操作方式

If the developer's request already implies a path, route directly:

Wants to build, create, start, or scaffold something new → read and follow references/scaffold.md
Has existing code to convert, port, migrate, or adapt → read and follow references/convert.md
Wants to check, review, validate, or audit before shipping → read and follow references/checklist.md
Already building, asks a specific question → continue with the rules below, consult API references as needed

If invoked without context or the intent is unclear, present these options and ask the developer to choose:

Start from scratch — I have an idea and no project yet
Convert an existing app — I have a web app I want to run inside Nimiq Pay
Check if my app is ready — I want to validate my mini app before shipping
Just build — I'm already building, I just need the rules and API context

Do not guess. Do not load a reference until you understand what the developer needs.

After completing the scaffold or convert flow, always run the checklist (references/checklist.md) as the final step. When the developer says the app is done, ready, or complete during any flow, run the checklist.

如果开发者的请求已经暗示了某条路径，直接路由：

想要构建、创建、启动或初始化新项目 → 阅读并遵循 references/scaffold.md
有需要转换、移植、迁移或改造的现有代码 → 阅读并遵循 references/convert.md
希望在发布前检查、审查、验证或审计 → 阅读并遵循 references/checklist.md
已经在构建中，提出具体问题 → 继续遵循下面的规则，必要时查阅 API 参考

如果是在没有上下文的情况下被调用，或意图不明确，请展示这些选项并让开发者选择：

从零开始 —— 我有一个想法，但还没有项目
转换现有应用 —— 我有一个 Web 应用，想让它运行在 Nimiq Pay 中
检查我的应用是否就绪 —— 我想在发布前验证我的 mini app
直接构建 —— 我已经在构建了，只需要规则和 API 上下文

不要猜测。在理解开发者需求之前，不要加载任何参考文档。

完成 scaffold 或 convert 流程后，始终执行 checklist（references/checklist.md）作为最后一步。当开发者在任何流程中说应用已完成、已就绪或已结束时，运行 checklist。

Providers

Two providers are available. Use one or both depending on the app's needs.

有两个 provider 可用。根据应用需求使用其中一个或两个。

Nimiq provider

For NIM payments, message signing, staking, and blockchain state queries. Access exclusively through the Mini App SDK

init()

helper. Never access it any other way.

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

const nimiq = await init()

Available capabilities:

Account access: list the user's Nimiq addresses. Requires user confirmation.
Message signing: sign arbitrary messages with the user's Nimiq key. Requires user confirmation.
Consensus and block state: check if the wallet has network consensus, get the current block height. No confirmation needed.
NIM payments: send basic NIM transactions, with or without attached text data. Requires user confirmation. Amounts are in Luna (1 NIM = 100,000 Luna). Methods:
```
sendBasicTransaction
```
,
```
sendBasicTransactionWithData
```
.
Staking: all require user confirmation. Capability to method: create a new staker (
```
sendNewStakerTransaction
```
), add stake (
```
sendStakeTransaction
```
), set active stake (
```
sendSetActiveStakeTransaction
```
), update delegation (
```
sendUpdateStakerTransaction
```
), retire stake (
```
sendRetireStakeTransaction
```
), remove stake (
```
sendRemoveStakeTransaction
```
).

For exact method signatures, parameters, and return types, see references/nimiq-provider-api.md.

用于 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
```
。
质押：所有操作都需要用户确认。能力对应的方法：创建新的 staker（
```
sendNewStakerTransaction
```
）、增加质押（
```
sendStakeTransaction
```
）、设置活跃质押（
```
sendSetActiveStakeTransaction
```
）、更新委托（
```
sendUpdateStakerTransaction
```
）、退出质押（
```
sendRetireStakeTransaction
```
）、移除质押（
```
sendRemoveStakeTransaction
```
）。

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

Ethereum provider

For EVM chain interaction, ERC-20 tokens, message signing, and contract calls. Access via

window.ethereum

. This is a standard EIP-1193 provider. No SDK needed.

Available capabilities:

Account access: request the user's Ethereum addresses. Same address works across all EVM chains. Requires user confirmation.
Message signing: for typed structured data (permits, order approvals, login challenges) prefer
```
eth_signTypedData_v4
```
(EIP-712). It presents the user with a readable breakdown of what they're signing instead of an opaque hash. Use
```
personal_sign
```
only for plain text messages that have no structure worth showing. Both require user confirmation.
Transactions: send native token transfers or contract calls (
```
eth_sendTransaction
```
). Requires user confirmation.
Chain management: switch the active EVM chain (
```
wallet_switchEthereumChain
```
) or add a new one (
```
wallet_addEthereumChain
```
). Requires user confirmation.
Read-only queries: get balances, call contracts, estimate gas, read blocks and logs, get transaction receipts. No confirmation needed. Routed through RPC.
Arbitrary RPC:
```
rpcCall
```
proxies a JSON-RPC request through the host for methods not in the standard list. Use sparingly; prefer the typed methods above.
Discovery: Nimiq Pay implements EIP-6963, so wallet-discovery libraries (wagmi, RainbowKit, etc.) detect it automatically. You don't need to announce the provider manually.

For exact method signatures, parameters, and return types, see references/ethereum-provider-api.md.

用于 EVM 链交互、ERC-20 代币、消息签名和合约调用。通过

window.ethereum

访问。这是一个标准的 EIP-1193 provider。无需 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 等）可以自动检测到它。无需手动声明 provider。

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

Supported EVM chains

支持的 EVM 链

These are the chains currently exposed in Nimiq Pay. Custom chains can be added using

wallet_addEthereumChain

. Sepolia is for development and testing only. Do not ship mini apps that transact on Sepolia to real users.

For chain IDs, token addresses, and decimals, see references/chains-and-tokens.md.

这些是 Nimiq Pay 当前公开的链。可以使用

wallet_addEthereumChain

添加自定义链。Sepolia 仅用于开发和测试。不要将在 Sepolia 上进行交易的 mini app 发布给真实用户。

有关链 ID、代币地址和精度（decimals），请参阅 references/chains-and-tokens.md。

ERC-20 token rules

ERC-20 代币规则

Any ERC-20 token on any supported chain is accessible through

window.ethereum

. No custom provider or extra setup is needed.

The pattern is always:

Switch to the correct chain with
```
wallet_switchEthereumChain
```
Call the token contract using
```
eth_call
```
(for reads like
```
balanceOf
```
) or
```
eth_sendTransaction
```
(for writes like
```
transfer
```
)

Use an EVM library (viem, ethers.js, or wagmi) for ABI encoding. Do not manually encode contract calls.

USDT and USDC use 6 decimal places, not the 18 used by most ERC-20 tokens. Always use the token's actual

decimals

value when parsing or formatting amounts. A 1 USDT balance displayed with 18 decimals would show as

0.000000000001

instead of

1.0

任何受支持链上的任何 ERC-20 代币都可以通过

window.ethereum

访问。无需自定义 provider 或额外设置。

模式始终是：

使用
```
wallet_switchEthereumChain
```
切换到正确的链
使用
```
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

。

Mobile-first

移动优先

Mini apps run inside Nimiq Pay on mobile devices. Every UI decision must account for this:

Design for small screens first. No desktop-only layouts.
Use touch-friendly tap targets (minimum 44px).
Avoid horizontal scrolling.
Test on actual devices or device emulation, not just desktop browsers.

Mini app 运行在移动设备上的 Nimiq Pay 内。每个 UI 决策都必须考虑到这一点：

首先为小屏幕设计。不支持仅限桌面的布局。
使用适合触控的点击目标（最小 44px）。
避免横向滚动。
在真实设备或设备模拟上测试，而不仅仅是在桌面浏览器中测试。

User language

用户语言

Nimiq Pay exposes the user's selected language at

window.nimiqPay.language

. The value is an ISO 639-1 two-letter code (e.g.

'en'

'de'

), injected before page scripts run, read-only, static per session. When building anything with localization or i18n, use this value to match the user's Nimiq Pay language setting.

Nimiq Pay 在

window.nimiqPay.language

暴露用户选择的语言。该值是 ISO 639-1 两位字母代码（例如

'en'

、

'de'

），在页面脚本运行前注入，只读，每个会话静态不变。在构建任何需要本地化或 i18n 的功能时，使用该值来匹配用户的 Nimiq Pay 语言设置。

External APIs and backends

外部 API 和后端

Mini apps can and should call external APIs and use server-side backends. This makes mini apps richer. The only constraint is that wallet operations (payments, signing, account access) must go through the injected providers.

When the mini app calls a backend the developer controls, the backend must include the mini app's origin in its

Access-Control-Allow-Origin

response header. The origin is the URL Nimiq Pay loaded the mini app from.

In dev, the mini app runs in Nimiq Pay on a phone, so

localhost

from inside the WebView resolves to the phone, not the dev machine. If the backend also runs locally during dev, point

fetch

URLs at the dev machine's LAN IP (e.g.

http://192.168.x.x:3000

), not

localhost

Mini app 可以也应该调用外部 API 并使用服务端后端。这会让 mini app 更丰富。唯一的限制是钱包操作（支付、签名、账户访问）必须通过注入的 provider 进行。

当 mini app 调用开发者控制的后端时，后端必须在

Access-Control-Allow-Origin

响应头中包含 mini app 的来源（origin）。该 origin 是 Nimiq Pay 加载 mini app 所用的 URL。

在开发环境中，mini app 运行在手机上的 Nimiq Pay 中，因此 WebView 内部的

localhost

解析到手机本身，而不是开发机。如果开发时后端也在本地运行，请将

fetch

URL 指向开发机的局域网 IP（例如

http://192.168.x.x:3000

），而不是

localhost

。

Approval dialog UX

批准对话框 UX

Do not fire multiple provider calls that require user confirmation in rapid sequence. Each confirmation triggers a native dialog that the user must respond to. Queuing several creates a confusing experience. Batch read-only calls freely, but sequence confirmation-requiring calls with clear user intent between them.

不要快速连续触发多个需要用户确认的 provider 调用。每次确认都会触发一个必须由用户响应的原生对话框。将多个确认排队会造成混乱的体验。可以自由批量进行只读调用，但在需要确认的调用之间要留有清晰的用户意图。

Testing on testnet

在测试网上测试

Nimiq Pay has a hidden dev menu with a network switch. Long-press the settings button for 10 seconds to reveal it. Options: Default, Mainnet, Testnet.

The testnet switch only affects Nimiq provider operations. EVM operations continue running against mainnet chains. For EVM testing, developers can add custom chains (e.g. Sepolia) using

wallet_addEthereumChain

When suggesting test flows that involve payments or staking, recommend testnet to avoid using real funds.

On testnet, the "Get free NIM" button credits the account with 110'000 NIM per request. It appears on the home empty state and inside the Top Up modal.

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

测试网切换只影响 Nimiq provider 操作。EVM 操作继续针对主网链运行。对于 EVM 测试，开发者可以使用

wallet_addEthereumChain

添加自定义链（例如 Sepolia）。

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

在测试网上，“获取免费 NIM”按钮每次请求会向账户发放 110,000 NIM。它出现在首页空状态和充值（Top Up）弹窗中。

Anti-patterns

反模式

Do not do any of the following:

Do not access private keys. The app runs in a sandbox. Keys never leave the wallet. All signing goes through the approval dialog.
Do not bypass the approval dialog. Every sensitive action (account access, signing, transactions) requires explicit user confirmation through native Nimiq Pay dialogs.
Do not use third-party payment providers (Stripe, PayPal, etc.) for payments. Use the Nimiq and Ethereum providers exclusively.

不要做以下任何事：

不要访问私钥。 应用运行在沙箱中。密钥永远不会离开钱包。所有签名都通过批准对话框进行。
不要绕过批准对话框。 每个敏感操作（账户访问、签名、交易）都需要用户通过 Nimiq Pay 原生对话框明确确认。
不要使用第三方支付提供商（Stripe、PayPal 等）进行支付。请只使用 Nimiq 和 Ethereum provider。

Reference

参考

Documentation:

Reference implementations:

evm-mini-wallet — full EVM wallet mini app with token sends, receives, and balance tracking across all supported chains
nimiq-mini-app-demo — demo of all supported Nimiq and Ethereum provider methods

Nimiq visual assets:

Nimiq Design Kit

文档：

参考实现：

evm-mini-wallet —— 完整的 EVM 钱包 mini app，支持代币发送、接收以及所有受支持链上的余额追踪
nimiq-mini-app-demo —— 所有受支持的 Nimiq 和 Ethereum provider 方法的演示

Nimiq 视觉资源：

Nimiq Design Kit