bonzo-agent

# Bonzo Vault Keeper — AI DeFi Agent for Hedera

**Hedera Apex Hackathon 2026 — Bonzo Finance Bounty Submission**

An AI strategy copilot that evaluates, routes, and executes a leveraged yield play on Hedera mainnet: borrow HBARX cheaply from Bonzo Lend, convert via the optimal path (SaucerSwap instant swap vs Stader zero-fee unstake), and deploy into Bonzo's USDC/HBAR concentrated liquidity vault at ~60–90% APY. All through a natural language chat interface reachable via web dashboard, terminal, or HCS-10.

---

## Judge Quick Start

**Prerequisites:** Node.js ≥ 20, an `.env` file (see below)

```bash
npm install
cp .env.example .env
# Fill in HEDERA_ACCOUNT_ID, HEDERA_PRIVATE_KEY, ANTHROPIC_API_KEY (or OPENAI_API_KEY)
```

**Verify connectivity (read-only, no transactions):**

```bash
npm run smoke-test
```

Expected output — no wallet balance required, all calls are read-only.
Values are live mainnet data and will vary:

```
=== Bonzo Vault Keeper — Smoke Test ===

1. Bonzo Lend market data...
   HBARX borrow APY : 0.543%      ← live, varies
   HBARX utilization: 5.3%        ← live, varies
   HBAR price (USD)  : $0.0930    ← live, varies
   HBARX price (USD) : $0.1274    ← live, varies
   WHBAR borrow APY  : 0.100%     ← live, varies
   Net spread (vs 70% vault APY): 69.5%
   Viable: true
   ✓ Bonzo API

2. Stader HBARX exchange rate...
   1 HBARX = 1.371240 HBAR        ← increases over time
   ✓ Stader exchange rate

3. SaucerSwap quote for 10 HBARX...
   HBAR received  : 13.6891
   Price impact   : 0.001%
   ✓ SaucerSwap quote

4. Path comparison for 10 HBARX (vault APY=70%)...
   Recommendation : maxYield
   Rationale      : Stader gives more HBAR and opportunity cost is low
   Fast Mode HBAR : 13.6891
   MaxYield HBAR  : 13.7124
   ✓ Path comparison

5. Vault APY from on-chain data...
   Best APY estimate: 70.00%      ← live on-chain read
   ✓ Vault APY (live)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✓ All 5/5 checks passed — ready to submit
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**Launch the web dashboard:**

```bash
npm run serve
# Open http://localhost:3000
```

**Or use the terminal chat:**

```bash
npm run chat
```

---

## Connecting via HCS-10

After running `npm run register`, the agent is reachable at the inbound topic ID printed during registration. Any HCS-10 client can connect and send messages.

**Using `@hashgraphonline/standards-sdk`:**

```ts
import { HCS10Client } from "@hashgraphonline/standards-sdk";

const client = new HCS10Client({
  network: "mainnet",
  operatorId: "0.0.YOUR_ACCOUNT",
  operatorPrivateKey: "YOUR_PRIVATE_KEY",
});

// Connect to the agent's inbound topic (printed by npm run register)
const AGENT_INBOUND_TOPIC = "0.0.XXXXXXX";

const { connectionTopicId } = await client.initiateConnection(AGENT_INBOUND_TOPIC);

// Send a message — the agent will reply on the connection topic
await client.sendMessage(connectionTopicId, "What is the current HBARX spread?");

// Poll the Hedera Mirror Node for the agent's reply
const MIRROR = "https://mainnet.mirrornode.hedera.com";
const res = await fetch(
  `${MIRROR}/api/v1/topics/${connectionTopicId}/messages?order=asc&limit=25`
);
const { messages } = await res.json();
for (const msg of messages) {
  const text = Buffer.from(msg.message, "base64").toString("utf-8");
  console.log(JSON.parse(text));
}
```

The agent auto-accepts connections and responds to every inbound message through its full LangChain tool suite — the same agent you chat with in the web UI.

---

## The Strategy

```
Supply collateral (WHBAR or USDC) on Bonzo Lend (Aave v2 fork)
         │
         ▼
Borrow HBARX at ~0.6% variable APY
         │
    ┌────┴────────────────────────────────────────┐
    │ Fast Mode                  Max Yield Mode   │
    │ Swap HBARX → HBAR          Unstake via      │
    │ on SaucerSwap V1           Stader Labs      │
    │ instant · ~0.3% fee        0 fee · 1-day    │
    └────┬────────────────────────────────────────┘
         │
         ▼
