feat!: agentkit cli v0.2 by m1guelpf · Pull Request #38 · worldcoin/agentkit

m1guelpf · 2026-08-11T23:43:34Z

Simplify the AgentKit SDK & CLI

Context (how things worked before)

CLI

Previously, the CLI provided a single "register" command, which accepted an ETH address and would register it with the AgentBook contract on the provided chain. It either printed out the transaction details, or used an API endpoint to register. The API address was customizable as a flag.

Core

When building the Shopify integration, I did a quick refactor to split the AgentKit SDK into two packages: core and x402. This was done pretty quickly to get the integration done in time, and mostly just exposed an escape hatch to verify x402-shaped signatures without having to pull in their entire SDK.

x402

The x402 package contained all the x402-specific parts remaining after the core split. It implements a middleware that checks requests for agentkit data and, if present, applies a configurable discount or free trial.

How things work now

CLI

The CLI now manages your agent keys for you. It gets saved in your config directory and used for all calls.

There are now two commands. The first one, register, requests a World ID proof from the user and registers the agent's pKey on the AgentBook. Future calls do nothing.

The prove {req} command receives a request body, and returns the signed body back to the caller. It errors if the pKey is not registered in the AgentBook, prompting the agent to verify it.

Both of these commands are intended to be called by agents, although humans can also use them.

Core

The core package has been pretty much completely rewritten. It now exposes a verify(request) function that checks that the given request:

has the agentkit header
the agentkit header contains a valid signature of the request's body
the pKey that signed the body is in the agent book

If those checks succeed, it returns the nullifier hash of the human that the agent acts on behalf of. Otherwise it throws.

x402

The x402 package remains mostly unchanged, just switched to using the new signing implementation in core.

paolodamico · 2026-08-11T23:52:21Z

@codex review

paolodamico · 2026-08-11T23:52:28Z

cursor review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4ed8253cfb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-08-11T23:54:30Z

-			.optional()
-			.describe('Override API base URL for registration relay; defaults to https://x402-worldchain.vercel.app'),
-	}),
+	description: 'Register this agent with a World ID proof.',


Update the root quick start for addressless registration

Update the repository's primary registration instructions alongside this removal of the address argument. README.md:34-48 still directs users to run register <your-wallet-address> and describes Base, manual mode, custom relays, and Base Sepolia, but this command now accepts no address or options and creates its own World Chain identity. Users following the top-level quick start will either receive an unexpected-argument error or, depending on argument handling, register a different generated identity than the wallet they supplied.

Useful? React with 👍 / 👎.

paolodamico · 2026-08-17T19:38:38Z

-}
-
-export type AgentkitSignatureVerificationConfig = string | AgentkitSignatureVerificationOptions
+const AGENTKIT_HEADER = 'X-AgentKit'


Suggested change

const AGENTKIT_HEADER = 'X-AgentKit'

const AGENTKIT_HEADER = 'AgentKit'

the X- convention is no longer recommended

paolodamico · 2026-08-17T19:41:55Z

