World

https://docs.world.org/llms-full.txt
Admin
World is a privacy-preserving protocol and network that allows people to securely prove they are...
Tokens:538,686
Snippets:4,861
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Manual Setup for AgentKit Shopify Demo

Source: https://docs.world.org/llms-full.txt

Manual installation steps: install uv, clone the repository, generate an agent key, register in AgentBook, and get a discount code. Requires Python and eth-account.

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

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

### Suggested Prompt: MiniKit Install Steps

Source: https://docs.world.org/model-context-protocol/world-docs

Example prompt to use with the World Docs MCP to find current MiniKit installation steps.

```text
Use the World Docs MCP to find the current MiniKit install steps and add them to this project.
```

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

### Install

Source: https://docs.world.org/world-id/idkit/go

Install the Go module using go get.

```APIDOC
## Install

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

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

### Install the Go module

Source: https://docs.world.org/world-id/idkit/go

Use `go get` to install the idkit Go module.

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

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

### MiniKit.install()

Source: https://docs.world.org/mini-apps/quick-start/init

Initializes MiniKit at the start of your app. Returns an object with a success boolean indicating whether installation succeeded.

```APIDOC
## MiniKit.install()

### Description
Initializes MiniKit at the start of your app. Returns an object with a success boolean indicating whether installation succeeded.

### Method
install()

### Parameters
None

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

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

### Response
#### Success Response
- **success** (boolean) - Indicates whether installation was successful.

#### Response Example
```tsx
{ success: true }
```
```

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

### Install ProveKit CLI with cargo

Source: https://world.org/blog/engineering/introducing-pbh-priority-blockspace-for-humans

Install the ProveKit CLI using cargo. This is the recommended installation method after following the Quick Start Guide.

```bash
cargo install provekit-cli
```

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

### Install dependencies

Source: https://docs.world.org/mini-apps/migration/standalone-dapp

Install wagmi, @tanstack/react-query, and siwe using pnpm.

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

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

### Install @worldcoin/idkit-core with npm

Source: https://docs.world.org/world-id/idkit/javascript

Install the SDK using npm. Use this package manager if you prefer npm.

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

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

### Manually initialize MiniKit with MiniKit.install()

Source: https://docs.world.org/mini-apps/quick-start/init

Call MiniKit.install() at the start of your app if you are not using React. The function returns an object with a success property indicating whether installation succeeded.

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

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

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

### Install @worldcoin/idkit-core with pnpm

Source: https://docs.world.org/world-id/idkit/javascript

Install the SDK using pnpm. Use this package manager if you prefer pnpm.

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

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

### Install @worldcoin/idkit-core with yarn

Source: https://docs.world.org/world-id/idkit/javascript

Install the SDK using yarn. Use this package manager if you prefer yarn.

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

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

### Install AgentKit

Source: https://docs.world.org/agents/agent-kit/integrate

Install the @worldcoin/agentkit package using npm.

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

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

### Example Swap quick action link

Source: https://docs.world.org/mini-apps/sharing/swap-qa

An example URL generated by the helper function, showing the prefilled parameters for a Swap quick action.

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

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

### Install required dependencies

Source: https://docs.world.org/world-chain/tokens/usdc

Install viem and @inquirer/prompts using npm.

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

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

### Install @worldcoin/idkit with yarn

Source: https://docs.world.org/world-id/idkit/react

Install the package using yarn. Choose this if you use yarn as your package manager.

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

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

### Install MiniKit packages

Source: https://docs.world.org/mini-apps/migration/web-to-miniapp

Installs the required MiniKit packages for the mini app.

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

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

### Install @worldcoin/idkit with npm

Source: https://docs.world.org/world-id/idkit/react

Install the package using npm. Choose this if you use npm as your package manager.

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

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

### React widget quickstart with IDKitRequestWidget

Source: https://docs.world.org/world-id/overview

Add proof of human to your app with one React widget. Imports IDKitRequestWidget from @worldcoin/idkit, gets an rpContext via getRpContext("verify-account"), and renders the widget with handleVerify and onSuccess callbacks.

```tsx
import { IDKitRequestWidget } from "@worldcoin/idkit";
const rpContext = await getRpContext("verify-account");
<IDKitRequestWidget
  app_id="app_123"
  action="verify-account"
  rp_context={rpContext}
  // verify proof + nullifier on your backend
  handleVerify={verifyOnBackend}
  onSuccess={unlockFeature}
