docs

Build Nimiq mini apps without guessing.

One SDK workspace for provider access, Nimiq Better Auth, cross-device approvals, Ethereum helpers, local simulation, and repeatable tests.

Nimiq Pay mini apps cross several boundaries: an injected wallet provider in the host app, a web app that still needs normal auth sessions, desktop flows that must be approved on a phone, and tests that should run before a real wallet bridge exists. This SDK gives each boundary a small public package so the integration stays explicit.

Use the packages independently. Start with provider access, add auth when you need sessions, then test the same flow locally before you ship.

Start buildingView packages

Choose the layer you need

    Set up mini-app access
    Wait for window.nimiq, read the published provider, and fail clearly when the app is not running inside Nimiq Pay.
    Sign in with Nimiq
    Issue a server nonce, ask the mini app to sign it, verify the public key, and create a Better Auth session.
    Approve on another device
    Start a desktop order, claim it on the phone, approve with a Nimiq proof, and finalize the desktop session or action.
    Simulate locally
    Install deterministic Nimiq and Ethereum providers in development without opening the real host app.
    Test the flow
    Reuse local fetchers, stub providers, Vitest config, and smoke scenarios across apps.
    Packages covered
    @onmax/nimiq-mini-app-kit, @onmax/better-auth-nimiq, @onmax/better-auth-cross-device, @onmax/cross-device-nimiq, @onmax/unimiq, @onmax/unerc20, ledger, and E2E helpers.

What you get

The SDK keeps mini-app integration code small and explicit. It helps a new app answer four questions quickly: where does the wallet provider come from, who owns the session, which device approves the proof, and how do you test the flow without the production host.

  • Browser apps use @onmax/nimiq-mini-app-kit to wait for injected Nimiq and Ethereum providers.
  • Better Auth apps use @onmax/better-auth-nimiq for direct Nimiq sign-in.
  • Desktop-to-phone flows use @onmax/better-auth-cross-device with @onmax/cross-device-nimiq.
  • Generic Nimiq code uses @onmax/unimiq when it needs one facade across browser, Nuxt, Vite, Node.js, and Workers.
  • Token helper code uses @onmax/unerc20 when it already has an EIP-1193 provider.
  • App-local virtual balances use @onmax/better-auth-ledger when the value never leaves your application.

Start here

Install packages from PKG.new. Start with the runtime package, then add the auth or utility package that matches the job.

client/mini-app.ts
import { getMiniAppProvider, waitForMiniAppProvider } from '@onmax/nimiq-mini-app-kit'

const provider = getMiniAppProvider() ?? await waitForMiniAppProvider()
const accounts = await provider.listAccounts()
server/auth.ts
import { betterAuth } from 'better-auth'
import { nimiqAuth } from '@onmax/better-auth-nimiq'

export const auth = betterAuth({
  plugins: [
    nimiqAuth({ appName: 'My Mini App' }),
  ],
})
Open the quick start.
Copyright © 2026