Agent Capital Tree
Give AI agents capital without giving them the whole wallet. A human funds a root vault, then agents delegate smaller amounts into separate child vaults. ENSv2 roles and contract-enforced ancestor policies narrow what each child can do. The owner retains an independent recovery path.
ENSv2 Enhanced Access Control supplies the roles. Separate vaults bound each agent’s available funds. Uniswap v4 enables bounded swaps and liquidity positions; x402 enables service purchases with official Circle USDC. Curvegrid MultiBaas indexes the controller’s capital and strategy events.
Read-only preview recording. Balances, nodes and activity in the GIF are illustrative. The live dashboard and MCP read Ethereum Sepolia independently.
Live dashboard · Live Sepolia tree · MCP guide · Local setup · Jury walkthrough · Current status
The prototype runs on Ethereum Sepolia (chain 11155111) with official Circle Test-USDC. Uniswap v4 supports bounded swaps and vault-owned liquidity positions. x402 supports scoped service purchases. Curvegrid MultiBaas indexes controller capital and strategy events. Public contract addresses are in usdc-sepolia.json. This is an unaudited hackathon prototype using testnet assets.
Open the live root vault to inspect a real Sepolia tree without a wallet. Explicit preview mode contains illustrative balances and names. The live demo contains five real vaults over three levels: Capital → Researcher, Trader and Liquidity; Trader → Risk check. It includes a confirmed 0.010 Test-USDC x402 payment, a 0.010-token swap, two vault-owned LP NFTs and indexed policy/fee events. Current E2E evidence. Viewing a vault does not start a worker or authorize a transaction.
To check the keyless local MCP from the current checkout, use Node 22+, pnpm and Codex CLI. From an existing checkout, start at pnpm install; clone only when you need a new checkout:
git clone https://github.com/CodeByNikolas/agent-capital-tree.git
cd agent-capital-tree
pnpm install --frozen-lockfile --ignore-scripts
pnpm --filter @agent-capital-tree/sdk build
pnpm --filter @agent-capital-tree/multibaas build
pnpm --filter @agent-capital-tree/plugin build
pnpm --filter @agent-capital-tree/runtime build
pnpm mcp:doctor
pnpm mcp:verify
pnpm mcp:chat-verify
These checks need internet access for the public app and Sepolia RPC. They use a disposable Codex profile or a keyless local STDIO server and send no transaction. The setup guide explains how to register that server in Codex or Claude and ask for the live tree image. Wallet and companion writes have separate prerequisites and acceptance status in STATUS.md.
- A human creates and funds a root vault, then authorizes a master-agent operator.
- The master transfers part of its capital into a child vault. Children may delegate again within a three-level tree.
- Each node has a real ENS subname and EAC roles. Our controller explicitly checks ancestor policies, current authority, expiry and revocation.
- Each runtime worker has its own key, workspace and authenticated MCP context in a separate Docker container. Model-supplied IDs cannot select a parent’s signer.
- The human retains an independent recovery path for remaining assets, including closing existing LP positions.
Capital allocation is an actual transfer, not an overbookable allowance. Amount ceilings are per action, not cumulative spending limits. The vault’s allocated balance bounds total exposure. Model intelligence is not a security boundary; recovery does not guarantee the original dollar value.
Vaults are non-upgradeable EIP-1167 proxies: every root and child has a separate 45-byte contract, token balances and LP state, with one shared immutable implementation. VaultFactory deploys and initializes the controller binding in the same transaction; the implementation and initialized clones reject reinitialization. ENS registries are still deployed individually. Proxy deployment saves gas; calls incur a small delegation overhead. Existing full vaults cannot be converted in place.
The public researcher spawn used 3,556,781 gas, down from 5,914,316 for its full-vault predecessor (39.86% less), including the ENS registry and capital allocation. Both receipts document the comparison.
Native Codex subagents do not automatically become capital workers. For the short demo, use createChildVault: the current chat manages a real ENS node, vault and allocation without Docker or another model process. spawnChild is the separate autonomous-worker option. No automatic Codex hooks are enabled.
Service purchases: getPaymentServices lists explicitly configured services. purchaseService follows x402 v2’s HTTP402 flow. The agent signs an exact EIP-3009 authorization for its vault, recipient, amount, validity window and nonce. The vault’s ERC-1271 verifier checks the current ENS/PAY mandate at settlement. Nonces bind the authority generation, and retries retain the same authorization. The companion independently verifies Circle’s Transfer and AuthorizationUsed receipt events.
The supported payment token is Circle Sepolia USDC at 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238, with six decimals. 10000 raw units is 0.010000 USDC. Obtain test tokens from Circle’s faucet; the app cannot mint Circle USDC.
The x402 facilitator submits the signed authorization and pays settlement gas. USDC moves from the agent vault to the service provider. The agent can sign this payment without holding ETH; direct controller transactions such as delegation and swaps still require ETH in the transaction sender's wallet. The vault itself does not need ETH.
Uniswap: typed swaps and vault-owned LP positions use one fixed v4 pool. Management, fee collection and exit are separate permissions. The quote token is DEMO-USD, a clearly valueless six-decimal demo asset. Its pool price is not a real USD valuation. Agents cannot supply arbitrary router commands or redirect outputs.
Future work: policy-checked generic contract transactions, cumulative/rolling spending budgets cross-currency valuation, and an owner wallet embedded directly inside chat are not implemented. A child cannot spend more tokens than its vault currently owns; "cumulative budget" here means a separate lifetime or rolling counter that would remain binding even after top-ups or trading proceeds. The keyless MCP renders the live ENS agent tree as PNG with a Mermaid fallback.
Onboarding offers root creation and Open live demo. The Overview includes a dismissible How it works introduction with a six-step tour that retains the current vault or explicit preview, a balance ledger and a vault register. A shadcn sidebar provides separate pages for Agent tree, Activity, Uniswap, x402 Pay, Curvegrid, Applications, MCP and Setup & control. Curvegrid contains the per-agent MultiBaas report. Sidebar and header persist across navigation; the header stays visible while scrolling. The wallet button opens Sign out and an explorer link; app sign-out persists until explicit reconnect. Setup integration status is always expanded. Fraunces and IBM Plex, explicit dark/light themes and the supplied logo follow the corrected Kanoki design scope. USDC and DEMO-USD stay separate. Selecting a node opens its balance, capabilities and limits. A zero-USDC root links to Circle's faucet; funding uses the owner wallet.
See ENS ownership and namespace permissions for how users receive names without a server-side signing key.
Enter a vault contract address or a registered name under kanoki.eth in Open vault. Internal numeric IDs are not accepted in this field. Without a selected vault, the app shows onboarding; illustrative data requires explicit preview mode. All preview names, addresses and balances are illustrative examples, not evidence of contracts or funds. All earlier prototype vaults still exist on Sepolia but are outside the current Kanoki dashboard and MCP deployment. An active mandate does not imply an agent process is running.
Current balances and permissions come directly from Sepolia. MultiBaas history covers controller-emitted capital/strategy events. The Payments page independently scans Circle USDC AuthorizationUsed events for this tree's vaults and verifies same-transaction transfers in successful receipts. It shows the scanned block range and explicitly flags truncated coverage. This proves token settlement, but chain receipts alone cannot prove x402 merchant intent or service delivery. Indexing delay and the actual controller-history coverage boundary remain visible.
| Partner | Contribution | Code |
|---|---|---|
| ENS | Nested registries, real subnames, native EAC roles including PAY; contract-enforced ancestor restrictions | ManagedRegistry, Controller |
| Uniswap | Fixed-pool v4 swaps, vault-owned PositionManager NFT, typed LP lifecycle and independent owner exit | Swap authorization, vault swap, LP lifecycle, FEEDBACK.md |
| Curvegrid | MultiBaas event queries, receipt enrichment and canonical RPC verification for UI and MCP | Adapter, plan limits |
ENS roles are actual authorization, not descriptive text metadata. MultiBaas is an indexer, not an authorization service. Its free plan allows only a 100-block backfill; indexing is configured before new demo activity.
Use case: make delegated agent capital movements inspectable by the human owner and queryable through MCP. MultiBaas Event Queries supply controller history filtered by root; our adapter decodes allocations, recovery, policy changes, swaps and LP events. We independently check returned events against canonical RPC receipts before displaying them.
The Agent activity report lets reviewers select a vault, inspect its receipt-linked events, and compare allocations received, onward delegations, returns and swap input/output totals per token. These are totals from loaded events, not current balances, profit or lifetime expenditure. Source: MultiBaas adapter, activity API, agent report.
What worked: indexed, decoded contract events give the dashboard and MCP a common history interface. Root-filtered queries and receipt links make delegated capital flows explainable without relying on the agent's own account of what it did. Indexing was configured before the current demo's transactions.
Limits and challenges we encountered:
- 100-block historical backfill: our Default/free plan permits starting event indexing at most 100 blocks behind the chain head. This is a limit on backfilling previously unindexed events, not a statement that every query can only see the latest 100 blocks. Starting the indexer late cannot reconstruct older activity on this plan. We configured indexing before new demo activity and expose its starting block. Retention is a separate limit.
- Plan ceilings: the instance reported 2 indexed events/second, 30,000 API calls/month and 72 hours of event-log retention. These are this plan's reported limits, not universal MultiBaas limits or a guarantee that our history is complete. Historical contract calls were also disabled; that flag is separate from event backfill. See the recorded plan findings and sources.
- Index status and returned events can differ: the reported checkpoint lagged behind some events already returned by queries. The UI therefore shows the reported checkpoint, actual loaded event blocks, lag and canonical receipt verification separately. A valid receipt establishes an event's contents, not completeness of the index.
- Pagination and availability: summaries cover only loaded pages. More pages, missing older history or an unavailable indexer must not look like zero spending. The agent report shows loading skeletons and hides totals on history errors. Current balances, permissions and owner recovery use direct contract access independently of MultiBaas.
- Scope: this integration indexes our controller events. x402 USDC settlements have their own RPC-based history and are not attributed to MultiBaas. We do not claim an intentionally induced provider-outage E2E; controlled UI error responses test the display behavior only.
Developer feedback: clearer onboarding around backfill versus retention, explicit warnings when a requested start block exceeds the plan, and clearer checkpoint semantics relative to query results would help teams build reliable historical views. A documented example combining pagination, index coverage and reorg handling would also help.
Setup and tests: follow local setup and the commands below. The MultiBaas package contains adapter and verification tests. node --experimental-strip-types scripts/test-agent-activity.mjs checks exact totals and attribution; ACT_TEST_APP_URL=https://kanoki-app.vercel.app node scripts/test-agent-activity-browser.mjs checks the live report plus controlled loading/error states without sending transactions.
Standalone team profile: TEAM.md.
We are Nikolas Hack and Rami Ezzeddine, both studying Information Systems (Wirtschaftsinformatik) at the Technical University of Munich (TUM) and members of the TUM Blockchain Club. Together, we defined Kanoki's product scope, permission model and user flows, and reviewed the AI-assisted implementation; see our AI-use disclosure.
- Nikolas Hack — Head of IT & Development at TUM Blockchain Club, with a focus on building digital products. His personal portfolio uses React, Next.js and TypeScript. GitHub: @CodeByNikolas · Website.
- Rami Ezzeddine — Head of Legal & Finance at TUM Blockchain Club, building full-stack Web3 and AI applications with interests in DeFi, real-world asset tokenization and usable crypto interfaces. His background includes enterprise IT and SAP HCM consulting. GitHub: @raglibol-re · LinkedIn · X: @Rami15_.
For a fast local read-only check on Node 22+ hosts, run pnpm mcp:doctor, pnpm mcp:verify and pnpm mcp:chat-verify after installing dependencies and building SDK, MultiBaas, plugin and runtime. These use no wallet or signing key. The three-tool keyless server can be registered in Codex or Claude to view a live Sepolia tree and open the normal wallet browser for root setup. Its tool responses include dashboard-style PNGs with Mermaid fallback. See the local setup guide.
For chat-managed vaults on macOS, Linux or WSL2, install the bundled Kanoki plugin or build SDK, MultiBaas, plugin and runtime and run pnpm mcp:capital settings --enable-sepolia-writes. The default capital MCP exposes 22 tools, with no Docker, model key or runtime bearer required. Ask it to prepare a vault, approve the guided wallet setup, then return to chat: the matching root is restored automatically. The owner key stays in the wallet; a separate local operator signs bounded actions. createChildVault creates a funded vault, not an autonomous model process. Shared-limit onboarding requires an explicitly confirmed root-and-children limit and separate funding amount. Limited roots support delegation, restriction and reclaim; swaps, LP and x402 require an unrestricted root. The new controller release is still pending; see release gates. Advanced selection/recovery is only for intentionally selected existing roots. See the setup guide and actual acceptance status. New changes are published on main.
For autonomous workers, use Node 22, pnpm 11.13.1, Docker and Foundry 1.8.3. Follow the complete setup guide for wallet/operator separation, a private companion configuration, OpenAI API-key setup (preferred) and MCP registration. The host app-server holds inference authentication; Docker workers stay network isolated and receive scoped finance tools. ChatGPT/Codex login is an alternative, and HomeBox CLIProxyAPI remains an optional explicit configuration.
pnpm install --frozen-lockfile --ignore-scripts
pnpm build
pnpm typecheck
pnpm test
bash contracts/scripts/test-contracts.sh
node scripts/test-usdc-fork.mjs --payments
The fork test uses the actual Circle proxy and deployed Uniswap contracts on a disposable local Sepolia fork. It checks delegation, signatures, inherited restrictions, revocation, x402 settlement, retry behavior, LP opening/closure and recovery. It does not send public transactions or override token balances. See fork evidence and STATUS.md for the exact completed checks and current public acceptance.
Deployment runners require an Etherscan key in ETHERSCAN_API_KEY or the private file ~/.agent-capital-tree/etherscan-api-key. They finish with explorer verification. node scripts/verify-deployment.mjs verifies the current implementation, factories, controller, project/child registries, quote token and all existing vault-proxy associations, without wallet access or onchain writes. Run it after additional dashboard/MCP-created roots or children. It submits standard JSON from the compiled artifact's exact settings and hash-checked sources; the key is never included in that submission's source code. Verification results are recorded in the deployment manifest.
The controlled x402 seller is loopback-only, charges 0.01 USDC, and uses the test owner as recipient. It demonstrates the real protocol; it is not an independent commercial merchant. The companion’s service allowlist is a runtime restriction, not an onchain merchant allowlist. Service content remains untrusted.
Historical browser-wallet and native financial proofs are recorded in ACCEPTANCE.md. On the retired pre-Kanoki controller, native OpenAI API-key inference with gpt-6-luna / high passed funded MCP spawn, x402 payment and Uniswap swap on Sepolia (evidence). ChatGPT-login financial E2E, independent external-machine onboarding and native-marketplace financial writes remain unproven. The controlled seller and testnet token scope is stated in the evidence.
PLAN.md records product decisions. STATUS.md tracks completed deployment/tests and remaining work. Submission requirements and AI-use provenance are documented for the team. Team details are complete. The user reported submitting the Uniswap feedback form; no URL field was requested. ETHGlobal submission and partner selections still need confirmation.
Current Kanoki x402 proof: deployments/kanoki-payment.json. Researcher spent 0.010 Test-USDC; retry did not charge again. Settlement transaction. The seller was controlled and local. The current demo E2E and node scripts/test-live-demo.mjs cover real vaults, swaps, LPs, payment receipts and MultiBaas events. Earlier usdc-payment.json, usdc-multibaas.json and native-model reports belong to retired deployments; the latest Kanoki demo did not launch autonomous workers.