@agether/agether 1.7.3 → 2.0.1

package/README.md

@@ -14,9 +14,41 @@ OpenClaw plugin for **Agether** — onchain credit protocol for AI agents on Bas
 openclaw plugins install @agether/agether
 ```
 
-## Configure
+## Configure Secrets
 
-Edit `~/.openclaw/openclaw.json` and add the `agether` entry under `plugins.entries`:
+The plugin reads sensitive credentials from **OpenClaw secrets** (environment variables), not from the plugin config. This keeps your private key out of `openclaw.json`.
+
+### 1. Set your private key (required)
+
+```bash
+# Option A: Interactive setup (recommended)
+openclaw secrets configure
+# → source: env → id: AGETHER_PRIVATE_KEY
+
+# Option B: Set directly in your shell / .env
+export AGETHER_PRIVATE_KEY=0x...
+```
+
+### 2. Set an RPC key (optional — better rate limits)
+
+The plugin auto-detects RPC keys in this order, falling back to the free public endpoint:
+
+| Env Var | Provider | URL pattern |
+|---------|----------|------------|
+| `ALCHEMY_API_KEY` | Alchemy | `https://base-mainnet.g.alchemy.com/v2/<key>` |
+| `ANKR_API_KEY` | Ankr | `https://rpc.ankr.com/base/<key>` |
+| `QUICKNODE_URL` | QuickNode | Used as-is (full URL) |
+| *(none)* | PublicNode | `https://base-rpc.publicnode.com` (free, rate-limited) |
+
+```bash
+# Example: set via OpenClaw secrets
+openclaw secrets configure
+# → source: env → id: ALCHEMY_API_KEY
+```
+
+### 3. Plugin config (optional)
+
+The plugin works with an **empty config**. All fields are optional:
 
 ```jsonc
 // ~/.openclaw/openclaw.json
@@ -26,10 +58,13 @@ Edit `~/.openclaw/openclaw.json` and add the `agether` entry under `plugins.entr
       "agether": {
         "enabled": true,
         "config": {
-          "privateKey": "0x...",       // required — your wallet PK
-          "rpcUrl": "https://base-rpc.publicnode.com",  // optional (default)
-          "backendUrl": "http://95.179.189.214:3001",   // optional (default)
-          "autoDraw": false            // optional — auto-borrow for x402 payments
+          // All fields below are optional — plugin works with empty config {}
+          "agentId": "17676",          // auto-saved after registration
+          "autoDraw": false,           // auto-borrow for x402 payments
+          "dailySpendLimitUsdc": 0,    // 0 = unlimited
+          "yieldLimitedSpending": false,
+          "autoDrawBuffer": 0,
+          "healthAlertThreshold": 70   // LTV % to trigger health warnings
         }
       }
     }
@@ -43,7 +78,11 @@ Then restart the gateway:
 openclaw gateway --force
 ```
 
-> ⚠️ **Never share your private key.** The `privateKey` field is marked as sensitive in the plugin manifest.
+### Verify secrets are clean
+
+```bash
+openclaw secrets audit --check
+```
 
 ## Verify
 
@@ -59,18 +98,23 @@ Once installed, the following tools are available to your AI agent:
 
 | Tool | Description |
 |---|---|
+| `agether_health` | **Start here** — comprehensive check: balances, positions, LTV, liquidation risk, headroom |
+| `agether_preflight` | Setup readiness checklist: key, RPC, registration, balances |
 | `agether_balance` | Check ETH & USDC balances (EOA + AgentAccount) |
 | `agether_register` | Mint ERC-8004 identity & create AgentAccount |
 | `agether_set_agent` | Set a known agentId (from memory) and save to config |
 | `agether_score` | Get Bayesian credit score with 5-factor breakdown |
 | `morpho_status` | Show all Morpho credit positions |
 | `morpho_markets` | List supported Morpho Blue markets |
+| `morpho_rates` | Current market rates — supply APY, borrow APY, utilization |
+| `morpho_max_borrowable` | Calculate max additional USDC borrowable |
+| `morpho_yield_estimate` | Estimate theoretical yield for collateral |
 | `morpho_deposit` | Deposit collateral (WETH, wstETH, cbETH) |
-| `morpho_deposit_and_borrow` | Deposit collateral + borrow USDC in one step |
+| `morpho_deposit_and_borrow` | Deposit collateral + borrow USDC in one batched tx |
 | `morpho_borrow` | Borrow USDC against deposited collateral |
 | `morpho_repay` | Repay USDC debt |
 | `morpho_withdraw` | Withdraw collateral back to EOA |
-| `morpho_sponsor` | Human deposits collateral for an agent (by ID or address) |
+| `morpho_sponsor` | Deposit collateral for another agent (by ID or address) |
 | `wallet_fund` | Transfer USDC from EOA into AgentAccount |
 | `x402_pay` | Make paid API calls via x402 protocol (supports auto-draw) |
 
@@ -80,16 +124,25 @@ Quick commands that run without AI reasoning:
 
 - `/balance` — wallet balances
 - `/morpho` — Morpho positions overview
+- `/health` — position health: LTV, liquidation risk, balances
+- `/rates` — current Morpho market rates
+
+## Hooks
+
+The plugin registers automatic hooks:
+
+- **`command:new`** — logs agent balance context at the start of each new conversation
 
 ## Quick Start
 
 1. Install: `openclaw plugins install @agether/agether`
-2. Add config to `~/.openclaw/openclaw.json` (see above)
-3. Restart: `openclaw gateway --force`
-4. Open Telegram → *"What is my balance?"*
-5. *"Register me as an agent on Agether"*
-6. Fund your wallet with ETH (gas) + WETH/wstETH/cbETH (collateral)
-7. *"Deposit 0.05 WETH and borrow $50 USDC"*
+2. Set secret: `export AGETHER_PRIVATE_KEY=0x...` (or use `openclaw secrets configure`)
+3. Enable: add `"agether": { "enabled": true, "config": {} }` to `plugins.entries`
+4. Restart: `openclaw gateway --force`
+5. Open Telegram → *"What is my balance?"*
+6. *"Register me as an agent on Agether"*
+7. Fund your wallet with ETH (gas) + WETH/wstETH/cbETH (collateral)
+8. *"Deposit 0.05 WETH and borrow $50 USDC"*
 
 ## Getting Collateral on Base
 
@@ -101,11 +154,21 @@ Quick commands that run without AI reasoning:
 
 | Option | Required | Default | Description |
 |---|---|---|---|
-| `privateKey` | ✅ | — | Wallet private key for signing transactions |
-| `rpcUrl` | — | `https://base-rpc.publicnode.com` | Base RPC endpoint |
-| `backendUrl` | — | `http://95.179.189.214:3001` | Agether backend API |
-| `autoDraw` | — | `false` | Auto-borrow from credit line when USDC is insufficient for x402 payments |
 | `agentId` | — | — | Pre-set agent ID (auto-saved after registration) |
