### Install and Run Documentation Server

Source: https://github.com/worldcoin/developer-docs/blob/main/README.md

Run these commands at the root of the documentation to install dependencies and start the development server.

```bash
pnpm i
pnpm dev
```

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

### Manual Setup for AgentKit Shopify Demo

Source: https://github.com/worldcoin/developer-docs/blob/main/agents/hats/index.mdx

This manual setup involves installing a utility, cloning the demo repository, generating an agent key, registering with AgentBook for World ID verification, and then fetching a unique discount code for the hat.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/worldcoin/agentkit-shopify-demo.git
cd agentkit-shopify-demo

# Generate an agent key
uv run --with eth-account python3 -c \
  "from eth_account import Account; a = Account.create(); print(a.key.hex())" > .agent-key

# Register in AgentBook (opens QR for World ID verification)
npx --registry https://registry.npmjs.org @worldcoin/agentkit-cli register <your-wallet-address>

# Get the discount code
PRIVATE_KEY=$(cat .agent-key) ./skills/shopify-agent-discount/get-coupon.py \
  https://humanrequired.shop/products/human-in-the-loop-hat
```

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

### Install Go Module

Source: https://github.com/worldcoin/developer-docs/blob/main/world-id/idkit/go.mdx

Install the IDKit Go module using the go get command.

```APIDOC
## Install Go Module

```bash
go get github.com/worldcoin/idkit/go/idkit@latest
```
```

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

### Install Go IDKit Module

Source: https://github.com/worldcoin/developer-docs/blob/main/world-id/idkit/go.mdx

Use 'go get' to install the latest version of the IDKit Go module.

```bash
go get github.com/worldcoin/idkit/go/idkit@latest
```

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

### Example Get Permissions Response

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/get-permissions.mdx

An example of a successful response from the getPermissions command, showing the status and permission settings.

```json
{
  "executedWith": "minikit",
  "data": {
    "status": "success",
    "version": 1,
    "permissions": {
      "notifications": true,
      "contacts": false,
      "microphone": true
    },
    "timestamp": "2026-03-28T18:24:00.000Z"
  }
}
```

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

### Install Dependencies

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/migration/standalone-dapp.mdx

Install the necessary libraries for Wagmi integration and SIWE.

```bash
pnpm add wagmi @tanstack/react-query siwe
```

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

### Install Foundry

Source: https://github.com/worldcoin/developer-docs/blob/main/world-chain/developers/deploy.mdx

Installs the Foundry CLI toolkit. This command downloads and installs the Foundry binaries.

```bash
curl -L https://foundry.paradigm.xyz | bash
```

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

### Install @worldcoin/idkit-core

Source: https://github.com/worldcoin/developer-docs/blob/main/world-id/idkit/javascript.mdx

Install the IDKit core SDK using npm, pnpm, or yarn.

```bash
npm i @worldcoin/idkit-core
```

```bash
pnpm add @worldcoin/idkit-core
```

```bash
yarn add @worldcoin/idkit-core
```

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

### Install Project Dependencies

Source: https://github.com/worldcoin/developer-docs/blob/main/world-chain/tokens/usdc.mdx

Installs the necessary libraries, viem and @inquirer/prompts, for blockchain interaction and CLI prompts.

```bash
npm install viem @inquirer/prompts
```

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

### Install Project Dependencies

Source: https://github.com/worldcoin/developer-docs/blob/main/world-chain/developers/template.mdx

Install the necessary project dependencies using pnpm. Ensure you have pnpm, npm, yarn, or bun installed.

```bash
pnpm install
```

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

### Install and Register AgentKit

Source: https://context7.com/worldcoin/developer-docs/llms.txt

Install the AgentKit package and register an agent wallet address in the World Chain AgentBook using the CLI.

```bash
# Install
npm install @worldcoin/agentkit

# Register agent wallet address in the World Chain AgentBook
npx @worldcoin/agentkit-cli register <agent-wallet-address>

