Skip to content

feat!: agentkit cli v0.2 #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
m1guelpf wants to merge 2 commits into from
Open

feat!: agentkit cli v0.2 #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4ed8253
new cli :3
m1guelpf Aug 11, 2026
82beecd
more refactor
m1guelpf Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 18 additions & 56 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,90 +2,52 @@

# **AgentKit**

**Verify that an agent is backed by a real, [World ID-verified human](https://docs.world.org/agents/agent-kit).**
**Let an agent show that a person with a verified [World ID](https://docs.world.org/agents/agent-kit) controls it.**

<img src="registration.gif" alt="AgentKit Registration" width="960" />
<img src="registration.gif" alt="AgentKit registration" width="960" />

</div>

## Skills
For your Agent to use your registration when accessing x402 endpoints
```bash
npx skills add worldcoin/agentkit agentkit-x402
```

For developers building x402 servers, add the integration guide to your knowledge base:
```bash
npx skills add worldcoin/agentkit integrate-agentkit
```

## How it Works

1. An agent wallet is registered in AgentBook using a World ID proof.
2. A website or API using x402 challenges the agent to sign a CAIP-122 message.
3. The server verifies the signature, resolves the registering human from AgentBook, and applies the configured access policy.

This lets applications distinguish between arbitrary automation and automation acting on behalf of a real human, without exposing the human's underlying identity.

## For Agents
AgentKit lets an agent show that a verified person controls it. A service can then give the agent free access, a trial, or a discount. AgentKit does not give the identity of the person to the service.

### Register
## 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:

@paolodamico paolodamico Aug 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


```bash
npx @worldcoin/agentkit-cli register <your-wallet-address>
npx skills add worldcoin/agentkit agentkit-x402
```

This will prompt a World ID verification via World App. You only need to register once per wallet.
The skill gives instructions to the agent. The agent tries AgentKit before it makes an x402 payment. During the first registration, World App can ask you to complete a World ID check.

Check whether a wallet is already registered:
To start registration yourself, use this command:

```bash
npx @worldcoin/agentkit-cli status <your-wallet-address>
npx @worldcoin/agentkit-cli register
```

For the full registration guide (manual mode, custom relays, Base Sepolia): [`./cli/REGISTRATION.md`](./cli/REGISTRATION.md)
For more information, read the [registration guide](./cli/REGISTRATION.md). You can also read the [agent skill](./skills/agentkit-x402/SKILL.md).

### Use
## Build with AgentKit

Once registered, create an AgentKit client and use `agentkit.fetch` for x402 HTTP calls. It tries AgentKit verification before payment and only leaves the normal x402 payment flow in place when verification is unavailable, fails, or is exhausted.
Install the server package:

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

```typescript
import { createAgentkitClient } from '@worldcoin/agentkit'

const agentkit = createAgentkitClient({
signer: {
address: agentWallet.address,
chainId: 'eip155:8453',
type: 'eip191',
signMessage: message => agentWallet.signMessage(message),
},
})
Use this package to add AgentKit to an x402 service. The service can give free access, trials, or discounts.

const response = await agentkit.fetch('https://api.example.com/data')
```
Read the [x402 integration guide](./x402/DOCS.md) for setup instructions and examples.

If your agent cannot change its HTTP client code, install the agent skill as fallback guidance:
To help an agent protect a normal HTTP endpoint, add this skill:

```bash
npx skills add worldcoin/agentkit agentkit-x402
npx skills add worldcoin/agentkit integrate-agentkit
```

The full flow — parsing 402 responses, signing the CAIP-122 challenge, and sending the `agentkit` header — is documented in the agent skill: [`./skills/agentkit-x402/SKILL.md`](./skills/agentkit-x402/SKILL.md)

## For x402 Developers

### Integrate

Add AgentKit to your x402 server to offer human-backed agents free access, free trials, or discounts.
To help an agent protect an x402 endpoint, add this skill:

```bash
npm install @worldcoin/agentkit
npx skills add worldcoin/agentkit integrate-agentkit-x402
```

For the full integration guide (client wrapper, hooks setup, access modes, World Chain payments, AgentBook configuration): [`./x402/DOCS.md`](./x402/DOCS.md)
14 changes: 6 additions & 8 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

39 changes: 28 additions & 11 deletions cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,43 @@
# @worldcoin/agentkit-cli

Register agent wallet addresses with World ID-verified humans via the [AgentBook](../contracts/src/AgentBook.sol) smart contract.
Register an agent with a World ID-verified human through AgentBook.

## Quick Start
## Usage

```bash
agentkit register
```

Prompt your agent:
That is the entire registration command. On its first run, the CLI creates a local identity, checks whether it is already registered, and only starts World ID verification when registration is still needed. Successful registrations are submitted through the hosted relay.

The private key is stored at:

```text
$XDG_CONFIG_HOME/agentkit/key
```
Run `npx @worldcoin/agentkit-cli --llms`, then help me register your wallet address in the AgentBook.

When `XDG_CONFIG_HOME` is not set to an absolute path, the CLI uses:

```text
~/.config/agentkit/key
```

Use this by default. Do not ask the agent to inspect the repo to infer the flow.
Keep this file private and back it up. It is the durable identity for this agent. The private key never leaves the machine; registration sends the derived public address and World ID proof to the hosted relay.

@paolodamico paolodamico Aug 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit. "back it up" and "never leaves the machine" seems contradictory


## Usage
Full registration guide: [REGISTRATION.md](./REGISTRATION.md)

## Sign a request as this agent

Pass the exact UTF-8 request body to `prove`:

```bash
agentkit register <address> [options]
agentkit status <address>
agentkit prove '{"query":"weather","city":"Lisbon"}'
```

By default, `agentkit register <address>` uses Base mainnet and submits through the hosted relay. Use `--manual` to print raw registration call data instead.
For a request with no body, pass an empty string:

Use `agentkit status <address>` to check whether an agent wallet is already registered in the canonical AgentBook on World Chain.
```bash
agentkit prove ''
```

Full registration guide: [REGISTRATION.md](./REGISTRATION.md)
The command requires the key created by `agentkit register` and confirms that its address is registered before signing. It returns a `signature` field containing the hexadecimal value for the `X-AgentKit` request header. The retried request body must exactly match the body passed to `prove`.
Loading