/>
```

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

### Manual usage example

Source: https://docs.world.org/llms-full.txt

Example of using low-level helpers from @worldcoin/agentkit to handle requests, parse headers, validate messages, and verify signatures.

```APIDOC
## Manual usage example

### Description
Demonstrates how to use the low-level helpers from @worldcoin/agentkit to handle requests, parse the AgentKit header, validate the message, verify the signature, and look up the human ID.

### Imports
- `AGENTKIT` - constant for the header name
- `createAgentBookVerifier` - creates an AgentBook verifier
- `declareAgentkitExtension` - declares the AgentKit extension
- `parseAgentkitHeader` - parses the AgentKit header
- `validateAgentkitMessage` - validates the AgentKit message
- `verifyAgentkitSignature` - verifies the AgentKit signature

### Usage
```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 }
	}

	const humanId = await agentBook.lookupHuman(verification.address)
	if (!humanId) {
		return { error: 'Agent is not registered in the AgentBook' }
	}

	return { humanId }
}
```

### Parameters
- `domain` (string) - Required - The domain for the extension
- `resourceUri` (string) - Required - The resource URI
- `network` (string) - Required - The network identifier (e.g., 'eip155:480')
- `statement` (string) - Required - The statement to include in the message

### Return Values
- `validation.valid` (boolean) - Whether the message is valid
- `validation.error` (string) - Error message if invalid
- `verification.valid` (boolean) - Whether the signature is valid
- `verification.address` (string) - The address associated with the signature
- `humanId` (string) - The human ID from the AgentBook lookup
```

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

### Manual usage example

Source: https://docs.world.org/agents/agent-kit/sdk-reference

Example of importing and using low-level helpers from the Agent Kit SDK for manual request handling.

```APIDOC
## Manual usage example

### Description
Use the low-level helpers directly when you are not using the x402 Hono wrapper or when you want full control over request handling.

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

const extensions = declareAgentkitExtension({
	domain: 'api.example.com',
	resourceUri: ...
});
```
```

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

### Example: signInWithWallet function using MiniKit.walletAuth()

Source: https://docs.world.org/mini-apps/commands/wallet-auth

This example shows the recommended authentication flow. It fetches a nonce from the backend, constructs the input with a statement and expiration time, calls MiniKit.walletAuth(), and handles the fallback case. The nonce must be alphanumeric and at least 8 characters.

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

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

### Install @worldcoin/idkit with pnpm

Source: https://docs.world.org/world-id/idkit/react

Install the package using pnpm. Choose this if you use pnpm as your package manager.

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

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

### SageSupport Component Installation

Source: https://docs.world.org/mini-apps/sharing/sage-qa

Install the sage-support package using npm.

```APIDOC
## Install sage-support

### Description
Install the Sage Support React component package.

### Command
```bash
npm install sage-support
```
```

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

### Install Mini Apps UI Kit via npm

Source: https://docs.world.org/mini-apps/guidelines/app-guidelines

Install the @worldcoin/mini-apps-ui-kit-react package to use the React-based design system for mini apps.

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

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

### Go SDK example using github.com/worldcoin/idkit/go/idkit

Source: https://docs.world.org/world-id/idkit/signatures

Example of using the idkit.SignRequest function for one-shot signing and idkit.NewSigner for a reusable signer. It uses the RP_SIGNING_KEY environment variable and supports options like WithAction and WithTTL (default 300 seconds).

```go
import "github.com/worldcoin/idkit/go/idkit"

// One-shot signing with options
sig, err := idkit.SignRequest(
  os.Getenv("RP_SIGNING_KEY"),
  idkit.WithAction("my-action"),
  idkit.WithTTL(300), // optional, default 300s
)

// Or create a reusable signer for high-throughput backends
signer, err := idkit.NewSigner(os.Getenv("RP_SIGNING_KEY"))
sig, err = signer.SignRequest(idkit.WithAction("my-action"))

```

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

### Manual usage example

Source: https://docs.world.org/agents/agent-kit/sdk-reference

Example of using low-level helpers to verify an AgentKit header and signature manually.

