Autonomous on-chain position management on the CROO Agent Protocol. A constellation of six agents that monitor, execute, and independently verify real money moves on Base, USDC settled, every step backed by a real transaction hash.
Hire on CROO · HelmExecutor on Base · CROO Protocol · Basescan
HELM is a constellation of six CROO agents that work as one trading desk. A Watcher monitors a position and, on a price trigger, orchestrates a full rebalance across the others. A Hand executes the real swap on Base through a deployed executor contract and forwards the proceeds to the end user. A Notary independently attests the swap from three on-chain witnesses. A Scribe writes the cited report. An Advisor sells on-chain-verified research and deep token-safety. A Lookup maps the agent-to-agent order graph and scores every provider's on-chain reputation. One rebalance emits three A2A orders across three counterparty agents, each backed by a real Base transaction hash. It is multi-asset (any registered Base token), priced verified-first (stablecoin, then Chainlink, then DEX), and bounded by real money-path guards. Built for the CROO Agent Hackathon.
HELM is the only entry that exercises CAP's fund-transfer path: it moves real USDC through a deployed HelmExecutor contract, swaps it on Aerodrome, and returns the output to the user, all validated against CROO's on-chain order state. Most agents on a marketplace only advise; HELM advises, then acts, then proves it acted, hiring three independent agents to do the acting and the proving so no single agent both moves money and grades its own work.
The whole thing is verifiable rather than trust-me. Every price the Advisor quotes is read live from Chainlink and Aerodrome; every swap the Hand runs lands as a real Base transaction; every attestation the Notary signs reconciles the fill across three independent witnesses; and every agent-to-agent order is indexed straight from CAPCore events, so provider reputation is objective and permissionless. The agents are registered on CROO and run live under pm2; the contract is deployed on Base mainnet. This repository is that working build.
- What HELM Does
- Why It Exists
- How It Works
- The Constellation and the Watcher's Orchestration
- The Hand and the HelmExecutor Contract
- The Notary: Independent On-Chain Verification
- The Scribe: Cited Reports
- The Advisor: On-Chain-Verified Research and Token-Safety
- The Lookup: CAPSCOPE Graph and Reputation
- Multi-Asset and Verified-First Pricing
- The Money-Path Guards
- The Human and AI Front Door: Console and MCP
- Deployed on Base
- The Agents (Live on CROO)
- Verify It Yourself
- Using HELM
- Project Structure
- Quick Start
- Tech Stack
- Security and Operational Notes
- For Judges and Reviewers
HELM is six agents working as one:
-
A Watcher (orchestrator). It takes a monitoring order, polls the price within the CAP delivery SLA, and on a deterministic trigger runs a full rebalance: it hires a Hand to swap, a Notary to attest, and a Scribe to report, sequentially, and returns their real tx hashes. An optional LLM may add judgment but can only hold, never force a move, so a hallucination can never touch funds.
-
A Hand (execution). It executes the real swap on Base through the
HelmExecutorcontract, using CAP's fund-transfer path. It routes to the best venue net of gas, floorsminOuton a fresh Chainlink price, is bidirectional (buys and sells), and forwards the output to the beneficiary the user names. -
A Notary (verification). It re-reads the swap transaction and reconciles
amountOutacross three independent witnesses (the ERC-20 Transfer, the AerodromeSwap, and the executor's ownSwapExecuted), scores the fill against the Chainlink oracle, scans the block for a sandwich, and returns a signed pass or fail attestation with a keccak256 hash. It is barred from attesting a swap run by its own agent. -
A Scribe (reporting). It turns the executed action into a concise, cited, human-readable report: what moved, the realized rate, the verdict, and the real Base transaction behind it.
-
An Advisor (research). It sells on-chain-verified research and advisory: verified prices, oracle-vs-DEX divergence, price impact, volatility, portfolio valuation, idle-yield comparison, and deep token-safety (EIP-1967 proxy detection plus a sell-tax and honeypot round-trip). Every number is read live from Base; the model only interprets it. The Watcher also hires the Advisor as a pre-trade safety gate.
-
A Lookup (CAPSCOPE). It indexes the CROO agent-to-agent order graph straight from CAPCore events and scores every provider's on-chain reputation (clear-rate, refund-rate, volume). The reputation lane can only score itself; HELM reads cross-agent history permissionlessly.
Put together: a position is watched, a swap is executed, the swap is independently verified, and the result is written up, with the whole flow discoverable as a real order graph and every counterparty ranked by objective reputation.
On-chain position management is repetitive, adversarial work: watch a price, decide, route the trade, floor the slippage, submit, then prove the fill was fair and not sandwiched. Doing it by hand is slow; handing it to a single "trading agent" asks you to trust one black box with your money and its own report card.
HELM splits the job across a market of specialized agents that hire each other over CROO. The agent that moves the money is not the agent that grades the trade, and neither is the agent that ranks the providers. The Watcher orchestrates but cannot withdraw; the Hand executes but its output is bound to the user's beneficiary; the Notary verifies but is excluded when it shares an agent with the Hand. The result is a division of labor where each step is checkable and no step trusts the previous one's word.
It is also deliberately verifiable rather than confident. Pure-LLM research agents will state a price with total conviction and no source. HELM's Advisor reads the price from a Chainlink feed and an Aerodrome pool, cross-checks them, and lets the model only interpret the verified numbers, so the information is trustworthy even when the phrasing is generated. Every claim the system makes resolves to a real Base transaction, a live on-chain read, or a public CAPCore event.
A user (or a Navigator agent) hires the Watcher's "Position Monitor" service with a threshold and an amount. The Watcher polls the price for a bounded window kept inside the CAP delivery SLA. When the deterministic trigger fires, an optional LLM makes the final call and explains its reasoning; if it declines, the Watcher keeps watching. On a go, it runs the rebalance sequentially: hire Hand, then Notary, then Scribe. Payments go through a serialized queue so a real parallel fan-out actually settles instead of colliding on the AA-wallet nonce. If the window elapses with no trigger, it delivers a clean "no action" result so the order still settles.
Providers are chosen best-first by objective on-chain reputation, with a self-healing reroute for the non-fund steps. The funded Hand step fails closed: it never re-escrows a principal on retry, so a reroute can never double-spend the user's money.
HelmExecutor (Solidity 0.8.28, OpenZeppelin AccessControl plus ReentrancyGuard) is the one contract HELM deploys. CROO deploys no shared swap executor, so each fund order routes its providerFundAddress to this contract. A keeper (the Hand's operator key) calls executeSwap(orderId, tokenIn, tokenOut, amountIn, minOut, dexTarget, data, beneficiary). The contract validates the order against CAPCore, swaps through a whitelisted DEX (Aerodrome), enforces received >= minOut, sends the output and any unspent input to the beneficiary (the end user, or the order requestor if unset), and calls markFundExecuted so CAP clears the order. A refundToRequestor path returns trapped principal if a swap cannot run.
Fund execution is gated on-chain: CAPCore's markFundExecuted is restricted to holders of FUND_EXECUTOR_ROLE, which CROO grants to the deployed executor. Until it is granted, executeSwap reverts at that step, which is the one item still pending for live swaps (see Deployed on Base).
The Notary takes a swap tx hash and reconstructs the fill from three independent sources in the receipt: the ERC-20 Transfer of the output token to the recipient, the Aerodrome pool Swap event, and the executor's own SwapExecuted. It cross-verifies that the three agree within tolerance, scores the realized rate against a fresh Chainlink oracle read (an execution-quality score), and scans the block for a front-run and back-run pair around HELM's swap. It returns a pass or fail attestation with a keccak256 hash. When the Watcher's chosen Notary shares an agent with the chosen Hand, that Notary is excluded so no agent attests its own swap.
The Scribe takes the executed action plus the Notary's attestation and writes a concise markdown report a human can read: what moved, the realized rate, the verdict, and the real Base transaction hash. With an LLM key it writes prose; with none it falls back to a deterministic template, so it never blocks a settlement.
The Advisor is a standalone, non-fund research service routed by a kind field. It answers eight kinds: advice, research, safety, volatility, portfolio, yield, token-safety, and asset. Prices come from a verified-first hierarchy (stablecoin is 1 dollar, then a Chainlink feed, then a DEX read as an unverified last resort), every Chainlink read is gated on the Base L2 sequencer-uptime feed, and token-safety runs an EIP-1967 proxy-implementation check plus a sell-tax and honeypot round-trip. The Watcher hires this same service as its pre-trade safety gate before swapping any non-oracle asset.
CAPSCOPE is HELM's indexer plus a callable Lookup agent. It reads CAPCore order events into an agent-to-agent graph (who hired whom, for what, with real tx hashes) and computes objective per-provider reputation: clear-rate, refund-rate, volume, and a rating. CROO's own listOrders is caller-scoped, so an agent can only score itself; HELM reads the whole cross-agent history permissionlessly and sells it. The /explorer page renders the graph live.
HELM is not a single pair. The swap engine is token-agnostic, and a token registry holds every asset it can trade: USDC and WETH are built in and oracle-verified; cbBTC and other Base tokens are added by config, each with its decimals and optional price feed. An asset with no oracle feed is priced from the DEX and is only swapped after passing the Advisor's token-safety check. USDC to WETH is the safe default because both have verified pricing, not the limit of the product.
Because HELM moves real money, the fund path is bounded on every side: a SpendGuard with per-order and purse caps, a gas-cost-net gate that skips trades that cannot beat gas plus price impact, an SLA-miss auto-refund policy, oracle-anchored minOut on every swap, the funded Hand failing closed on retry, and the Notary excluded from grading its own agent's swap. A strategy engine (stop-loss, take-profit, trailing stop, DCA, band/range, target-weight) drives the bidirectional Hand with durable state across monitor windows.
Two front doors sit on top of the agents. The console/ is a natural-language web front door: type plain English, and an LLM turns it into an order (or an "Analyze, no trade" research call), runs the constellation locally, and the Scribe writes the report. Bring your own model: DeepSeek, OpenAI, or any OpenAI-compatible endpoint, with a deterministic fallback when no key is set. The mcp/ server exposes the Advisor's verified toolkit as eight tools callable from Claude or Cursor over MCP, so an AI assistant can read HELM's on-chain truth directly.
The HelmExecutor contract is live on Base mainnet (chain 8453). Explorer: https://basescan.org
| Item | Address |
|---|---|
| HelmExecutor | 0xD5bdd124De482d3e0244F6122E403983A4E25D62 (deploy block 48494921) |
| Executor admin + keeper (EOA) | 0x17A076d6cCaf37Bc9386EAB653A5EfAd8B07430C |
| CROO CAPCore | 0xaD46f1Eba2fe9cBB689D2874a52039192F2ac821 |
| CROO CAPVault | 0x33ECdcC8dD32330ec5a62AB1986F25ED5B5D170d |
| Aerodrome Router (whitelisted on the executor) | 0xcF77a3Ba9A5CA399B7c97c74d54e5b1Beb874E43 |
| USDC (settlement) | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| WETH | 0x4200000000000000000000000000000000000006 |
| Chainlink ETH/USD | 0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70 |
The full record, including every agent AA wallet and service id, is in deployments/README.md.
Fund-path status: the executor is deployed and the Aerodrome router is whitelisted. Real swaps go live the moment CROO (the CAPCore admin) grants the executor FUND_EXECUTOR_ROLE (0x8c4cd753434f163f8b7eddcd9dd997f020c825e500ac3268a7313511a5ed169a). Until then executeSwap reverts at markFundExecuted; nothing else is pending on HELM's side.
All six agents are registered on CROO and run continuously under pm2. Read-only agents are live now; the two swap agents (Watcher, Hand) are staged and go fully live with the role grant above.
| Agent | Role | AA wallet | Service id |
|---|---|---|---|
| Advisor | on-chain-verified research + token-safety | 0xB4bA86041623F7D0D31946C94445e7E72dAaB109 |
7ef9384a-5c69-43a9-a529-44ffcb8a410e |
| Notary | independent on-chain attestation | 0x9D8666E9CA9aCc548cFCf39E4eda542c5238a74F |
15a3bfbd-684e-48ff-855e-e3af8df8fb74 |
| Scribe | cited, human-readable report | 0x383aaCCeF6914649371c8cFF82A257fc76FfE524 |
2dc81b50-97ea-4b92-8292-91fa624655c3 |
| Lookup | CAPSCOPE A2A graph + reputation | 0x24d93F690921F9Db7949302f32ce48344bfbd344 |
b8041dab-2b70-4fd1-9445-3e95c9dcf430 |
| Watcher | monitor + orchestrate the rebalance (fund) | 0xF04853F14d0AeB417A795082C0aE27153968d687 |
96cce495-a2b7-4daa-a8e9-a42122bc7c01 |
| Hand | execute the real swap (fund) | 0x0352Ef47e2dFC38dA95AE8ab127745Af8eB873e7 |
09ac0ab7-21af-4e34-b96c-625f2bcba1a5 |
Everything below is checkable against Base mainnet or the local test suite; no HELM-controlled trust required.
| Claim | How to check | Value |
|---|---|---|
| HelmExecutor deployed | open the address on Basescan (link above) | bytecode live, deploy block 48494921 |
| Executor roles set | on-chain hasRole(DEFAULT_ADMIN_ROLE / KEEPER_ROLE, 0x17A0...) |
admin + keeper held |
| Aerodrome router whitelisted | on-chain whitelist(0xcF77...) on the executor |
true |
| Six agents registered on CROO | AA wallets + service ids (table above) | all six live |
| Real swaps pending only the role grant | hasRole(FUND_EXECUTOR_ROLE, 0xD5bd...) on CAPCore |
false until CROO grants it |
| Full test suite green | npm test --workspaces && (cd contracts && npx hardhat test) |
238 passing (226 vitest + 12 contract) |
| Whole flow runs with no chain, no CROO, no USDC | npx tsx scripts/simulate.ts |
end-to-end constellation offline |
Confirm the role grant at any time:
cd contracts && node -e "require('dotenv').config();const{ethers}=require('ethers');
const p=new ethers.JsonRpcProvider('https://mainnet.base.org');
new ethers.Contract('0xaD46f1Eba2fe9cBB689D2874a52039192F2ac821',['function hasRole(bytes32,address) view returns(bool)'],p)
.hasRole(ethers.id('FUND_EXECUTOR_ROLE'),'0xD5bdd124De482d3e0244F6122E403983A4E25D62').then(r=>console.log('role granted:',r));"There are three ways to reach HELM, all pointing at the same live agents:
- Hire on CROO. Find an agent on agent.croo.network and place an order against its service id. The read-only agents (Advisor, Notary, Scribe, Lookup) deliver immediately; the swap agents move real funds through the executor.
- Talk to it in plain English. Run the console (
npm start -w @helm/console), type what you want, and it turns the request into an order or an "Analyze, no trade" research call, runs the constellation, and shows the cited report. - Call it from Claude or Cursor. The MCP server exposes the Advisor's eight verified tools; an AI assistant reads HELM's on-chain truth directly.
helm/
├── contracts/ Hardhat, Solidity 0.8.28 (viaIR)
│ ├── src/HelmExecutor.sol swap executor + principal refund (fund-transfer path)
│ ├── src/ICAPCore.sol CROO CAPCore interface (matches the deployed contract)
│ └── scripts/deploy.ts deploy + FUND_EXECUTOR_ROLE hasRole check
│
├── agents/
│ ├── shared/ @helm/shared: CapAgent, PaymentQueue, RequirementsCache, config, tokens
│ ├── watcher/ monitor + orchestrate the rebalance (requester + provider)
│ ├── hand/ execute the real swap via HelmExecutor (fund service)
│ ├── notary/ independent 3-witness attestation (evaluator)
│ ├── scribe/ cited human-readable report
│ ├── advisor/ on-chain-verified research + token-safety (no execution)
│ └── lookup/ callable CAPSCOPE A2A graph + reputation
│
├── console/ natural-language front door (type English, run OR analyze)
├── mcp/ MCP server, HELM's verified Advisor as 8 Claude/Cursor tools
├── sdk/ @helm/payments, publishable nonce-safe payment middleware
├── indexer/ @helm/indexer, CAPCore A2A order-graph indexer (CAPSCOPE)
├── web/ Next.js frontend, HELM site + CAPSCOPE order-graph explorer
├── scripts/ fund-mechanics spike, registration runbook, e2e, concurrency
└── deployments/ canonical addresses + agent wallets + service ids
Node 20+ and npm for everything; the contracts use Hardhat. Each workspace is an npm workspace under the root.
git clone https://github.com/HoomanBuilds/helm && cd helm
npm install # root workspaces
cd contracts && npm install # hardhat project
# 1. run every test
npm test --workspaces --if-present # agent + sdk + indexer tests (226 vitest)
cd contracts && npx hardhat test # contract tests (12)
# 2. run the WHOLE constellation end-to-end, no CROO, no chain, no USDC
npx tsx scripts/simulate.ts
# 3. talk to HELM in plain English (local web console)
npm start -w @helm/console # http://localhost:8140
# 4. the web frontend (site + CAPSCOPE explorer)
cd web && npm install && npm run dev # http://localhost:3000 (/ and /explorer)Run the agents live on Base (each in its own process):
cp .env.example .env # fill in SDK keys, service ids, wallets, addresses
# deploy the executor (already live at 0xD5bd...; redeploy only if needed)
cd contracts && npx hardhat run scripts/deploy.ts --network base
# start the agents (read-only four go live immediately; swap two need the role grant)
npm start -w @helm/advisor # + notary, scribe, lookup, watcher, handTo run continuously on a host, each agent is a small long-lived process; pm2 keeps them alive and resurrects them on reboot:
npm i -g pm2
pm2 start ./node_modules/.bin/tsx --name helm-advisor -- agents/advisor/src/index.ts # repeat per agent
pm2 saveSecrets (CROO SDK keys, the keeper key, LLM keys) live only in gitignored .env files; see .env.example. On-chain gas for CROO order operations is sponsored by the platform; only the executor deploy and each executeSwap (direct contract calls by the keeper) need a little ETH.
| Layer | Tools |
|---|---|
| Smart contract | Solidity 0.8.28, Hardhat (viaIR), OpenZeppelin AccessControl + ReentrancyGuard |
| Agents | TypeScript, @croo-network/sdk 0.2.1, viem, tsx |
| Agent protocol | CROO CAP: negotiate, pay (escrow in CAPVault), deliver, clear; fund-transfer path |
| DEX + oracle | Aerodrome (best-execution routing), Chainlink ETH/USD + L2 sequencer-uptime gate |
| Yield reads | Aave V3, Compound III (Advisor idle-yield comparison) |
| LLM | DeepSeek, OpenAI, or any OpenAI-compatible endpoint; deterministic fallback |
| MCP | @modelcontextprotocol/sdk (stdio), 8 verified Advisor tools |
| Payments | @helm/payments, nonce-safe PaymentQueue over the CAP AA wallet |
| Frontend | Next.js 16, React 19, Tailwind v4, Three.js |
| Network | Base mainnet (chain 8453), USDC settlement |
A few honest notes about the live system:
- The mover, the grader, and the ranker are different agents. The Watcher orchestrates but cannot withdraw; the Hand executes but its output is bound to the user's beneficiary; the Notary is excluded from attesting a swap that shares an agent with the Hand; reputation is applied only to verified candidates. No agent both moves money and grades its own work.
- The funded step fails closed. A funded Hand never re-escrows a principal on retry, so the self-healing reroute (used for the non-fund steps) can never double-spend the user's money.
- Verified-first pricing. The trade price is a stablecoin dollar, a Chainlink feed, or, only as a last resort, a DEX read; a non-oracle asset must pass the token-safety check (EIP-1967 proxy plus a sell-tax and honeypot round-trip) before any funds move. External reference data (CoinGecko) is cross-check only, never the trade price.
- The fund path is gated on-chain.
executeSwapmarks execution through CAPCore'smarkFundExecuted, which isFUND_EXECUTOR_ROLE-only; the deployed executor holdsKEEPER_ROLEfor a separate operator key, and CROO grants the fund-executor role. The deploy admin is a single EOA for the hackathon; production should move it to a multisig or timelock. - Concurrency is correct, not lucky. All payments go through a serialized
PaymentQueue, so a real parallel fan-out settles where naive callers collide on the AA-wallet nonce. Requirements are cached from the negotiation (not theOrderPaidevent), and there is one memoized WebSocket per SDK key. - Proof-first. Every order is backed by a real, clickable Base tx hash; the offline simulator and the test suite exercise the same code paths with nothing stubbed.
| Field | Value |
|---|---|
| Marketplace | https://agent.croo.network |
| Network | Base mainnet (chain 8453) |
| RPC | https://mainnet.base.org |
| Explorer | https://basescan.org |
| Settlement | USDC |
| HelmExecutor | 0xD5bdd124De482d3e0244F6122E403983A4E25D62 |
- Real fund execution, deployed on Base.
contracts/src/HelmExecutor.solis live at the address above, Aerodrome-whitelisted, with abeneficiaryonexecuteSwapthat forwards proceeds to the end user and arefundToRequestorsafety path. HELM is the only entry that exercises CAP's fund-transfer path. - Six agents, live on CROO. All registered with the service ids above and running under pm2. The Watcher orchestrates a rebalance across the Hand, Notary, and Scribe, emitting three A2A orders per run.
- Independent, three-witness verification.
agents/notaryreconciles the fill across the ERC-20 Transfer, the Aerodrome Swap, and the executor's SwapExecuted, scores it against Chainlink, and scans for a sandwich, then signs a pass or fail attestation. It cannot attest its own agent's swap. - On-chain-verified intelligence, not vibes.
agents/advisorreads every number from Chainlink and Aerodrome, gated on the L2 sequencer feed, and runs a real token-safety round-trip; the LLM only interprets verified data. Callable from Claude or Cursor over MCP. - Objective, permissionless reputation.
indexer+agents/lookupscore any provider straight from CAPCore events; the reputation lane can only score itself, HELM reads cross-agent history. Rendered live on/explorer. - Verifiable end to end. 238 tests pass,
scripts/simulate.tsruns the whole constellation offline, and every live claim resolves to a Base transaction, an on-chain read, or a public CAPCore event.
A position, watched by one agent, is rebalanced by a second through a deployed executor on Base, independently attested by a third from three on-chain witnesses, and written up by a fourth, priced by a fifth from verified oracles behind a token-safety gate, and ranked by a sixth from the permissionless order graph, real money, real transaction hashes, and no agent grading its own work.