celo-agent-cli
v0.1.8
Published
CLI for JAW agent wallets — secure session key management for AI agents
Readme
tl;dr
- The Celo Agent CLI gives AI agents a complete onchain toolkit in a single install, including wallets, token transfers, identity, and payments
- Agents pay for everything in stablecoins
- Native ERC-8004 support: agents get verifiable onchain identity and reputation
- x402 support lets agents pay for APIs and data feeds per-request, in stablecoins
- Self.xyz TEE attestation proves a real human is behind the agent
- ENS subnames give agents human-readable addresses
- Install in one line
npx celo-agent-cli initOne install. Everything an agent needs.
The Celo Agent CLI is an end-to-end toolkit that enables AI agents to securely create wallets, move stablecoins, and register onchain identity — settling on Celo.
This is infrastructure for programmable money. Pre-integrated, agent-aware, and secure by default.
The problem is infrastructure, not intelligence
AI agents can reason. They can plan. They can execute workflows.
But the moment they need to move funds onchain, most teams are assembling the answer themselves:
- A wallet library
- A gas abstraction layer
- A token transfer API
- An identity system
Each from a different provider, and none designed for agent-specific threat models.
The result is fragmented, fragile infrastructure sitting underneath systems that are supposed to operate autonomously.
The Celo Agent CLI replaces that stack with one integrated toolkit:
npm install -g celo-agent-cli
celo-agent initThat's it. From there, your agent can create a wallet, check balances, send tokens, register an onchain identity, build reputation, and pay for x402 endpoints.
All in stablecoins, all without touching a native gas token.
What's in the box
Wallets with built-in guardrails
Create and manage session-scoped ERC-4337 smart wallets with configurable allowances, spending limits, and contract permissions — mitigating prompt injection risk at the infrastructure level. The private key never enters the agent's context window.
Send tokens, do anything onchain
Transfer USDC, CELO, or any ERC-20 token. Execute arbitrary contract calls. All with built-in gas abstraction — agents pay in stablecoins, never in native gas tokens.
Onchain agent identity and reputation
Register your agent via ERC-8004 and build portable, verifiable reputation on Celo. Other agents and services can discover your capabilities, verify your identity, and check your track record — all onchain.
Self.xyz TEE attestation
Prove a real human is behind the agent with passport-grade identity verification inside a Trusted Execution Environment. No PII exposed — just a cryptographic proof that the operator is a verified human.
ENS subnames
Give your agent a human-readable name (e.g. my-agent.celo-agent.eth) with multi-chain address resolution across Ethereum, Celo mainnet, and Celo Sepolia via ENSIP-11.
OASF capabilities on IPFS
Formally describe your agent's skills and domains using the Open Agentic Schema Framework, pinned to IPFS for permanent discoverability. Other agents can programmatically evaluate your capabilities before initiating collaboration.
Payments-first, gas-abstracted
Native gas abstraction via Pimlico paymaster. Agents pay end-to-end in stablecoins for every interaction. No gas token management required.
How it's built
The CLI is built with three layers that work together in a single system.
Wallet infrastructure
Session-scoped ERC-4337 smart contract wallets powered by JAW. Your agent gets a smart wallet with per-token spending limits, contract whitelists, and configurable expiry. The private key is encrypted at rest with a machine-derived secret and never enters the agent's context — which matters a lot when you're running an LLM that could be prompted to leak it.
Transaction orchestration
One command to send tokens or execute any onchain action. The JAW Account class handles UserOp building, bundler submission, and paymaster integration internally. Your agent doesn't need to know the details — it just says what it wants and the infrastructure handles the rest.
ERC-8004 for onchain agent identity
ERC-8004 is the emerging Ethereum standard for agent identity. With the Celo Agent CLI, registering your agent's identity is part of the setup flow:
celo-agent init
# Step 1: Wallet setup (passkey approval)
# Step 2: Self.xyz verification (TEE passport proof)
# Step 3: ERC-8004 registration (agent NFT + ENS + OASF)
# Step 4: Project scaffold (server template with A2A + MCP)From there, your agent accumulates reputation, becomes discoverable by other agents and services, and participates in a trustless agent economy.
Stablecoin-native, gas-abstracted, x402-ready
Three things that matter for agents specifically:
No gas token management. Agents pay for every onchain action in USDC. No need to hold CELO or any native gas token. The Pimlico paymaster handles it.
Keys never touch the LLM. The session wallet architecture keeps private keys encrypted at rest and out of the agent's context window. Prompt injection attacks can't convince an agent to give over keys they don't know.
x402 for HTTP micropayments. As more APIs and data services adopt the x402 protocol, agents can pay per-request in stablecoins as part of the normal HTTP flow. No API keys to manage. No subscriptions. The agent just pays for what it uses.
Every command is a dry run by default
Before any transaction broadcasts, the CLI shows your agent exactly what will happen. In agentic contexts where an agent might be making thousands of decisions, preview-before-commit is the safety layer that keeps humans in control of what actually touches the chain.
# Preview (default — no --broadcast flag)
celo-agent send --to 0xRecipient --amount 10 --symbol USDC
# Execute (explicit opt-in)
celo-agent send --to 0xRecipient --amount 10 --symbol USDC --broadcastQuick Start
# Install
npm install -g celo-agent-cli
# Interactive setup — wallet, identity, registry, scaffold all in one
celo-agent init
# Or step-by-step:
celo-agent setup --name my-agent --max-spend 100 --expiry 7
celo-agent status
celo-agent send --to 0xRecipient --amount 10 --symbol USDC --broadcast
celo-agent balanceSDK Usage
import { createWalletClient } from 'celo-agent-sdk'
const wallet = createWalletClient()
// Send USDC
const result = await wallet.send({ to: '0xRecipient', amount: '10', token: 'USDC' })
console.log(result.txHash)
// Check balance
const balance = await wallet.balance()
console.log(balance.balances)
// Pay for an API with x402
const fetchWithPay = wallet.x402Fetch({ maxAmount: '1000000' })
const res = await fetchWithPay('https://paid-api.com/data')How It Works
┌─────────────────────────────────────────────────────────────────────┐
│ ONE-TIME SETUP (human) │
│ │
│ 1. celo-agent init │
│ 2. CLI generates session keypair → encrypts to disk (chmod 600) │
│ 3. Browser opens → human approves with passkey │
│ 4. Passkey signs UserOp → grantPermissions(sessionKey, limits) │
│ 5. Smart wallet stores session key + limits on-chain │
│ │
│ Passkey is used only here. Never again at runtime. │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ AGENT RUNTIME (headless) │
│ │
│ Agent ──SDK──▶ celo-agent send --to 0x... --amount 10 --symbol USDC│
│ │ │
│ ├─ Loads encrypted session key from disk │
│ ├─ Builds + signs UserOp │
│ ├─ Submits to Bundler │
│ ├─ Smart Wallet validates via PermissionManager │
│ └─ Returns { txHash, status } as JSON │
│ │
│ Agent never sees the key. Signing happens inside CLI process. │
└─────────────────────────────────────────────────────────────────────┘Architecture
┌─────────────────────────────────────────────────────────┐
│ Your AI Agent │
│ │
│ import { createWalletClient } from 'celo-agent-sdk' │
│ const wallet = createWalletClient() │
│ await wallet.send({ to, amount, token }) │
└──────────────────────┬───────────────────────────────────┘
│ child_process.execFile
▼
┌─────────────────────────────────────────────────────────┐
│ celo-agent CLI (secure core) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ keystore │ │ account │ │ commands │ │
│ │ encrypt │ │ load JAW │ │ send/call │ │
│ │ decrypt │ │ Account │ │ sign/x402 │ │
│ │ chmod600 │ │ │ │ 8004/self │ │
│ └──────────┘ └──────────┘ └───────────┘ │
│ │
│ All key material stays in this process. │
│ Outputs clean JSON to stdout. │
└──────────────────────┬───────────────────────────────────┘
│ UserOp (ERC-4337)
▼
┌─────────────────────────────────────────────────────────┐
│ On-Chain (Celo Sepolia) │
│ │
│ JAW Smart Wallet (ERC-4337) │
│ ├── Owner: human passkey (root signer) │
│ ├── Session key: agent (scoped signer) │
│ └── JustaPermissionManager │
│ ├── spending limits │
│ ├── token whitelist │
│ ├── function selectors │
│ └── expiry │
│ │
│ ERC-8004 Agent Registry │
│ ├── Agent NFT (identity) │
│ ├── Reputation (feedback from other agents) │
│ ├── Self.xyz TEE attestation │
│ ├── ENS subname (celo-agent.eth) │
│ └── OASF capabilities (IPFS) │
│ │
│ Pimlico Paymaster │
│ └── Gasless transactions in stablecoins │
└─────────────────────────────────────────────────────────┘On-Chain Footprint (per agent)
| Registry | What's stored | |----------|--------------| | JAW Smart Wallet | ERC-4337 account with session key permissions | | ERC-8004 Identity | Agent NFT + metadata (name, description, services, trust) | | ERC-8004 Reputation | Feedback from other agents (score, tags, evidence) | | Self.xyz | TEE attestation (ZK passport proof) | | ENS | Human-readable name → multi-chain address resolution | | IPFS | OASF capabilities record (skills, domains) |
Security Model
| Threat | Mitigation |
|--------|------------|
| Agent reads private key | Signing inside separate CLI process — key never in agent memory |
| Agent reads keystore file | chmod 600 — only CLI owner can read |
| Stolen keystore file | Encrypted with machine secret (sha256(hostname + username)) — useless on another machine |
| Session key leaks | Spend limits enforced on-chain by JustaPermissionManager |
| Prompt injection | No key in LLM context — nothing to extract |
| Agent overspends | Daily limits enforced by smart contract, not by trust |
| Session key expired | Agent can't transact — human must re-run setup |
x402 Protocol
x402 enables pay-per-request APIs using on-chain USDC payments. No API keys — the cryptographic signature IS the payment.
Client (pay for APIs)
import { createWalletClient } from 'celo-agent-sdk'
const wallet = createWalletClient()
const fetchWithPay = wallet.x402Fetch({ maxAmount: '1000000' })
const res = await fetchWithPay('https://paid-api.com/data')Server (charge for APIs)
import express from 'express'
const app = express()
const PAYEE = '0xYourAddress'
const USDC = '0x01C5C0122039549AD1493B8220cABEdD739BC44E' // Celo Sepolia
app.get('/paid-data', (req, res) => {
const payment = req.headers['x-payment']
if (!payment) {
const requirements = {
accepts: [{
scheme: 'exact',
network: 'eip155:11142220',
maxAmountRequired: '10000', // 0.01 USDC
payTo: PAYEE,
asset: `eip155:11142220/erc20:${USDC}`,
}],
}
const encoded = Buffer.from(JSON.stringify(requirements)).toString('base64')
res.setHeader('PAYMENT-REQUIRED', encoded)
return res.status(402).json(requirements)
}
res.json({ data: 'premium content' })
})x402 Flow
Client Server Chain
│ │ │
├── GET /paid-data ──────────────▶ │
│ │ │
◀── 402 + payment requirements ──┤ │
│ │ │
├── sign EIP-3009 ─────────────── │
│ │ │
├── GET /paid-data ──────────────▶ │
│ + payment header │ │
│ ├── verify + settle ────────▶│
│ │ │
◀── 200 + data ──────────────────┤ │CLI Reference
Every command outputs clean JSON to stdout. Errors output { "error": "message" }.
| Command | Description |
|---------|-------------|
| celo-agent init | Interactive onboarding: wallet + identity + registry + scaffold |
| celo-agent setup | Generate session key + grant permissions (passkey) |
| celo-agent send | Send CELO or USDC tokens |
| celo-agent balance | Check wallet balances |
| celo-agent call | Execute arbitrary contract calls |
| celo-agent status | Show agent config + permission status |
| celo-agent revoke | Revoke session key permissions |
| celo-agent sign | Raw / EIP-191 / EIP-712 signing |
| celo-agent x402-sign | Sign x402 payment (EIP-3009) |
| celo-agent export | Re-encrypt keystore for Docker deployment |
| celo-agent ens-claim | Claim ENS subname on celo-agent.eth |
| celo-agent self-register | Self.xyz TEE identity verification |
| celo-agent 8004-register | Register on ERC-8004 Identity Registry |
| celo-agent 8004-metadata | Update agent metadata on-chain |
| celo-agent 8004-reputation | Read/submit reputation feedback |
Deployment
# 1. Export keystore for deployment
celo-agent export --dir deploy
# 2. Set env vars on hosting provider (Render, Fly, Railway)
# JAW_KEYSTORE_B64=<from .env.deploy>
# JAW_CONFIG_B64=<from .env.deploy>
# PORT=3000
# 3. Deploy — Dockerfile handles CLI install, entrypoint decodes secrets
# BASE_URL auto-detected on Render/Fly/RailwayThe server template includes A2A + MCP endpoints and auto-updates ERC-8004 metadata with live service URLs on startup.
Environment Variables
All variables have hardcoded defaults for Celo Sepolia testnet. No .env file required to get started.
| Variable | Default | Description |
|----------|---------|-------------|
| JAW_API_KEY | built-in | JAW API key |
| JAW_CHAIN_ID | 11142220 | Chain ID (Celo Sepolia) |
| JAW_USDC_ADDRESS | per-chain | USDC contract address |
| PIMLICO_API_KEY | built-in | Pimlico paymaster API key |
| JUSTANAME_ENS_DOMAIN | celo-agent.eth | Parent ENS domain |
| PINATA_JWT | built-in | IPFS pinning (Pinata) |
Scaffolding Templates
celo-agent init --template <name> --dir <path>| Template | What you get |
|----------|-------------|
| server | Express server with A2A + MCP + x402 endpoints + Dockerfile |
| x402-agent | x402 payment client + server |
| transfer-agent | Token transfer agent |
| custom | Minimal starter |
Each template includes example files for send-tx, x402-server, and x402-client.