+| `autoDraw` | — | `false` | Auto-borrow from credit line when USDC is insufficient for x402 payments |
+| `dailySpendLimitUsdc` | — | `0` | Daily USDC spending cap (0 = unlimited) |
+| `yieldLimitedSpending` | — | `false` | Limit auto-draw to theoretical yield |
+| `autoDrawBuffer` | — | `0` | Extra USDC buffer when auto-drawing |
+| `healthAlertThreshold` | — | `70` | LTV % to trigger health warnings |
+
+### Secrets (env vars)
+
+| Env Var | Required | Description |
+|---|---|---|
+| `AGETHER_PRIVATE_KEY` | ✅ | Wallet private key for signing transactions |
+| `ALCHEMY_API_KEY` | — | Alchemy API key for premium Base RPC |
+| `ANKR_API_KEY` | — | Ankr API key for premium Base RPC |
+| `QUICKNODE_URL` | — | Full QuickNode RPC URL |
 
 ## Links
 

package/openclaw.plugin.json

@@ -1,44 +1,51 @@
 {
   "id": "agether",
   "name": "Agether Credit",
-  "description": "Onchain credit protocol for AI agents — Morpho-backed overcollateralized credit, ERC-8004 identity, x402 payments",
-  "version": "1.2.0",
+  "description": "Onchain credit protocol for AI agents — Morpho-backed overcollateralized credit, ERC-8004 identity, x402 payments. Private key and RPC keys are read from OpenClaw secrets (env vars); no plaintext config needed.",
+  "version": "2.0.1",
   "skills": ["skills/agether"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
     "properties": {
-      "privateKey": {
-        "type": "string",
-        "description": "Wallet private key for signing transactions"
-      },
       "agentId": {
         "type": "string",
-        "description": "ERC-8004 agent ID (set after registration)"
-      },
-      "rpcUrl": {
-        "type": "string",
-        "description": "Base RPC endpoint",
-        "default": "https://base-rpc.publicnode.com"
-      },
-      "backendUrl": {
-        "type": "string",
-        "description": "Agether backend URL",
-        "default": "http://95.179.189.214:3001"
+        "description": "ERC-8004 agent ID (set after registration, auto-saved by tools)"
       },
       "autoDraw": {
         "type": "boolean",
         "description": "Auto-borrow from Morpho credit line when USDC balance is low for x402 payments",
         "default": false
+      },
+      "dailySpendLimitUsdc": {
+        "type": "number",
+        "description": "Daily USDC spending cap for x402 payments (0 = unlimited)",
+        "default": 0
+      },
+      "yieldLimitedSpending": {
+        "type": "boolean",
+        "description": "Limit auto-draw spending to theoretical yield on deposited collateral",
+        "default": false
+      },
+      "autoDrawBuffer": {
+        "type": "number",
+        "description": "Extra USDC buffer when auto-drawing from Morpho (e.g. 0.5 = borrow $0.50 extra)",
+        "default": 0
+      },
+      "healthAlertThreshold": {
+        "type": "number",
+        "description": "LTV percentage threshold for health warnings (e.g. 70 = warn at 70% LTV, liquidation at 80%)",
+        "default": 70
       }
     },
-    "required": ["privateKey"]
+    "required": []
   },
   "uiHints": {
-    "privateKey": { "label": "Private Key", "sensitive": true },
     "agentId": { "label": "Agent ID", "placeholder": "17676" },
-    "rpcUrl": { "label": "RPC URL", "placeholder": "https://base-rpc.publicnode.com" },
-    "backendUrl": { "label": "Backend URL", "placeholder": "http://95.179.189.214:3001" },
-    "autoDraw": { "label": "Auto-Draw Credit", "placeholder": "false" }
+    "autoDraw": { "label": "Auto-Draw Credit", "placeholder": "false" },
+    "dailySpendLimitUsdc": { "label": "Daily Spend Limit (USDC)", "placeholder": "0" },
+    "yieldLimitedSpending": { "label": "Yield-Limited Spending", "placeholder": "false" },
+    "autoDrawBuffer": { "label": "Auto-Draw Buffer (USDC)", "placeholder": "0" },
+    "healthAlertThreshold": { "label": "Health Alert Threshold (%)", "placeholder": "70" }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agether/agether",
-  "version": "1.7.3",
+  "version": "2.0.1",
   "description": "OpenClaw plugin for Agether — onchain credit for AI agents",
   "main": "src/index.ts",
   "openclaw": {

package/skills/agether/SKILL.md

@@ -26,21 +26,23 @@ If you don't paste it, the user sees NOTHING. An empty colon ":" with no data af
 1. **PASTE tool results into your reply.** Every tool returns JSON. Extract the key fields and write them in your message. The user cannot see tool output directly.
 2. **ALWAYS paste tx links.** Tools return `tx` field like `https://basescan.org/tx/0x...`. Copy it verbatim into your reply.
 3. **After on-chain actions, call `agether_balance` and paste the balances.**
-4. **On first message, call `agether_balance`.** If `agentId` is `"?"`, you need to set it up — see AGENT ID RESOLUTION below. If not registered at all, call `agether_register`.
+4. **On first message, call `agether_health`.** This is your single best "context loader" — it returns balances, positions, LTV, alerts, and headroom in one call. If `agentId` is `"?"`, see AGENT ID RESOLUTION below.
 5. **Be proactive** — if the user asks to call a paid API, do the full flow without asking.
-6. **Never ask for private keys** — already configured.
+6. **Never ask for private keys** — they come from OpenClaw secrets (AGETHER_PRIVATE_KEY env var).
 7. **Max LTV is 80%** (125% collateral ratio). To borrow $X, you need $X × 1.25 in collateral value.
 8. **When user says "register" → ALWAYS call `agether_register`.** A wallet CAN have multiple ERC-8004 identities. The tool handles everything. Never refuse to register because the wallet "already has an identity". Just call the tool.
 9. **Never guess about blockchain state.** If you're unsure, call the tool. Don't tell the user something is impossible — try it first.
 10. **Your EOA wallet IS the user's wallet.** Same private key, same address. If the user says "I have WETH", call `agether_balance` — you'll see it in the `collateral` field. You already have access to those tokens.
 11. **`morpho_deposit` and `morpho_deposit_and_borrow` transfer collateral from your EOA automatically.** You do NOT need anyone to "send you" tokens. If your EOA has WETH, just call the deposit tool directly. The SDK handles EOA→Safe account→Morpho in one flow.
 12. **To get USDC for x402:** call `morpho_deposit_and_borrow` with collateral from your EOA. Do NOT ask the user to send tokens — check your balance first.
+13. **Check health before large actions.** Before borrowing, depositing, or withdrawing significant amounts, call `agether_health` to see current LTV and headroom. This prevents failed transactions.
+14. **Batch awareness:** `morpho_deposit_and_borrow` is a batched operation (deposit + borrow in one tx). Always prefer it over separate `morpho_deposit` then `morpho_borrow` when doing both — it saves gas and is atomic.
 
 ---
 
 ## 🆔 AGENT ID RESOLUTION (CRITICAL)
 
-If `agether_balance` returns `agentId: "?"`, ALL Morpho tools will fail. You MUST resolve this first:
+If `agether_health` or `agether_balance` returns `agentId: "?"`, ALL Morpho tools will fail. You MUST resolve this first:
 
 ```
 1. Check your memory for a previously registered agentId
@@ -50,7 +52,7 @@ If `agether_balance` returns `agentId: "?"`, ALL Morpho tools will fail. You MUS
      → IF user says no  → call `agether_register(name: "<ask name>")`
 3. IF no agentId in memory:
      → call `agether_register(name: "<ask name>")`
-4. After either path → call `agether_balance` to confirm agentId is set
+4. After either path → call `agether_health` to confirm everything is working
 ```
 
 Both `agether_set_agent` and `agether_register` save the agentId to config permanently (survives restarts).
@@ -59,6 +61,12 @@ Both `agether_set_agent` and `agether_register` save the agentId to config perma
 
 ## 🛠 YOUR TOOLS
 
+### Health & Diagnostics
+| Tool | What it does |
+|------|-------------|
+| `agether_health` | **START HERE.** Comprehensive check: balances, all positions with LTV & liquidation risk, borrowing headroom, alerts — all in one call. |
+| `agether_preflight` | Setup readiness check: private key present? RPC working? Agent registered? Balances OK? Returns pass/fail checklist. |
+
 ### Identity & Wallet
 | Tool | What it does |
 |------|-------------|
@@ -73,70 +81,118 @@ Both `agether_set_agent` and `agether_register` save the agentId to config perma
 |------|--------|-------------|
 | `morpho_markets` | none | List supported Morpho markets and parameters |
 | `morpho_status` | none | Show all Morpho positions (collateral + debt) |
+| `morpho_rates` | `token?` | Current market rates — supply APY, borrow APY, utilization |
+| `morpho_max_borrowable` | none | Calculate max additional USDC borrowable given current collateral/debt |
+| `morpho_yield_estimate` | `token`, `amount`, `periodDays?` | Estimate theoretical yield for collateral |
 | `morpho_deposit` | `amount`, `token` | Deposit collateral from EOA → Morpho (no borrow) |
-| `morpho_deposit_and_borrow` | `collateralAmount`, `token`, `borrowAmount` | Deposit + borrow in one flow. **Best for first-time setup** |
+| `morpho_deposit_and_borrow` | `collateralAmount`, `token`, `borrowAmount` | **PREFERRED** — Deposit + borrow in one batched tx. Best for first-time setup |
 | `morpho_borrow` | `amount` (USD) | Borrow USDC against existing collateral → lands in Safe account |
-| `morpho_repay` | `amount` (USD) | Repay USDC debt from Safe account → Morpho |
+| `morpho_repay` | `amount` (USD or "all") | Repay USDC debt from Safe account → Morpho |
 | `morpho_withdraw` | `amount` (or "all"), `token` | Withdraw collateral back to EOA wallet |
-| `morpho_sponsor` | `agentId`/`agentAddress`, `amount`, `token`, `borrow?` | Deposit collateral for another agent |
+| `morpho_sponsor` | `agentId`/`agentAddress`, `amount`, `token` | Deposit collateral for another agent |
 
 ### x402 Payments
 | Tool | Params | What it does |
 |------|--------|-------------|
 | `x402_pay` | `url`, `method?`, `body?`, `autoDraw?` | Make a paid API call. Pays with USDC via EIP-3009 signature |
 
-### Slash Commands (user types these)
+### Slash Commands (user types these — no AI invocation)
 | Command | What it does |
 |---------|-------------|
 | `/balance` | Quick balance check |
 | `/morpho` | Quick Morpho position summary |
+| `/health` | Quick position health: LTV, liquidation risk, balances |
+| `/rates` | Current Morpho market rates |
 
 ---
 
 ## 📋 DECISION TREES
 
+### Session start (first message or new conversation)
+```
+1. agether_health                ← ONE call for full context
+2. Check the "alerts" array:
+     → If any 🔴 alerts → WARN user immediately (liquidation risk!)
+     → If any 🟡 alerts → mention the risk casually
+     → If "agentId: ?" → go to AGENT ID RESOLUTION
+3. Now you have full context to handle any request
+```
+
 ### User asks to call a paid API (x402)
 ```
-1. agether_balance → check USDC in Safe account AND collateral on EOA
-2. IF Safe account has USDC ≥ $0.01:
+1. agether_health               ← get full picture in one call
+2. Look at balances.agentAccount.usdc:
+   IF USDC ≥ $0.01:
      → x402_pay(url)
-3. IF no USDC but has collateral deposited in Morpho:
+3. IF no USDC but positions exist with headroom:
      → morpho_borrow(amount: "1")    ← borrow $1
      → x402_pay(url)
-4. IF no USDC AND no Morpho collateral BUT EOA has WETH/wstETH/cbETH:
+4. IF no USDC AND no positions BUT EOA has WETH/wstETH/cbETH:
      → morpho_deposit_and_borrow(collateralAmount, token, borrowAmount: "1")
      → x402_pay(url)
-5. IF no USDC AND no collateral anywhere:
-     → Tell user: "Need collateral (WETH/wstETH/cbETH) on Base to get credit. Send to <EOA address>"
+5. IF nothing at all:
+     → Tell user: "Need collateral (WETH/wstETH/cbETH) on Base. Send to <EOA address>"
 ```
 
 ### User wants to borrow USDC via Morpho
 ```
-1. agether_balance               ← check collateral on EOA
-2. morpho_deposit_and_borrow(collateralAmount, token, borrowAmount)
-3. agether_balance               ← show the result with balance changes
-4. Show: tx hash, collateral deposited, USDC borrowed, new balances
+1. agether_health               ← check collateral, headroom, current LTV
+2. IF headroom allows the borrow amount AND collateral already in Morpho:
+     → morpho_borrow(amount)
+3. IF EOA has collateral but nothing in Morpho yet:
+     → morpho_deposit_and_borrow(collateralAmount, token, borrowAmount)
+4. agether_balance               ← show the result with balance changes
+5. Show: tx hash, collateral deposited, USDC borrowed, new balances, new LTV
 ```
 
 ### User wants to repay + withdraw
 ```
-1. morpho_status                 ← check current debt and collateral
-2. morpho_repay(amount)          ← repay USDC
+1. agether_health               ← check current debt, collateral, LTV
+2. morpho_repay(amount or "all") ← repay USDC
 3. morpho_withdraw("all", token) ← get collateral back
 4. agether_balance               ← show final balances
 ```
 
+### User asks about position health or liquidation risk
+```
+1. agether_health               ← returns LTV, risk level, alerts per position
+2. Paste the positions table with LTV percentages
+3. IF any position has LTV > 70%:
+     → Suggest: "Consider repaying debt or adding collateral"
+     → Show: morpho_max_borrowable for headroom context
+```
+
+### User wants to optimize rates or compare markets
+```
+1. morpho_rates                  ← get all market rates
+2. morpho_yield_estimate(token, amount) ← estimate yield
+3. Present: which market has lowest borrow APY, highest supply APY
+4. Suggest optimal strategy based on their holdings
+```
+
 ### User asks to check or refresh credit score
 ```
 1. IF user says "refresh" / "update" / "get new score":
-     → agether_score(refresh: true)   ← pays via x402, computes fresh score, writes on-chain
+     → Check USDC balance first (refresh costs x402)
+     → agether_score(refresh: true)   ← pays via x402, computes fresh score
      → Paste the score and tx link
 2. IF user says "check" / "what's my score":
-     → agether_score(refresh: false)  ← free, reads current on-chain score
+     → agether_score(refresh: false)  ← free read
      → Paste the score
 3. NEVER say "not registered" or "no score yet" without calling the tool first!
 ```
 
+### Something seems wrong / setup issues
+```
+1. agether_preflight             ← run the diagnostic checklist
+2. Show each check with its status
+3. Address any ❌ or ⚠️ items:
+   - Missing private key → guide to `openclaw secrets configure`
+   - Not registered → offer to register
+   - No ETH for gas → show EOA address for funding
+   - No USDC → suggest deposit_and_borrow flow
+```
+
 ### User asks "what can I do?" or "what is agether?"
 ```
 Explain: You're an AI agent with on-chain credit on Base.
@@ -144,6 +200,7 @@ You can:
 - Deposit WETH/wstETH/cbETH as collateral
 - Borrow USDC instantly (125% collateral ratio)
 - Pay for APIs using x402 protocol
+- Monitor position health and avoid liquidation
 - All on Base mainnet, all autonomous
 ```
 
@@ -157,7 +214,7 @@ Example after repay:
 ```
 ✅ Repaid $1.50 USDC
 
-� Tx: https://basescan.org/tx/0xabc123def456...
+🔗 Tx: https://basescan.org/tx/0xabc123def456...
 💰 Balances:
   EOA: 0.05 ETH, 0 USDC
   AgentAccount: 0 ETH, $3.50 USDC
@@ -199,6 +256,7 @@ If something **fails**:
 
 | Error | Meaning | What to do |
 |-------|---------|-----------|
+| `Missing AGETHER_PRIVATE_KEY` | Private key not set in secrets | Run `openclaw secrets configure` → source: env → id: AGETHER_PRIVATE_KEY |
 | `ExceedsMaxLtv` | Collateral too low for borrow amount | Deposit more collateral or borrow less. LTV must be ≤ 80% |
 | `Payment rejected (402)` | No USDC for x402 payment | Borrow USDC first: `morpho_borrow` or `morpho_deposit_and_borrow` |
 | `No collateral deposited` | Trying to borrow without collateral | `morpho_deposit` first |
@@ -208,10 +266,25 @@ If something **fails**:
 
 ---
 
+## 🔐 SECRETS SETUP (for reference)
+
+The plugin reads secrets from environment variables via OpenClaw's secrets system:
+
+| Secret | Env Var | Required | Notes |
+|--------|---------|----------|-------|
+| Wallet private key | `AGETHER_PRIVATE_KEY` | Yes | Set via `openclaw secrets configure` → source: env |
+| Alchemy RPC key | `ALCHEMY_API_KEY` | No | Higher rate limits than free RPC |
+| Ankr RPC key | `ANKR_API_KEY` | No | Alternative premium RPC |
+| QuickNode RPC URL | `QUICKNODE_URL` | No | Full URL including API key |
+
+If no RPC key is set, the plugin falls back to `https://base-rpc.publicnode.com` (free, rate-limited).
+
+---
+
 ## 🏗 ARCHITECTURE (for context)
 
 ```
-EOA Wallet (private key)
+EOA Wallet (private key from AGETHER_PRIVATE_KEY)
   ├── Owns ERC-8004 Identity NFT (agentId)  ← can own MULTIPLE
   └── Owns Safe Account (via Safe7579 + ERC-4337, 1 per agentId)
         ├── Holds USDC (from borrows)

package/src/index.ts

@@ -3,6 +3,16 @@
  *
  * Each tool = MorphoClient / X402Client call → format result with txLink.
  * Market discovery via Morpho GraphQL API (no backend dependency for markets).
+ *
+ * v2: Secrets-first config
+ * ─────────────────────────
+ * - privateKey     → AGETHER_PRIVATE_KEY env var (set via `openclaw secrets configure` → crypto)
+ * - rpcUrl         → auto-resolved from ALCHEMY_API_KEY / ANKR_API_KEY / QUICKNODE_URL env vars,
+ *                    falls back to https://base-rpc.publicnode.com
+ * - backendUrl     → hardcoded (no config needed)
+ * - agentId        → optional plugin config field (auto-saved by tools)
+ *
+ * The plugin works with an empty `plugins.entries.agether.config: {}`.
  */
 
 import axios from "axios";
@@ -13,6 +23,12 @@ import {
   X402Client,
 } from "@agether/sdk";
 
+// ─── Constants ────────────────────────────────────────────
+
+const BACKEND_URL = "http://95.179.189.214:3001";
+const DEFAULT_RPC = "https://base-rpc.publicnode.com";
+const BASESCAN = "https://basescan.org/tx";
+
 // ─── Helpers ──────────────────────────────────────────────
 
 interface PluginConfig {
@@ -22,7 +38,6 @@ interface PluginConfig {
   backendUrl: string;
 }
 
-const BASESCAN = "https://basescan.org/tx";
 function txLink(hash: string): string {
   return hash ? `${BASESCAN}/${hash}` : "";
 }
@@ -44,16 +59,48 @@ function fail(err: unknown) {
   return { content: [{ type: "text" as const, text: `❌ ${msg}` }], isError: true };
 }
 
-function getConfig(api: any): PluginConfig {
-  const cfg = api.config?.plugins?.entries?.["agether"]?.config;
-  if (!cfg?.privateKey) {
-    throw new Error("Agether plugin not configured: missing privateKey in plugins.entries.agether.config");
+// ─── Secrets-first config resolution ──────────────────────
+
+/**
+ * Resolve RPC URL from environment secrets.
+ * Priority: ALCHEMY_API_KEY → ANKR_API_KEY → QUICKNODE_URL → publicnode fallback.
+ */
+function resolveRpcUrl(): string {
+  const alchemy = process.env.ALCHEMY_API_KEY;
+  if (alchemy) return `https://base-mainnet.g.alchemy.com/v2/${alchemy}`;
+
+  const ankr = process.env.ANKR_API_KEY;
+  if (ankr) return `https://rpc.ankr.com/base/${ankr}`;
+
+  const quicknode = process.env.QUICKNODE_URL;
+  if (quicknode) return quicknode;
+
+  return DEFAULT_RPC;
+}
+
+/**
+ * Resolve private key from environment secrets.
+ * Set via `openclaw secrets configure` (source: env → AGETHER_PRIVATE_KEY).
+ */
+function resolvePrivateKey(): string {
+  const key = process.env.AGETHER_PRIVATE_KEY;
+  if (!key) {
+    throw new Error(
+      "Missing AGETHER_PRIVATE_KEY. " +
+      "Set it via: openclaw secrets configure → source: env → id: AGETHER_PRIVATE_KEY\n" +
+      "Or export AGETHER_PRIVATE_KEY=0x... in your shell / .env file.",
+    );
   }
+  return key;
+}
+
+function getConfig(api: any): PluginConfig {
+  const cfg = api.config?.plugins?.entries?.["agether"]?.config ?? {};
   return {
-    privateKey: cfg.privateKey,
+    privateKey: resolvePrivateKey(),
     agentId: cfg.agentId,
-    rpcUrl: cfg.rpcUrl || "https://base-rpc.publicnode.com",
-    backendUrl: cfg.backendUrl || "http://95.179.189.214:3001",
+    rpcUrl: resolveRpcUrl(),
+    backendUrl: BACKEND_URL,
   };
 }
 
@@ -76,13 +123,17 @@ function persistAgentId(agentId: string): string {
     const home = process.env.HOME || process.env.USERPROFILE || "/root";
     const cfgPath = path.join(home, ".openclaw", "openclaw.json");
     const raw = fs.readFileSync(cfgPath, "utf-8");
-    const cfg = JSON.parse(raw);
-    if (cfg?.plugins?.entries?.agether?.config) {
-      cfg.plugins.entries.agether.config.agentId = agentId;
-      fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
-      return "saved";
-    }
-    return "config structure not found";
+    const json = JSON.parse(raw);
+
+    // Ensure config path exists
+    if (!json.plugins) json.plugins = {};
+    if (!json.plugins.entries) json.plugins.entries = {};
+    if (!json.plugins.entries.agether) json.plugins.entries.agether = {};
+    if (!json.plugins.entries.agether.config) json.plugins.entries.agether.config = {};
+
+    json.plugins.entries.agether.config.agentId = agentId;
+    fs.writeFileSync(cfgPath, JSON.stringify(json, null, 2));
+    return "saved";
   } catch (e) {
     return `write failed: ${e instanceof Error ? e.message : String(e)}`;
   }
@@ -789,6 +840,163 @@ export default function register(api: any) {
     },
   });
 
