MiniKit

https://github.com/worldcoin/minikit-js
Admin
Minikit JS is a JavaScript library for interacting with Worldcoin mini-apps, providing essential...
Tokens:10,917
Snippets:108
Trust Score:9.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Set up Local Development Environment

Source: https://github.com/worldcoin/minikit-js/blob/main/README.md

Install dependencies and run the example mini app locally for development and testing.

```bash
pnpm i
cd demo/with-next
pnpm dev
```

--------------------------------

### Initialize Mini App Environment

Source: https://github.com/worldcoin/minikit-js/blob/main/demo/next-15-template/README.md

Commands to configure the local development environment and start the application server.

```bash
cp .env.example .env.local
```

```bash
npm run dev
```

```bash
ngrok http 3000
```

```bash
npx auth secret
```

--------------------------------

### Start Development Server

Source: https://github.com/worldcoin/minikit-js/blob/main/demo/with-next/README.md

Commands to launch the development server using various package managers.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/worldcoin/minikit-js/blob/main/CLAUDE.md

Use this command to install all project dependencies. Ensure pnpm is installed and the project is set up correctly.

```bash
pnpm i
```

--------------------------------

### Install minikit-react

Source: https://github.com/worldcoin/minikit-js/blob/main/packages/react/README.md

Install the minikit-react package using pnpm.

```bash
pnpm i @worldcoin/minikit-react
```

--------------------------------

### Initialize MiniKit SDK

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Install and initialize the MiniKit instance to enable World App features. Check the installation result and verify the runtime environment.

```typescript
// Install via npm/pnpm
// pnpm i @worldcoin/minikit-js

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

// Initialize MiniKit in your app (typically in a layout or provider)
const installResult = MiniKit.install('app_your_app_id');

if (installResult.success) {
  console.log('MiniKit installed successfully');
} else {
  console.error('MiniKit installation failed:', installResult.errorMessage);
  // Possible errors: 'outside_of_worldapp', 'app_out_of_date', 'already_installed'
}

// Check if running inside World App
if (MiniKit.isInWorldApp()) {
  console.log('Running in World App');
  console.log('User wallet:', MiniKit.user.walletAddress);
  console.log('Device OS:', MiniKit.deviceProperties.deviceOS);
  console.log('Launch location:', MiniKit.location); // 'app-store', 'home', 'chat', etc.
}
```

--------------------------------

### Install MiniKit Packages

Source: https://github.com/worldcoin/minikit-js/blob/main/skills/web-to-miniapp/SKILL.md

Install the necessary MiniKit packages for your Next.js project using npm.

```bash
npm install @worldcoin/minikit-js @worldcoin/minikit-react
```

--------------------------------

### Run Comprehensive Demo Locally

Source: https://github.com/worldcoin/minikit-js/blob/main/CLAUDE.md

Starts the comprehensive demo application locally. This requires navigating to the demo directory and then running the development command.

```bash
cd demo/with-next && pnpm dev
```

--------------------------------

### Install MiniKit JS

Source: https://github.com/worldcoin/minikit-js/blob/main/README.md

Install the MiniKit JS package using pnpm or include it via CDN.

```bash
pnpm i @worldcoin/minikit-js
```

--------------------------------

### Start Development Servers with Turbo

Source: https://github.com/worldcoin/minikit-js/blob/main/CLAUDE.md

Initiates all development servers across the monorepo using Turbo. For specific demos, navigate to the demo directory first.

```bash
pnpm dev
```

--------------------------------

### Create Mini App Project with CLI

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Scaffold a new mini app project using the `@worldcoin/create-mini-app` CLI tool. This command sets up a Next.js 15 project with pre-configured MiniKit, authentication, example components, and Wagmi integration.

```bash
# Create a new mini app project
npx @worldcoin/create-mini-app my-mini-app

# Or use npx directly
npx create-mini-app my-mini-app

# The CLI creates a Next.js 15 project with:
# - MiniKit pre-configured
# - Authentication setup
# - Example components for all commands
# - Wagmi integration
```

--------------------------------

### Generate Authentication Secret

Source: https://github.com/worldcoin/minikit-js/blob/main/CLAUDE.md

Generates a secret key for authentication purposes, typically used during local development setup.

```bash
npx auth secret
```

--------------------------------

### Initialize World Mini App project

Source: https://github.com/worldcoin/minikit-js/blob/main/packages/create-mini-app/README.md

Use this command to scaffold a new project using the official Next.js 15 template.