# Add the AgentKit skill to your coding assistant
npx skills add worldcoin/agentkit agentkit-x402
```

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

### Install Human-in-the-Loop Dependencies

Source: https://context7.com/worldcoin/developer-docs/llms.txt

Install the necessary packages for implementing a World ID approval gate for AI agents. This setup allows pausing AI workflows and requiring a verified World ID proof.

```bash
# Server
npm install @worldcoin/human-in-the-loop ai workflow

```

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

### Install AgentKit

Source: https://github.com/worldcoin/developer-docs/blob/main/agents/agent-kit/integrate.mdx

Install the AgentKit package using npm.

```bash
npm install @worldcoin/agentkit
```

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

### Mini Apps (MiniKit-JS) - Install and initialize

Source: https://context7.com/worldcoin/developer-docs/llms.txt

Instructions for installing and initializing the MiniKit-JS SDK, which enables the development of mini applications that run within the World App.

```APIDOC
## MiniKit-JS SDK

### Installation

To scaffold a new Next.js 15 mini app:
```bash
npx @worldcoin/create-mini-app@latest my-mini-app
```

To install manually:
```bash
pnpm install @worldcoin/minikit-js
```

### Initialization

Wrap your application with `MiniKitProvider` to enable MiniKit functionality.

```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>;
}

// src/app/layout.tsx
import Providers from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

### Checking World App Environment

Use `MiniKit.isInstalled()` to determine if the application is running within the World App.

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

if (MiniKit.isInstalled()) {
  console.log("Running inside World App");
}
```
```

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

### Install Sage Support Package

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/sharing/sage-qa.mdx

Install the Sage Support npm package to begin integration. This is the first step before using the SageSupport component.

```bash
npm install sage-support
```

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

### Download and Initialize simple-worldchain-node

Source: https://github.com/worldcoin/developer-docs/blob/main/world-chain/reference/node-setup.mdx

Clone the repository, navigate into the directory, and copy the example environment file to create your configuration.

```bash
git clone https://github.com/worldcoin/simple-worldchain-node.git
cd simple-worldchain-node
cp .env.example .env
```

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

### Install and Initialize MiniKit-JS (Bash & TSX)

Source: https://context7.com/worldcoin/developer-docs/llms.txt

Scaffold a new mini app project or install the MiniKit-JS SDK manually. Wrap your application with `MiniKitProvider` and check if the app is running inside World App.

```bash
# Scaffold a new Next.js 15 mini app\nnpx @worldcoin/create-mini-app@latest my-mini-app\n\n# Or install manually\npnpm install @worldcoin/minikit-js
```

```tsx
// src/app/providers.tsx — wrap your app with MiniKitProvider\n"use client";\nimport { MiniKitProvider } from "@worldcoin/minikit-js/minikit-provider";\n\nexport default function Providers({ children }: { children: React.ReactNode }) {\n  return <MiniKitProvider>{children}</MiniKitProvider>;\n}\n\n// src/app/layout.tsx\nimport Providers from "./providers";\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    <html lang="en">\n      <body>\n        <Providers>{children}</Providers>\n      </body>\n    </html>\n  );\n}\n\n// Check if running inside World App\nimport { MiniKit } from "@worldcoin/minikit-js";\nif (MiniKit.isInstalled()) {\n  console.log("Running inside World App");\n}
```

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

### Install @worldcoin/idkit with npm, pnpm, or yarn

Source: https://github.com/worldcoin/developer-docs/blob/main/world-id/idkit/react.mdx

Install the @worldcoin/idkit package using your preferred package manager.

```bash
npm i @worldcoin/idkit
```

```bash
pnpm add @worldcoin/idkit
```

```bash
yarn add @worldcoin/idkit
```

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

### Install AgentKit Shopify Plugin

Source: https://github.com/worldcoin/developer-docs/blob/main/agents/hats/index.mdx

Use these commands to install the AgentKit Shopify plugin via the Claude plugin marketplace. After installation, you can ask Claude to help purchase the hat.

```bash
/plugin marketplace add worldcoin/agentkit-shopify-demo
/plugin install agentkit-shopify@worldcoin-agentkit
/reload-plugins