+  // ═══════════════════════════════════════════════════════
+  //  TOOL: agether_health  (comprehensive position health)
+  // ═══════════════════════════════════════════════════════
+  api.registerTool({
+    name: "agether_health",
+    description:
+      "Comprehensive health check: balances, all Morpho positions with LTV & liquidation risk, " +
+      "borrowing headroom, and current market rates — all in one call. " +
+      "Use this as the first call in any session to get full context before making decisions.",
+    parameters: { type: "object", properties: {}, required: [] },
+    async execute() {
+      try {
+        const cfg = getConfig(api);
+        const agetherCfg = api.config?.plugins?.entries?.agether?.config ?? {};
+        const healthThreshold = agetherCfg.healthAlertThreshold ?? 70;
+        const client = createClient(cfg);
+
+        // Gather everything in parallel where possible
+        const [balances, status, maxBorrow] = await Promise.all([
+          client.getBalances(),
+          client.getStatus(),
+          client.getMaxBorrowable(),
+        ]);
+
+        // Build per-position health analysis
+        const positionHealth = status.positions.map((p: any) => {
+          const matchingMarket = maxBorrow.byMarket.find(
+            (m: any) => m.collateralToken === p.collateralToken,
+          );
+          const collateralValue = matchingMarket ? Number(matchingMarket.collateralValue) / 1e6 : 0;
+          const debt = parseFloat(p.debt);
+          const ltv = collateralValue > 0 ? (debt / collateralValue) * 100 : 0;
+          const maxLtv = 80; // Morpho LLTV
+          const headroom = matchingMarket ? Number(matchingMarket.maxAdditional) / 1e6 : 0;
+
+          let risk: string;
+          if (debt === 0) risk = "🟢 no debt";
+          else if (ltv >= maxLtv) risk = "🔴 LIQUIDATION ZONE";
+          else if (ltv >= healthThreshold) risk = "🟡 WARNING — approaching liquidation";
+          else risk = "🟢 healthy";
+
+          return {
+            collateralToken: p.collateralToken,
+            collateral: p.collateral,
+            collateralValueUsd: `$${collateralValue.toFixed(2)}`,
+            debt: `$${debt.toFixed(2)}`,
+            ltvPercent: `${ltv.toFixed(1)}%`,
+            maxLtv: `${maxLtv}%`,
+            headroomUsdc: `$${headroom.toFixed(2)}`,
+            risk,
+          };
+        });
+
+        const alerts: string[] = [];
+        for (const ph of positionHealth) {
+          if (ph.risk.includes("LIQUIDATION")) {
+            alerts.push(`🔴 ${ph.collateralToken}: LTV at ${ph.ltvPercent} — at risk of liquidation!`);
+          } else if (ph.risk.includes("WARNING")) {
+            alerts.push(`🟡 ${ph.collateralToken}: LTV at ${ph.ltvPercent} — consider adding collateral or repaying debt`);
+          }
+        }
+
+        // Check gas (ETH) is sufficient for transactions
+        const ethBalance = parseFloat(balances.eth);
+        if (ethBalance < 0.0005) {
+          alerts.push("⛽ Low ETH for gas — may fail on-chain transactions. Send ETH to EOA.");
+        }
+
+        const result = {
+          agentId: balances.agentId,
+          walletAddress: balances.address,
+          balances: {
+            eoa: { eth: balances.eth, usdc: balances.usdc },
+            agentAccount: balances.agentAccount
+              ? { address: balances.agentAccount.address, usdc: balances.agentAccount.usdc }
+              : null,
+          },
+          totalDebt: `$${status.totalDebt}`,
+          totalBorrowingHeadroom: `$${(Number(maxBorrow.total) / 1e6).toFixed(2)}`,
+          positions: positionHealth,
+          alerts: alerts.length > 0 ? alerts : ["✅ All positions healthy"],
+          rpcSource: process.env.ALCHEMY_API_KEY ? "Alchemy" :
+                     process.env.ANKR_API_KEY ? "Ankr" :
+                     process.env.QUICKNODE_URL ? "QuickNode" : "PublicNode (free)",
+        };
+
+        return ok(JSON.stringify(result, null, 2));
+      } catch (e) { return fail(e); }
+    },
+  });
+
+  // ═══════════════════════════════════════════════════════
+  //  TOOL: agether_preflight  (setup readiness check)
+  // ═══════════════════════════════════════════════════════
+  api.registerTool({
+    name: "agether_preflight",
+    description:
+      "Check that the agent is fully set up: private key present, RPC working, " +
+      "agent registered, balances non-zero. Returns a checklist of pass/fail items. " +
+      "Call this if anything seems wrong or on first-time setup.",
+    parameters: { type: "object", properties: {}, required: [] },
+    async execute() {
+      const checks: Array<{ check: string; status: string; detail?: string }> = [];
+
+      // 1. Private key
+      try {
+        resolvePrivateKey();
+        checks.push({ check: "Private key (AGETHER_PRIVATE_KEY)", status: "✅ set" });
+      } catch {
+        checks.push({ check: "Private key (AGETHER_PRIVATE_KEY)", status: "❌ missing", detail: "Set via: openclaw secrets configure → source: env → id: AGETHER_PRIVATE_KEY" });
+      }
+
+      // 2. RPC URL
+      const rpcUrl = resolveRpcUrl();
+      const rpcSource = process.env.ALCHEMY_API_KEY ? "Alchemy" :
+                        process.env.ANKR_API_KEY ? "Ankr" :
+                        process.env.QUICKNODE_URL ? "QuickNode" : "PublicNode (free fallback)";
+      checks.push({ check: "RPC endpoint", status: `✅ ${rpcSource}`, detail: rpcUrl.replace(/\/[a-zA-Z0-9_-]{20,}$/, '/***') });
+
+      // 3. Agent registration
+      try {
+        const cfg = getConfig(api);
+        const client = createClient(cfg);
+        const balances = await client.getBalances();
+
+        if (balances.agentId && balances.agentId !== '?') {
+          checks.push({ check: "Agent registration", status: `✅ ID: ${balances.agentId}` });
+        } else {
+          checks.push({ check: "Agent registration", status: "⚠️ not registered", detail: "Call agether_register to create an identity" });
+        }
+
+        // 4. ETH for gas
+        const eth = parseFloat(balances.eth);
+        if (eth >= 0.001) {
+          checks.push({ check: "ETH for gas", status: `✅ ${eth.toFixed(6)} ETH` });
+        } else {
+          checks.push({ check: "ETH for gas", status: `⚠️ ${eth.toFixed(6)} ETH — low`, detail: `Send ETH to ${balances.address}` });
+        }
+
+        // 5. USDC availability
+        const eoaUsdc = parseFloat(balances.usdc);
+        const safeUsdc = balances.agentAccount ? parseFloat(balances.agentAccount.usdc) : 0;
+        if (safeUsdc > 0) {
+          checks.push({ check: "USDC (AgentAccount)", status: `✅ $${safeUsdc.toFixed(2)}` });
+        } else if (eoaUsdc > 0) {
+          checks.push({ check: "USDC", status: `⚠️ $${eoaUsdc.toFixed(2)} in EOA only`, detail: "Use wallet_fund or morpho_deposit_and_borrow to get USDC into AgentAccount" });
+        } else {
+          checks.push({ check: "USDC", status: "❌ no USDC anywhere", detail: "Deposit collateral and borrow, or send USDC to EOA" });
+        }
+      } catch (e: any) {
+        checks.push({ check: "Blockchain connectivity", status: "❌ failed", detail: e.message });
+      }
+
+      return ok(JSON.stringify({ preflight: checks }, null, 2));
+    },
+  });
+
   // ═══════════════════════════════════════════════════════
   //  SLASH COMMANDS (no AI needed)
   // ═══════════════════════════════════════════════════════