```bash
npx @worldcoin/create-mini-app@latest my-mini-app
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/worldcoin/minikit-js/blob/main/demo/with-next/README.md

Standard commands for running the local server and exposing it via ngrok.

```bash
pnpm dev
```

```bash
ngrok 3000
```

--------------------------------

### Add Web to Mini App Agent

Source: https://github.com/worldcoin/minikit-js/blob/main/README.md

Use the 'skills' command to add the agent for migrating an existing web app to a mini app.

```bash
npx skills add worldcoin/minikit-js web-to-miniapp
```

--------------------------------

### Add Mini App to Web Agent

Source: https://github.com/worldcoin/minikit-js/blob/main/README.md

Use the 'skills' command to add the agent for migrating a mini app to a web application.

```bash
npx skills add worldcoin/minikit-js miniapp-to-web
```

--------------------------------

### Import MiniKit from root

Source: https://github.com/worldcoin/minikit-js/blob/main/packages/core/README.md

Standard import for the main MiniKit object.

```ts
import { MiniKit } from '@worldcoin/minikit-js';
```

--------------------------------

### Build and Release with Changesets

Source: https://github.com/worldcoin/minikit-js/blob/main/CLAUDE.md

Automates the process of building packages and publishing them with version bumps managed by changesets.

```bash
pnpm release
```

--------------------------------

### Dual-Provider Wallet Connection

Source: https://github.com/worldcoin/minikit-js/blob/main/skills/web-to-miniapp/SKILL.md

Implement logic to detect World App and use `getWorldAppProvider()`, falling back to `window.ethereum` for browser wallets. This ensures compatibility with both environments.

```typescript
import { getWorldAppProvider } from '@worldcoin/minikit-js';
import { useMiniKit } from '@worldcoin/minikit-js/minikit-provider';
import { createWalletClient, custom } from 'viem';
import { worldchain } from 'viem/chains';

// Inside your component:
let isWorldApp = false;
try {
  isWorldApp = !!useMiniKit().isInstalled;
} catch {
  isWorldApp = typeof window !== 'undefined' && !!window.WorldApp;
}

// When connecting:
const provider = isWorldApp ? getWorldAppProvider() : window.ethereum;

const walletClient = createWalletClient({
  chain: worldchain,
  transport: custom(provider),
});
```

--------------------------------

### Build All Packages with Turbo

Source: https://github.com/worldcoin/minikit-js/blob/main/CLAUDE.md

Executes the build process for all packages within the monorepo using Turbo, ensuring all code is compiled and ready.

```bash
pnpm build
```

--------------------------------

### Release Package Version

Source: https://github.com/worldcoin/minikit-js/blob/main/README.md

Run the 'pnpm changeset' command to manage version bumping for the package.

```bash
pnpm changeset
```

--------------------------------

### Add MiniKitProvider

Source: https://github.com/worldcoin/minikit-js/blob/main/skills/web-to-miniapp/SKILL.md

Integrate the `MiniKitProvider` into your application's layout to enable MiniKit functionality. Ensure it wraps your application's children.

```tsx
// src/app/providers.tsx
'use client';
import { MiniKitProvider } from '@worldcoin/minikit-js/minikit-provider';
export default function Providers({ children }: { children: React.ReactNode }) {
  return <MiniKitProvider>{children}</MiniKitProvider>;
}
```

```tsx
import Providers from './providers';
// ...
<body>
  <Providers>{children}</Providers>
</body>;
```

--------------------------------

### User Profile Utilities in MiniKit.js

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Utilities for looking up World App users by username or wallet address, retrieving current user info, displaying profile cards, and generating mini app deep links.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';

// Get user by username
const alice = await MiniKit.getUserByUsername('alice');
console.log('Address:', alice.walletAddress);
console.log('Username:', alice.username);
console.log('Profile picture:', alice.profilePictureUrl);

// Get user by wallet address
const user = await MiniKit.getUserByAddress('0x...');
console.log('Username:', user.username);

// Get current user info (after auth)
const currentUser = MiniKit.user;
console.log('Wallet:', currentUser.walletAddress);
console.log('Verification:', currentUser.verificationStatus?.isOrbVerified);

// Show user profile card
MiniKit.showProfileCard('alice'); // By username
MiniKit.showProfileCard(undefined, '0x...'); // By address

// Generate mini app deep link URL
const appUrl = MiniKit.getMiniAppUrl('app_your_id', '/dashboard');
// Returns: https://world.org/mini-app?app_id=app_your_id&path=%2Fdashboard
```

--------------------------------

### Share Content with MiniKit.share

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Use MiniKit.share to open the native World App share sheet for files, text, or URLs. The `files` parameter is optional.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';

async function shareContent() {
  const result = await MiniKit.share({
    title: 'Check out my achievement!',
    text: 'I just completed a verification on World App',
    url: 'https://myapp.com/achievement/123',
    files: [imageFile], // Optional: File objects to share
  });

  console.log('Shared files count:', result.data.shared_files_count);
}
```

--------------------------------

### MiniKit.share - Share Content

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Share files, text, or URLs via the native World App share sheet.

```APIDOC
## POST MiniKit.share