```APIDOC
## Manual usage example

### Description
Use the low-level helpers directly when you are not using the x402 Hono wrapper or when you want full control over request handling.

### Code
```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 }
	}

	const humanId = await agentBook.lookupHuman(verification.address)
	if (!humanId) {
		return { error: 'Agent is not registered in the AgentBook' }
	}

	return { humanId }
}
```
```

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

### Install server and client packages

Source: https://docs.world.org/agents/human-in-the-loop/integrate

Install the required npm packages for the server and client. The server requires @worldcoin/human-in-the-loop, ai@^6, workflow, @workflow/ai, and zod. The client requires @worldcoin/human-in-the-loop-react, @worldcoin/idkit, ai@^6, and react.

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

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

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

### Install AgentKit Shopify Plugin via Claude Code

Source: https://docs.world.org/llms-full.txt

Use these Claude Code commands to install the AgentKit Shopify demo plugin. After installation, ask Claude to help purchase the product at https://humanrequired.shop/products/human-in-the-loop-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 dependencies with pnpm

Source: https://docs.world.org/world-chain/developers/template

Installs the dependencies for the World ID template app using pnpm.

```bash
pnpm install
```

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

### Example Response

Source: https://docs.world.org/mini-apps/commands/close-miniapp

Example JSON response showing a successful close with executedWith 'minikit' and status 'success'.

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

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

### Install MiniKit-JS with pnpm

Source: https://docs.world.org/mini-apps/quick-start/installing

Install the core MiniKit-JS library using pnpm. It is framework agnostic.

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

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

### Request config example for IDKit

Source: https://docs.world.org/world-id/idkit/javascript

Example TypeScript code showing how to import IDKit and configure a request.

```typescript
import { IDKit } 
```

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

### WalletAuth Response Example

Source: https://docs.world.org/mini-apps/commands/wallet-auth

Example JSON response from the wallet auth command, showing a successful 'minikit' execution with address, message, and signature.

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

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

### Install IDKit and Expo Crypto

Source: https://docs.world.org/world-id/idkit/react-native

Run this command to install the required packages for the React Native integration. It uses `npx expo install` to ensure compatible versions.

```bash
npx expo install @worldcoin/idkit expo-crypto
```

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

### SendHapticFeedbackResponse Example

Source: https://docs.world.org/mini-apps/commands/send-haptic-feedback

Example JSON response showing a successful haptic feedback execution via minikit, including version and timestamp.

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

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

### Start local web server with pnpm dev

Source: https://docs.world.org/world-chain/developers/template

Run this command in the root directory of the World ID template app to start the local web server. The Contract ABI is automatically re-generated and saved to src/abi/ContractAbi.json on each run.

```bash
pnpm dev
```

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

### Success (OK) response example

Source: https://docs.world.org/llms-full.txt

Example of a successful response with a proof and nullifier for the identifier 'orb'.

```json
{
    "id": "req_18c0f7f03e7d",
    "version": 1,
    "responses": [
        {
            "identifier": "orb",
            "issuer_schema_id": 1,
            "proof": "0x0000000000000000000000000000000000000000000000000000000000000000000000000",
            "nullifier": "nil_00000000000000000000000000000000000000000000000001"
        }
    ]
}
```

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

### Success with Session (OK) response example

Source: https://docs.world.org/llms-full.txt

Example of a successful response with a session nullifier instead of a regular nullifier.

```json
{
    "id": "req_18c0f7f03e7d",
    "version": 1,
    "responses": [
        {
            "identifier": "orb",
            "issuer_schema_id": 1,
            "proof": "0x0000000000000000000000000000000000000000000000000000000000000000000000000",
            "session_nullifier": "00000000000000000000000000000000000000000000000001"
        }
    ]
}
```

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

### Install sage-support npm package

Source: https://docs.world.org/mini-apps/sharing/sage-qa

Install the Sage Support npm package in your React application.

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

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

### Example output of cast wallet new

Source: https://docs.world.org/world-chain/developers/deploy

Example output from the cast wallet new command, showing a newly created keypair with its address and private key. The private key must be kept secret.

```bash
Successfully created new keypair.
Address:     0xB815A0c4bC23930119324d4359dB65e27A846A2d
Private key: 0xcc1b30a6af68ea9a9917f1dda20c927704c5cdb2bbe0076901a8a0e40bf997c5
```

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

### Any Constraint Priority Example

