World ID

Intro to IDKit

This guide assumes you have already completed the steps to set up the Developer Portal.

IDKit is required in your app's frontend for Anonymous Actions, both for Cloud and On-Chain use cases.

Creating actions

Create an action for your app in the Developer Portal. You must provide the following values:

  • Action Name: The stringified action to be taken by the user.
  • Description: This is shown to your user in the World app as they sign with their World ID. Make sure to fully describe the exact action the user is taking.
  • Max Verifications: For Cloud actions only. The number of times a user can take this action. A value of 0 indicates that unlimited verifications can take place.

An action scopes uniqueness for users, which means users will always generate the same ID (nullifier hash) when performing the same action. Cloud actions natively handle sybil-resistance with a limit set in the Developer Portal. For on-chain use cases, you can track this nullifier hash in your smart contract to implement sybil-resistance.

Dynamic Actions

To accommodate dynamic content, actions can also be created at the time a user completes a World ID verification. Simply pass the desired action and action_description values in IDKit's parameters. A new action will automatically be created and tracked, and will appear the next time you log into the Developer Portal.

Installing IDKit

The JS package can be included in your project either as a module (which supports tree shaking to reduce bundle size) or you can add the script directly to your website.

Install IDKit

npm install @worldcoin/idkit


Import and render IDKit. You'll want to do this on the screen where the user executes the protected action (e.g. before they click "Claim airdrop" or "Vote on proposal").

import { IDKitWidget } from '@worldcoin/idkit'
	app_id="app_GBkZ1KlVUdFTjeMXKlVUdFT" // obtained from the Developer Portal
	action="vote_1" // this is your action name from the Developer Portal
	onSuccess={onSuccess} // callback when the modal is closed
	handleVerify={handleVerify} // optional callback when the proof is received
	credential_types={['orb', 'phone']} // optional, defaults to ['orb']
	enableTelemetry // optional, defaults to false
	{({ open }) => <button onClick={open}>Verify with World ID</button>}

More configuration options can be found in the IDKit reference.

When a user clicks the button, the IDKit modal will open and prompt them to scan a QR code and verify with World ID. Once this proof is received, the optional handleVerify callback is called immediately and the onSuccess callback will be called when the modal is closed. One of these callbacks should begin the process of verifying the proof.

IDKit with Dynamic Actions

As an example, using IDKit with Dynamic Actions may look like this:

const getUserChoice = userId => {
	const choice = userChoices['userId']
	return choice

return (
        {/* ... */}
        {/* ... */}


Upon successful completion of the World ID flow, you will receive a response object. This response object of type ISuccessResult has the following attributes. Normally, you will forward these parameters to your backend or smart contract for verification.


	"merkle_root": "0x1f38b57f3bdf96f05ea62fa68814871bf0ca8ce4dbe073d8497d5a6b0a53e5e0",
	"nullifier_hash": "0x0339861e70a9bdb6b01a88c7534a3332db915d3d06511b79a5724221a6958fbe",
	"proof": "0x063942fd7ea1616f17787d2e3374c1826ebcd2d41d2394...",
	"credential_type": "orb"
  • Name

    This is the hash pointer to the root of the Merkle tree that proves membership of the user's identity in the list of identities verified by the Orb. ABI encoded.

  • Name

    The unique identifier for this combination of user, app, and action. ABI encoded.

  • Name

    The Zero-knowledge proof of the verification. ABI encoded.

  • Name
    "orb" | "phone"

    Either orb or phone. Will always return the strongest credential with which a user has been verified.

Verify the Proof

You must verify the proof returned from IDKit with the API or smart contract before allowing a user to perform an action. The process varies depending on your use case. Proceed to the Cloud Verification or On-Chain Verification sections to learn how to verify proofs.