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

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:

Looks up the next nonce for the agent address
Prompts the World App verification flow
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.

​Step 1: Install AgentKit

​Step 2: Register the agent in AgentBook

​Step 3: Wrap x402 calls in the agent

​Step 4: Wire the hooks-based server flow

​Step 5: Configure the default mode and storage

Step 1: Install AgentKit

Step 2: Register the agent in AgentBook

Step 3: Wrap x402 calls in the agent

Step 4: Wire the hooks-based server flow

Step 5: Configure the default mode and storage