Source: https://docs.world.org/llms-full.txt

Example of an 'any' constraint with ['poh', 'passport'] showing priority order: PoH is preferred, passport is fallback.

```json
{
  "constraints": { "any": ["poh", "passport"] }
}
```

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

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

Source: https://docs.world.org/world-id/from-idkit-standalone

Install the @worldcoin/idkit-core package using your preferred package manager. These commands are alternatives; choose one based on your project's package manager.

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

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

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

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

### Install Foundry CLI

Source: https://docs.world.org/world-chain/developers/deploy

Run this command in your terminal to install the Foundry CLI toolkit. The Foundry CLI will automatically download the correct Solidity compiler version during the build process.

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

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

### Manual usage example

Source: https://docs.world.org/agents/agent-kit/sdk-reference

Example of using low-level helpers from @worldcoin/agentkit to handle requests manually, including parsing headers, validating messages, verifying signatures, and looking up human IDs.

```APIDOC
## Manual usage example

### Description
Use the low-level helpers directly when you are not using the x402 Hono wrapper or when you want full control over request handling.

### Functions
- `declareAgentkitExtension({ domain, resourceUri, network, statement })` - Declares the agent kit extension with domain, resource URI, network, and statement.
- `createAgentBookVerifier()` - Creates an AgentBook verifier.
- `parseAgentkitHeader(header)` - Parses the AgentKit header from a request.
- `validateAgentkitMessage(payload, resourceUri)` - Validates the AgentKit message.
- `verifyAgentkitSignature(payload)` - Verifies the AgentKit signature.
- `agentBook.lookupHuman(address)` - Looks up the human ID for a given address.

### Code Example
```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 }
	}

	const humanId = await agentBook.lookupHuman(verification.address)
	if (!humanId) {
		return { error: 'Agent is not registered in the AgentBook' }
	}

	return { humanId }
}
```

### Supported Chains and Signature Behavior
- Chain namespace: `eip155:*`
- Payload `type`: `eip191` or `eip1271`
- Optional `signatureScheme`: `eip191`, `eip1271`, or `eip6492`
- Message format: SIWE

### Production Notes
- Treat `InMemoryAgentKitStorage` as a demo-only implementation.
- If you need limited free uses, persistent storage is part of the integration, not an optional enhancement.
- If you need `discount` mode, wire `verifyFailureHook` into the facilitator before you ship.
- Use Hono as a reference example, not as a framework restriction. The package surface is generic enough to be adapted to Express or Next.js handlers.
```

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

### Share Response Example

Source: https://docs.world.org/mini-apps/commands/share

Example JSON response when the share is executed with MiniKit. Shows a success status, version 1, shared_files_count of 2, and a timestamp.

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

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

### Multiple Credentials Request Example

Source: https://docs.world.org/llms-full.txt

Example of a ProofRequest with two credential requests (passport and poh) and an 'all' constraint requiring both.

```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"]
  }
}
```

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

### Start node in background with Docker Compose

Source: https://docs.world.org/world-chain/reference/node-setup

Builds and starts the node containers in detached mode. Run from the simple-worldchain-node folder after configuration.

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

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

### Install IDKit 4.x

Source: https://docs.world.org/world-id/idkit/integrate

Install IDKit using the latest 4.x version. Choose the command or declaration appropriate for your environment: JavaScript, React, Swift (SPM), or Kotlin (Gradle).

```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>")
  }

```

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

### Implement custom AgentKitStorage and configure free-trial mode

Source: https://docs.world.org/agents/agent-kit/integrate

Use this TypeScript example to implement a custom storage class that persists usage counters and nonces in a database, and configure the agent kit hooks with free-trial mode (3 uses). The example imports AgentKitStorage from '@worldcoin/agentkit' and assumes a 'db' object with the required methods.

```TypeScript
import type { AgentKitStorage } from '@worldcoin/agentkit'

class DatabaseAgentKitStorage implements AgentKitStorage {
	async tryIncrementUsage(endpoint: string, humanId: string, limit: number) {
		return db.tryIncrementUsage(endpoint, humanId, limit)
	}

	async hasUsedNonce(nonce: string) {
		return db.hasUsedNonce(nonce)
	}

	async recordNonce(nonce: string) {
		await db.recordNonce(nonce)
	}
}

const hooks = createAgentkitHooks({
	agentBook,
	storage: new DatabaseAgentKitStorage(),
	mode: { type: 'free-trial', uses: 3 },
})
```

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

