What a mini app is
A mini app is a website. That is the least exciting and most useful way to start, because everything surprising about the model is a consequence of it.
Nimiq's documentation describes mini apps as web applications that run inside the Nimiq Pay app, in what it calls a specialised web browser embedded within Nimiq Pay. Your app loads, the user stays inside Nimiq Pay, and while it is open it can ask the wallet for things it could never ask for in an ordinary browser tab: your addresses, a signature, a payment sent from your account.
So the question that matters is not what a mini app can display. It is what a mini app can cause. The rest of this page is about that boundary, and it is checkable rather than reassuring, because the SDK that draws it is published and we read it.
The wallet keeps custody, and that is enforced
The documentation states the custody model in three parts. A mini app runs in a sandbox with no direct access to private keys. The Nimiq Pay app mediates all wallet operations. Keys never leave the wallet. On top of that sits the rule that does the real work: every sensitive action requires explicit user approval through native dialogs that mini apps cannot bypass, with viewing accounts, signing messages and sending payments named as examples.
The request lifecycle the documentation sets out has five steps, and the shape is the point:
- The mini app calls a method on the provider.
- The injected provider forwards the message to the host app.
- Nimiq Pay validates it and shows a confirmation dialog where one is needed.
- Nimiq Pay executes the operation, if it was approved.
- The result travels back to the mini app.
Step three is the whole security model. The dialog is drawn by Nimiq Pay, not by the mini app, which means the address, the amount and the recipient you are looking at are reported by the component holding the key rather than by the page that wants the signature. A mini app can lie about anything in its own interface and still cannot change one character of what that dialog says. This is the same separation Keyguard enforces in the browser, described in Nimiq Pay explained, rebuilt for a phone.
The ten methods, which is the whole list
"Sandboxed" is a word that reassures without informing, so here is the concrete version. In
@nimiq/mini-app-sdk version 0.1.0, which this site carries as a dependency and
which we read on 14 September 2026, the Nimiq provider carries a fixed set called
WALLET_METHODS. It holds exactly ten names.
| Method | What it asks the wallet to do |
|---|---|
listAccounts | Return the addresses in the wallet |
sign | Sign a message, text or hex |
sendBasicTransaction | Send NIM to a recipient, with an optional fee and validity start height |
sendBasicTransactionWithData | The same, carrying a data field |
sendNewStakerTransaction | Create a staker, delegating to a validator address |
sendStakeTransaction | Add stake to an existing staker |
sendSetActiveStakeTransaction | Set the active stake balance |
sendUpdateStakerTransaction | Change delegation to a different validator |
sendRetireStakeTransaction | Retire an amount of stake |
sendRemoveStakeTransaction | Remove retired stake from the staking contract |
Amounts in those calls are in Luna, the smallest unit, at 100,000 Luna to one NIM, which is the same convention the rest of the protocol uses. Six of the ten are the staking lifecycle, which is a fair summary of what Nimiq expects mini apps to be for.
The generic escape hatch is the interesting part. The SDK also exposes a request()
call that takes any method name, and its behaviour is the enforcement: if the name is one of the
ten, it goes to the wallet. If it is not, it goes to a Nimiq RPC node whose URL the mini app
configured itself, and if no URL was configured it throws with an error saying so. A mini app
cannot invent a wallet instruction and have Nimiq Pay honour it. It can ask for one of ten
things, and the wallet still puts a dialog in front of the sensitive ones.
Alongside those, the SDK offers a handful of calls that touch no key at all:
isConsensusEstablished and getBlockNumber for chain state,
getHostLanguage so a mini app can match the language you picked in Nimiq Pay, and
requestDeviceIdentifier, which we come back to below.
What mini apps cannot do
Stated as absences, because absences are what you can actually rely on. Read against the published provider interface on 14 September 2026:
- There is no method that returns a private key, a seed or recovery words. Not a restricted one. There is no such call in the interface at all, which is a stronger guarantee than a permission that could be granted.
- There is no method that sends without going through the host. Every transfer is a request to Nimiq Pay, and the documented rule is that sensitive actions get a native dialog the mini app cannot bypass.
- There is no way to extend the list. Ten names, fixed in the shipped package. Anything else is routed away from the wallet entirely.
- There is no stable identity for you. The device identifier is scoped to the requesting origin, and the SDK says outright that it identifies the device, not the user, and should not be used for authentication.
- There is no silent first contact. If the URL is not in the Nimiq Pay mini app list, or has never been opened before, Nimiq Pay shows a warning first.
What a mini app absolutely can do is everything a website can do: show you a false balance, misdescribe what a button does, and hope you approve the dialog without reading it. The dialog is honest. Nothing forces you to read it.
The device identifier, and what it is not
Some mini apps need to remember a device rather than a person: a leaderboard, a save slot, a
rate limit. The SDK provides requestDeviceIdentifier for that, and the design is
worth understanding because it is the only thing here that looks like tracking.
The first call from a given origin prompts you, showing the reason the mini app supplied. Later calls resolve silently. What comes back is a 64 character hex SHA-256, derived from a host side device ID hashed together with the mini app's own origin, which means two different mini apps receive two unrelated values and cannot line them up. It stays stable across Nimiq Pay reinstalls and across different accounts on the same device, because it is a property of the hardware rather than of you.
That last sentence cuts both ways, and the SDK says so: it identifies the device, not the user, and it should not be used as an identity for authentication. If a mini app treats it as a login, that is a mini app getting it wrong.
How to judge a mini app before you use it
The custody model removes the catastrophic failure. It does not remove the ordinary one, which is approving a transaction that does something other than what you thought. Five questions, in the order they are worth asking:
- Who published it, and can you find them? A name, a site, a repository, a track record. Anonymous is not automatically bad and is definitely less checkable.
- Is the source public? Open source does not mean audited, but it means the claim and the code can be compared by someone.
- Did Nimiq Pay warn you when it opened? That warning means the URL is not in the known list. It is not proof of anything. It is a reason to slow down.
- What exactly is it asking you to sign? Read the native dialog, every time. Recipient, amount, and for staking calls the validator address. If the dialog and the app's own description disagree, the dialog is the one telling the truth.
- Does the ask match the purpose? A game that wants a message signature is plausible. A leaderboard that wants a transfer is not. Mismatch between what something is and what it wants is the oldest signal there is.
And the rule that overrides all five: no mini app, and no anything, ever needs your recovery words. There is no legitimate reason for a mini app to display a field asking for them, because there is no method in the provider that would use them. The full treatment of backups is in Nimiq backups compared.
Examples, and an honest gap
We would like to point you at a directory. There is not one we can cite. The documentation confirms Nimiq Pay maintains an internal mini app list, since it warns on URLs outside it, but it describes no submission or approval process, and Nimiq's public apps page did not label any of its entries as a mini app when we read it on 14 September 2026. The App Store release notes for version 2.19.0 mention mini apps competition entries, which suggests the set is growing faster than anything documenting it.
So the examples we can name with confidence are our own, which we flag plainly as self interested. NimBooks and Darkfall are both built by us, both open source under MIT, and both run inside Nimiq Pay as well as in an ordinary browser. NimBooks does balances, history, CSV statements and signed proof of payment receipts. Darkfall is a dungeon crawler with a player run trading post where items change hands for NIM, wallet to wallet. They are useful here mainly as proof that the second bullet in the list above is answerable: you can read both of them.
Where this fits
Mini apps are the least understood part of Nimiq Pay and the part most likely to change, so treat the version numbers on this page as the thing to re-check rather than the thing to quote. The app they run inside is covered in Nimiq Pay explained, and everything else we have written is on the Learn hub.