https://github.com/masaun/world-agent-kit-template
Template for World Agent Kit integraiton
https://github.com/masaun/world-agent-kit-template
world-agent-kit zero-knowledge-proof
Last synced: about 1 month ago
JSON representation
Template for World Agent Kit integraiton
- Host: GitHub
- URL: https://github.com/masaun/world-agent-kit-template
- Owner: masaun
- Created: 2026-04-16T02:49:17.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-17T07:59:21.000Z (3 months ago)
- Last Synced: 2026-04-17T09:38:10.584Z (3 months ago)
- Topics: world-agent-kit, zero-knowledge-proof
- Language: TypeScript
- Homepage:
- Size: 29.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# World AgentKit Template
## Overview
This repo is the template for the `World AgentKit` integration by referencing the [World AgentKit integration guide](https://docs.world.org/agents/agent-kit/integrate).
## What this demonstrates
| Step | Component | Description |
|------|-----------|-------------|
| 1 | `src/server.ts` | Hono server with a protected `/data` endpoint |
| 2 | `src/server.ts` | `createAgentkitHooks` enforces a 3-use free-trial per registered human |
| 3 | `src/agent.ts` | Agent builds a SIWE message, signs it, and sends the `X-AgentKit` header |
| 4 | Both | First 3 requests succeed; the 4th returns 402 (trial exhausted) |
### Workflow
```
Agent Server World Chain
| | |
|-- GET /data + X-AgentKit ------> | |
| |-- lookupHuman(address) ----> |
| |<- humanId ------------------- |
| | (free trial: 1/3 used) |
|<-- 200 { data } ----------------- | |
...
|-- GET /data + X-AgentKit ------> | (3/3 uses exhausted)
|<-- 402 { payment required } ---- |
```
## Quick start
### 1. Install dependencies
```bash
bun install
```
### 2. Configure environment
```bash
cp .env.example .env
```
Edit `.env` and set `AGENT_PRIVATE_KEY`.
```bash
AGENT_PRIVATE_KEY="0xYourPrivateKeyHere"
```
### 3. Register your `agent's wallet address` (`public key`) to the [`AgentBook`](https://worldscan.org/address/0xa23ab2712ea7bba896930544c7d6636a96b944da#code) contract on `World Chain mainnet`:
Register your ``, which is public key of the `AGENT_PRIVATE_KEY` that you set the step 2 above.
```bash
bunx @worldcoin/agentkit-cli register
```
The CLI prompts you to verify with World App, then submits the registration
transaction to World Chain.
### 4. Start the server
```bash
bun run dev:server
```
Output:
```
World AgentKit Demo Server
Listening on http://localhost:3000
Protected endpoint: GET http://localhost:3000/data
Free-trial uses: 3 per registered human
```
### 5. Run the agent demo (separate terminal)
```bash
bun run dev:agent
```
Expected output:
```
--- Request #1 --- → 200 (free trial 1/3)
--- Request #2 --- → 200 (free trial 2/3)
--- Request #3 --- → 200 (free trial 3/3)
--- Request #4 --- → 402 (trial exhausted — payment required)
```
## Project layout
```
.
├── src/
│ ├── server.ts # Hono server + AgentKit hooks + 402 enforcement
│ └── agent.ts # Agent wallet + SIWE signing + demo loop
├── .env.example
├── package.json
└── tsconfig.json
```
## Key constants (`World Chain - mainnet`)
| Name | Value |
|------|-------|
| Chain ID (CAIP-2) | `eip155:480` |
| World USDC | `0x79A02482A880bCE3F13e09Da970dC34db4CD24d1` |
| AgentBook contract | [`0xA23aB2712eA7BBa896930544C7d6636a96b944dA`](https://worldscan.org/address/0xa23ab2712ea7bba896930544c7d6636a96b944da#code) |
| Default facilitator | `https://x402-worldchain.vercel.app/facilitator` |
## Production checklist
- [ ] Replace `InMemoryAgentKitStorage` with a database-backed implementation
(implement `getUsageCount`, `incrementUsage`, `hasUsedNonce`, `recordNonce`)
- [ ] Set `PAY_TO` to your actual payment address
- [ ] Integrate real x402 payment verification for the post-trial flow
- [ ] Load `AGENT_PRIVATE_KEY` from a secrets manager (e.g. AWS Secrets Manager)
- [ ] Set `BASE_URL` to your public domain
## References
- [World AgentKit integration guide](https://docs.world.org/agents/agent-kit/integrate)
- [SDK reference](https://docs.world.org/agents/agent-kit/sdk-reference)
- [x402 protocol](https://x402.org)
## Extra - How to generate a public key/private key pair and regster it to the `AgentBook` contract on `World Chain mainnet` for testing purpose
- Generate a public key/private key pair and regster it to the `AgentBook` contract on `World Chain mainnet` for testing purpose:
```bash
sh random-key-pair-generation-and-registration.sh
```
Or, manually executing the following commands 1 by 1:
1/ Generate an agent `private key`:
```bash
bun -e "console.log('0x' + require('crypto').randomBytes(32).toString('hex'))"
```
2/ Derive an agent `wallet address` (`public key`) with a generated `privat key` above using `viem`:
```bash
# NOTE: You need to set "0x" to the privateKeyToAccount() below - before executing the following code.
bun -e "
const { privateKeyToAccount } = require('viem/accounts');
const a = privateKeyToAccount('0x');
console.log(a.address);
"
```
3/ Register your agent (NOTE: This is the same with the step 3 of the "Quick start" above)
Register your agent's `wallet-address` (agent's `public-key`)
```bash
bunx @worldcoin/agentkit-cli register
```