### Example JSON result

Source: https://docs.world.org/mini-apps/commands/share-contacts

Example JSON response from MiniKit.shareContacts() when executed with minikit, showing a contact with username, walletAddress, profilePictureUrl, and a timestamp.

```json
{
  "executedWith": "minikit",
  "data": {
    "contacts": [
      {
        "username": "alex",
        "walletAddress": "0x1234567890123456789012345678901234567890",
        "profilePictureUrl": "https://cdn.example.com/profile/alex.png"
      }
    ],
    "timestamp": "2026-03-28T18:24:00.000Z"
  }
}
```

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

### Example Response JSON

Source: https://docs.world.org/mini-apps/commands/get-permissions

A sample JSON response from MiniKit.getPermissions() showing a successful minikit execution with permission booleans and a timestamp.

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

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

### Geolocation access example

Source: https://docs.world.org/mini-apps/more/webview-spec

Example of using the Geolocation API to get the current position. Location is supported on both Android and iOS platforms.

```javascript
navigator.geolocation.getCurrentPosition((position) => {
    console.log(position);
});
```

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

### Create project directory and initialize npm

Source: https://docs.world.org/world-chain/tokens/usdc

Commands to create a new project directory and initialize a Node.js project with npm.

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

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

### Example curl request for wallet address

Source: https://docs.world.org/mini-apps/reference/credit-api

Example curl command to get data for a specific wallet address. The response is a JSON object with state and score.

```bash
curl -s "https://credit.cash/api/borrower/0x764C890E7D96481cBEa64c64C0F9cFF34bFF2Ce7"
```

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

### Migrating from QR / connect-URL

Source: https://docs.world.org/world-id/idkit/react

Migration guide showing how to replace the legacy IDKitRequestWidget with the useIDKitRequest hook.

```APIDOC
## Migrating from QR / connect-URL

### Description
This section provides a migration guide for moving from the legacy IDKitRequestWidget to the useIDKitRequest hook.

### Before — QR / connect-URL widget
```tsx
import { IDKitRequestWidget, orbLegacy } from "@worldcoin/idkit";

<IDKitRequestWidget
  open={open}
  onOpenChange={setOpen}
  app_id="app_xxxxx"
  ...
/>
```

### After — useIDKitRequest hook
```tsx
import { useIDKitRequest } from "@worldcoin/idkit";

const { open, reset, isSuccess, result } = useIDKitRequest();
```
```

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

### JavaScript fetch request to get user operation

Source: https://docs.world.org/api-reference/developer-portal/get-user-operation

Use this JavaScript fetch example to retrieve a user operation by its hash. Replace {user_op_hash} with the actual hash.

```javascript
const options = {method: 'GET'};

fetch('https://developer.world.org/api/v2/minikit/userop/{user_op_hash}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

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

### Download simple-worldchain-node and create .env

Source: https://docs.world.org/world-chain/reference/node-setup

Clones the simple-worldchain-node repository and creates a .env file from the example template. Run these commands before configuring your node.

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

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

### GetPermissionsResponse Type and Example

Source: https://docs.world.org/mini-apps/commands/get-permissions

The response type and an example JSON response from MiniKit.getPermissions(). The response includes the execution method, permission status, version, and a timestamp.

```ts
type GetPermissionsResponse =
    | {
        executedWith: "minikit";
        data: {
          status: "success";
          version: number;
          permissions: {
            notifications?: any;
            contacts?: any;
            microphone?: any;
          };
          timestamp: string;
        };
      }
    | {
        executedWith: "fallback";
        data: unknown;
      };
```

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

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

### JavaScript fetch request to get transaction debug URL

Source: https://docs.world.org/api-reference/developer-portal/get-transaction-debug-url

Use this fetch example to call the endpoint from a browser or Node.js environment. Replace <token> with your actual token.

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://developer.world.org/api/v2/minikit/transaction/debug', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

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

### Send Notification Response Example

Source: https://docs.world.org/api-reference/developer-portal/send-notification

Example 200 response showing the notification send status. The result array contains per-wallet status with walletAddress, sent, and reason fields.

```json
{
  "success": true,
  "status": 123,
  "result": [
    {
      "walletAddress": "<string>",
      "sent": true,
      "reason": "<string>"
    }
  ]
}
```

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

### Migrating from QR / connect-URL

Source: https://docs.world.org/world-id/idkit/javascript

Migration guide for moving from the old QR/connect-URL flow to the new IDKitInviteCodeRequest-based flow.

```APIDOC
## Migrating from QR / connect-URL