# Then ask Claude:
# "Help me purchase this product: https://humanrequired.shop/products/human-in-the-loop-hat"
```

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

### Install MiniKit-JS with pnpm

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/quick-start/installing.mdx

Install the core MiniKit-JS library using pnpm. This is the recommended method for project integration.

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

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

### Example Swap Quick Action Link

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/sharing/swap-qa.mdx

This is an example of a generated deep link URL for the Swap quick action, demonstrating how parameters are encoded within the URL.

```url
https://worldcoin.org/mini-app?app_id=app_6c5c5717c77abe83be8814c032c3a6f9&path=%2F%3FfromToken%3D0x2cFc85d8E48F8EAB294be644d9E25C3030863003
```

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

### Request Examples

Source: https://github.com/worldcoin/developer-docs/blob/main/world-id/reference/authenticator.mdx

Examples of authenticator requests for single credential, multiple credentials, and complex constraints.

```APIDOC
## Request Examples

### Single Credential
```json
{
  "id": "req_18c0f7f03e7d",
  "version": 1,
  "created_at": "1771612953",
  "expires_at": "1771613013",
  "rp_id": "rp_0000000000000000000000000000000000001",
  "action": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "nonce": "0x11d223ce7b91ac212f42cf50f0a3439ae3fcdba4ea32acb7f194d1051ed324c2",
  "signature": "304502205cce35752b1642327bebf9f203960dc83f92fa919a4567981ce0c157060ca04e022100f328e42ff2609ddc1fbc7da17896ded2687acb3a4eeb8847a6f3a87ce50ed016",
  "requests": [
    {
      "identifier": "passport",
      "issuer_schema_id": 9303,
      "signal": "abcd-efgh-ijkl"
    }
  ]
}
```

### Multiple Credentials
```json
{
  "id": "req_18c0f7f03e7d",
  "version": 1,
  "created_at": "1771612953",
  "expires_at": "1771613013",
  "rp_id": "rp_0000000000000000000000000000000000001",
  "action": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "nonce": "0x11d223ce7b91ac212f42cf50f0a3439ae3fcdba4ea32acb7f194d1051ed324c2",
  "signature": "304502205cce35752b1642327bebf9f203960dc83f92fa919a4567981ce0c157060ca04e022100f328e42ff2609ddc1fbc7da17896ded2687acb3a4eeb8847a6f3a87ce50ed016",
  "requests": [
    {
      "identifier": "passport",
      "issuer_schema_id": 9303,
      "signal": "abcd-efgh-ijkl"
    },
    {
      "identifier": "poh",
      "issuer_schema_id": 1,
      "signal": "abcd-efgh-ijkl"
    }
  ],
  "constraints": {
    "all": ["passport", "poh"]
  }
}
```

### More Complex Constraints
```json
{
  "id": "req_18c0f7f03e7d",
  "version": 1,
  "created_at": "1771612953",
  "expires_at": "1771613013",
  "rp_id": "rp_0000000000000000000000000000000000001",
  "action": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "nonce": "0x11d223ce7b91ac212f42cf50f0a3439ae3fcdba4ea32acb7f194d1051ed324c2",
  "signature": "304502205cce35752b1642327bebf9f203960dc83f92fa919a4567981ce0c157060ca04e022100f328e42ff2609ddc1fbc7da17896ded2687acb3a4eeb8847a6f3a87ce50ed016",
  "requests": [
    {
      "identifier": "passport",
      "issuer_schema_id": 9303,
      "signal": "abcd-efgh-ijkl"
    },
    {
      "identifier": "my-number-card",
      "issuer_schema_id": 9310,
      "signal": "mnop-qrst-uvwx"
    },
    {
      "identifier": "orb",
      "issuer_schema_id": 1,
      "signal": "abcd-efgh-ijkl"
    }
  ],
  "constraints": {
    "all": [
      "orb",
      {
        "any": ["passport", "my-number-card"]
      }
    ]
  }
}
```
```

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

### Start World Chain Node

Source: https://github.com/worldcoin/developer-docs/blob/main/world-chain/reference/node-setup.mdx

Run this command from the simple-worldchain-node folder to start your node in the background with automatic rebuilding.

```bash
docker compose up -d --build
```

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

### Install Foundry for World Chain Development

Source: https://context7.com/worldcoin/developer-docs/llms.txt

Install Foundry, a fast and modular toolkit for Ethereum application development, used here for building and deploying to World Chain.

```bash
# Install Foundry
curl -L https://foundry.paradigm.xyz | bash

