Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.world.org/llms.txt

Use this file to discover all available pages before exploring further.

AgentKit Beta extends x402 allowing websites to distinguish human-backed agents from bots and scripts. Enable agentic traffic to access api endpoints while blocking malicious actors, scalpers and spam. This quickstart follows a default implementation path:
  • Agent-side x402 calls use agentkit.fetch from createAgentkitClient
  • Accepts payments on both World Chain and Base
  • Agent registration on World Chain
  • AgentBook lookup always resolves on World Chain (caller side is chain-agnostic)
  • free-trial mode with 3 uses
  • Hono plus @x402/hono as the reference server example

​
Step 1: Install AgentKit

npm install @worldcoin/agentkit

​
Step 2: Register the agent in AgentBook

Register the wallet address your agent will sign with: 
npx @worldcoin/agentkit-cli register <agent-address>
Check whether a wallet is already registered: 
npx @worldcoin/agentkit-cli status <agent-address>
By default, the CLI registers on World Chain and submits through the hosted relay. AgentBook lookup always resolves against the canonical World Chain deployment. During registration, the CLI:
  1. Looks up the next nonce for the agent address
  2. Prompts the World App verification flow
  3. Submits the registration transaction
Once the wallet is registered, AgentKit can resolve it to an anonymous human identifier at request time.

Example of the registration flow

​
Step 3: Wrap x402 calls in the agent

Use this in agents that call paid x402 APIs. Without this client, agents may go straight to payment instead of using their AgentKit registration. 
import { createAgentkitClient } from '@worldcoin/agentkit'

const agentkit = createAgentkitClient({
	signer: {
		address: agentWallet.address,
		chainId: 'eip155:8453',
		type: 'eip191',
		signMessage: message => agentWallet.signMessage(message),
	},
})

const response = await agentkit.fetch('https://api.example.com/data')
Use agentkit.fetch anywhere the agent would otherwise call fetch for x402-protected APIs. It tries AgentKit first, then leaves the normal x402 payment fallback in place. If you cannot change the agent’s HTTP client, add the fallback skill: 
npx skills add worldcoin/agentkit agentkit-x402

​
Step 4: Wire the hooks-based server flow

The example below shows the maintained Hono wrapper path. AgentKit itself is not Hono-only: Express and Next.js route handlers can use the same hooks and low-level helpers from the SDK Reference. 
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 '@x402/hono'
import {
	agentkitResourceServerExtension,
	createAgentBookVerifier,
	createAgentkitHooks,
	declareAgentkitExtension,
	InMemoryAgentKitStorage,
} from '@worldcoin/agentkit'

const WORLD_CHAIN = 'eip155:480'
const BASE = "eip155:8453";
const WORLD_USDC = '0x79A02482A880bCE3F13e09Da970dC34db4CD24d1'
const payTo = '0xYourAddress'

const facilitatorClient = new HTTPFacilitatorClient({
	url: 'https://x402-worldchain.vercel.app/facilitator',
})

const evmScheme = new ExactEvmScheme()
	// Register a money parser to accept USDC payments on WorldChain.
	.registerMoneyParser(async (amount, network) => {
		if (network !== WORLD_CHAIN) return null

		return {
			amount: String(Math.round(amount * 1e6)),
			asset: WORLD_USDC,
			extra: { name: 'USD Coin', version: '2' },
		}
	})

const agentBook = createAgentBookVerifier()
const storage = new InMemoryAgentKitStorage()

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

const resourceServer = new x402ResourceServer(facilitatorClient)
	.register(WORLD_CHAIN, evmScheme)
	.register(BASE, new ExactEvmScheme())
	.registerExtension(agentkitResourceServerExtension)

const routes = {
	'GET /data': {
		// Accept payments on both World Chain and Base
		accepts: [
			{
				scheme: 'exact',
				price: '$0.01',
				network: WORLD_CHAIN,
				payTo,
			},
			{
				scheme: 'exact',
				price: '$0.01',
				network: BASE,
				payTo,
			},
		],
		extensions: declareAgentkitExtension({
			statement: 'Verify your agent is backed by a real human',
			mode: { type: 'free-trial', uses: 3 },
		}),
	},
}

const httpServer = new x402HTTPResourceServer(resourceServer, routes)
	.onProtectedRequest(hooks.requestHook)

const app = new Hono()
app.use(paymentMiddlewareFromHTTPServer(httpServer))

app.get('/data', c => {
	return c.json({ message: 'Protected content' })
})

serve({ fetch: app.fetch, port: 4021 })
This example accepts payments on both World Chain and Base. AgentBook lookup automatically resolves against the canonical World Chain deployment.

​
Step 5: Configure the default mode and storage

This guide uses free-trial mode so registered human-backed agents get 3 free requests before the normal x402 payment flow resumes. InMemoryAgentKitStorage is fine for local testing, but production should persist both usage counters and nonces. 
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 },
})
Need discount mode, custom AgentBook deployments, or the low-level validation helpers? Continue to the SDK Reference.