@@ -835,4 +1043,95 @@ export default function register(api: any) {
       }
     },
   });
+
+  api.registerCommand({
+    name: "health",
+    description: "Quick position health check — LTV, liquidation risk, balances (no AI)",
+    handler: async () => {
+      try {
+        const cfg = getConfig(api);
+        const agetherCfg = api.config?.plugins?.entries?.agether?.config ?? {};
+        const healthThreshold = agetherCfg.healthAlertThreshold ?? 70;
+        const client = createClient(cfg);
+
+        const [balances, status, maxBorrow] = await Promise.all([
+          client.getBalances(),
+          client.getStatus(),
+          client.getMaxBorrowable(),
+        ]);
+
+        let text = `🏥 Health — Agent #${balances.agentId}\n`;
+        text += `EOA: ${balances.eth} ETH, $${balances.usdc} USDC\n`;
+        if (balances.agentAccount) {
+          text += `Safe: $${balances.agentAccount.usdc} USDC\n`;
+        }
+        text += `Total debt: $${status.totalDebt}\n`;
+        text += `Headroom: $${(Number(maxBorrow.total) / 1e6).toFixed(2)}\n`;
+
+        for (const p of status.positions) {
+          const mm = maxBorrow.byMarket.find((m: any) => m.collateralToken === p.collateralToken);
+          const cv = mm ? Number(mm.collateralValue) / 1e6 : 0;
+          const debt = parseFloat(p.debt);
+          const ltv = cv > 0 ? (debt / cv) * 100 : 0;
+          const icon = debt === 0 ? "🟢" : ltv >= 80 ? "🔴" : ltv >= healthThreshold ? "🟡" : "🟢";
+          text += `\n${icon} ${p.collateralToken}: ${p.collateral} col, $${p.debt} debt, LTV ${ltv.toFixed(1)}%`;
+        }
+        if (status.positions.length === 0) text += "\nNo active positions.";
+
+        return { text };
+      } catch (e: any) {
+        return { text: `❌ ${e.message}` };
+      }
+    },
+  });
+
+  api.registerCommand({
+    name: "rates",
+    description: "Show current Morpho market rates (no AI)",
+    handler: async () => {
+      try {
+        const cfg = getConfig(api);
+        const client = createClient(cfg);
+        const rates = await client.getMarketRates();
+
+        if (rates.length === 0) return { text: "No markets found." };
+
+        let text = "📈 Morpho Rates\n";
+        for (const r of rates as any[]) {
+          text += `\n${r.collateralToken}/${r.loanToken}: borrow ${(r.borrowApy * 100).toFixed(2)}%, supply ${(r.supplyApy * 100).toFixed(2)}%, util ${(r.utilization * 100).toFixed(1)}%`;
+        }
+        return { text };
+      } catch (e: any) {
+        return { text: `❌ ${e.message}` };
+      }
+    },
+  });
+
+  // ═══════════════════════════════════════════════════════
+  //  HOOKS (automatic actions)
+  // ═══════════════════════════════════════════════════════
+
+  api.registerHook(
+    "command:new",
+    async () => {
+      // On new conversation, log a quick context summary so the agent
+      // starts with awareness of the current state.
+      try {
+        const cfg = getConfig(api);
+        const client = createClient(cfg);
+        const balances = await client.getBalances();
+        const agentId = balances.agentId ?? "?";
+        const safeUsdc = balances.agentAccount?.usdc ?? "0";
+        api.logger?.info?.(
+          `[agether] Session start — Agent #${agentId}, EOA: ${balances.eth} ETH / $${balances.usdc} USDC, Safe: $${safeUsdc} USDC`,
+        );
+      } catch {
+        // Silently fail — hook should not block conversations
+      }
+    },
+    {
+      name: "agether.session-context",
+      description: "Logs agent balance context at the start of each new conversation",
+    },
+  );
 }

