Skip to content

minikit 2.0 improvements #89

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andy-t-wang merged 2 commits into from
Apr 1, 2026
Merged

minikit 2.0 improvements #89

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0db4b05
wip minikit
andy-t-wang Apr 1, 2026
8d73d97
fix spell
andy-t-wang Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@
"words": [
"agentbook",
"agentic",
"anymatch",
"agentkit",
"anymatch",
"AQAB",
"blockchain",
"Blockscout",
Expand Down Expand Up @@ -118,8 +118,8 @@
"quicknode",
"quotidiennes",
"Rabby",
"Recompensas",
"readdirp",
"Recompensas",
"Récompenses",
"reenroll",
"Roboto",
Expand All @@ -141,6 +141,7 @@
"Solana",
"sont",
"spammy",
"stablecoins",
"Sunsetting",
"Superbridge",
"superchain",
Expand All @@ -155,8 +156,8 @@
"tute",
"uniffi",
"unpackedProof",
"userop",
"urlencode",
"userop",
"UUPS",
"uvwx",
"verifyProof",
Expand Down
14 changes: 7 additions & 7 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@
{
"group": "Commands",
"pages": [
"mini-apps/commands/verify",
"mini-apps/commands/pay",
"mini-apps/commands/wallet-auth",
"mini-apps/commands/send-transaction",
Expand Down Expand Up @@ -111,6 +112,11 @@
{
"group": "Further Reading",
"pages": [
"mini-apps/more/minikit-v2",
"mini-apps/more/webview-spec",
"mini-apps/ecosystem/ecosystem",
"mini-apps/more/community-tools-perks",
"mini-apps/more/faq",
{
"group": "Growth Playbook",
"pages": [
Expand All @@ -120,13 +126,7 @@
"mini-apps/growth/notifications",
"mini-apps/growth/analytics"
]
},
"mini-apps/more/releases",
"mini-apps/more/webview-spec",
"mini-apps/ecosystem/ecosystem",
"mini-apps/more/community-tools-perks",
"mini-apps/more/minikit-v2",
"mini-apps/more/faq"
}
]
}
]
Expand Down
Binary file removed images/docs/mini-apps/commands/pay-command.mp4
View file
Open in desktop
Binary file not shown.
Binary file added images/docs/mini-apps/commands/pay-updated.gif
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 11 additions & 7 deletions mini-apps/commands/attestation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,10 @@ description: "Request an attestation token using the unified MiniKit API."

Use `MiniKit.attestation()` to request an app attestation token for a request hash.

## Availability

- Works natively in World App
- Supports a custom fallback outside World App

## Basic Usage

```tsx
<CodeGroup>
```tsx title="Example"
import { MiniKit } from "@worldcoin/minikit-js";
import type {
CommandResultByVia,
Expand All @@ -37,6 +33,14 @@ export async function requestAttestation() {
}
```

```ts title="Type"
type MiniKitAttestationOptions = {
requestHash: string;
fallback?: () => unknown;
};
```
</CodeGroup>

## Result

<CodeGroup>
Expand Down Expand Up @@ -70,7 +74,7 @@ type AttestationResponse =

## Fallback Behavior

Use a custom `fallback` if you want equivalent behavior outside World App.
Define a custom fallback in the command payload for support outside mini apps.

## Error Codes

Expand Down
19 changes: 12 additions & 7 deletions mini-apps/commands/chat.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,10 @@ description: "Share a message through World Chat using the unified MiniKit API."

Use `MiniKit.chat()` to open World Chat with a prefilled message.

## Availability

- Works natively in World App
- Supports a custom fallback outside World App

## Basic Usage

```tsx
<CodeGroup>
```tsx title="Example"
import { MiniKit } from "@worldcoin/minikit-js";
import type {
CommandResultByVia,
Expand All @@ -38,6 +34,15 @@ export async function shareToChat() {
}
```

```ts title="Type"
type MiniKitChatOptions = {
message: string;
to?: string[];
fallback?: () => unknown;
};
```
</CodeGroup>

## Result

<CodeGroup>
Expand Down Expand Up @@ -73,7 +78,7 @@ type ChatResponse =

## Fallback Behavior

Use a custom `fallback` if you want equivalent sharing behavior outside World App.
Define a custom fallback in the command payload for support outside mini apps.

## Error Codes

Expand Down
17 changes: 10 additions & 7 deletions mini-apps/commands/close-miniapp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,10 @@ description: "Programmatically close the mini app using the unified MiniKit API.

Use `MiniKit.closeMiniApp()` to programmatically close the mini app.

## Availability

- Works natively in World App
- Supports a custom fallback outside World App

## Basic Usage

```tsx
<CodeGroup>
```tsx title="Example"
import { MiniKit } from "@worldcoin/minikit-js";
import type {
CommandResultByVia,
Expand All @@ -35,6 +31,13 @@ export async function closeMiniApp() {
}
```

```ts title="Type"
type MiniKitCloseMiniAppOptions = {
fallback?: () => unknown;
};
```
</CodeGroup>

## Result

<CodeGroup>
Expand Down Expand Up @@ -66,4 +69,4 @@ type CloseMiniAppResponse =

## Fallback Behavior

Use a custom `fallback` if you want equivalent behavior outside World App.
Define a custom fallback in the command payload for support outside mini apps.
17 changes: 10 additions & 7 deletions mini-apps/commands/get-permissions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,10 @@ description: "Read current mini app permission settings using the unified MiniKi

Use `MiniKit.getPermissions()` to read the current permission state for the mini app.

## Availability

- Works natively in World App
- Supports a custom fallback outside World App

## Basic Usage

```tsx
<CodeGroup>
```tsx title="Example"
import { MiniKit } from "@worldcoin/minikit-js";
import type {
CommandResultByVia,
Expand All @@ -35,6 +31,13 @@ export async function getPermissions() {
}
```

```ts title="Type"
type MiniKitGetPermissionsOptions = {
fallback?: () => unknown;
};
```
</CodeGroup>

## Result

<CodeGroup>
Expand Down Expand Up @@ -78,7 +81,7 @@ type GetPermissionsResponse =

## Fallback Behavior

Use a custom `fallback` if you want equivalent permission behavior outside World App.
Define a custom fallback in the command payload for support outside mini apps.

## Error Codes

Expand Down
42 changes: 20 additions & 22 deletions mini-apps/commands/how-to-send-notifications.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,28 +13,6 @@ To send notifications to users you need to:
- Request permission to send notifications from the user, via MiniKit (see [Request Permission](/mini-apps/commands/request-permission)),
- Actually send the notification using our API or the Developer Portal.

Notifications are queued on our servers, users may not receive them immediately.

## Manually sending notifications from Developer Portal

<Note type="info">
This form doesn't support localized notifications yet. To take advantage of
localizations, use the API.
</Note>

You can send notifications to multiple wallet addresses (up to 1000) directly from the Developer Portal.

<div className="flex justify-center">
<img
src="/images/docs/mini-apps/commands/notifications-dev-portal.png"
alt="Notification Interface in the Developer Portal"
className="m-auto block"
width="300"
/>
</div>

Use the form to input addresses, and content details. Once you click the `Send` button and get a success response, your notifications will be queued for delivery.

## Calling the send-notification endpoint

The API endpoint provides capabilities for sending notifications programmatically. These notifications can be localized,
Expand Down Expand Up @@ -83,6 +61,26 @@ If their language isn't included in your localizations, you'll receive a specifi

For complete API documentation including all supported languages and response formats, see the [API Reference](/api-reference/developer-portal/send-notification).

## Manually sending notifications from Developer Portal

<Note type="info">
This form doesn't support localized notifications yet. To take advantage of
localizations, use the API.
</Note>

You can send notifications to multiple wallet addresses (up to 1000) directly from the Developer Portal.

<div className="flex justify-center">
<img
src="/images/docs/mini-apps/commands/notifications-dev-portal.png"
alt="Notification Interface in the Developer Portal"
className="m-auto block"
width="300"
/>
</div>

Use the form to input addresses, and content details. Once you click the `Send` button and get a success response, your notifications will be queued for delivery.

## Testing

We currently have a limit of 40 notifications per 4 hours for unverified apps. This is to help you test your notification implementations.
Expand Down
55 changes: 29 additions & 26 deletions mini-apps/commands/pay.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,16 @@
---
title: "Pay"
description: "Request a payment using the unified MiniKit API."
description: "Request a payment from the user"
"og:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png"
"twitter:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png"
---

Use `MiniKit.pay()` to request a payment inside World App.

<Note>
These examples assume MiniKit has already been initialized through
`MiniKitProvider` or `MiniKit.install()`.
</Note>

## Availability

- Works natively in World App
- Supports a custom fallback outside World App
This command is an abstraction for a simple transfer. This shouldn't be used outside of World App. Pay supports WLD and all local stablecoins.

## Basic Usage

```tsx
<CodeGroup>
```tsx title="Example"
import { MiniKit } from "@worldcoin/minikit-js";
import {
Tokens,
Expand All @@ -30,7 +21,8 @@ import {
} from "@worldcoin/minikit-js/commands";

export async function sendPayment() {
const response = await fetch("/api/initiate-payment", { method: "POST" });
// Create a nonce in the backend to use as a reference for this payment.
const response = await fetch("/api/generate-nonce", { method: "POST" });
const { id } = await response.json();

const input = {
Expand All @@ -43,7 +35,10 @@ export async function sendPayment() {
},
],
description: "Example payment",
} satisfies MiniKitPayOptions;
fallback: () => {
alert("Please complete the payment in World App to proceed.");
},
Comment on lines +38 to +40
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Guard pay example against fallback execution path

This example now passes a fallback callback, which means MiniKit.pay() can return executedWith: "fallback", but the snippet still treats result.data as a minikit payment payload and immediately POSTs it to /api/confirm-payment. In non-World-App contexts this can send undefined/non-payment data and make the verification step fail, so the sample should branch on result.executedWith (as done in other command docs) before using payment fields.

Useful? React with 👍 / 👎.

};

const result: CommandResultByVia<PayResult, PayResult, "minikit"> =
await MiniKit.pay(input);
Expand All @@ -58,6 +53,20 @@ export async function sendPayment() {
}
```

```ts title="Type"
type MiniKitPayOptions = {
reference: string;
to: string;
tokens: {
symbol: Tokens;
token_amount: string;
}[];
description: string;
fallback?: () => unknown;
};
```
</CodeGroup>

## Result

<CodeGroup>
Expand Down Expand Up @@ -93,10 +102,6 @@ type PayResponse =
```
</CodeGroup>

## Fallback Behavior

Use a custom `fallback` if you want equivalent payment behavior outside World App.

## Backend Verification

Always verify the payment on your backend before treating it as final.
Expand Down Expand Up @@ -140,14 +145,12 @@ export async function POST(req: NextRequest) {
| `generic_error` | Unexpected failure |
| `user_blocked` | Payments are not available in the user's region |

## Fallback Behavior

Define a custom fallback in the command payload for support outside mini apps.

## Preview

<div className="grid justify-items-center text-center">
<video className="m-auto" width="300" autoPlay muted loop playsInline>
<source
src="/images/docs/mini-apps/commands/pay-command.mp4"
type="video/mp4"
/>
Your browser does not support the video tag.
</video>
<img className="m-auto" width="300" src="/images/docs/mini-apps/commands/pay-updated.gif" alt="Pay command demo" />
</div>
Loading
Loading