# Create project and write contract
forge init hello-world-chain && cd hello-world-chain
```

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

### Install Mini Apps UI Kit

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/guidelines/app-guidelines.mdx

Install the Worldcoin Mini Apps UI Kit using NPM. This package provides pre-built React components for consistent app development.

```bash
npm install @worldcoin/mini-apps-ui-kit-react
```

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

### Share Success Example

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/share.mdx

An example JSON payload representing a successful share operation executed via 'minikit'.

```json
{
  "executedWith": "minikit",
  "data": {
    "status": "success",
    "version": 1,
    "shared_files_count": 2,
    "timestamp": "2026-03-28T18:24:00.000Z"
  }
}
```

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

### Install Human-in-the-Loop and Peer Dependencies

Source: https://github.com/worldcoin/developer-docs/blob/main/agents/human-in-the-loop/integrate.mdx

Install the necessary packages for server-side and client-side integration. Ensure you have the correct peer dependencies for React.

```bash
# Server — human-in-the-loop + peer dependencies
npm install @worldcoin/human-in-the-loop ai workflow

# Client — React bindings + peer dependencies
npm install @worldcoin/human-in-the-loop-react @worldcoin/idkit ai react
```

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

### Send Transaction Response Example

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/send-transaction.mdx

An example of a successful transaction response when executed with 'minikit', including the user operation hash and transaction details.

```json
{
  "executedWith": "minikit",
  "data": {
    "userOpHash": "0x8004b63530b968a2a2c9ff414e01fc06a3ec5e4068d36d923df6aa4334744369",
    "status": "success",
    "version": 2,
    "from": "0x1234567890123456789012345678901234567890",
    "timestamp": "2026-03-28T18:24:00.000Z"
  }
}
```

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

### Start Local Web Server for World ID Template App

Source: https://github.com/worldcoin/developer-docs/blob/main/world-chain/developers/template.mdx

Run this command in the root directory of the World ID template app to start the local development server. Ensure your .env file is correctly configured with necessary environment variables.

```bash
pnpm dev
```

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

### Pay Command Example Result

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/pay.mdx

An example JSON object representing a successful payment executed via 'minikit', including transaction details.

```json
{
  "executedWith": "minikit",
  "data": {
    "transactionId": "tx_1234567890abcdef",
    "reference": "order-123",
    "from": "0x1234567890123456789012345678901234567890",
    "chain": "worldchain",
    "timestamp": "2026-03-28T18:24:00.000Z"
  }
}
```

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

### Install IDKit SDK

Source: https://github.com/worldcoin/developer-docs/blob/main/world-id/idkit/integrate.mdx

Install the IDKit core package for JavaScript or the React SDK. Swift and Kotlin packages are also available for mobile integrations.

```bash
npm i @worldcoin/idkit-core
```

```bash
npm i @worldcoin/idkit
```

```swift
.package(url: "https://github.com/worldcoin/idkit-swift.git", from: "<version>")
```

```kotlin
dependencies {
    implementation("com.worldcoin:idkit:<version>")
}
```

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

### Install MiniKit Dependencies

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/migration/web-to-miniapp.mdx

Add the necessary MiniKit JavaScript and React packages to your project.

```bash
pnpm add @worldcoin/minikit-js @worldcoin/minikit-react
```

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

### Create Project Directory and Initialize npm

Source: https://github.com/worldcoin/developer-docs/blob/main/world-chain/tokens/usdc.mdx

Sets up a new project directory and initializes npm for dependency management.

```bash
mkdir usdc-world-transfer
cd usdc-world-transfer
npm init -y
```

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

### Initiate Payment

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/pay.mdx

This example demonstrates how to use the `MiniKit.pay` function to request a payment. It includes generating a nonce, defining payment details, and handling the result.

```APIDOC
## POST /pay