### Description
Share files, text, or URLs via the native World App share sheet.

### Method
POST

### Endpoint
/share

### Parameters
#### Request Body
- **title** (string) - Required - The title to display for the shared content.
- **text** (string) - Required - The main text content to share.
- **url** (string) - Optional - A URL to include with the shared content.
- **files** (Array<File>) - Optional - An array of File objects to share.

### Request Example
```json
{
  "title": "Check out my achievement!",
  "text": "I just completed a verification on World App",
  "url": "https://myapp.com/achievement/123",
  "files": [imageFile]
}
```

### Response
#### Success Response (200)
- **shared_files_count** (integer) - The number of files successfully shared.
```

--------------------------------

### Check Code Formatting with Prettier

Source: https://github.com/worldcoin/minikit-js/blob/main/CLAUDE.md

Runs Prettier to check for code formatting issues across the project.

```bash
pnpm lint
```

--------------------------------

### MiniKit.signMessage

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Requests the user to sign an arbitrary message with their wallet.

```APIDOC
## MiniKit.signMessage

### Description
Request the user to sign an arbitrary message with their wallet.

### Parameters
#### Request Body
- **message** (string) - Required - The message to be signed.

### Response
- **data** (object) - Contains 'signature', 'address', and 'message'.
- **executedWith** (string) - Indicates if executed via 'minikit' or 'wagmi'.
```

--------------------------------

### Run Core Package Tests

Source: https://github.com/worldcoin/minikit-js/blob/main/CLAUDE.md

Executes the test suite specifically for the core SDK package using Jest.

```bash
cd packages/core && pnpm test
```

--------------------------------

### Configure Wagmi with World App Connector

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Set up Wagmi configuration to include the World App connector. This connector handles native MiniKit interactions in World App and provides fallbacks for web environments. It supports only World Chain (chainId: 480).

```typescript
import { createConfig, http } from 'wagmi';
import { worldchain } from 'viem/chains';
import { worldApp } from '@worldcoin/minikit-js/wagmi';
import { injected, walletConnect } from 'wagmi/connectors';

// Create Wagmi config with World App connector first
const wagmiConfig = createConfig({
  chains: [worldchain],
  connectors: [
    worldApp(), // Uses native MiniKit in World App, auto-detects environment
    injected(), // Fallback for browser wallets
    walletConnect({ projectId: '...' }),
  ],
  transports: {
    [worldchain.id]: http('https://worldchain-mainnet.g.alchemy.com/public'),
  },
});

// The worldApp connector automatically:
// - Uses native MiniKit commands in World App
// - Registers Wagmi config for MiniKit fallbacks on web
// - Handles wallet auth via eth_requestAccounts
// - Only supports World Chain (chainId: 480)
```

--------------------------------

### MiniKit.attestation - Request App Attestation

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Request an attestation token for verifying requests from your mini app.

```APIDOC
## POST MiniKit.attestation

### Description
Request an attestation token for verifying requests from your mini app.

### Method
POST

### Endpoint
/attestation

### Parameters
#### Request Body
- **requestHash** (string) - Required - A SHA256 hash of the data being sent for verification.

### Request Example
```json
{
  "requestHash": "sha256_hash_of_request_data"
}
```

### Response
#### Success Response (200)
- **attestation_token** (string) - The attestation token to be sent to your backend for verification.
```

--------------------------------

### Manage Permissions with MiniKit.getPermissions / MiniKit.requestPermission

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Check current notification and contact permissions using MiniKit.getPermissions, and request specific permissions with MiniKit.requestPermission.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';

// Get current permissions
async function checkPermissions() {
  const result = await MiniKit.getPermissions();

  console.log('Notifications enabled:', result.data.permissions.notifications);
  console.log('Contacts enabled:', result.data.permissions.contacts);
}

// Request a specific permission
async function requestNotificationPermission() {
  const result = await MiniKit.requestPermission({
    permission: 'notifications', // 'notifications' | 'contacts'
  });

  if (result.data.status === 'success') {
    console.log('Permission granted');
  }
}
```

--------------------------------

### Request App Attestation with MiniKit.attestation

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Obtain an attestation token using MiniKit.attestation by providing a hash of your request data. This token is used for verifying mini app requests on your backend.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';
import { sha256 } from 'js-sha256';

async function getAttestation() {
  // Create a hash of your request data
  const requestData = JSON.stringify({ action: 'verify-user', timestamp: Date.now() });
  const requestHash = sha256(requestData);

  const result = await MiniKit.attestation({
    requestHash: requestHash,
  });

  console.log('Attestation token:', result.data.attestation_token);

  // Send token to backend for verification
  await fetch('/api/verify-attestation', {
    method: 'POST',
    body: JSON.stringify({
      attestationToken: result.data.attestation_token,
      requestData: requestData,
    }),
  });
}
```

--------------------------------

### MiniKit.getPermissions / MiniKit.requestPermission - Manage Permissions

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Check and request user permissions for notifications and contacts.

```APIDOC
## GET MiniKit.getPermissions

