World ID

https://github.com/worldcoin/world-id-docs
Admin
World ID is a privacy-first decentralized identity protocol that provides global proof of personhood...
Tokens:193,339
Snippets:1,579
Trust Score:9.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Usage: Install and run the template

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/world-id/sign-in/getting-started.mdx

Run this command after setting NEXTAUTH_URL, WLD_CLIENT_ID, and WLD_CLIENT_SECRET in the .env file. It installs dependencies and starts the development server.

```bash
pnpm i && pnpm dev
```

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

### Install Foundry

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

Downloads and installs the Foundry CLI toolkit using the official installer script.

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

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

### Install MiniKit-JS and MiniKit-React packages

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/mini-apps/quick-start/installing.mdx

Install the MiniKit-JS core library and the MiniKit-React hooks library. These are the two packages needed for manual installation.

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

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

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

### Install IDKit with yarn

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/world-id/id/web-react.mdx

Install the @worldcoin/idkit package using yarn.

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

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

### Install UI Kit with NPM

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/mini-apps/design/ui-kit.mdx

Install the @worldcoin/mini-apps-ui-kit-react package using NPM. This is the first step to using the UI Kit components.

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

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

### Install IDKit with npm

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/world-id/id/web-react.mdx

Install the @worldcoin/idkit package using npm.

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

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

### Install viem and @inquirer/prompts

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

Installs the required dependencies: viem for blockchain interactions and @inquirer/prompts for interactive CLI prompts.

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

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

### Install IDKit with pnpm

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/world-id/id/web-react.mdx

Install the @worldcoin/idkit package using pnpm.

```bash
pnpm i @worldcoin/idkit
```

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

### Quick Action Universal Link Example

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/mini-apps/sharing/quick-actions.mdx

Example Universal Link Schema with a custom path for a Quick Action, linking to a specific feature in another mini app.

```text
https://world.org/mini-app?app_id=app_8e407cfbae7ae51c19b07faff837aeeb&path=%2Fswap
```

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

### Install @worldcoin/idkit-standalone

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/world-id/id/web-vanilla.mdx

Install the @worldcoin/idkit-standalone package using npm, pnpm, or yarn. Choose the command that matches your package manager.

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

```bash
pnpm i @worldcoin/idkit-standalone
```

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

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

### Install @worldcoin/minikit-react package

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Command to install the @worldcoin/minikit-react package, which provides hooks for checking transaction status.

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

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

### VUNI Quick Action Example URLs

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/mini-apps/sharing/vuni-qa.mdx

Example URLs for the VUNI Quick Action. Each URL uses the app_id app_10ca32093aa9ad0e52bc812d63daf818 and a URL-encoded path parameter to access different routes and tabs. The last example shows a localized route with the /en/ prefix.

```text
# Access pools with trades tab
https://worldcoin.org/mini-app?app_id=app_10ca32093aa9ad0e52bc812d63daf818&path=%2Fpool%3Ftab%3Dtrades

# View investor info with referrals tab
https://worldcoin.org/mini-app?app_id=app_10ca32093aa9ad0e52bc812d63daf818&path=%2Finvestor%2F0x6917A2418aBDc514E1745207200bFbA75E1dfd6E%3Ftab%3Dreferrals

# Access with referral code
https://worldcoin.org/mini-app?app_id=app_10ca32093aa9ad0e52bc812d63daf818&path=%3Fref%3DGD9WWI

# Access pools with stats tab (localized)
https://worldcoin.org/mini-app?app_id=app_10ca32093aa9ad0e52bc812d63daf818&path=%2Fen%2Fpool%3Ftab%3Dstats
```

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

### Install dependencies with pnpm

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

Install project dependencies using pnpm.

```bash
pnpm install
```

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

### Install MiniKit and trigger commands in the same useEffect

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/mini-apps/more/faq.mdx

Place any commands that should run on initialization inside the same useEffect hook that calls MiniKit.install() to avoid race conditions where MiniKit hasn't finished installing on the Window object.

```tsx
'use client'

import { useEffect, ReactNode } from 'react'
import { MiniKit } from '@worldcoin/minikit-js'

export const MiniKitProvider = ({ children }: { children: ReactNode }) => {
	useEffect(() => {
		MiniKit.install()

		// Add any commands you wish to trigger on start here to prevent race conditions
		MiniKit.commands.walletAuth({
			// ...
		})
	}, [])

	return <>{children}</>
}
```

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

### Install IDKit with npm, yarn, or pnpm

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Install the @worldcoin/idkit package using your preferred package manager. Choose one command based on your environment.

```bash
npm install @worldcoin/idkit
```

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

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

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

### Install MiniKit-React with npm

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Install the MiniKit-React package, which provides hooks for easier interaction with the MiniKit SDK.

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

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

### Start World Chain node

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

Starts the World Chain node in the background, building images if necessary.

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

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

### Install MiniKit-JS with npm

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Install the core MiniKit-JS library using npm. This is the framework-agnostic package for building mini apps.

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

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