### Description
Initiates a payment request to the user.

### Method
POST

### Endpoint
`/pay` (This is an SDK method, not a direct HTTP endpoint)

### Parameters
#### Request Body
- **reference** (string) - Required - A unique identifier for the payment, often a nonce generated by the backend.
- **to** (string) - Required - The recipient's wallet address.
- **tokens** (array) - Required - An array of token objects to be paid.
  - **symbol** (Tokens) - Required - The symbol of the token (e.g., Tokens.WLD).
  - **token_amount** (string) - Required - The amount of the token, represented as a string in its smallest unit (e.g., using `tokenToDecimals`).
- **description** (string) - Optional - A brief description of the payment.
- **fallback** (function) - Optional - A callback function to execute if the payment cannot be completed via World App.

### Request Example
```typescript
import { MiniKit } from "@worldcoin/minikit-js";
import { Tokens, tokenToDecimals } from "@worldcoin/minikit-js/commands";

async function sendPayment() {
  const response = await fetch("/api/generate-nonce", { method: "POST" });
  const { id } = await response.json();

  const input = {
    reference: id,
    to: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    tokens: [
      {
        symbol: Tokens.WLD,
        token_amount: tokenToDecimals(1, Tokens.WLD).toString(),
      },
    ],
    description: "Example payment",
    fallback: () => {
      alert("Please complete the payment in World App to proceed.");
    },
  };

  const result = await MiniKit.pay(input);
  // ... handle result
}
```

### Response
#### Success Response
- **executedWith** (string) - Indicates how the payment was executed ('minikit' or 'fallback').
- **data** (object) - Contains details of the transaction if executed with 'minikit'.
  - **transactionId** (string) - The unique ID of the transaction.
  - **reference** (string) - The reference ID provided for the payment.
  - **from** (string) - The sender's wallet address.
  - **chain** (string) - The blockchain the transaction occurred on (e.g., 'worldchain').
  - **timestamp** (string) - The ISO 8601 timestamp of the transaction.

#### Response Example
```json
{
  "executedWith": "minikit",
  "data": {
    "transactionId": "tx_1234567890abcdef",
    "reference": "order-123",
    "from": "0x1234567890123456789012345678901234567890",
    "chain": "worldchain",
    "timestamp": "2026-03-28T18:24:00.000Z"
  }
}
```

#### Fallback Response Example
```json
{
  "executedWith": "fallback",
  "data": null
}
```

