Initialization

When your mini app initializes inside World App, MiniKit stores device context, launch context, and basic user metadata on the client.

Initialize MiniKit before calling any command:

import { MiniKit } from "@worldcoin/minikit-js";

const { success } = MiniKit.install();

if (!success) {
  console.error("MiniKit is unavailable in this environment");
}

If you are using React, MiniKitProvider calls MiniKit.install() for you.

MiniKit State

After install, these are the public MiniKit state accessors you can rely on:

type MiniKitState = {
  user: {
    walletAddress?: string;
    username?: string;
    profilePictureUrl?: string;
    permissions?: {
      notifications: boolean;
      contacts: boolean;
    };
    optedIntoOptionalAnalytics?: boolean;
  };
  deviceProperties: {
    safeAreaInsets?: {
      top: number;
      right: number;
      bottom: number;
      left: number;
    };
    deviceOS?: string;
    worldAppVersion?: number;
  };
  location: "chat" | "home" | "app-store" | "deep-link" | "wallet-tab" | null;
};

Example:

import { MiniKit } from "@worldcoin/minikit-js";

console.log(MiniKit.user.optedIntoOptionalAnalytics);
console.log(MiniKit.deviceProperties.safeAreaInsets);
console.log(MiniKit.deviceProperties.deviceOS);
console.log(MiniKit.deviceProperties.worldAppVersion);
console.log(MiniKit.location);

Notes:

• MiniKit.user.optedIntoOptionalAnalytics is available during initialization.
• walletAddress, username, and profilePictureUrl are usually populated later, for example after walletAuth().
• MiniKit.location is the mapped launch location. Use this instead of reading older launch-origin fields directly.

Permissions

MiniKitProvider installs MiniKit, but it does not automatically fetch permission state.

If you need the current permission settings, call MiniKit.getPermissions() explicitly:

import { MiniKit } from "@worldcoin/minikit-js";
import type { MiniAppGetPermissionsSuccessPayload } from "@worldcoin/minikit-js/commands";

const result = await MiniKit.getPermissions();
const permissions: MiniAppGetPermissionsSuccessPayload["permissions"] =
  result.data.permissions;

console.log(permissions.notifications);
console.log(permissions.contacts);
console.log(permissions.microphone);

Notes:

• MiniKit.user.permissions is cached MiniKit state and should be treated as incomplete until you fetch permissions.
• getPermissions() can return notifications, contacts, and microphone.
• The cached MiniKit.user.permissions shape only exposes notifications and contacts.

Launch Location

MiniKit normalizes the raw World App launch origin into:

type MiniAppLaunchLocation =
  | "chat"
  | "home"
  | "app-store"
  | "deep-link"
  | "wallet-tab"
  | null;

Example:

import { MiniKit } from "@worldcoin/minikit-js";

if (MiniKit.location === "chat") {
  console.log("Opened from chat");
}

Raw World App Object

If you need the untransformed World App payload, read window.WorldApp directly.

type WorldAppContext = {
  world_app_version: number;
  device_os: "ios" | "android";
  is_optional_analytics: boolean;
  supported_commands: Array<{
    name:
      | "attestation"
      | "pay"
      | "wallet-auth"
      | "send-transaction"
      | "sign-message"
      | "sign-typed-data"
      | "share-contacts"
      | "request-permission"
      | "get-permissions"
      | "send-haptic-feedback"
      | "share"
      | "chat"
      | "close-miniapp";
    supported_versions: number[];
  }>;
  safe_area_insets: {
    top: number;
    right: number;
    bottom: number;
    left: number;
  };
  location: string | null | undefined;
};

Example:

{
  "world_app_version": 4000301,
  "device_os": "ios",
  "is_optional_analytics": true,
  "supported_commands": [
    { "name": "attestation", "supported_versions": [1] },
    { "name": "pay", "supported_versions": [1] },
    { "name": "wallet-auth", "supported_versions": [2] },
    { "name": "send-transaction", "supported_versions": [2] },
    { "name": "sign-message", "supported_versions": [1] },
    { "name": "sign-typed-data", "supported_versions": [1] },
    { "name": "share-contacts", "supported_versions": [1] },
    { "name": "request-permission", "supported_versions": [1] },
    { "name": "get-permissions", "supported_versions": [1] },
    { "name": "send-haptic-feedback", "supported_versions": [1] },
    { "name": "share", "supported_versions": [1] },
    { "name": "chat", "supported_versions": [1] },
    { "name": "close-miniapp", "supported_versions": [1] }
  ],
  "safe_area_insets": {
    "top": 0,
    "right": 0,
    "bottom": 0,
    "left": 0
  },
  "location": "deep-link"
}

Use window.WorldApp only when you need the raw payload. In application code, prefer MiniKit.user, MiniKit.deviceProperties, and MiniKit.location.