package/test/kya.test.ts

@@ -1,157 +0,0 @@
-/**
- * KYA gate feature — unit tests for plugin tools.
- *
- * Mocks MorphoClient so no blockchain connection is needed.
- */
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-// ── Mock state ──
-
-const mockIsKyaRequired = vi.fn<() => Promise<boolean>>();
-const mockRegister = vi.fn();
-const mockGetBalances = vi.fn();
-const mockGetAgentId = vi.fn().mockReturnValue('12345');
-const mockGetAccountAddress = vi.fn().mockResolvedValue('0xAGENTACCOUNT');
-
-vi.mock('@agether/sdk', () => {
-  // MorphoClient must work with `new` — use a class
-  class MockMorphoClient {
-    isKyaRequired = mockIsKyaRequired;
-    register = mockRegister;
-    getBalances = mockGetBalances;
-    getAgentId = mockGetAgentId;
-    getAccountAddress = mockGetAccountAddress;
-  }
-  class MockX402Client {}
-  return {
-    MorphoClient: MockMorphoClient,
-    X402Client: MockX402Client,
-  };
-});
-
-// Suppress fs.readFileSync for persistAgentId
-vi.mock('fs', async (importOriginal) => {
-  const orig = await importOriginal<typeof import('fs')>();
-  return {
-    ...orig,
-    default: {
-      ...orig,
-      readFileSync: vi.fn().mockReturnValue('{}'),
-      writeFileSync: vi.fn(),
-    },
-    readFileSync: vi.fn().mockReturnValue('{}'),
-    writeFileSync: vi.fn(),
-  };
-});
-
-import registerPlugin from '../src/index';
-
-// ── Helpers ──
-
-/** Minimal mock for the OpenClaw plugin API */
-function createMockApi(config?: Record<string, any>) {
-  const tools = new Map<string, { execute: Function }>();
-  return {
-    config: {
-      plugins: {
-        entries: {
-          agether: {
-            config: {
-              privateKey: '0x' + 'ab'.repeat(32),
-              agentId: '12345',
-              rpcUrl: 'http://127.0.0.1:8545',
-              backendUrl: 'http://localhost:3001',
-              ...config,
-            },
-          },
-        },
-      },
-    },
-    registerTool(def: { name: string; execute: Function }) {
-      tools.set(def.name, def);
-    },
-    registerCommand() { /* noop */ },
-    getTool(name: string) {
-      return tools.get(name);
-    },
-  };
-}
-
-// ── Tests ──
-
-describe('agether_kya_status tool', () => {
-  let api: ReturnType<typeof createMockApi>;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    api = createMockApi();
-    registerPlugin(api);
-  });
-
-  it('returns DISABLED message when isKyaRequired = false', async () => {
-    mockIsKyaRequired.mockResolvedValue(false);
-
-    const tool = api.getTool('agether_kya_status')!;
-    const result = await tool.execute();
-
-    expect(result.content[0].text).toContain('DISABLED');
-    expect(result.isError).toBeUndefined();
-  });
-
-  it('returns ENABLED message when isKyaRequired = true', async () => {
-    mockIsKyaRequired.mockResolvedValue(true);
-
-    const tool = api.getTool('agether_kya_status')!;
-    const result = await tool.execute();
-
-    expect(result.content[0].text).toContain('ENABLED');
-    expect(result.isError).toBeUndefined();
-  });
-});
-
-describe('agether_register kyaMessage', () => {
-  let api: ReturnType<typeof createMockApi>;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    api = createMockApi();
-    registerPlugin(api);
-  });
-
-  it('includes "gate disabled" kyaMessage when kyaRequired = false', async () => {
-    mockRegister.mockResolvedValue({
-      agentId: '99999',
-      address: '0xWALLET',
-      agentAccount: '0xACCOUNT',
-      alreadyRegistered: false,
-      kyaRequired: false,
-      tx: '0xTXHASH',
-    });
-
-    const tool = api.getTool('agether_register')!;
-    const result = await tool.execute('test-id', { name: 'TestAgent' });
-    const data = JSON.parse(result.content[0].text);
-
-    expect(data.kyaRequired).toBe(false);
-    expect(data.kyaMessage).toContain('gate disabled');
-  });
-
-  it('includes "KYA required" kyaMessage when kyaRequired = true', async () => {
-    mockRegister.mockResolvedValue({
-      agentId: '99999',
-      address: '0xWALLET',
-      agentAccount: '0xACCOUNT',
-      alreadyRegistered: false,
-      kyaRequired: true,
-      tx: '0xTXHASH',
-    });
-
-    const tool = api.getTool('agether_register')!;
-    const result = await tool.execute('test-id', { name: 'TestAgent' });
-    const data = JSON.parse(result.content[0].text);
-
-    expect(data.kyaRequired).toBe(true);
-    expect(data.kyaMessage).toContain('KYA required');
-  });
-});

package/vitest.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    testTimeout: 10_000,
-  },
-});