> ## Documentation Index
> Fetch the complete documentation index at: https://docs.world.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Initialization

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

If you are using React, `MiniKitProvider` will perform the initialization for you.

Otherwise, manually initialize MiniKit at the start of your app:

```tsx theme={null}
import { MiniKit } from "@worldcoin/minikit-js";

const { success } = MiniKit.install();
```

## MiniKit State

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

<Tabs>
  <Tab title="Type">
    ```tsx theme={null}
    // MiniKit state
    {
      user: {
        walletAddress?: string;
        username?: string;
        profilePictureUrl?: string;
        permissions?: {
          notifications: boolean;
          contacts: boolean;
        };
        optedIntoOptionalAnalytics?: boolean;
        verificationStatus?: {
          isOrbVerified: boolean;
          isDocumentVerified: boolean;
          isSecureDocumentVerified: boolean;
        };
        preferredCurrency?: string;
        pendingNotifications?: number;
      };
      deviceProperties: {
        safeAreaInsets?: {
          top: number;
          right: number;
          bottom: number;
          left: number;
        };
        deviceOS?: string;
        worldAppVersion?: number;
      };
      location: "chat" | "home" | "app-store" | "deep-link" | "wallet-tab" | null;
    }
    ```
  </Tab>
</Tabs>

Notes:

* `walletAddress`, `verificationStatus`, `preferredCurrency`, `pendingNotifications`, and `optedIntoOptionalAnalytics` are all available at initialization.
* `username` and `profilePictureUrl` are populated 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:

```tsx theme={null}
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;
```

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:

<Tabs>
  <Tab title="Type">
    ```tsx theme={null}
    type MiniAppLaunchLocation =
      | "chat"
      | "home"
      | "app-store"
      | "deep-link"
      | "wallet-tab"
      | null;
    ```
  </Tab>

  <Tab title="Example">
    ```tsx theme={null}
    import { MiniKit } from "@worldcoin/minikit-js";

    if (MiniKit.location === "chat") {
      console.log("Opened from chat");
    }
    ```
  </Tab>
</Tabs>

## Raw World App Object

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

<Tabs>
  <Tab title="Type">
    ```tsx theme={null}
    // window.WorldApp
    {
      world_app_version: number;
      device_os: "ios" | "android";
      is_optional_analytics: boolean;
      wallet_address: string;
      verification_status: {
        is_orb_verified: boolean;
        is_document_verified: boolean;
        is_secure_document_verified: boolean;
      };
      preferred_currency: string;
      pending_notifications: number;
      supported_commands: Array<{
        name:
          | "verify"
          | "attestation"
          | "pay"
          | "wallet-auth"
          | "send-transaction"
          | "sign-message"
          | "sign-typed-data"
          | "share-contacts"
          | "request-permission"
          | "get-permissions"
          | "send-haptic-feedback"
          | "share"
          | "chat"
          | "close-miniapp"
          | "microphone-stream-started"
          | "microphone-stream-ended";
        supported_versions: number[];
      }>;
      safe_area_insets: {
        top: number;
        right: number;
        bottom: number;
        left: number;
      };
      location: {
        open_origin: string;
      } | null | undefined;
    }
    ```
  </Tab>

  <Tab title="Example">
    ```json theme={null}
    {
      "world_app_version": 4001000,
      "device_os": "ios",
      "is_optional_analytics": true,
      "wallet_address": "0x377da9cab87c04a1d6f19d8b4be9aef8df26fcdd",
      "verification_status": {
        "is_orb_verified": true,
        "is_document_verified": true,
        "is_secure_document_verified": false
      },
      "preferred_currency": "USD",
      "pending_notifications": 0,
      "supported_commands": [
        { "name": "verify", "supported_versions": [1] },
        { "name": "attestation", "supported_versions": [1] },
        { "name": "pay", "supported_versions": [1] },
        { "name": "wallet-auth", "supported_versions": [1, 2] },
        { "name": "send-transaction", "supported_versions": [1, 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] },
        { "name": "microphone-stream-started", "supported_versions": [1] },
        { "name": "microphone-stream-ended", "supported_versions": [1] }
      ],
      "safe_area_insets": {
        "top": 0,
        "right": 0,
        "bottom": 0,
        "left": 0
      },
      "location": {
        "open_origin": "deeplink"
      }
    }
    ```
  </Tab>
</Tabs>

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