Installation

Install one flow at a time from PKG.new. Every package in this workspace is ESM-only and published from packages/*.

Use this page when you know the flow you are building and need the smallest package set. The SDK separates provider access, auth sessions, cross-device approval, chain utilities, ledger helpers, and tests so you do not pull every integration into one app by default.

Requirements

Mini-app runtime first

Use this when the first problem is provider access, Ethereum discovery, host language, local simulation, or the Nuxt simulator sidecar.

Install @onmax/nimiq-mini-app-kit

import { getNimiqPayLanguage, initMiniAppProvider } from '@onmax/nimiq-mini-app-kit'

const provider = await initMiniAppProvider({ timeout: 10_000 })
const language = getNimiqPayLanguage()
const accounts = await provider.listAccounts()

console.log({ address: accounts[0], language })

Expected behavior: the app gets the selected Nimiq account and the host language when opened in Nimiq Pay.

Do not use this package as your generic Nimiq RPC client. Use @onmax/unimiq for server, Worker, and mock-driver code.

Direct Nimiq sign-in

Use this when the browser can sign through window.nimiq and should receive a Better Auth session immediately.

Install from PKG.new:

• Install better-auth
• Install @onmax/better-auth-nimiq
• Install @onmax/nimiq-mini-app-kit

import { signInWithNimiq } from '@onmax/better-auth-nimiq/client'

const result = await signInWithNimiq(authClient.$fetch.bind(authClient), {
  appName: 'Arcade Rewards',
  endpointPrefix: '/nimiq',
})

console.log(result.token)

Do not use this flow for QR handoff. The direct helper expects provider access in the same browser.

Cross-device approval

Use this when a desktop starts a login, sign, or transaction order and a phone approves it.

Install from PKG.new:

• Install better-auth
• Install @onmax/better-auth-cross-device
• Install @onmax/cross-device-nimiq
• Install @onmax/nimiq-mini-app-kit

import { startCrossDeviceOrder } from '@onmax/better-auth-cross-device/client'

const order = await startCrossDeviceOrder(authClient.$fetch.bind(authClient), {
  endpointPrefix: '/cross-device',
  kind: 'login',
  displayTitle: 'Sign in to Arcade Rewards',
  displaySummary: 'Approve this login from Nimiq Pay.',
})

console.log(order.claimUrl)

Expected behavior: show claimUrl as a QR code or deep link. Keep desktopToken private to the desktop browser; it finalizes the order later.

Generic Nimiq and ERC-20 utilities

Use @onmax/unimiq when your code needs Nimiq address, signature, rate, wallet, transaction, mock, Nuxt, Vue, or Vite helpers.

Use @onmax/unerc20 when you already have an EIP-1193 provider and need ERC-20 reads or transfers.

Install from PKG.new:

• Install @onmax/unimiq
• Install @onmax/unerc20

import { formatTokenAmountAtomic, readErc20Balance, readErc20Decimals } from '@onmax/unerc20'

const token = '0xc2132D05D31c914a87C6611C10748AEb04B58e8F'
const account = '0x1234567890abcdef1234567890abcdef12345678'

const [balance, decimals] = await Promise.all([
  readErc20Balance(window.ethereum, { token, account }),
  readErc20Decimals(window.ethereum, token),
])

console.log(formatTokenAmountAtomic(balance, decimals))

Ledger balances

Use this for app-owned credits, points, or internal balances attached to Better Auth users.

Install from PKG.new:

• Install better-auth
• Install @onmax/better-auth-ledger

Do not use it as a payment settlement layer. Real-money purchase and withdrawal logic belongs in your app.

Test helpers

Use this for deterministic Vitest scenarios before you depend on a real wallet bridge.

Install @onmax/better-auth-nimiq-pay-e2e

import { defineConfig } from 'vitest/config'
import { createVitestE2EConfig } from '@onmax/better-auth-nimiq-pay-e2e/vitest'

export default defineConfig(createVitestE2EConfig({
  enabled: process.env.E2E_ENABLED === '1',
}))

Verify the workspace

pnpm install
pnpm docs:dev
pnpm test

Expected behavior: the docs app starts locally, and pnpm test runs the package workspace scenarios through vitest.workspace.ts.