### Error Codes
- `input_error`: The payment payload is invalid.
- `user_rejected`: The user rejected the request.
- `payment_rejected`: The user cancelled the payment.
- `invalid_receiver`: The recipient address is invalid or not allowed.
- `insufficient_balance`: The user does not have enough balance.
- `transaction_failed`: The payment failed on-chain.
- `generic_error`: Unexpected failure.
- `user_blocked`: Payments are not available in the user's region.
```

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

### Example Success Response

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/request-permission.mdx

An example of a successful response payload when a permission is granted via the minikit.

```json
{
  "executedWith": "minikit",
  "data": {
    "status": "success",
    "version": 1,
    "permission": "notifications",
    "timestamp": "2026-03-28T18:24:00.000Z"
  }
}
```

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

### Create a New Foundry Project

Source: https://github.com/worldcoin/developer-docs/blob/main/world-chain/developers/deploy.mdx

Initializes a new Foundry project in the current directory and navigates into it. This sets up the basic project structure.

```bash
forge init hello-world-chain && cd hello-world-chain
```

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

### World App Object Example

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/quick-start/init.mdx

An example of the raw World App payload. This can be useful for testing or debugging purposes.

```json
{
  "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"
  }
}
```

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

### Manual Agent Kit Integration Example

Source: https://github.com/worldcoin/developer-docs/blob/main/agents/agent-kit/sdk-reference.mdx

Use these low-level helpers directly when not using the x402 Hono wrapper or for full control over request handling. Ensure necessary imports are included.

```typescript
import {
	AGENTKIT,
	createAgentBookVerifier,
	declareAgentkitExtension,
	parseAgentkitHeader,
	validateAgentkitMessage,
	verifyAgentkitSignature,
} from '@worldcoin/agentkit'

const extensions = declareAgentkitExtension({
	domain: 'api.example.com',
	resourceUri: 'https://api.example.com/data',
	network: 'eip155:480',
	statement: 'Verify your agent is backed by a real human',
})

const agentBook = createAgentBookVerifier()

async function handleRequest(request: Request) {
	const header = request.headers.get(AGENTKIT)
	if (!header) return

	const payload = parseAgentkitHeader(header)

	const validation = await validateAgentkitMessage(payload, 'https://api.example.com/data')
	if (!validation.valid) {
		return { error: validation.error }
	}

	const verification = await verifyAgentkitSignature(payload)
	if (!verification.valid || !verification.address) {
		return { error: verification.error }
	}

	// Always resolves against the canonical World Chain AgentBook
	const humanId = await agentBook.lookupHuman(verification.address)
	if (!humanId) {
		return { error: 'Agent is not registered in the AgentBook' }
	}

	return { humanId }
}
```

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

### Manually Initialize MiniKit

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/quick-start/init.mdx

Call `MiniKit.install()` at the start of your app if you are not using React's `MiniKitProvider`. This initializes the SDK and stores device and user context.

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

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

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

### Create Mini App with Template

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/quick-start/installing.mdx

Use this command to create a new mini app project with the official template. It's recommended to use pnpm for package management.

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

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

### Sign Typed Data Success Example

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/sign-typed-data.mdx

An example of a successful response payload when signing typed data using MiniKit.

```json
{
  "executedWith": "minikit",
  "data": {
    "status": "success",
    "version": 1,
    "signature": "0xabcdef1234567890",
    "address": "0x1234567890123456789012345678901234567890"
  }
}
```

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

### MiniKit.walletAuth() Usage

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/wallet-auth.mdx

Demonstrates how to use `MiniKit.walletAuth()` to initiate the SIWE authentication flow. This includes fetching a nonce from your backend, constructing the options object, calling the `walletAuth` command, and handling the result by sending it back to your backend for completion.

```APIDOC
## MiniKit.walletAuth()

### Description
Initiates the Sign-In with Ethereum (SIWE) authentication flow for a user within the World App.

### Method
`MiniKit.walletAuth(options)`

### Parameters
#### Options Object (`MiniKitWalletAuthOptions`)
- **nonce** (string) - Required - An alphanumeric string of at least 8 characters, generated on your backend.
- **statement** (string) - Optional - A human-readable statement included in the SIWE message.
- **expirationTime** (Date) - Optional - The date and time when the SIWE message expires.
- **notBefore** (Date) - Optional - The date and time before which the SIWE message is not valid.
- **requestId** (string) - Optional - An arbitrary ID for correlating the request on your backend.
- **fallback** (() => Promise<T>) - Optional - A custom function to handle authentication outside of the World App environment.

