diff --git a/mini-apps/api-reference/ethereum-provider.md b/mini-apps/api-reference/ethereum-provider.md
index 8b9a9bd9..8fd78839 100644
--- a/mini-apps/api-reference/ethereum-provider.md
+++ b/mini-apps/api-reference/ethereum-provider.md
@@ -2,7 +2,7 @@
 <!-- type: api reference -->
 <!-- summary: Reference for the EIP-1193 Ethereum provider injected into mini apps, including EIP-6963 compatibility -->
 
-# Ethereum Provider API (window.ethereum)
+# Ethereum Provider API
 
 This provider implements [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) and supports [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) provider discovery. It is injected into the mini app environment.
 
diff --git a/mini-apps/api-reference/index.md b/mini-apps/api-reference/index.md
index 6cfbb435..530d3e7d 100644
--- a/mini-apps/api-reference/index.md
+++ b/mini-apps/api-reference/index.md
@@ -4,7 +4,7 @@
 
 # API Reference
 
-This API is injected by the host app into the mini app environment. The providers are available on the `window` object. This section is reference-only.
+This API is injected by the host app into the mini app environment. For Nimiq access, the recommended pattern is to use the Mini App SDK `init()` helper. This section is reference-only.
 
 ## Contents
 
@@ -17,14 +17,15 @@ To load and build a mini app, see [Load a Local Mini App in Nimiq Pay](https://n
 
 ### Nimiq Provider
 
-```javascript
-const nimiq = window.nimiq
+```typescript
+import { init } from '@nimiq/mini-app-sdk'
 
-const accounts = await nimiq.listAccounts()
-const address = accounts[0]
+const nimiq = await init()
 
+const accounts = await nimiq.listAccounts()
 const signed = await nimiq.sign('hello')
-console.log({ address, signed })
+
+console.log({ accounts, signed })
 ```
 
 ### Ethereum dApp (EIP-1193)
diff --git a/mini-apps/api-reference/nimiq-provider.md b/mini-apps/api-reference/nimiq-provider.md
index 00aa9b2d..8f573e7d 100644
--- a/mini-apps/api-reference/nimiq-provider.md
+++ b/mini-apps/api-reference/nimiq-provider.md
@@ -2,14 +2,18 @@
 <!-- type: api reference -->
 <!-- summary: Reference for the Nimiq provider injected into mini apps -->
 
-# Nimiq Provider API (window.nimiq)
+# Nimiq Provider API
 
 This provider exposes Nimiq blockchain operations and is injected into the mini app environment.
 
 ## Access
 
-```javascript
-const nimiq = window.nimiq
+Use the Mini App SDK `init()` helper to wait until Nimiq Pay injects the provider.
+
+```ts
+import { init } from '@nimiq/mini-app-sdk'
+
+const nimiq = await init()
 ```
 
 ## Methods
@@ -36,7 +40,7 @@ Returns the user's Nimiq account addresses.
 
 **Example**
 
-```javascript
+```ts
 const accounts = await nimiq.listAccounts()
 ```
 
@@ -62,7 +66,7 @@ Signs a message with the user's Nimiq key.
 
 **Example**
 
-```javascript
+```ts
 const signed = await nimiq.sign('hello')
 ```
 
@@ -84,7 +88,7 @@ Checks whether the Nimiq network consensus is established.
 
 **Example**
 
-```javascript
+```ts
 const ready = await nimiq.isConsensusEstablished()
 ```
 
@@ -106,7 +110,7 @@ Returns the current Nimiq block height.
 
 **Example**
 
-```javascript
+```ts
 const height = await nimiq.getBlockNumber()
 ```
 
@@ -119,6 +123,7 @@ Sends a basic NIM payment.
 - `recipient` (string, required): Nimiq user-friendly address.
 - `value` (number, required): amount in Luna (1 NIM = 100,000 Luna).
 - `fee` (number, optional): transaction fee in Luna.
+- `validityStartHeight` (number, optional): block height from which the transaction becomes valid.
 
 **Returns**
 
@@ -135,10 +140,14 @@ Sends a basic NIM payment.
 
 **Example**
 
-```javascript
+```ts
 const txHash = await nimiq.sendBasicTransaction({
   recipient: 'NQ07 0000 0000 0000 0000 0000 0000 0000 0000',
   value: 100000,
+  // Optional. Nimiq Pay chooses a fee automatically, using 0 if possible.
+  fee: 1000,
+  // Optional.
+  validityStartHeight: 123456,
 })
 ```
 
@@ -151,7 +160,8 @@ Sends a NIM payment with an attached text message.
 - `recipient` (string, required): Nimiq user-friendly address.
 - `value` (number, required): amount in Luna (1 NIM = 100,000 Luna).
 - `fee` (number, optional): transaction fee in Luna.
-- `data` (string, optional): text message to attach.
+- `data` (string, required): text message to attach.
+- `validityStartHeight` (number, optional): block height from which the transaction becomes valid.
 
 **Returns**
 
@@ -168,11 +178,15 @@ Sends a NIM payment with an attached text message.
 
 **Example**
 
-```javascript
+```ts
 const txHash = await nimiq.sendBasicTransactionWithData({
   recipient: 'NQ07 0000 0000 0000 0000 0000 0000 0000 0000',
   value: 100000,
   data: 'mic check',
+  // Optional. Nimiq Pay chooses a fee automatically, using 0 if possible.
+  fee: 1000,
+  // Optional.
+  validityStartHeight: 123456,
 })
 ```
 
@@ -184,7 +198,8 @@ Creates a new staking transaction.
 
 - `delegation` (string, required): validator address or delegation target.
 - `value` (number, required): amount in Luna.
-- `fee` (number, required): transaction fee in Luna.
+- `fee` (number, optional): transaction fee in Luna.
+- `validityStartHeight` (number, optional): block height from which the transaction becomes valid.
 
 **Returns**
 
@@ -201,22 +216,26 @@ Creates a new staking transaction.
 
 **Example**
 
-```javascript
+```ts
 const txHash = await nimiq.sendNewStakerTransaction({
   delegation: 'NQ07 0000 0000 0000 0000 0000 0000 0000 0000',
   value: 100000,
+  // Optional. Nimiq Pay chooses a fee automatically, using 0 if possible.
   fee: 1000,
+  // Optional.
+  validityStartHeight: 123456,
 })
 ```
 
-### `sendAddStakeTransaction`
+### `sendStakeTransaction`
 
 Adds stake to an existing staker.
 
 **Parameters**
 
 - `value` (number, required): amount in Luna.
-- `fee` (number, required): transaction fee in Luna.
+- `fee` (number, optional): transaction fee in Luna.
+- `validityStartHeight` (number, optional): block height from which the transaction becomes valid.
 
 **Returns**
 
@@ -233,10 +252,13 @@ Adds stake to an existing staker.
 
 **Example**
 
-```javascript
-const txHash = await nimiq.sendAddStakeTransaction({
+```ts
+const txHash = await nimiq.sendStakeTransaction({
   value: 100000,
+  // Optional. Nimiq Pay chooses a fee automatically, using 0 if possible.
   fee: 1000,
+  // Optional.
+  validityStartHeight: 123456,
 })
 ```
 
@@ -247,7 +269,8 @@ Sets the active stake amount.
 **Parameters**
 
 - `newActiveBalance` (number, required): active stake amount in Luna.
-- `fee` (number, required): transaction fee in Luna.
+- `fee` (number, optional): transaction fee in Luna.
+- `validityStartHeight` (number, optional): block height from which the transaction becomes valid.
 
 **Returns**
 
@@ -264,10 +287,13 @@ Sets the active stake amount.
 
 **Example**
 
-```javascript
+```ts
 const txHash = await nimiq.sendSetActiveStakeTransaction({
   newActiveBalance: 100000,
+  // Optional. Nimiq Pay chooses a fee automatically, using 0 if possible.
   fee: 1000,
+  // Optional.
+  validityStartHeight: 123456,
 })
 ```
 
@@ -278,8 +304,9 @@ Updates staker settings.
 **Parameters**
 
 - `newDelegation` (string, required): new validator address or delegation target.
-- `reactivateAllStake` (boolean, required): whether to reactivate all stake.
-- `fee` (number, required): transaction fee in Luna.
+- `reactivateAllStake` (boolean, optional): whether to reactivate all stake.
+- `fee` (number, optional): transaction fee in Luna.
+- `validityStartHeight` (number, optional): block height from which the transaction becomes valid.
 
 **Returns**
 
@@ -296,11 +323,14 @@ Updates staker settings.
 
 **Example**
 
-```javascript
+```ts
 const txHash = await nimiq.sendUpdateStakerTransaction({
   newDelegation: 'NQ07 0000 0000 0000 0000 0000 0000 0000 0000',
   reactivateAllStake: true,
+  // Optional. Nimiq Pay chooses a fee automatically, using 0 if possible.
   fee: 1000,
+  // Optional.
+  validityStartHeight: 123456,
 })
 ```
 
@@ -311,7 +341,8 @@ Retires stake from a staker.
 **Parameters**
 
 - `retireStake` (number, required): amount in Luna to retire.
-- `fee` (number, required): transaction fee in Luna.
+- `fee` (number, optional): transaction fee in Luna.
+- `validityStartHeight` (number, optional): block height from which the transaction becomes valid.
 
 **Returns**
 
@@ -328,10 +359,13 @@ Retires stake from a staker.
 
 **Example**
 
-```javascript
+```ts
 const txHash = await nimiq.sendRetireStakeTransaction({
   retireStake: 100000,
+  // Optional. Nimiq Pay chooses a fee automatically, using 0 if possible.
   fee: 1000,
+  // Optional.
+  validityStartHeight: 123456,
 })
 ```
 
@@ -342,7 +376,8 @@ Removes stake from a staker.
 **Parameters**
 
 - `value` (number, required): amount in Luna.
-- `fee` (number, required): transaction fee in Luna.
+- `fee` (number, optional): transaction fee in Luna.
+- `validityStartHeight` (number, optional): block height from which the transaction becomes valid.
 
 **Returns**
 
@@ -359,9 +394,12 @@ Removes stake from a staker.
 
 **Example**
 
-```javascript
+```ts
 const txHash = await nimiq.sendRemoveStakeTransaction({
   value: 100000,
+  // Optional. Nimiq Pay chooses a fee automatically, using 0 if possible.
   fee: 1000,
+  // Optional.
+  validityStartHeight: 123456,
 })
 ```
diff --git a/mini-apps/dual-chain-mini-app-tutorial.md b/mini-apps/dual-chain-mini-app-tutorial.md
index cbc2a770..64538593 100644
--- a/mini-apps/dual-chain-mini-app-tutorial.md
+++ b/mini-apps/dual-chain-mini-app-tutorial.md
@@ -12,8 +12,8 @@
 
 In this tutorial, you will build a mini app that uses both injected providers:
 
-- `window.nimiq` for Nimiq account and signing flows
-- `window.ethereum` for EIP-1193 account and signing flows
+- the Nimiq provider for Nimiq account and signing flows
+- the Ethereum provider for EIP-1193 account and signing flows
 
 You will implement methods that require user confirmations so you can test real wallet interactions end to end.
 
@@ -60,20 +60,24 @@ export default defineConfig({
 })
 ```
 
-## 5. Add the dual-chain mini app
+## 5. Install the Nimiq Mini App SDK
+
+Install the published Nimiq Mini App SDK before editing `src/App.vue`.
+
+```bash
+npm install @nimiq/mini-app-sdk
+```
+
+## 6. Add the dual-chain mini app
 
 In `src/App.vue`, use separate script, template, and style blocks.
 
-### 5.1 Add the script block
+### 6.1 Add the script block
 
 ```vue
 <script setup lang="ts">
-import { ref } from 'vue'
-
-interface NimiqProvider {
-  listAccounts: () => Promise<string[]>
-  sign: (message: string | { message: string, isHex: boolean }) => Promise<unknown>
-}
+import { init } from '@nimiq/mini-app-sdk'
+import { onMounted, ref } from 'vue'
 
 interface EthereumProvider {
   request: (args: { method: string, params?: unknown[] | Record<string, unknown> }) => Promise<any>
@@ -81,12 +85,14 @@ interface EthereumProvider {
 
 declare global {
   interface Window {
-    nimiq?: NimiqProvider
     ethereum?: EthereumProvider
   }
 }
 
+let nimiqPromise: ReturnType<typeof init> | null = null
+
 const loading = ref(false)
+const isNimiqConnecting = ref(true)
 const status = ref<string | null>(null)
 const errorMessage = ref<string | null>(null)
 
@@ -95,6 +101,17 @@ const nimiqSignature = ref<string | null>(null)
 const ethAccounts = ref<string[] | null>(null)
 const ethSignature = ref<string | null>(null)
 
+function getProviderErrorMessage(value: unknown): string | null {
+  if (typeof value !== 'object' || value === null || !('error' in value))
+    return null
+
+  const maybeError = (value as { error?: { message?: unknown } }).error
+  if (maybeError && typeof maybeError.message === 'string')
+    return maybeError.message
+
+  return 'Provider request failed.'
+}
+
 // Convert a UTF-8 string to hex for personal_sign.
 function toHexUtf8(input: string) {
   return `0x${Array.from(new TextEncoder().encode(input))
@@ -102,31 +119,59 @@ function toHexUtf8(input: string) {
     .join('')}`
 }
 
-function resetMessages() {
+function resetFeedback() {
   errorMessage.value = null
   status.value = null
 }
 
+onMounted(async () => {
+  try {
+    nimiqPromise = init({ timeout: 10_000 })
+    await nimiqPromise
+  }
+  catch (error) {
+    errorMessage.value = error instanceof Error ? error.message : String(error)
+  }
+  finally {
+    isNimiqConnecting.value = false
+  }
+})
+
 async function runNimiqFlow() {
-  if (!window.nimiq) {
-    errorMessage.value = 'Nimiq provider not found. Open this app inside Nimiq Pay.'
+  resetFeedback()
+  nimiqAccounts.value = null
+  nimiqSignature.value = null
+
+  if (!nimiqPromise) {
+    errorMessage.value = 'Nimiq provider not ready. Open this app inside Nimiq Pay.'
+    status.value = 'Nimiq flow failed.'
     return
   }
 
-  resetMessages()
   loading.value = true
 
   try {
+    const nimiq = await nimiqPromise
+
     // Prompt 1: account sharing confirmation.
     status.value = 'Requesting Nimiq accounts...'
-    const accounts = await window.nimiq.listAccounts()
+    const accountsResult = await nimiq.listAccounts()
+    const accountsError = getProviderErrorMessage(accountsResult)
+    if (accountsError)
+      throw new Error(accountsError)
+
+    const accounts = accountsResult as string[]
     nimiqAccounts.value = accounts
     if (!accounts.length)
       throw new Error('No Nimiq accounts returned.')
 
     // Prompt 2: signing confirmation.
     status.value = 'Requesting Nimiq signing confirmation...'
-    const signatureResult = await window.nimiq.sign('Nimiq Pay dual-chain tutorial')
+    const signatureResult = await nimiq.sign('Nimiq Pay dual-chain tutorial')
+    const signatureError = getProviderErrorMessage(signatureResult)
+    if (signatureError)
+      throw new Error(signatureError)
+
     nimiqSignature.value = JSON.stringify(signatureResult, null, 2)
     status.value = 'Nimiq flow completed.'
   }
@@ -140,12 +185,16 @@ async function runNimiqFlow() {
 }
 
 async function runEthereumFlow() {
+  resetFeedback()
+  ethAccounts.value = null
+  ethSignature.value = null
+
   if (!window.ethereum) {
     errorMessage.value = 'Ethereum provider not found. Open this app inside Nimiq Pay.'
+    status.value = 'Ethereum flow failed.'
     return
   }
 
-  resetMessages()
   loading.value = true
 
   try {
@@ -179,7 +228,7 @@ async function runEthereumFlow() {
 </script>
 ```
 
-### 5.2 Add the template block
+### 6.2 Add the template block
 
 ```vue
 <template>
@@ -187,7 +236,7 @@ async function runEthereumFlow() {
     <h1>Dual-Chain Mini App</h1>
 
     <div class="actions">
-      <button :disabled="loading" @click="runNimiqFlow">
+      <button :disabled="loading || isNimiqConnecting" @click="runNimiqFlow">
         Run Nimiq flow
       </button>
       <button :disabled="loading" @click="runEthereumFlow">
@@ -195,6 +244,10 @@ async function runEthereumFlow() {
       </button>
     </div>
 
+    <p v-if="isNimiqConnecting">
+      Waiting for the Nimiq provider to initialize...
+    </p>
+
     <p v-if="status">
       <strong>Status:</strong> {{ status }}
     </p>
@@ -213,7 +266,7 @@ async function runEthereumFlow() {
 </template>
 ```
 
-### 5.3 Add the style block (mobile-friendly)
+### 6.3 Add the style block (mobile-friendly)
 
 ```vue
 <style scoped>
@@ -278,7 +331,7 @@ button:disabled {
 </style>
 ```
 
-## 6. Run the mini app
+## 7. Run the mini app
 
 ```bash
 npm run dev -- --host
@@ -290,7 +343,7 @@ Copy the **Network** URL from the terminal output, for example:
 http://192.168.1.42:5173
 ```
 
-## 7. Test inside Nimiq Pay
+## 8. Test inside Nimiq Pay
 
 1. Make sure your phone and dev machine are on the same Wi‑Fi network.
 2. Open **Nimiq Pay**.
@@ -304,7 +357,7 @@ You should see:
 - Nimiq accounts and a Nimiq signature response.
 - Ethereum account(s) and an Ethereum signature response.
 
-## 8. Troubleshooting
+## 9. Troubleshooting
 
 **No Ethereum account returned**\
   The Ethereum success path requires at least one account available through Nimiq Pay.
diff --git a/mini-apps/mini-app-tutorial.md b/mini-apps/mini-app-tutorial.md
index 0cc3c019..d53ed29e 100644
--- a/mini-apps/mini-app-tutorial.md
+++ b/mini-apps/mini-app-tutorial.md
@@ -10,7 +10,7 @@
 > - On iOS, share the email associated with your Apple account. Install TestFlight, and the Nimiq Pay test build will appear there once your account is allowlisted.
 > - On Android, share the email associated with your Google account. You will receive an email when access is enabled.
 
-In this tutorial, you’ll build a minimal mini app that runs inside Nimiq Pay and calls three Nimiq provider methods:
+In this tutorial, you'll build a minimal mini app that runs inside Nimiq Pay and calls three Nimiq provider methods:
 
 | Method | Description |
 | --- | --- |
@@ -44,7 +44,15 @@ npm install
 
 :::
 
-## 2. Configure the dev server
+## 2. Install the Nimiq Mini App SDK
+
+Install the Nimiq Mini App SDK. For package details, see [`@nimiq/mini-app-sdk`](https://www.npmjs.com/package/@nimiq/mini-app-sdk).
+
+```bash
+npm install @nimiq/mini-app-sdk
+```
+
+## 3. Configure the dev server
 
 Enable network access so Nimiq Pay on your device can reach the app:
 
@@ -91,7 +99,7 @@ export default defineConfig({
 
 :::
 
-## 3. Add mini app logic and UI
+## 4. Add mini app logic and UI
 
 Replace the main app component with the variant for your framework:
 
@@ -99,57 +107,61 @@ Replace the main app component with the variant for your framework:
 
 ```vue [Vue + Vite (src/App.vue)]
 <script setup lang="ts">
-import { onMounted, onUnmounted, ref } from 'vue'
-
-interface NimiqProvider {
-  listAccounts: () => Promise<string[]>
-  isConsensusEstablished: () => Promise<boolean>
-  getBlockNumber: () => Promise<number>
-}
-
-declare global {
-  interface Window {
-    nimiq?: NimiqProvider
-  }
-}
+import { init } from '@nimiq/mini-app-sdk'
+import { onMounted, ref } from 'vue'
 
-const isAvailable = ref(false)
+let nimiqPromise: ReturnType<typeof init> | null = null
+const isConnecting = ref(true)
+const isReady = ref(false)
 const accounts = ref<string[] | null>(null)
 const consensus = ref<boolean | null>(null)
 const blockNumber = ref<number | null>(null)
 const errorMessage = ref<string | null>(null)
 
-let checkInterval: number | undefined
+function getProviderErrorMessage(value: unknown): string | null {
+  if (typeof value !== 'object' || value === null || !('error' in value))
+    return null
 
-onMounted(() => {
-  isAvailable.value = !!window.nimiq
-  checkInterval = window.setInterval(() => {
-    if (window.nimiq) {
-      isAvailable.value = true
-      clearInterval(checkInterval)
-    }
-  }, 500)
-})
+  const maybeError = (value as { error?: { message?: unknown } }).error
+  if (maybeError && typeof maybeError.message === 'string')
+    return maybeError.message
 
-onUnmounted(() => {
-  if (checkInterval)
-    clearInterval(checkInterval)
+  return 'Provider request failed.'
+}
+
+onMounted(async () => {
+  try {
+    nimiqPromise = init({ timeout: 10_000 })
+    await nimiqPromise
+    isReady.value = true
+  }
+  catch (error) {
+    errorMessage.value = error instanceof Error ? error.message : String(error)
+  }
+  finally {
+    isConnecting.value = false
+  }
 })
 
 async function runThreeRequests() {
-  if (!window.nimiq)
+  if (!nimiqPromise)
     return
 
   errorMessage.value = null
 
   try {
+    const nimiq = await nimiqPromise
     const [accountsResult, consensusResult, blockResult] = await Promise.all([
-      window.nimiq.listAccounts(),
-      window.nimiq.isConsensusEstablished(),
-      window.nimiq.getBlockNumber(),
+      nimiq.listAccounts(),
+      nimiq.isConsensusEstablished(),
+      nimiq.getBlockNumber(),
     ])
 
-    accounts.value = accountsResult
+    const accountsError = getProviderErrorMessage(accountsResult)
+    if (accountsError)
+      throw new Error(accountsError)
+
+    accounts.value = accountsResult as string[]
     consensus.value = consensusResult
     blockNumber.value = blockResult
   }
@@ -163,11 +175,15 @@ async function runThreeRequests() {
   <div style="padding: 24px; font-family: system-ui;">
     <h1>Nimiq Mini App</h1>
 
-    <p v-if="!isAvailable">
-      Open this inside Nimiq Pay to access <code>window.nimiq</code>.
+    <p v-if="isConnecting">
+      Waiting for Nimiq Pay to initialize the provider...
     </p>
 
-    <button :disabled="!isAvailable" @click="runThreeRequests">
+    <p v-else-if="!isReady">
+      Open this mini app inside Nimiq Pay to connect to the Nimiq provider.
+    </p>
+
+    <button :disabled="isConnecting || !isReady" @click="runThreeRequests">
       Run 3 requests
     </button>
 
@@ -183,39 +199,74 @@ async function runThreeRequests() {
 ```
 
 ```jsx [React + JSX (src/App.jsx)]
-import { useEffect, useState } from 'react'
+import { init } from '@nimiq/mini-app-sdk'
+import { useEffect, useRef, useState } from 'react'
+
+function getProviderErrorMessage(value) {
+  if (typeof value !== 'object' || value === null || !('error' in value))
+    return null
+
+  const maybeError = value.error
+  if (maybeError && typeof maybeError.message === 'string')
+    return maybeError.message
+
+  return 'Provider request failed.'
+}
 
 function App() {
-  const [isAvailable, setIsAvailable] = useState(Boolean(window.nimiq))
+  const nimiqPromiseRef = useRef(null)
+  const [isConnecting, setIsConnecting] = useState(true)
+  const [isReady, setIsReady] = useState(false)
   const [accounts, setAccounts] = useState(null)
   const [consensus, setConsensus] = useState(null)
   const [blockNumber, setBlockNumber] = useState(null)
   const [errorMessage, setErrorMessage] = useState(null)
 
   useEffect(() => {
-    const checkInterval = window.setInterval(() => {
-      if (window.nimiq) {
-        setIsAvailable(true)
-        window.clearInterval(checkInterval)
+    let ignore = false
+
+    async function connect() {
+      try {
+        nimiqPromiseRef.current = init({ timeout: 10000 })
+        await nimiqPromiseRef.current
+        if (!ignore)
+          setIsReady(true)
       }
-    }, 500)
+      catch (error) {
+        if (!ignore)
+          setErrorMessage(error instanceof Error ? error.message : String(error))
+      }
+      finally {
+        if (!ignore)
+          setIsConnecting(false)
+      }
+    }
 
-    return () => window.clearInterval(checkInterval)
+    connect()
+
+    return () => {
+      ignore = true
+    }
   }, [])
 
   async function runThreeRequests() {
-    if (!window.nimiq)
+    if (!nimiqPromiseRef.current)
       return
 
     setErrorMessage(null)
 
     try {
+      const nimiq = await nimiqPromiseRef.current
       const [accountsResult, consensusResult, blockResult] = await Promise.all([
-        window.nimiq.listAccounts(),
-        window.nimiq.isConsensusEstablished(),
-        window.nimiq.getBlockNumber(),
+        nimiq.listAccounts(),
+        nimiq.isConsensusEstablished(),
+        nimiq.getBlockNumber(),
       ])
 
+      const accountsError = getProviderErrorMessage(accountsResult)
+      if (accountsError)
+        throw new Error(accountsError)
+
       setAccounts(accountsResult)
       setConsensus(consensusResult)
       setBlockNumber(blockResult)
@@ -229,16 +280,15 @@ function App() {
     <div style={{ padding: 24, fontFamily: 'system-ui' }}>
       <h1>Nimiq Mini App</h1>
 
-      {!isAvailable && (
-        <p>
-          Open this inside Nimiq Pay to access
-          {' '}
-          <code>window.nimiq</code>
-          .
-        </p>
+      {isConnecting && (
+        <p>Waiting for Nimiq Pay to initialize the provider...</p>
       )}
 
-      <button disabled={!isAvailable} onClick={runThreeRequests}>
+      {!isConnecting && !isReady && (
+        <p>Open this mini app inside Nimiq Pay to connect to the Nimiq provider.</p>
+      )}
+
+      <button disabled={isConnecting || !isReady} onClick={runThreeRequests}>
         Run 3 requests
       </button>
 
@@ -272,39 +322,72 @@ export default App
 ```svelte [Svelte (src/App.svelte)]
 <script>
   import { onMount } from 'svelte'
+  import { init } from '@nimiq/mini-app-sdk'
 
-  let isAvailable = false
+  let nimiqPromise = null
+  let isConnecting = true
+  let isReady = false
   let accounts = null
   let consensus = null
   let blockNumber = null
   let errorMessage = null
 
-  onMount(() => {
-    isAvailable = !!window.nimiq
+  function getProviderErrorMessage(value) {
+    if (typeof value !== 'object' || value === null || !('error' in value))
+      return null
 
-    const checkInterval = window.setInterval(() => {
-      if (window.nimiq) {
-        isAvailable = true
-        window.clearInterval(checkInterval)
+    const maybeError = value.error
+    if (maybeError && typeof maybeError.message === 'string')
+      return maybeError.message
+
+    return 'Provider request failed.'
+  }
+
+  onMount(() => {
+    let active = true
+
+    async function connect() {
+      try {
+        nimiqPromise = init({ timeout: 10000 })
+        await nimiqPromise
+        if (active)
+          isReady = true
+      }
+      catch (error) {
+        if (active)
+          errorMessage = error instanceof Error ? error.message : String(error)
+      }
+      finally {
+        if (active)
+          isConnecting = false
       }
-    }, 500)
+    }
+
+    connect()
 
-    return () => window.clearInterval(checkInterval)
+    return () => {
+      active = false
+    }
   })
 
   async function runThreeRequests() {
-    if (!window.nimiq)
+    if (!nimiqPromise)
       return
 
     errorMessage = null
 
     try {
+      const nimiq = await nimiqPromise
       const [accountsResult, consensusResult, blockResult] = await Promise.all([
-        window.nimiq.listAccounts(),
-        window.nimiq.isConsensusEstablished(),
-        window.nimiq.getBlockNumber(),
+        nimiq.listAccounts(),
+        nimiq.isConsensusEstablished(),
+        nimiq.getBlockNumber(),
       ])
 
+      const accountsError = getProviderErrorMessage(accountsResult)
+      if (accountsError)
+        throw new Error(accountsError)
+
       accounts = accountsResult
       consensus = consensusResult
       blockNumber = blockResult
@@ -318,13 +401,15 @@ export default App
 <div style="padding: 24px; font-family: system-ui;">
   <h1>Nimiq Mini App</h1>
 
-  {#if !isAvailable}
+  {#if isConnecting}
+    <p>Waiting for Nimiq Pay to initialize the provider...</p>
+  {:else if !isReady}
     <p>
-      Open this inside Nimiq Pay to access <code>window.nimiq</code>.
+      Open this mini app inside Nimiq Pay to connect to the Nimiq provider.
     </p>
   {/if}
 
-  <button disabled={!isAvailable} on:click={runThreeRequests}>
+  <button disabled={isConnecting || !isReady} on:click={runThreeRequests}>
     Run 3 requests
   </button>
 
@@ -348,7 +433,7 @@ export default App
 
 :::
 
-## 4. Run the mini app
+## 5. Run the mini app
 
 Start the Vite dev server:
 
@@ -362,14 +447,14 @@ Note the **Network** URL in the terminal, for example:
 http://192.168.1.42:5173
 ```
 
-## 5. Test inside Nimiq Pay
+## 6. Test inside Nimiq Pay
 
-1. Make sure your phone and dev machine are on the same Wi‑Fi network.
+1. Make sure your phone and dev machine are on the same Wi-Fi network.
 2. Open **Nimiq Pay**.
 3. Go to **Mini Apps**.
 4. Enter your network URL: `http://<your-ip>:5173`
 
-Open your mini app and tap **Run 3 requests**.
+Open your mini app and wait for the provider to initialize. Once the button becomes enabled, tap **Run 3 requests**.
 
 You should see:
 
@@ -379,12 +464,9 @@ You should see:
 
 If you see an error message, confirm:
 
-- You are opening the app inside Nimiq Pay (not a regular browser).
-- `window.nimiq` exists in the console.
+- You are opening the app inside Nimiq Pay and not a regular browser.
 - Your dev server is reachable from the device.
 
-From here, you can start adding your own UI, additional Nimiq calls, or mix in `window.ethereum` to build dual-chain mini apps.
-
 For the full list of available methods and events, see the [Nimiq Provider API](/mini-apps/api-reference/nimiq-provider) and [Ethereum Provider API](/mini-apps/api-reference/ethereum-provider).
 
 You can also check [this demo](https://github.com/Eligioo/nimiq-mini-app-demo) repository to see all supported methods.
diff --git a/mini-apps/overview.md b/mini-apps/overview.md
index c3914370..13b9a08e 100644
--- a/mini-apps/overview.md
+++ b/mini-apps/overview.md
@@ -16,14 +16,12 @@ Think of it like a specialized web browser embedded within Nimiq Pay. Your mini
 
 Mini apps run in a WebView and talk to Nimiq Pay through injected providers.
 
-To use an injected provider, read it from `window`, confirm it is available, and then call its methods as in this example:
+For Nimiq provider access, the recommended pattern is to use the Mini App SDK `init()` helper to wait until the provider is ready:
 
 ```javascript
-const nimiq = window.nimiq
+import { init } from '@nimiq/mini-app-sdk'
 
-if (!nimiq) {
-  throw new Error('Nimiq provider not available')
-}
+const nimiq = await init()
 
 const [accounts, consensus, blockNumber] = await Promise.all([
   nimiq.listAccounts(),
@@ -36,11 +34,11 @@ const [accounts, consensus, blockNumber] = await Promise.all([
 
 | Component | Lives in | What it does |
 |---|---|---|
-| Injected Provider (`window.ethereum`, `window.nimiq`) | WebView (injected by Nimiq Pay) | Exposes wallet APIs and sends requests to the host |
+| Injected Provider (`window.ethereum`, Nimiq provider) | WebView (injected by Nimiq Pay) | Exposes wallet APIs and sends requests to the host |
 | Host-side API | Nimiq Pay (native) | Receives requests, validates them, shows approval dialogs, executes actions |
-| Mini App SDK (optional) | WebView (your app or injected) | Typed Nimiq-native APIs + `Result<T, E>` patterns; uses its own message format |
+| Mini App SDK | WebView (your app or injected) | Waits for the Nimiq provider, adds typed access for TypeScript, and exposes Nimiq-native APIs |
 
-Your mini app uses standard Web3 APIs via `window.ethereum` and Nimiq-specific APIs via `window.nimiq`.
+Your mini app uses standard Web3 APIs via `window.ethereum` and Nimiq-specific APIs via the Mini App SDK `init()` helper.
 
 ### Request lifecycle