### Description
Check the current status of user permissions for notifications and contacts.

### Method
GET

### Endpoint
/getPermissions

### Response
#### Success Response (200)
- **permissions.notifications** (boolean) - Indicates if notification permissions are enabled.
- **permissions.contacts** (boolean) - Indicates if contact permissions are enabled.
```

```APIDOC
## POST MiniKit.requestPermission

### Description
Request a specific permission from the user.

### Method
POST

### Endpoint
/requestPermission

### Parameters
#### Request Body
- **permission** (string) - Required - The permission to request. Possible values: 'notifications', 'contacts'.

### Request Example
```json
{
  "permission": "notifications"
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the permission request. Expected value: 'success' if granted.
```

--------------------------------

### MiniKit.shareContacts

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Opens the contact picker to allow users to select World App contacts.

```APIDOC
## MiniKit.shareContacts

### Description
Opens the contact picker to let users select World App contacts for payments or messaging.

### Parameters
#### Request Body
- **isMultiSelectEnabled** (boolean) - Optional - Allow selecting multiple contacts.
- **inviteMessage** (string) - Optional - Custom invite message for non-users.
- **fallback** (function) - Optional - Fallback logic for web environments.

### Response
- **data** (object) - Contains 'contacts' array with username, walletAddress, and profilePictureUrl.
```

--------------------------------

### Close Mini App with MiniKit.closeMiniApp

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Programmatically close the current mini app and return to the World App using MiniKit.closeMiniApp.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';

async function exitApp() {
  await MiniKit.closeMiniApp();
  // App will close, this code won't execute in World App
}
```

--------------------------------

### Import using tree-shakeable subpaths

Source: https://github.com/worldcoin/minikit-js/blob/main/packages/core/README.md

Import specific commands or helpers from subpaths to reduce bundle size.

```ts
import {
  MiniKitSendTransactionOptions,
  SendTransactionErrorCodes,
} from '@worldcoin/minikit-js/commands';
import { getIsUserVerified } from '@worldcoin/minikit-js/address-book';
import {
  parseSiweMessage,
  verifySiweMessage,
} from '@worldcoin/minikit-js/siwe';
```

--------------------------------

### MiniKit.sendTransaction

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Executes smart contract transactions on World Chain, supporting batch transactions and gas sponsorship.

```APIDOC
## MiniKit.sendTransaction

### Description
Sends transactions to smart contracts on World Chain. Supports batch transactions with gas sponsorship in World App.

### Parameters
#### Request Body
- **chainId** (number) - Required - The chain ID (must be 480 for World Chain).
- **transactions** (array) - Required - List of transaction objects containing 'to', 'data', and optional 'value'.
- **fallback** (function) - Optional - Fallback logic for web environments where batching may not be supported.

### Response
- **data** (object) - Contains 'userOpHash'.
- **executedWith** (string) - Indicates if executed via 'minikit' or 'wagmi'.
```

--------------------------------

### Authenticate Users with SIWE

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Perform Sign-In with Ethereum (SIWE) authentication. The result should be sent to a backend server for verification.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';

async function authenticateUser() {
  try {
    const result = await MiniKit.walletAuth({
      nonce: crypto.randomUUID(), // Server-generated nonce for security
      statement: 'Sign in to My Mini App',
      expirationTime: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days
      notBefore: new Date(Date.now() - 24 * 60 * 60 * 1000), // 1 day ago
    });

    console.log('Auth result:', result.executedWith); // 'minikit' | 'wagmi' | 'fallback'
    console.log('Wallet address:', result.data.address);
    console.log('Signature:', result.data.signature);
    console.log('SIWE message:', result.data.message);

    // Send to backend for verification
    const verifyResponse = await fetch('/api/verify-siwe', {
      method: 'POST',
      body: JSON.stringify({
        address: result.data.address,
        message: result.data.message,
        signature: result.data.signature,
      }),
    });

    return verifyResponse.json();
  } catch (error) {
    console.error('Authentication failed:', error);
  }
}
```

--------------------------------

### Sign Arbitrary Messages with MiniKit

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Request the user to sign an arbitrary message with their Worldcoin wallet. The signature can then be verified on a backend server. Note the 'executedWith' property indicates the signing method used.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';

async function signMessage() {
  try {
    const result = await MiniKit.signMessage({
      message: 'I agree to the terms and conditions of My App',
    });

    console.log('Signature:', result.data.signature);
    console.log('Address:', result.data.address);
    console.log('Executed with:', result.executedWith); // 'minikit' | 'wagmi'

    // Verify signature on backend
    const isValid = await verifySignature(
      result.data.message,
      result.data.signature,
      result.data.address
    );
  } catch (error) {
    console.error('Signing failed:', error);
  }
}
```

--------------------------------

### MiniKit.closeMiniApp - Close the Mini App

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Programmatically close the mini app and return to World App.

```APIDOC
## POST MiniKit.closeMiniApp