-	return options?.rpcUrls?.[chainId] ?? options?.rpcUrl
+type VerifyRequestDependencies = {
+	recoverAddress?: (body: Uint8Array, signature: Hex) => Promise<string>
+	lookupNullifierHash?: (address: string) => Promise<string | null>


nit. let's start moving away from the confusing nullifier hash terminology, maybe lookupId?

paolodamico · 2026-08-17T19:42:34Z

+export async function verifyRequest(request: Request, dependencies: VerifyRequestDependencies = {}): Promise<string> {
+	const signature = request.headers.get(AGENTKIT_HEADER)?.trim()
+	if (!signature) {
+		throw verificationError('Missing X-AgentKit header', 'MISSING_HEADER')


Suggested change

throw verificationError('Missing X-AgentKit header', 'MISSING_HEADER')

throw verificationError(`Missing ${AGENTKIT_HEADER} header`, 'MISSING_HEADER')

paolodamico · 2026-08-17T19:43:43Z

+	if (!signature) {
+		throw verificationError('Missing X-AgentKit header', 'MISSING_HEADER')
+	}
+	if (!isHex(signature) || !/^0x[0-9a-fA-F]{130}$/.test(signature)) {


seems redundant to do isHex and this regex

paolodamico · 2026-08-17T19:46:22Z

-			valid: false,
-			error: `Signature verification error: ${reason}. The SIWE message the server reconstructed from your payload:\n\n${message}`,
-		}
+		body = new Uint8Array(await request.clone().arrayBuffer())


nit. I wonder if there's a way to absorb the request body into the sha input blocks without an additional copy in memory

paolodamico · 2026-08-17T20:15:52Z

-```bash
-API_URL=https://your-api.example.com agentkit register 0x1234567890abcdef1234567890abcdef12345678 --network base-sepolia --auto
-```
+## Sign an x402 request body


I don't think this particularly applies to x402

paolodamico · 2026-08-17T20:19:18Z

 	 */
 	tryIncrementUsage(endpoint: string, humanId: string, limit: number): Promise<boolean>
-
-	hasUsedNonce?(nonce: string): Promise<boolean>


nonce usage should remain

paolodamico · 2026-08-17T20:20:03Z

+type VerifyFunction = (request: Request) => Promise<string>
+type RecoverAddressFunction = (body: Uint8Array, signature: Hex) => Promise<string>
+
+export function createAgentkitHooksInternal(


nit. internal function exported?

paolodamico · 2026-08-17T20:27:21Z

+## Use AgentKit

-Register your wallet in AgentBook so servers can verify you are human-backed. Registration is gasless by default (uses a hosted relay on Base mainnet).
+Add the AgentKit x402 skill:


high we have mentions to x402 everywhere, it should be focused on the new version

paolodamico · 2026-08-17T20:27:51Z

- **Smart wallet support**: EVM verification automatically supports both smart contract wallets (ERC-1271) and EOA wallets via RPC calls to the chain.
- **On-chain verification**: AgentBook lookups happen at request time, so revoked registrations take effect immediately.
- **Per-human tracking**: Usage limits are tracked by anonymous human identifier, not by wallet address. Multiple agents controlled by one person share a single counter.
+- The signature authenticates only the normalized request body. It does not automatically bind the method, URL, host, audience, timestamp, or nonce. Put any required context in the signed body and validate it in the application.


this needs to be fixed

thomas-waite

Overall, think this is a really good step. It makes it much simpler to use, with the key/crypto stuff being abstracted away.

Main thing to discuss is the signature scheme, and also thinking about renaming the x402 server component

thomas-waite · 2026-08-17T20:39:34Z

+	return join(configHome, 'agentkit', 'key')
+}
+
+export async function loadOrCreateAgentIdentity(keyPath: string = getAgentkitKeyPath()): Promise<AgentIdentity> {


This is hiding the env, configured home etc. within the key.ts CLI file. Feel like this stuff should be configured in the index.ts and injected in, not critical though

thomas-waite · 2026-08-17T20:40:54Z

+}
+
+export function getAgentkitKeyPath(
+	env: NodeJS.ProcessEnv = process.env,


Why pass the whole env into the function? Why not just specify the path in the index.ts and inject in?

You could construct a config type object in the index.ts cleanly and inject it into the CLI

thomas-waite · 2026-08-17T20:42:12Z

+				args: [signer.address],
+			})
+		} catch (err) {
+			return c.error({


All of this error handling feels to me like it should be handled within the ClientContract class

thomas-waite · 2026-08-17T20:56:52Z

+
+const temporaryDirectories: string[] = []
+
+afterEach(async () => {


Have done a fresh install of this branch and run bun test. Getting some test failures around

# Unhandled error between tests ------------------------------- error: Cannot find module 'ajv/dist/core' from '/Users/thomas.waite/Documents/tfh/agentkit/node_modules/ajv-draft-04/dist/index.js'

new cli :3

4ed8253

m1guelpf requested review from Takaros999 and paolodamico as code owners August 11, 2026 23:43

chatgpt-codex-connector Bot reviewed Aug 11, 2026

View reviewed changes

paolodamico reviewed Aug 12, 2026

View reviewed changes

Comment thread cli/src/prove.ts Outdated

more refactor

82beecd

paolodamico changed the title ~~new cli~~ feat!: agentkit cli v0.2 Aug 17, 2026

paolodamico reviewed Aug 17, 2026

View reviewed changes

thomas-waite reviewed Aug 17, 2026

View reviewed changes

thomas-waite mentioned this pull request Aug 20, 2026

Sign requests with RFC 9421 HTTP Message Signatures #39

Open

	const AGENTKIT_HEADER = 'X-AgentKit'
	const AGENTKIT_HEADER = 'AgentKit'

	throw verificationError('Missing X-AgentKit header', 'MISSING_HEADER')
	throw verificationError(`Missing ${AGENTKIT_HEADER} header`, 'MISSING_HEADER')


		const temporaryDirectories: string[] = []

		afterEach(async () => {

Uh oh!

Conversation

m1guelpf commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context (how things worked before)

CLI

Core

x402

How things work now

CLI

Core

x402

Uh oh!

paolodamico commented Aug 11, 2026

Uh oh!

paolodamico commented Aug 11, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot Aug 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thomas-waite left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

m1guelpf commented Aug 11, 2026 •

edited

Loading

thomas-waite left a comment •

edited

Loading