### Description
This section explains how to migrate from the previous QR/connect-URL flow to the new IDKitInviteCodeRequest-based flow.

### Before — QR / connect-URL flow
```typescript
const request = await IDKit.request({
  app_id: "app_xxxxx",
  action: "<action>",
  // ... other parameters
});
```

### After — New flow
```typescript
const request = await IDKit.request({
  app_id: "app_xxxxx",
  action: "<action>",
  // ... other parameters
});

const expiresAt = request.expiresAt; // Unix seconds
const completion = await request.pollUntilCompletion();
```
```

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

### Example successful chat result JSON

Source: https://docs.world.org/mini-apps/commands/chat

Example JSON response when the command is executed with 'minikit'. Shows a success status, version 1, count 2, and a timestamp.

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

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

### GET /status/{id}

Source: https://docs.world.org/mini-apps/guidelines/smart-contract-development-guidelines

Gets the status of an operation by ID.

```APIDOC
## GET /status/{id}

### Description
Gets the status of an operation by ID.

### Method
GET

### Endpoint
/status/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The operation ID.

### Response
#### Success Response (200)
- **status** (string) - The status of the operation.

#### Response Example
{
  "status": "pending"
}
```

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

### Import Hono, serve, HTTPFacilitatorClient, ExactEvmScheme, and x402 server utilities

Source: https://docs.world.org/agents/agent-kit/integrate

Imports the core modules needed to build an x402-enabled HTTP server with Hono. Includes Hono, @hono/node-server's serve, HTTPFacilitatorClient from @x402/core/http, ExactEvmScheme from @x402/evm/exact/server, and paymentMiddlewareFromHTTPServer, x402HTTPResourceServer, x402ResourceServer from @x402/evm/exact/server.

```typescript
import { Hono } from 'hono'
import { serve } from '@hono/node-server'
import { HTTPFacilitatorClient } from '@x402/core/http'
import { ExactEvmScheme } from '@x402/evm/exact/server'
import {
	paymentMiddlewareFromHTTPServer,
	x402HTTPResourceServer,
	x402ResourceServer,
} from 
```

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

### Create a new Mini App with the official template

Source: https://docs.world.org/mini-apps/quick-start/installing

Run this command to scaffold a new mini app using the next-15 template. Follow the instructions and use pnpm for cleanliness.

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

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

### IDKit Configuration Example

Source: https://docs.world.org/world-id/idkit/javascript

Shows how to configure IDKit with app_id, action, and optional settings like production mode, return_to, and bridge_url. Note: Generate rp_context in your backend only; never expose your RP signing key in client code.

```typescript
import { IDKit, orbLegacy } from "@worldcoin/idkit-core";

const request = await IDKit.request({
  app_id: "app_xxxxx",
  action: "my-action",
  // Only set this to staging for testing with the simulator
  production: false,
  // Optional: mobile deep-link callback URL
  return_to: "myapp://verify-done",
  // Optional: custom bridge URL
  bridge_url: undefined,
});
```

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

### Manual AgentKit request handling with low-level helpers

Source: https://docs.world.org/agents/agent-kit/sdk-reference

Use this example when not using the x402 Hono wrapper or when you need full control over request handling. It imports helpers from @worldcoin/agentkit, declares an extension with domain, resourceUri, network, and statement, creates an AgentBook verifier, and handles a request by parsing the AGENTKIT header, validating the message, verifying the signature, and looking up the human ID. The example returns an error if validation or verification fails or if the agent is not registered.

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

	const humanId = await agentBook.lookupHuman(verification.address)
	if (!humanId) {
		return { error: 'Agent is not registered in the AgentBook' }
	}

	return { humanId }
}
```

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

### Create a new Foundry project

Source: https://docs.world.org/world-chain/developers/deploy

Navigate to your desired directory and run this command to create a new Foundry project named 'hello-world-chain' and change into it. Smart contracts are stored in the 'src' directory.

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

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

