Pay. Verify. Create your agent. Access the onchain economy.
The missing SDK between real humans and the Celo agentic economy.
root-agent-sdk gives any Celo project 3 core functions to onboard verified humans and create AI agents with economic agency:
createUser()— Auto wallet + fiat ramp (WaaP + Transak)verifyUser()— Human verification with Self Agent ID (ZK credentials)createAgent()— ERC-8004 agent wallet with inherited ZK credentials
Plus optional:
createEscrow()— Conditional payments with configurable split fees (PsyEscrow)
npm install root-agent-sdkimport { RootAgent } from 'root-agent-sdk'
const root = new RootAgent({
celoNetwork: 'mainnet',
transakApiKey: 'your-key',
selfConfig: { appId: 'your-app', scope: ['humanity'] }
})
// 1. Onboard a real human
const user = await root.createUser({ method: 'email', email: 'user@example.com' })
// 2. Fund their wallet (returns Transak URL)
const fundUrl = await user.fundWallet()
// 3. Verify their identity (ZK, no data exposed)
const verified = await root.verifyUser({
user,
method: 'self',
scope: ['humanity', 'sanctions']
})
// 4. Create their agent with inherited credentials
const agent = await root.createAgent({
owner: user.wallet,
name: 'myAgent',
selfCredentials: verified.zkCredentials,
permissions: ['transfer', 'escrow']
})
// Agent can now transact on Celo with verifiable human identity
await agent.execute({ to: '0x...', value: '1000000' })PsyChat is a mental health platform where psychologists offer therapy sessions to patients on Celo. The root-agent-sdk powers the full flow:
- Patient onboarding —
createUser()gives each patient a Celo wallet and lets them buy cUSD via Transak - Identity verification —
verifyUser()confirms the patient is a real human via Self Protocol (ZK proof of humanity), without exposing personal data - Payment agent —
createAgent()creates an AI agent that manages session payments. The agent inherits the patient's ZK credentials, proving it acts on behalf of a verified human - Session escrow —
createEscrow()deploys a PsyEscrow contract that holds cUSD until the session completes:- Patient deposits before the session
- If they cancel 48h+ in advance → full refund
- After session completes → 85% to psychologist, 10% to platform, 5% gas reserve
- No-show after 1h grace → same split (anti-dropout)
- Emergency timeout at 7 days → auto-release
const escrow = await root.createEscrow({
agent: agent.wallet,
splits: {
provider: { address: psychologist.wallet, share: 8500 },
platform: { address: '0xPlatform...', share: 1000 },
gasReserve: { share: 500 }
},
cancelWindow: 48 * 3600,
timeout: 7 * 86400
})
// Patient deposits for a session
await escrow.instance.deposit('session-001', psychologist.wallet, '25.00', scheduledTime)
// After session completes, agent releases payment
await escrow.instance.release('session-001')Creates a new SDK instance.
interface RootAgentConfig {
celoNetwork: 'mainnet' | 'alfajores' // Required
transakApiKey?: string // For fiat on-ramp
selfConfig?: { // For identity verification
appId: string
scope: SelfScope[] // 'age' | 'nationality' | 'sanctions' | 'humanity'
}
waapConfig?: { // For managed wallets (Human.tech)
appId: string
apiKey: string
}
gasSponsorship?: boolean // Enable gas sponsorship
}Creates a new user with an auto-generated Celo wallet.
const user = await root.createUser({
method: 'email', // 'email' | 'social' | 'phone'
email: 'user@test.com' // required if method is 'email'
// socialProvider: 'google' | 'apple' | 'twitter' — if method is 'social'
// phone: '+1234567890' — if method is 'phone'
})Returns: RootUser
| Field | Type | Description |
|---|---|---|
wallet |
string |
Celo wallet address |
method |
string |
Auth method used |
identifier |
string |
Email, phone, or social ID |
fundWallet() |
() => Promise<string> |
Returns Transak URL for buying cUSD |
verified |
boolean |
Whether identity is verified |
selfId |
string? |
Self Agent ID (after verification) |
Verifies a user's identity using Self Protocol with ZK proofs.
const verification = await root.verifyUser({
user: user, // RootUser from createUser()
method: 'self', // Verification provider
scope: ['age', 'nationality', 'sanctions'] // Credentials to verify
})Returns: UserVerification
| Field | Type | Description |
|---|---|---|
selfId |
string |
Self Agent ID |
soulboundNFT |
string? |
Soulbound NFT reference |
zkCredentials |
ZKCredential[] |
Array of verified ZK credentials |
verified |
boolean |
All requested scopes verified |
Creates an ERC-8004 AI agent with its own wallet.
const agent = await root.createAgent({
owner: user.wallet,
name: 'myAgent',
selfCredentials: verification.zkCredentials, // Optional: inherit human's ZK creds
permissions: ['transfer', 'escrow'] // 'transfer' | 'escrow' | 'swap' | 'delegate'
})Returns: RootAgentInstance
| Field | Type | Description |
|---|---|---|
wallet |
string |
Agent's Celo wallet |
owner |
string |
Owner's wallet address |
name |
string |
Agent name |
selfId |
string? |
Agent's Self ID |
zkCredentials |
ZKCredential[]? |
Inherited ZK credentials |
permissions |
AgentPermission[] |
Allowed operations |
execute(tx) |
Function |
Execute a transaction |
id |
string? |
Agentscan registration ID |
const result = await agent.execute({
to: '0xRecipient...',
value: '1000000', // Amount in wei (for cUSD transfers)
data: '0x...' // Optional: raw calldata for contract calls
})
// Returns: { hash, status: 'success' | 'failed', blockNumber }Deploys or connects to a PsyEscrow smart contract.
const escrow = await root.createEscrow({
agent: agent.wallet,
splits: {
provider: { address: '0xPsychologist...', share: 8500 },
platform: { address: '0xPlatform...', share: 1000 },
gasReserve: { share: 500 }
},
cancelWindow: 48 * 3600, // 48 hours in seconds
timeout: 7 * 86400 // 7 days in seconds
})// Deposit cUSD for a session
await escrow.instance.deposit('session-id', psychologistAddress, '25.00', scheduledTimestamp)
// Release funds after session completes (split fee applied)
await escrow.instance.release('session-id')
// Cancel session (full refund if before cancel window)
await escrow.instance.cancel('session-id')
// Claim no-show (after grace window)
await escrow.instance.claimNoShow('session-id')
// Read session state
const session = await escrow.instance.getSession('session-id')Registers an agent on agentscan.info.
const agentId = await root.registerAgent(agent)┌─────────────────────────────────────────────────────────┐
│ Your App / DApp │
├─────────────────────────────────────────────────────────┤
│ root-agent-sdk │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │createUser│ │verifyUser│ │createAgent│ │ escrow │ │
│ │ │ │ │ │ │ │ │ │
│ │ WaaP / │ │ Self │ │ ERC-8004 │ │PsyEscrow│ │
│ │ ethers │ │ Protocol │ │ wallet │ │contract │ │
│ │ Transak │ │ ZK proofs│ │agentscan │ │ splits │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘ │
│ │ │ │ │ │
├───────┴──────────────┴──────────────┴──────────────┴─────┤
│ Celo Network │
│ (mainnet / alfajores) │
│ │
│ cUSD (ERC-20) · Soulbound NFTs · PsyEscrow.sol │
└─────────────────────────────────────────────────────────┘
For advanced usage, the SDK also exports:
import {
getCeloProvider, // Get ethers JsonRpcProvider for Celo
getCUSDBalance, // Get cUSD balance for any wallet
sendCUSD, // Send cUSD ERC-20 transfer
estimateGas, // Estimate gas for a transaction
buildTransakUrl, // Build Transak on-ramp URL
SelfAdapter, // Identity adapter (pluggable)
PSYESCROW_ABI, // PsyEscrow contract ABI
} from 'root-agent-sdk'| Network | Chain ID | RPC |
|---|---|---|
| Mainnet | 42220 | https://forno.celo.org |
| Alfajores | 44787 | https://alfajores-forno.celo-testnet.org |
MIT