### Description
Programmatically close the mini app and return to World App.

### Method
POST

### Endpoint
/closeMiniApp

### Response
No specific response body is detailed for success. The app will close upon successful execution.
```

--------------------------------

### Fix Code Formatting with Prettier

Source: https://github.com/worldcoin/minikit-js/blob/main/CLAUDE.md

Automatically formats the code according to Prettier rules to fix any formatting issues.

```bash
pnpm format
```

--------------------------------

### MiniKit.sendHapticFeedback - Trigger Haptic Feedback

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Trigger device haptic feedback for better UX on touch interactions.

```APIDOC
## POST MiniKit.sendHapticFeedback

### Description
Trigger device haptic feedback for better UX on touch interactions.

### Method
POST

### Endpoint
/sendHapticFeedback

### Parameters
#### Request Body
- **hapticsType** (string) - Required - The type of haptic feedback to trigger. Possible values: 'selection-changed', 'impact', 'notification'.
- **style** (string) - Optional - The style of haptic feedback. For 'impact', possible values are 'light', 'medium', 'heavy'. For 'notification', possible values are 'success', 'warning', 'error'.

### Request Example
```json
{
  "hapticsType": "impact",
  "style": "heavy"
}
```

### Response
No specific response body is detailed for success.
```

--------------------------------

### Disable SSR for MiniKit Pages

Source: https://github.com/worldcoin/minikit-js/blob/main/skills/web-to-miniapp/SKILL.md

Wrap your page component in a dynamic import with `ssr: false` to prevent hydration mismatches caused by `window.WorldApp` not being available on the server.

```tsx
// src/app/page.tsx
'use client';
import dynamic from 'next/dynamic';
const App = dynamic(() => import('../components/App'), { ssr: false });
export default function Page() {
  return <App />;
}
```

--------------------------------

### Replace ERC20 Approve with Permit2

Source: https://github.com/worldcoin/minikit-js/blob/main/skills/web-to-miniapp/SKILL.md

Adapt frontend and smart contract code to use Permit2 for token approvals, as standard `token.approve()` calls are blocked in the World App mini app. The Permit2 address is constant across all EVM chains.

```typescript
// Before (blocked in mini app):
await walletClient.writeContract({
  address: TOKEN,
  abi: erc20Abi,
  functionName: 'approve',
  args: [SPENDER, amount],
});

// After:
const expiration = Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60;
await walletClient.writeContract({
  address: '0x000000000022D473030F116dDEE9F6B43aC78BA3', // Permit2
  abi: [
    {
      name: 'approve',
      type: 'function',
      stateMutability: 'nonpayable',
      inputs: [
        { name: 'token', type: 'address' },
        { name: 'spender', type: 'address' },
        { name: 'amount', type: 'uint160' },
        { name: 'expiration', type: 'uint48' },
      ],
      outputs: [],
    },
  ],
  functionName: 'approve',
  args: [TOKEN, SPENDER, amount, expiration],
});
```

```solidity
// Before:
token.transferFrom(msg.sender, address(this), amount);

// After:
import {IAllowanceTransfer} from "permit2/src/interfaces/IAllowanceTransfer.sol";

IAllowanceTransfer public immutable permit2;
// Set in constructor: permit2 = IAllowanceTransfer(0x000000000022D473030F116dDEE9F6B43aC78BA3);

permit2.transferFrom(msg.sender, address(this), uint160(amount), address(token));
```

--------------------------------

### Trigger Haptic Feedback with MiniKit.sendHapticFeedback

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Use MiniKit.sendHapticFeedback to provide tactile feedback for user interactions. Supports 'selection-changed', 'impact', and 'notification' types with various styles.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';

// Selection changed feedback (subtle)
await MiniKit.sendHapticFeedback({
  hapticsType: 'selection-changed',
});

// Impact feedback with style
await MiniKit.sendHapticFeedback({
  hapticsType: 'impact',
  style: 'heavy', // 'light' | 'medium' | 'heavy'
});

// Notification feedback
await MiniKit.sendHapticFeedback({
  hapticsType: 'notification',
  style: 'success', // 'success' | 'warning' | 'error'
});
```

--------------------------------

### User Profile Utilities

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Utilities for looking up World App users and managing profile information.

```APIDOC
## GET MiniKit.getUserByUsername

### Description
Look up a World App user by their username.

### Method
GET

### Endpoint
/getUserByUsername

### Parameters
#### Query Parameters
- **username** (string) - Required - The username of the user to look up.

### Response
#### Success Response (200)
- **walletAddress** (string) - The user's wallet address.
- **username** (string) - The user's username.
- **profilePictureUrl** (string) - The URL of the user's profile picture.
```