### Request Example
```tsx
import { MiniKit } from "@worldcoin/minikit-js";
import type {
  CommandResultByVia,
  MiniKitWalletAuthOptions,
  WalletAuthResult,
} from "@worldcoin/minikit-js/commands";

export async function signInWithWallet() {
  const response = await fetch("/api/nonce");
  const { nonce } = await response.json();

  const input = {
    nonce,
    statement: "Sign in to Example Mini App",
    expirationTime: new Date(Date.now() + 1000 * 60 * 60),
    // requestId: "optional-tracking-id",
    // notBefore: new Date(),
  } satisfies MiniKitWalletAuthOptions;

  const result: CommandResultByVia<WalletAuthResult> =
    await MiniKit.walletAuth(input);

  if (result.executedWith === "fallback") {
    return;
  }

  await fetch("/api/complete-siwe", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      payload: result.data,
      nonce,
    }),
  });
}
```

### Result (`WalletAuthResponse`)
- **executedWith** ("minikit" | "wagmi" | "fallback") - Indicates how the command was executed.
- **data** - The result of the authentication.
  - If `executedWith` is "minikit" or "wagmi":
    - **address** (string) - The Ethereum address of the authenticated user.
    - **message** (string) - The full SIWE message that was signed.
    - **signature** (string) - The signature of the SIWE message.
  - If `executedWith` is "fallback":
    - **unknown** - Data from the fallback execution.

### Response Example (Success)
```json
{
  "executedWith": "minikit",
  "data": {
    "address": "0x1234567890123456789012345678901234567890",
    "message": "example.com wants you to sign in with your Ethereum account",
    "signature": "0xabcdef1234567890"
  }
}
```

### Backend Verification Example
```ts
import { cookies } from "next/headers";
import { NextRequest, NextResponse } from "next/server";
import type { MiniAppWalletAuthSuccessPayload } from "@worldcoin/minikit-js/commands";
import { verifySiweMessage } from "@worldcoin/minikit-js/siwe";

type RequestBody = {
  payload: MiniAppWalletAuthSuccessPayload;
  nonce: string;
};

export async function POST(req: NextRequest) {
  const { payload, nonce } = (await req.json()) as RequestBody;

  if (nonce !== cookies().get("siwe")?.value) {
    return NextResponse.json(
      { isValid: false, error: "Invalid nonce" },
      { status: 400 },
    );
  }

  try {
    const verification = await verifySiweMessage(
      payload,
      nonce,
    );

    return NextResponse.json({
      isValid: verification.isValid,
      address: verification.siweMessageData.address,
    });
  } catch (error) {
    return NextResponse.json(
      { isValid: false, error: error instanceof Error ? error.message : "Unknown error" },
      { status: 400 },
    );
  }
}
```
```

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

### SIWE Payload Example

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/wallet-auth.mdx

An example JSON object representing a successful SIWE payload returned by `MiniKit.walletAuth()` when executed with 'minikit' or 'wagmi'.

```json
{
  "executedWith": "minikit",
  "data": {
    "address": "0x1234567890123456789012345678901234567890",
    "message": "example.com wants you to sign in with your Ethereum account",
    "signature": "0xabcdef1234567890"
  }
}
```

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

### Configure Server and Client Environment Variables

Source: https://github.com/worldcoin/developer-docs/blob/main/agents/human-in-the-loop/integrate.mdx

Set up environment variables for server-side World ID integration and optional client-side app ID. Obtain these from the World developer portal.

```bash
# Server — used by @worldcoin/human-in-the-loop
WORLD_RP_ID=your_rp_id
WORLD_SIGNING_KEY=your_signing_key