Deposit HBAR + USDC into Bonzo USDC-HBAR Vault (~60–90% APY)
         │
         ▼
Monitor health factor + rate spread → unwind if risk rises
```

**Net yield = Vault APY − HBARX borrow rate − conversion costs**

The agent fetches a live SaucerSwap on-chain quote, computes the opportunity cost of the Stader cooldown, and picks the path with better net value automatically.

---

## Bounty Requirements

This submission fulfills all Bonzo Finance bounty requirements. Every requirement runs against live Hedera mainnet — no mocks, no testnet.

| Requirement | Status | Implementation |
|---|---|---|
| **Hedera Agent Kit** | ✅ | `HederaLangchainToolkit` + full HAK tool suite used throughout |
| **HOL Standards SDK** | ✅ | `npm run register` — creates HCS-10 inbound/outbound topics + HCS-11 profile metadata |
| **Reachable via HCS-10** | ✅ | Inbound topic listener (gRPC streaming), auto-accepts connections, routes to agent |
| **Natural language chat** | ✅ | LangChain ReAct agent, 25+ custom tools, full conversation history, web + terminal + HCS-10 |
| **Intent-based UI** | ✅ | Web dashboard with live market metrics — every action executes real on-chain strategy steps |

---

## Features

- **Dual-path routing** — compares SaucerSwap (instant swap) vs Stader (zero-fee unstake) with live on-chain quotes; recommends best path based on opportunity cost math
- **Natural language execution** — describe what you want; the agent calls the right tools, shows you what will happen, and asks for confirmation before any transaction
- **Live web dashboard** — dark-theme chat UI with real-time market metrics (HBARX borrow rate, vault APY, net spread, health factor), SSE alert stream
- **Background monitor** — checks market conditions every 60s, emits alerts on rate changes, utilization spikes, low health factor, or spread collapse
- **On-chain vault APY** — computes real APY from `getPricePerFullShare()` history (Beefy-style), no off-chain oracles
- **Adaptive health polling** — polls health factor at intervals that tighten as risk increases: 5min → 1min → 30s → 15s as HF drops toward 1.5
- **Auto-unwind trigger** — if both on-chain and REST API confirm HF < 1.5 and `MONITOR_AUTO_UNWIND=true`, the agent initiates exit steps automatically
- **HCS-10 reachable** — registered via HOL Standards SDK; accepts inbound connections and processes messages from any HCS-10 client

---

## Example Chat Session

```
you> hey

agent> Current spread is 69.4% — vault APY 70% minus 0.6% HBARX borrow. Strong entry
       window. HBARX utilization at 5.3%, rates are stable.

       I can help you enter the strategy, compare conversion paths, check your position,
       or monitor the market. What do you want to do?

you> Compare paths for 500 HBARX

agent> [calls compare_conversion_paths, get_hbarx_exchange_rate]

       Fast Mode (SaucerSwap)   → 682.1 HBAR  |  instant  |  ~0.9% cost
       Max Yield Mode (Stader)  → 688.7 HBAR  |  1-day    |  0% fee

       Opportunity cost of 1-day cooldown: ~$0.18 in missed vault yield
       Stader advantage: 6.6 HBAR ≈ $0.61

       Recommendation: Max Yield Mode — Stader wins by $0.43.

you> Enter the strategy with 1000 WHBAR and 50 USDC

agent> [evaluates spread, compares paths, estimates health factors]

       Before I proceed:
         • Supply 1000 WHBAR as collateral — health factor: ∞
         • Borrow 400 HBARX at 0.60% APY — health factor post-borrow: ~2.8 ✓
         • Max Yield Mode: unstake 400 HBARX → ~548 HBAR (1-day cooldown)
         • Vault deposit: 50 USDC + ~50 USDC worth of HBAR
         • Estimated net APY: ~69.4% (vault 70% − borrow 0.6%)

       Risks: variable borrow rates, impermanent loss on USDC/HBAR, liquidation if
       HF drops below 1.0. Keep HF above 2.0.

       Proceed? (yes/no)
```

---

## Architecture

```
src/
  agent/
    setup.ts          LangChain ReAct agent + 25+ custom tools + HAK toolkit
    system-prompt.ts  Strategy copilot persona and decision logic
    hcs10.ts          HCS-

[truncated…]