```APIDOC
## GET MiniKit.getUserByAddress

### Description
Look up a World App user by their wallet address.

### Method
GET

### Endpoint
/getUserByAddress

### Parameters
#### Query Parameters
- **address** (string) - Required - The wallet address of the user to look up.

### Response
#### Success Response (200)
- **username** (string) - The user's username.
```

```APIDOC
## GET MiniKit.user

### Description
Retrieve information about the currently authenticated user.

### Method
GET

### Endpoint
/user

### Response
#### Success Response (200)
- **walletAddress** (string) - The current user's wallet address.
- **verificationStatus.isOrbVerified** (boolean) - Indicates if the user has completed Orb verification.
```

```APIDOC
## POST MiniKit.showProfileCard

### Description
Display a user's profile card.

### Method
POST

### Endpoint
/showProfileCard

### Parameters
#### Request Body
- **username** (string) - Optional - The username of the user whose profile card to show.
- **address** (string) - Optional - The wallet address of the user whose profile card to show. Use either username or address.

### Request Example
```json
{
  "username": "alice"
}
```
OR
```json
{
  "address": "0x..."
}
```

### Response
No specific response body is detailed for success.
```

```APIDOC
## GET MiniKit.getMiniAppUrl

### Description
Generate a deep link URL for a mini app.

### Method
GET

### Endpoint
/getMiniAppUrl

### Parameters
#### Query Parameters
- **appId** (string) - Required - The unique identifier of the mini app.
- **path** (string) - Required - The path within the mini app to link to.

### Response
#### Success Response (200)
- **url** (string) - The generated deep link URL.
```

--------------------------------

### Send Smart Contract Transactions with MiniKit

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Execute smart contract transactions on World Chain. Supports batch transactions and gas sponsorship via World App. Ensure correct chainId and transaction data are provided.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';
import { useUserOperationReceipt } from '@worldcoin/minikit-react';
import { encodeFunctionData, createPublicClient, http } from 'viem';
import { worldchain } from 'viem/chains';

// In a React component
function TransactionComponent() {
  const client = createPublicClient({
    chain: worldchain,
    transport: http('https://worldchain-mainnet.g.alchemy.com/public'),
  });

  const { poll, isLoading } = useUserOperationReceipt({ client });

  async function mintToken() {
    const contractAddress = '0xF0882554ee924278806d708396F1a7975b732522';

    try {
      const result = await MiniKit.sendTransaction({
        chainId: 480, // World Chain only
        transactions: [
          {
            to: contractAddress,
            data: encodeFunctionData({
              abi: [
                {
                  name: 'mintToken',
                  type: 'function',
                  inputs: [],
                  outputs: [],
                },
              ],
              functionName: 'mintToken',
              args: [],
            }),
            value: '0x0', // Optional: ETH value in hex
          },
        ],
      });

      console.log('UserOp submitted:', result.data.userOpHash);
      console.log('Executed with:', result.executedWith); // 'minikit' | 'wagmi'

      // Poll for transaction receipt
      const receipt = await poll(result.data.userOpHash);
      console.log('Transaction confirmed:', receipt.transactionHash);
      console.log('Receipt:', receipt.receipt);
    } catch (error) {
      console.error('Transaction failed:', error);
    }
  }

  return <button onClick={mintToken} disabled={isLoading}>Mint Token</button>;
}
```

```typescript
// Batch transactions (World App only - not supported on web wagmi fallback)
async function batchTransactions() {
  const result = await MiniKit.sendTransaction({
    chainId: 480,
    transactions: [
      { to: '0x...', data: '0x...', value: '0x0' },
      { to: '0x...', data: '0x...', value: '0x0' },
    ],
    // Provide fallback for web since Wagmi doesn't support batching
    fallback: async () => {
      // Execute transactions sequentially on web
      return executeSequentially();
    },
  });
}
```

--------------------------------

### Implement command fallback logic

Source: https://github.com/worldcoin/minikit-js/blob/main/packages/core/README.md

Provides a fallback function to execute logic when the app is running outside of the World App environment.

```ts
const result = await MiniKit.sendHapticFeedback({
  hapticsType: 'impact',
  style: 'light',
  fallback: () => {
    navigator.vibrate?.(20);
    return {
      status: 'success',
      version: 1,
      timestamp: new Date().toISOString(),
    };
  },
});
```

--------------------------------

### Bundle Transactions with MiniKit.sendTransaction

Source: https://github.com/worldcoin/minikit-js/blob/main/skills/web-to-miniapp/SKILL.md

Use `MiniKit.sendTransaction` to send multiple transactions atomically. This bypasses the EIP-1193 provider for batching.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';
import { encodeFunctionData } from 'viem';

await MiniKit.sendTransaction({
  chainId: 480,
  transactions: [
    {
      to: PERMIT2,
      data: encodeFunctionData({
        abi: permit2Abi,
        functionName: 'approve',
        args: [TOKEN, SPENDER, amount, expiration],
      }),
    },
    {
      to: CONTRACT,
      data: encodeFunctionData({
        abi: contractAbi,
        functionName: 'swap',
        args: [amount],
      }),
    },
  ],
});
```