# Client — used by the <HumanApproval> component (optional if passing appId prop)
NEXT_PUBLIC_WORLD_APP_ID=app_...
```

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

### Example World Chat Success Response

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/chat.mdx

An example JSON object representing a successful message share via World Chat.

```json
{
  "executedWith": "minikit",
  "data": {
    "status": "success",
    "version": 1,
    "count": 2,
    "timestamp": "2026-03-28T18:24:00.000Z"
  }
}
```

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

### Attestation Success Example

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/attestation.mdx

An example of a successful attestation response payload, including the execution method, status, version, and the generated token.

```json
{
  "executedWith": "minikit",
  "data": {
    "status": "success",
    "version": 1,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.mock.payload"
  }
}
```

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

### Set up MiniKit and Wagmi Providers

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/migration/standalone-dapp.mdx

Wrap your application with MiniKitProvider and WagmiProvider to enable seamless integration. Ensure the NEXT_PUBLIC_APP_ID environment variable is set.

```tsx
"use client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { MiniKitProvider } from "@worldcoin/minikit-js/minikit-provider";
import { WagmiProvider } from "wagmi";
import { config } from "./config";

const queryClient = new QueryClient();

export default function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <MiniKitProvider
          props={{
            appId: process.env.NEXT_PUBLIC_APP_ID!,
            wagmiConfig: config,
          }}
        >
          {children}
        </MiniKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}
```

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

### Close Mini App JSON Response Example

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/commands/close-miniapp.mdx

An example of a successful response when the mini app is closed using the 'minikit' execution path.

```json
{
  "executedWith": "minikit",
  "data": {
    "status": "success",
    "version": 1
  }
}
```

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

### Tunneling service example

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/more/faq.mdx

Use ngrok or a similar service to expose your local development server publicly. This is necessary for testing your mini app directly on a mobile device within the World App.

```bash
ngrok http http://localhost:3000
```

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

### Configure Wallet Client for World App

Source: https://github.com/worldcoin/developer-docs/blob/main/mini-apps/migration/web-to-miniapp.mdx

Set up a viem wallet client that uses `getWorldAppProvider()` when running inside World App, and falls back to `window.ethereum` for standard browser environments. This ensures proper wallet interaction.

```tsx
import { MiniKit, getWorldAppProvider } from "@worldcoin/minikit-js";
import { createWalletClient, custom } from "viem";
import { worldchain } from "viem/chains";

const provider = MiniKit.isInWorldApp()
  ? getWorldAppProvider()
  : window.ethereum;

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

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

### Deploy a smart contract to World Chain Sepolia with Foundry

Source: https://context7.com/worldcoin/developer-docs/llms.txt

Instructions for setting up Foundry, writing a simple Solidity contract, and deploying it to the World Chain Sepolia testnet.

```APIDOC
## World Chain

### Deploy a smart contract to World Chain Sepolia with Foundry

World Chain is an EVM-equivalent OP Stack L2 (Chain ID 480 mainnet, 4801 testnet, 2s block time). Use Foundry to build, test, and deploy.

```bash
# Install Foundry
curl -L https://foundry.paradigm.xyz | bash

# Create project and write contract
forge init hello-world-chain && cd hello-world-chain
```

```solidity
// src/HelloWorldChain.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

contract HelloWorldChain {
    string private word;

    constructor() {
        word = "Hello World Chain!";
    }

    function setWord(string memory newWord) public {
        word = newWord;
    }

    function getWord() public view returns (string memory) {
        return word;
    }
}
```

```bash
# Test
forge test

# Compile
forge build

# Generate a wallet
cast wallet new

# Fund from testnet faucet: https://www.alchemy.com/faucets/world-chain-sepolia

# Deploy to World Chain Sepolia (Chain ID 4801)
forge create src/HelloWorldChain.sol:HelloWorldChain \
  --rpc-url https://worldchain-sepolia.g.alchemy.com/public \
  --private-key 0xYOUR_PRIVATE_KEY

# Deploy to World Chain Mainnet (Chain ID 480)
forge create src/HelloWorldChain.sol:HelloWorldChain \
  --rpc-url https://worldchain-mainnet.g.alchemy.com/public \
  --private-key 0xYOUR_PRIVATE_KEY \
  --verify \
  --etherscan-api-key YOUR_WORLDSCAN_API_KEY
```
```