### Example output links

Source: https://github.com/worldcoin/world-id-docs/blob/main/src/pages/mini-apps/sharing/world-chat-qa.mdx

Example output links produced by the helper function for message, payment with amount, and request with amount. They show the encoded path format.

```text
// Message draft
https://worldcoin.org/mini-app?app_id=app_e293fcd0565f45ca296aa317212d8741&path=%2Fjohndoe%2Fdraft%3Fmessage%3DHello

// Payment draft with amount
https://worldcoin.org/mini-app?app_id=app_e293fcd0565f45ca296aa317212d8741&path=%2Fjohndoe%2Fdraft%3Fpay%3D5.25

// Request draft with amount
https://worldcoin.org/mini-app?app_id=app_e293fcd0565f45ca296aa317212d8741&path=%2Fjohndoe%2Fdraft%3Frequest%3D10
```

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

### Create MiniKit Provider component

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Create a MiniKitProvider component that installs the SDK. The 'use client' directive is required for Next.js. Passing appId is optional but allows access via window.MiniKit.appId.

```tsx
'use client' // Required for Next.js

import { ReactNode, useEffect } from 'react'
import { MiniKit } from '@worldcoin/minikit-js'

export default function MiniKitProvider({ children }: { children: ReactNode }) {
	useEffect(() => {
		// Passing appId in the install is optional 
		// but allows you to access it later via `window.MiniKit.appId`
		MiniKit.install(appId?) 
	}, [])

	return <>{children}</>
}
```

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

### Sign Message command example with MiniKit

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Example of sending a Sign Message command using MiniKit and verifying the signature with Safe. Includes imports, payload creation, and signature verification.

```TypeScript
import { MiniKit, SignMessageInput } from '@worldcoin/minikit-js'

    const signAndVerifyMessage = async () => {
      const signMessagePayload: SignMessageInput = {
        message: "Hello world",
      };

      const {finalPayload} = await MiniKit.commandsAsync.signMessage(signMessagePayload);

      if (finalPayload.status === "success") {
        const messageHash = hashSafeMessage(messageToSign);

        const isValid = await (
          await Safe.init({
            provider:
              "https://worldchain-mainnet.g.alchemy.com/v2/your-api-key",
            safeAddress: finalPayload.address,
          })
        ).isValidSignature(messageHash, finalPayload.signature);

        // Checks functionally if the signature is correct
        if (isValid) {
          console.log("Signature is valid");
        }
      }
    };
```

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

### Listening for the verify response (event listeners)

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Example of subscribing to the MiniAppVerifyAction response event, handling success and error cases, and sending the proof to the backend for verification.

```tsx
import { MiniKit, ResponseEvent, ISuccessResult, MiniAppVerifyActionPayload } from '@worldcoin/minikit-js'

// ...
useEffect(() => {
	if (!MiniKit.isInstalled()) {
		return
	}

	MiniKit.subscribe(ResponseEvent.MiniAppVerifyAction, async (response: MiniAppVerifyActionPayload) => {
		if (response.status === 'error') {
			return console.log('Error payload', response)
		}

		// Verify the proof in the backend
		const verifyResponse = await fetch('/api/verify', {
			method: 'POST',
			headers: {
				'Content-Type': 'application/json',
			},
			body: JSON.stringify({
				payload: response as ISuccessResult, // Parses only the fields we need to verify
				action: 'voting-action',
				signal: '0x12312', // Optional
			}),
		})

		// TODO: Handle Success!
		const verifyResponseJson = await verifyResponse.json()
		if (verifyResponseJson.status === 200) {
			console.log('Verification success!')
		}
	})

	return () => {
		MiniKit.unsubscribe(ResponseEvent.MiniAppVerifyAction)
	}
}, [])
```

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

### JavaScript fetch request to POST /api/v1/signup

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Use this fetch call to sign up a new user from JavaScript. It sends the same JSON payload as the cURL example. The response handling is not shown here.

```js
fetch('/api/v1/signup', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
	},
	body: JSON.stringify({
		email: 'bob@worldidbot.com',
		password: '987654321',
		name: 'Bob',
		team_name: 'The Bob Project',
	}),
})
```

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

### Sending verify command (event listeners)

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Example of sending the verify command using MiniKit.commands.verify within an event listener context. Includes the same payload structure as the async handler.

```tsx
import { MiniKit, VerifyCommandInput, VerificationLevel } from '@worldcoin/minikit-js'

const verifyPayload: VerifyCommandInput = {
	action: 'voting-action', // This is your action ID from the Developer Portal
	signal: '0x12312', // Optional additional data
	verification_level: VerificationLevel.Orb, // Orb | Device
}

const payload = MiniKit.commands.verify(verifyPayload)
```

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

### Fork World Chain Sepolia with anvil

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Starts a local fork of World Chain Sepolia using anvil. Substitute RPC_URL with the RPC URL of the World Chain Sepolia network.