### Generated Deeplink URL example

Source: https://docs.world.org/mini-apps/sharing/dna-qa

Example deeplink URL for the Worldcoin mini-app. The amount must be in the unit of fromToken (e.g., wei for Ethereum-based tokens). The sourceDeeplinkPath is URL-encoded. DNA_APP_ID should be defined in your environment. For Send tab, provide fromToken, amount, and recipient address or username; toToken is not required. For Swap tab, provide fromToken, toToken, and amount in base unit.

```bash
https://worldcoin.org/mini-app?app_id=app_8e407cfbae7ae51c19b07faff837aeeb&path=%2Fwallet%3Ftab%3Dsend%26fromToken%3D0x79A02482A880bCE3F13e09Da970dC34db4CD24d1%26amount%3D1234500%26toToken%3D0x4200000000000000000000000000000000000006%26recipientAddress%3D0xRecipientAddressHere%26sourceAppId%3Dapp_a4f7f3e62c1de0b9490a5260cb390b56%26sourceDeeplinkPath%3D%252Fsome%252Fpath
```

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

### Installation

Source: https://docs.world.org/world-id/idkit/kotlin

Add the IDKit dependency to your Gradle project. The package is published to GitHub Packages, requiring authentication credentials.

```APIDOC
## Install

### Description
Add the IDKit dependency to your Gradle project. The package is published to GitHub Packages, requiring authentication credentials.

### Dependency
```kotlin
dependencyResolutionManagement {
    repositories {
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/worldcoin/idkit")
            credentials {
                username = System.getenv("GITHUB_ACTOR")
                password = System.getenv("GITHUB_TOKEN") // requires read:packages
            }
        }
    }
}

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

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

### Create NewSigner with RP_SIGNING_KEY

Source: https://docs.world.org/world-id/idkit/go

Initializes a signer using the private key from the RP_SIGNING_KEY environment variable. Logs a fatal error if the key is missing or invalid.

```go
signer, err := idkit.NewSigner(os.Getenv("RP_SIGNING_KEY"))
if err != nil {
	log.Fatal(err)
}
```

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

### Initialize IDKit with signal and action

Source: https://docs.world.org/world-id/idkit/javascript

Shows how to create an IDKit instance with a signal and action, then apply the orbLegacy preset with a custom signal.

```typescript
const idkit = new IDKit({
  app_id: "app_123",
  action: "my-action",
  rp_context,
  allow_legacy_proofs: true,
}).preset(orbLegacy({ signal: "user-123" }));
```

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

### Sybil resistance example in Solidity

Source: https://docs.world.org/world-id/reference/address-book

Example function for sybil resistance: stores nullifiers and checks they are not reused.

```solidity
/// @param root The root (returned by the IDKit widget).
```

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

### Go SignRequest Example

Source: https://docs.world.org/llms-full.txt

Uses the github.com/worldcoin/idkit/go/idkit package. Provides one-shot signing with options and a reusable signer for high-throughput backends. The ttl option is optional and defaults to 300 seconds.

```go
import "github.com/worldcoin/idkit/go/idkit"

// One-shot signing with options
sig, err := idkit.SignRequest(
  os.Getenv("RP_SIGNING_KEY"),
  idkit.WithAction("my-action"),
  idkit.WithTTL(300), // optional, default 300s
)

// Or create a reusable signer for high-throughput backends
signer, err := idkit.NewSigner(os.Getenv("RP_SIGNING_KEY"))
sig, err = signer.SignRequest(idkit.WithAction("my-action"))
```

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

### Single Credential Request Example

Source: https://docs.world.org/llms-full.txt

Example of a ProofRequest with a single credential request for a passport with issuer_schema_id 9303.

```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"
    }
  ]
}
```

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

### Example JSON response

Source: https://docs.world.org/mini-apps/reference/credit-api

Example response from the Credit API showing an INACTIVE state and a score of 1947.

```json
{
  "state": "INACTIVE",
  "score": 1947
}
```

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

### More Complex Constraints Request Example

Source: https://docs.world.org/llms-full.txt

Example of a ProofRequest with three credential requests and a nested constraint: all of orb and any of passport or my-number-card.

```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"]
      }
    ]
  }
}
```
Tokens:
Raw