--------------------------------

### Send a transaction with MiniKit

Source: https://github.com/worldcoin/minikit-js/blob/main/packages/core/README.md

Executes a transaction using the MiniKit SDK. Raw calldata in the data field takes priority over abi, functionName, and args.

```ts
await MiniKit.sendTransaction({
  transaction: [
    {
      address: tokenAddress,
      data: '0xa9059cbb...',
      abi: erc20Abi,
      functionName: 'transfer',
      args: [to, amount],
    },
  ],
});
```

--------------------------------

### Send Chat Messages with MiniKit.chat

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Send messages to other World App users using MiniKit.chat. If the `to` address is omitted, the chat composer will open.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';

async function sendChatMessage() {
  const result = await MiniKit.chat({
    message: 'Hey! Check out this cool mini app!',
    to: '0x...', // Recipient wallet address (optional - opens chat composer if omitted)
  });

  console.log('Chat sent:', result.data.status);
}
```

--------------------------------

### Use React Hooks for Transaction Polling and Username Search

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Integrate React hooks for polling transaction receipts and searching usernames. The `useUserOperationReceipt` hook requires a Viem client configured for World Chain. The `UsernameSearch` component handles user input and displays search results.

```typescript
import { useUserOperationReceipt, useTransactionReceipt, UsernameSearch } from '@worldcoin/minikit-react';
import { createPublicClient, http } from 'viem';
import { worldchain } from 'viem/chains';

// Transaction receipt polling hook
function TransactionStatus() {
  const client = createPublicClient({
    chain: worldchain,
    transport: http(),
  });

  const { poll, isLoading, reset } = useUserOperationReceipt({ client });

  async function handleTransaction(userOpHash: string) {
    try {
      const { transactionHash, receipt } = await poll(userOpHash);
      console.log('Confirmed:', transactionHash);
      console.log('Status:', receipt.status);
    } catch (error) {
      console.error('Failed:', error);
    }
  }

  return <div>{isLoading ? 'Waiting for confirmation...' : 'Ready'}</div>;
}

// Username search component
function ContactSearch() {
  const [value, setValue] = useState('');
  const [results, setResults] = useState(null);

  return (
    <div>
      <UsernameSearch
        value={value}
        handleChange={(e) => setValue(e.target.value)}
        setSearchedUsernames={setResults}
        className="border rounded p-2"
      />
      {results?.data?.map((user) => (
        <div key={user.address}>
          {user.username} - {user.address}
        </div>
      ))}
    </div>
  );
}
```

--------------------------------

### Access World App Contacts with MiniKit

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Open the contact picker to allow users to select contacts from World App for payments or messaging. A fallback function can be provided for web environments where World App is not available.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';

async function selectContacts() {
  try {
    const result = await MiniKit.shareContacts({
      isMultiSelectEnabled: true, // Allow selecting multiple contacts
      inviteMessage: 'Join me on My App!', // Optional invite message for non-users
      fallback: () => {
        // Show manual address input on web
        return showManualAddressInput();
      },
    });

    console.log('Selected contacts:', result.data.contacts);
    // [{ username: 'alice', walletAddress: '0x...', profilePictureUrl: '...' }, ...]

    for (const contact of result.data.contacts) {
      console.log(`${contact.username}: ${contact.walletAddress}`);
    }
  } catch (error) {
    console.error('Contact selection failed:', error);
  }
}
```

--------------------------------

### Define transaction types

Source: https://github.com/worldcoin/minikit-js/blob/main/packages/core/README.md

TypeScript interfaces for defining transaction structures and options within MiniKit.

```ts
type Transaction = {
  address: string;
  value?: string;
  data?: string;
  abi?: Abi | readonly unknown[];
  functionName?: ContractFunctionName<...>;
  args?: ContractFunctionArgs<...>;
};

interface MiniKitSendTransactionOptions<TCustomFallback = SendTransactionResult> {
  transaction: Transaction[];
  chainId?: number; // defaults to 480 on World App
  permit2?: Permit2[];
  formatPayload?: boolean;
}
```

--------------------------------

### MiniKit.chat - Send Chat Messages

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Send messages to other World App users via World Chat.