```bash
# Substitute the RPC_URL with the RPC URL of the World Chain Sepolia network
anvil -f $RPC_URL
```

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

### Send Notification - JavaScript fetch Request

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Use this JavaScript fetch example to send a notification. It uses the same endpoint and requires an api_key in the Authorization header. The body includes app_id, wallet_addresses, title, message, and mini_app_path.

```js
fetch(apiUrl, {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer {api_key}',
    },
    body: JSON.stringify({
        app_id: "app_id",
        wallet_addresses: ["0x123", "0x456"],
        title: "title",
        message: "message",
        mini_app_path: "mini_app_path"
    })
})
```

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

### Handle shareContacts response with event listener

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Use this snippet to subscribe to the MiniAppShareContacts response event. It checks if MiniKit is installed, subscribes to ResponseEvent.MiniAppShareContacts, and handles the success response. Unsubscribes on cleanup.

```tsx
import { MiniKit, tokenToDecimals, Tokens, PayCommandInput, ResponseEvent } from '@worldcoin/minikit-js'
    // ...
    useEffect(() => {
        if (!MiniKit.isInstalled()) {
            console.error("MiniKit is not installed");
            return;
        }

        MiniKit.subscribe(
            ResponseEvent.MiniAppShareContacts,
            async (response: MiniAppShareContactsPayload) => {
                if (response.status == "success") {
                    const contacts = await res.json();
                    // Handle the response
                }
            }
        );

        return () => {
            MiniKit.unsubscribe(ResponseEvent.MiniAppShareContacts);
        };
    }, []);
```

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

### Authorization Callback - Authorization Code and ID Token

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Example callback URLs for the authorization code flow and implicit flow. The authorization code is returned as a query parameter, while the ID token is returned as a URL fragment.

```http
https://example.app/api/auth/callback/worldcoin?code=e777d780f437330bbd795b35
```

```http
https://example.app/api/auth/callback/worldcoin#id_token=eyJhbGciOiJSUzI1NiIsInR5cCI6I...
```

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

### Send transaction with permit2 signature using MiniKit

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Example of sending a transaction with a permit2 signature using MiniKit's sendTransaction command. It shows how to construct the permit transfer and transfer details, and includes a placeholder for the permit2 signature. The transaction uses the DEX ABI and specifies the spender address.

```tsx
// Make sure this is only the function you're calling 
    // Otherwise you will get an error
    import DEXABI from '../../abi/DEX.json'
    import { MiniKit } from '@worldcoin/minikit-js'

    // ...
    const sendTransaction = async () => {
      if (!MiniKit.isInstalled()) {
        return;
      }

      const deadline = Math.floor((Date.now() + 30 * 60 * 1000) / 1000).toString()

      // Transfers can also be at most 1 hour in the future.
      const permitTransfer = {
        permitted: {
          token: testTokens.worldchain.USDC,
          amount: '10000',
        },
        nonce: Date.now().toString(),
        deadline,
      }

      const permitTransferArgsForm = [
        [permitTransfer.permitted.token, permitTransfer.permitted.amount],
        permitTransfer.nonce,
        permitTransfer.deadline,
      ]

      const transferDetails = {
        to: '0x126f7998Eb44Dd2d097A8AB2eB28dEA1646AC8',
        requestedAmount: '10000',
      }

      const transferDetailsArgsForm = [transferDetails.to, transferDetails.requestedAmount]

      const {commandPayload, finalPayload} = await MiniKit.commandsAsync.sendTransaction({
        transaction: [
          {
            address: '0x34afd47fbdcc37344d1eb6a2ed53b253d4392a2f',
            abi: DEXABI,
            functionName: 'signatureTransfer',
            args: [permitTransferArgsForm, transferDetailsArgsForm, 'PERMIT2_SIGNATURE_PLACEHOLDER_0'],
          },
        ],
        permit2: [
          {
            ...permitTransfer,
            spender: '0x34afd47fbdcc37344d1eb6a2ed53b253d4392a2f',
          },
        ],
      })
    }
```

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

### Render IDKit widget with app_id, action, and callbacks

Source: https://github.com/worldcoin/world-id-docs/blob/main/public/llms-full.txt

Use this snippet to render the IDKit widget on the screen where the user performs a protected action. The `app_id` and `action` come from the Developer Portal. The `onSuccess` callback fires when the modal closes, and `handleVerify` is called immediately after proof receipt; one of these should start backend verification.

```tsx
import { IDKitWidget, VerificationLevel } from '@worldcoin/idkit'

<IDKitWidget
	app_id="app_GBkZ1KlVUdFTjeMXKlVUdFT" // obtained from the Developer Portal
	action="vote_1" // this is your action id from the Developer Portal
	onSuccess={onSuccess} // callback when the modal is closed
	handleVerify={handleVerify} // optional callback when the proof is received
	verification_level={VerificationLevel.Device}
>
	{({ open }) => <button onClick={open}>Verify with World ID</button>}
</IDKitWidget>
```
Tokens:
Raw