```APIDOC
## POST MiniKit.chat

### Description
Send messages to other World App users via World Chat.

### Method
POST

### Endpoint
/chat

### Parameters
#### Request Body
- **message** (string) - Required - The message content to send.
- **to** (string) - Optional - The recipient's wallet address. If omitted, the chat composer will be opened.

### Request Example
```json
{
  "message": "Hey! Check out this cool mini app!",
  "to": "0x..."
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the chat message sending operation.
```

--------------------------------

### Handle userOpHash Receipts

Source: https://github.com/worldcoin/minikit-js/blob/main/skills/web-to-miniapp/SKILL.md

Implement a `try-catch` block for `waitForTransactionReceipt` with a longer timeout to handle potential delays in `userOpHash` settlement. This prevents timeouts and allows for state refreshes.

```typescript
try {
  await publicClient.waitForTransactionReceipt({
    hash,
    timeout: 60_000,
    pollingInterval: 2_000,
  });
} catch {
  // userOp not yet settled — refresh state anyway
}
```

--------------------------------

### Add Eruda for Webview Debugging

Source: https://github.com/worldcoin/minikit-js/blob/main/skills/web-to-miniapp/SKILL.md

Include this script in your layout to enable the eruda mobile console for debugging within the World App webview.

```html
<!-- In layout.tsx body -->
<script src="https://cdn.jsdelivr.net/npm/eruda"></script>
<script>
  eruda.init();
</script>
```

--------------------------------

### Type Check All Packages

Source: https://github.com/worldcoin/minikit-js/blob/main/CLAUDE.md

Performs a type check across all packages in the monorepo to ensure TypeScript type safety.

```bash
pnpm type-check
```

--------------------------------

### MiniKit.signTypedData

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Requests the user to sign structured typed data following the EIP-712 standard.

```APIDOC
## MiniKit.signTypedData

### Description
Request the user to sign structured typed data following EIP-712 standard.

### Parameters
#### Request Body
- **domain** (object) - Required - EIP-712 domain object.
- **types** (object) - Required - EIP-712 types definition.
- **primaryType** (string) - Required - The primary type to sign.
- **message** (object) - Required - The data object to sign.
- **chainId** (number) - Optional - Defaults to 480.

### Response
- **data** (object) - Contains 'signature'.
```

--------------------------------

### Sign EIP-712 Typed Data with MiniKit

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Request the user to sign structured data following the EIP-712 standard. This is useful for signing complex data structures like orders or proposals. The chainId is optional and defaults to World Chain (480).

```typescript
import { MiniKit } from '@worldcoin/minikit-js';

async function signTypedData() {
  const result = await MiniKit.signTypedData({
    domain: {
      name: 'My App',
      version: '1',
      chainId: 480,
      verifyingContract: '0x...',
    },
    types: {
      Order: [
        { name: 'buyer', type: 'address' },
        { name: 'amount', type: 'uint256' },
        { name: 'nonce', type: 'uint256' },
      ],
    },
    primaryType: 'Order',
    message: {
      buyer: '0x...',
      amount: '1000000000000000000',
      nonce: '1',
    },
    chainId: 480, // Optional, defaults to 480 (World Chain)
  });

  console.log('Typed signature:', result.data.signature);
}
```

--------------------------------

### Send Token Payments

Source: https://context7.com/worldcoin/minikit-js/llms.txt

Execute token payments to other World App users. Handle specific error codes like user cancellation or insufficient balance.

```typescript
import { MiniKit } from '@worldcoin/minikit-js';
import { Tokens, tokenToDecimals } from '@worldcoin/minikit-js/commands';

async function sendPayment() {
  // Get recipient address from username
  const recipient = await MiniKit.getUserByUsername('alice');

  try {
    const result = await MiniKit.pay({
      reference: crypto.randomUUID(), // Unique payment ID (max 36 chars)
      to: recipient.walletAddress,
      tokens: [
        {
          symbol: Tokens.WLD,
          token_amount: tokenToDecimals(1.5, Tokens.WLD).toString(), // 1.5 WLD
        },
        {
          symbol: Tokens.USDC,
          token_amount: tokenToDecimals(10, Tokens.USDC).toString(), // $10 USDC (min $0.10)
        },
      ],
      description: 'Payment for coffee',
      // Optional: provide fallback for web
      fallback: () => {
        // Show Stripe checkout or other payment method
        return showAlternativePayment();
      },
    });

    console.log('Payment submitted:', result.data.transactionId);
    console.log('Reference:', result.data.reference);
    console.log('From:', result.data.from);
    console.log('Timestamp:', result.data.timestamp);

    // Verify payment on-chain using the reference ID
  } catch (error) {
    if (error.code === 'user_rejected') {
      console.log('User cancelled payment');
    } else if (error.code === 'insufficient_balance') {
      console.log('Insufficient balance');
    }
  }
}

// Available tokens: Tokens.WLD, Tokens.USDC, Tokens.EURC, Tokens.WMXN, Tokens.WBRL, etc.
```
Tokens:
Raw