@hypurrquant/defi-cli 1.0.10 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypurrquant/defi-cli",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Multi-chain DeFi CLI \u2014 lending, DEX, LP, bridge, vault, staking from your terminal",
   "type": "module",
   "license": "MIT",

package/skills/defi-cli/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: "Bash(defi:*), Bash(npx defi-cli:*), Bash(npx -y defi-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "1.0.0"
+  version: "1.0.11"
 ---
 
 # defi-cli Agent Guide
@@ -59,6 +59,29 @@ export DEFI_PRIVATE_KEY=0xYourPrivateKey   # only needed for broadcasting
 
 🟢 = mainnet broadcast verified | 🟡 = configs verified, awaiting funded broadcast
 
+## References
+
+- **`references/protocols.md`** — full protocol slug catalog per chain (39 protocols across 5 chains)
+- **`references/commands.md`** — every CLI command with flags, dry-run shape, and JSON envelope notes
+
+## Scripts (`scripts/`)
+
+Copy-paste runnable usage recipes. Each script honours `DEFI_CMD` (override the binary name, e.g. `DEFI_CMD="npx -y -p @hypurrquant/defi-cli@latest defi"`) and emits JSON on stdout, status on stderr.
+
+| Script | What it does | Invocation |
+|---|---|---|
+| `preflight.sh` | Verify install + wallet env | `bash preflight.sh` |
+| `yield-scan.sh` | Best supply APY across all chains | `ASSET=USDC bash yield-scan.sh` |
+| `lp-emission-discover.sh` | Active emission pools sorted by APR | `bash lp-emission-discover.sh mantle merchantmoe-mantle` |
+| `swap-quote.sh` | Compare every supported aggregator (dry-run) | `CHAIN=base FROM=WETH TO=USDC AMOUNT=10000000000000000 bash swap-quote.sh` |
+| `bridge-quote.sh` | Compare LI.FI / deBridge / CCTP (dry-run) | `FROM_CHAIN=base TO_CHAIN=arbitrum TOKEN=USDC AMOUNT=100000000 bash bridge-quote.sh` |
+| `lending-supply-flow.sh` | yield → rates → position → dry-run supply | `CHAIN=hyperevm PROTOCOL=hyperlend ASSET=USDC AMOUNT=1000000 bash lending-supply-flow.sh` |
+| `lp-claim-all.sh` | List all LP positions + claim CLI hints | `WALLET=0xABC… bash lp-claim-all.sh mantle` |
+| `portfolio-snapshot.sh` | Snapshot + PnL for a wallet | `WALLET=0xABC… bash portfolio-snapshot.sh hyperevm` |
+| `wallet-status.sh` | Resolved wallet + native balance per chain | `bash wallet-status.sh` |
+
+All `*-quote.sh` and `lending-supply-flow.sh` scripts are **dry-run only** — they never touch `--broadcast`. Add `--broadcast` to the printed CLI yourself after user confirmation.
+
 ## Protocol Slugs by Chain
 
 For full protocol list see `references/protocols.md`. High-level summary:
@@ -166,6 +189,19 @@ Bridge **source** must be a supported chain (hyperevm/mantle/base/bnb/monad). Br
 | `No fees to compound` | V3 position has no accumulated fees yet — wait for swaps to cross range |
 | `No pools found` | protocol may be inactive on this chain or discover branch missing config |
 | `DEFI_WALLET_ADDRESS not set` | set env var or pass `--address` |
+| `tokenId X has zero liquidity` | NFT position already removed; verify with `lp positions` |
+| `failed_probes[]` in yield output | RPC transport failure (not "asset unsupported"); set `<CHAIN>_RPC_URL` and retry |
+| `WARNING: no wallet configured` on stderr | dry-run preview using placeholder `0x000…001`; do **NOT** pass `--broadcast` until wallet is set |
+
+## Recent Behaviour Notes (v1.0.5 → v1.0.11 + post-release fixes)
+
+- **`lp remove` (V3 / Slipstream / Hybra / Algebra)** — pass only `--token-id`; `--token-a/--token-b/--liquidity` are optional. Liquidity is read from `NPM.positions(tokenId)` automatically.
+- **`schema <action>`** accepts hyphenated names (`schema lending-supply` ≡ `schema lending.supply`).
+- **`yield optimize` / `yield compare`** distinguishes "no opportunities" from "RPC failed" — failure surfaces a `failed_probes[]` envelope with per-protocol reason and a hint to set `<CHAIN>_RPC_URL`.
+- **`portfolio show` / `snapshot`** prices each asset via its own oracle (ERC20s no longer mispriced at the native rate) and includes the native gas-token balance in `total_value_usd`.
+- **`wallet address`** with no wallet returns `{ "address": null, "source": "none" }` (machine-parseable; the legacy `"(not set)"` sentinel is gone).
+- **`bridge --provider cctp`** below the protocol min-fee returns a structured error envelope with `minimum_amount_wei` / `minimum_amount_usdc` (no broadcast attempt).
+- **`setup`** masks API keys when displaying RPC URLs and suppresses key-echo when prompting for a private key; only `http://`/`https://` URLs are accepted.
 
 ## Examples
 

package/skills/defi-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypurrquant/defi-cli-skill",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "AI agent skill for defi-cli — multi-chain DeFi operations via CLI (7 chains, 48 protocols, 5 aggregators)",
   "keywords": [
     "ai-skill",

package/skills/defi-cli/references/commands.md

@@ -11,6 +11,8 @@ All amounts are in **wei** unless noted. USDC/USDT/USDT0 use 6 decimals; native
 defi --json status                                  # current chain protocols
 defi --json --chain mantle status                   # Mantle protocols + addresses
 defi --json schema                                  # full CLI schema as JSON
+defi --json schema lending.supply                   # one action's params + cli example
+defi --json schema lending-supply                   # hyphenated form also works (post-v1.0.11)
 ```
 
 ## Yield (read-only, safe)
@@ -21,6 +23,11 @@ defi --json --chain mantle yield compare --asset USDT
 defi --json yield optimize --asset USDC --amount 100000000   # diversification plan
 ```
 
+**Failure shape (post-v1.0.11)**: when every RPC probe fails, the command no longer pretends "no opportunities found" — it returns:
+```json
+{ "error": "...", "failed_probes": [{ "protocol": "aave-v3-mantle", "type": "lending", "reason": "..." }], "hint": "Set MANTLE_RPC_URL=..." }
+```
+
 ## Price (read-only, safe)
 
 ```bash
@@ -125,19 +132,21 @@ Collects accrued fees and re-adds them as liquidity in one tx. V3 fee-only proto
 ### Remove Liquidity
 
 ```bash
-# V3 / Slipstream (NFT-based)
-defi --json --chain <chain> lp remove --protocol <slug> \
-  --token-a <token> --token-b <token> --liquidity <amount> --token-id <id> [--gauge <addr>]
+# V3 / Slipstream / Algebra / Hybra (NFT-based) — only --token-id required
+# Liquidity is read live from NPM.positions(tokenId); --liquidity overrides if passed
+defi --json --chain <chain> lp remove --protocol <slug> --token-id <id> [--gauge <addr>]
 
 # Solidly V2 (LP-token-based)
 defi --json --chain <chain> lp remove --protocol <slug> \
   --token-a <token> --token-b <token> --liquidity <wei> --gauge <addr>
 
-# Liquidity Book (Merchant Moe / TraderJoe)
+# Liquidity Book (Merchant Moe / TraderJoe) — pair flags + bins required
 defi --json --chain <chain> lp remove --protocol <slug> \
   --token-a <token> --token-b <token> --pool <addr> --bins <bin1>,<bin2>,...
 ```
 
+If a V3/CL `--token-id` resolves to zero on-chain liquidity, the command surfaces `tokenId X has zero liquidity (already removed?)` instead of producing a no-op `decreaseLiquidity(0) + collect`.
+
 ### LP Positions
 
 ```bash
@@ -180,6 +189,8 @@ defi --json --chain <chain> portfolio snapshot [--address <addr>]
 defi --json --chain <chain> portfolio pnl [--address <addr>]
 ```
 
+**Pricing (post-v1.0.11)**: each ERC20 is priced via its own oracle (no longer the native asset's price). Native gas-token balance is fetched via `eth_getBalance` and included as `native_balance` / `native_value_usd` in the total. Tokens whose oracle returns 0 are omitted from the total instead of being mispriced. `snapshot` matches `show` to the cent.
+
 ## Token
 
 ```bash
@@ -195,10 +206,27 @@ defi --json --chain <chain> token transfer  --token <token> --to <addr> --amount
 ## Wallet
 
 ```bash
-defi --json wallet address
-defi --json --chain <chain> wallet balance [--address <addr>]
+defi --json wallet address                                       # { "address": "0x…", "source": "ows|private_key|env|none" }
+defi --json --chain <chain> wallet balance [--address <addr>]    # native balance via eth_getBalance
 ```
 
+`wallet address` returns `{ "address": null, "source": "none" }` when no wallet is configured (the legacy `"(not set)"` string sentinel is gone). Resolution precedence: `--address` flag → OWS vault (`DEFI_WALLET_ADDRESS=ows:<name>`) → `DEFI_PRIVATE_KEY` derived → plain `DEFI_WALLET_ADDRESS`.
+
+### Wallet placeholder warning
+
+For dry-run paths (`swap`, `bridge`, `lending supply`, etc.), if no wallet is configured the CLI emits a one-shot stderr warning and substitutes the placeholder `0x000…001` so calldata can still be previewed. **Never pass `--broadcast` when the placeholder is in use** — the warning will tell you so explicitly.
+
+## Setup (interactive wizard)
+
+```bash
+defi setup                                          # prompts for chain RPCs + wallet
+```
+
+Stored in `~/.defi/config.toml`. The wizard:
+- Suppresses keypress echo when prompting for a private key.
+- Accepts only `http://` and `https://` RPC URLs (rejects `ws://`, `wss://`, plain hosts).
+- Masks the URL path when displaying current configuration (`https://eth.example.com/***`) so embedded API keys do not leak in transcripts.
+
 ## Bridge (cross-chain)
 
 Source chain (`--chain`) must be a supported chain: `hyperevm`, `mantle`, `base`, `bnb`, `monad`. Destination (`--to-chain`) can be any chain LI.FI/deBridge route to, plus all CCTP V2 chains.
@@ -213,3 +241,8 @@ defi --json --chain base bridge --token USDC --amount 100000000 --to-chain arbit
 # Circle CCTP V2 destinations: ethereum, avalanche, optimism, arbitrum, base, polygon
 defi --json --chain base bridge --token USDC --amount 100000000 --to-chain arbitrum --provider cctp
 ```
+
+**CCTP min-fee guard (post-v1.0.7)**: when the burn amount cannot cover the protocol fee, the command short-circuits with a structured envelope (no broadcast attempt):
+```json
+{ "error": "amount_below_min_fee", "minimum_amount_wei": "...", "minimum_amount_usdc": "..." }
+```

package/skills/defi-cli/scripts/bridge-quote.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# bridge-quote.sh — dry-run a cross-chain bridge across LI.FI / deBridge / CCTP
+# Source must be one of: hyperevm, mantle, base, bnb, monad
+# Usage: FROM_CHAIN=base TO_CHAIN=arbitrum TOKEN=USDC AMOUNT=100000000 bash bridge-quote.sh
+set -euo pipefail
+
+DEFI="${DEFI_CMD:-defi}"
+FROM_CHAIN="${FROM_CHAIN:-base}"
+TO_CHAIN="${TO_CHAIN:-arbitrum}"
+TOKEN="${TOKEN:-USDC}"
+AMOUNT="${AMOUNT:-100000000}"
+
+# CCTP V2 only routes USDC and only between these chains
+CCTP_CHAINS="ethereum avalanche optimism arbitrum base polygon"
+PROVIDERS=(lifi debridge)
+if [[ "$TOKEN" == "USDC" ]] && [[ " $CCTP_CHAINS " == *" $TO_CHAIN "* ]] && [[ " $CCTP_CHAINS " == *" $FROM_CHAIN "* ]]; then
+  PROVIDERS+=(cctp)
+fi
+
+echo "[bridge-quote] $AMOUNT $TOKEN: $FROM_CHAIN -> $TO_CHAIN" >&2
+echo "[bridge-quote] providers: ${PROVIDERS[*]}" >&2
+
+OUT="["
+SEP=""
+for P in "${PROVIDERS[@]}"; do
+  echo "[bridge-quote] probing $P..." >&2
+  RES=$("$DEFI" --json --chain "$FROM_CHAIN" bridge \
+        --token "$TOKEN" --amount "$AMOUNT" --to-chain "$TO_CHAIN" --provider "$P" 2>/dev/null \
+        || echo "{\"provider\":\"$P\",\"error\":\"probe_failed\"}")
+  OUT="${OUT}${SEP}{\"provider\":\"$P\",\"result\":${RES}}"
+  SEP=","
+done
+OUT="${OUT}]"
+echo "$OUT"

package/skills/defi-cli/scripts/lending-supply-flow.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# lending-supply-flow.sh — full lending-supply preview without broadcasting
+# Walks: yield scan -> rates on chosen protocol -> existing position -> dry-run supply tx
+# Usage: CHAIN=hyperevm PROTOCOL=hyperlend ASSET=USDC AMOUNT=1000000 bash lending-supply-flow.sh
+set -euo pipefail
+
+DEFI="${DEFI_CMD:-defi}"
+CHAIN="${CHAIN:-hyperevm}"
+PROTOCOL="${PROTOCOL:-hyperlend}"
+ASSET="${ASSET:-USDC}"
+AMOUNT="${AMOUNT:-1000000}"
+
+echo "[1/4 lending-supply-flow] best $ASSET supply rates across all chains" >&2
+"$DEFI" --json yield scan --asset "$ASSET" --fields chain,protocol,supply_apy 2>/dev/null || true
+
+echo "[2/4 lending-supply-flow] rates for $PROTOCOL/$ASSET on $CHAIN" >&2
+"$DEFI" --json --chain "$CHAIN" lending rates --protocol "$PROTOCOL" --asset "$ASSET"
+
+echo "[3/4 lending-supply-flow] existing position on $PROTOCOL" >&2
+"$DEFI" --json --chain "$CHAIN" lending position --protocol "$PROTOCOL" 2>/dev/null \
+  || echo '{"position":null,"note":"no wallet configured or no position yet"}'
+
+echo "[4/4 lending-supply-flow] DRY-RUN supply tx ($AMOUNT $ASSET) — review before --broadcast" >&2
+"$DEFI" --json --chain "$CHAIN" lending supply \
+  --protocol "$PROTOCOL" --asset "$ASSET" --amount "$AMOUNT"
+
+echo "" >&2
+echo "[lending-supply-flow] To execute: re-run step 4 with --broadcast" >&2

package/skills/defi-cli/scripts/lp-claim-all.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# lp-claim-all.sh — list every LP position on a chain that has pending rewards,
+# then print the claim CLI command for each (DRY-RUN guidance only — does not broadcast).
+# Usage: WALLET=0xABC... bash lp-claim-all.sh <chain>
+set -euo pipefail
+
+DEFI="${DEFI_CMD:-defi}"
+CHAIN="${1:-mantle}"
+WALLET="${DEFI_WALLET_ADDRESS:-${WALLET:-}}"
+
+if [[ -z "$WALLET" ]]; then
+  echo '{"error":"Set DEFI_WALLET_ADDRESS or WALLET env var to scan positions"}' >&2
+  exit 1
+fi
+
+echo "[lp-claim-all] $CHAIN: scanning all LP positions for $WALLET" >&2
+"$DEFI" --json --chain "$CHAIN" lp positions --address "$WALLET"
+
+echo "" >&2
+echo "[lp-claim-all] To claim a specific position, use one of:" >&2
+echo "  V3 fees:        defi --json --chain $CHAIN lp claim --protocol <slug> --token-id <id> --broadcast" >&2
+echo "  Solidly gauge:  defi --json --chain $CHAIN lp claim --protocol <slug> --gauge <addr> --broadcast" >&2
+echo "  Slipstream NFT: defi --json --chain $CHAIN lp claim --protocol <slug> --gauge <addr> --token-id <id> --broadcast" >&2
+echo "  Merchant Moe:   defi --json --chain $CHAIN lp claim --protocol merchantmoe-mantle --pool <addr> --broadcast" >&2
+echo "  KittenSwap:     defi --json --chain $CHAIN lp claim --protocol kittenswap --pool <addr> --token-id <id> --broadcast" >&2

package/skills/defi-cli/scripts/lp-emission-discover.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# lp-emission-discover.sh — list active-emission LP pools on a chain, sorted by APR
+# Usage: bash lp-emission-discover.sh <chain> [protocol]
+# Examples:
+#   bash lp-emission-discover.sh mantle merchantmoe-mantle
+#   bash lp-emission-discover.sh base   aerodrome-cl
+#   bash lp-emission-discover.sh hyperevm kittenswap
+set -euo pipefail
+
+DEFI="${DEFI_CMD:-defi}"
+CHAIN="${1:-mantle}"
+PROTOCOL="${2:-}"
+
+if [[ -n "$PROTOCOL" ]]; then
+  echo "[lp-emission-discover] $CHAIN/$PROTOCOL — emission-only, APR-sorted desc" >&2
+  "$DEFI" --json --chain "$CHAIN" lp discover --protocol "$PROTOCOL" --emission-only
+else
+  echo "[lp-emission-discover] $CHAIN (all protocols) — emission-only, APR-sorted desc" >&2
+  "$DEFI" --json --chain "$CHAIN" lp discover --emission-only
+fi

package/skills/defi-cli/scripts/swap-quote.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# swap-quote.sh — dry-run a swap across every aggregator that supports the chain
+# Picks the best amount_out and prints a side-by-side comparison.
+# Usage: CHAIN=base FROM=WETH TO=USDC AMOUNT=1000000000000000000 bash swap-quote.sh
+set -euo pipefail
+
+DEFI="${DEFI_CMD:-defi}"
+CHAIN="${CHAIN:-hyperevm}"
+FROM="${FROM:-WHYPE}"
+TO="${TO:-USDC}"
+AMOUNT="${AMOUNT:-1000000000000000000}"
+SLIPPAGE="${SLIPPAGE:-50}"
+
+case "$CHAIN" in
+  hyperevm) PROVIDERS=(kyber openocean liquid lifi relay) ;;
+  mantle)   PROVIDERS=(openocean lifi relay) ;;
+  base)     PROVIDERS=(kyber openocean lifi relay) ;;
+  bnb)      PROVIDERS=(kyber openocean lifi relay) ;;
+  monad)    PROVIDERS=(lifi relay) ;;
+  *) echo "{\"error\":\"unknown chain: $CHAIN (expected hyperevm|mantle|base|bnb|monad)\"}" >&2; exit 1 ;;
+esac
+
+echo "[swap-quote] $CHAIN: $AMOUNT $FROM -> $TO @ ${SLIPPAGE}bps slippage" >&2
+echo "[swap-quote] providers: ${PROVIDERS[*]}" >&2
+
+OUT="["
+SEP=""
+for P in "${PROVIDERS[@]}"; do
+  echo "[swap-quote] probing $P..." >&2
+  RES=$("$DEFI" --json --chain "$CHAIN" swap --provider "$P" \
+        --from "$FROM" --to "$TO" --amount "$AMOUNT" --slippage "$SLIPPAGE" 2>/dev/null \
+        || echo "{\"provider\":\"$P\",\"error\":\"probe_failed\"}")
+  OUT="${OUT}${SEP}{\"provider\":\"$P\",\"result\":${RES}}"
+  SEP=","
+done
+OUT="${OUT}]"
+echo "$OUT"

package/skills/defi-cli/scripts/wallet-status.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# wallet-status.sh — print configured wallet + native balance on every supported chain
+# Usage: bash wallet-status.sh
+set -euo pipefail
+
+DEFI="${DEFI_CMD:-defi}"
+CHAINS=(hyperevm mantle base bnb monad)
+
+echo "[wallet-status] resolving configured wallet..." >&2
+ADDR_JSON=$("$DEFI" --json wallet address)
+echo "$ADDR_JSON"
+
+# Extract null check without jq dependency: address field is "null" when unset.
+if echo "$ADDR_JSON" | grep -q '"address":null'; then
+  echo "[wallet-status] no wallet configured — skipping per-chain balances" >&2
+  echo "[wallet-status] To configure: export DEFI_WALLET_ADDRESS=0x... or run 'defi setup'" >&2
+  exit 0
+fi
+
+OUT="["
+SEP=""
+for C in "${CHAINS[@]}"; do
+  echo "[wallet-status] probing native balance on $C..." >&2
+  RES=$("$DEFI" --json --chain "$C" wallet balance 2>/dev/null \
+        || echo "{\"chain\":\"$C\",\"error\":\"rpc_unreachable\"}")
+  OUT="${OUT}${SEP}${RES}"
+  SEP=","
+done
+OUT="${OUT}]"
+echo "$OUT"

package/skills/defi-cli/scripts/exploit-scan.sh

@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-# exploit-scan.sh — run a one-shot exploit detection scan across all chains
-# Usage: bash exploit-scan.sh [chain]
-set -euo pipefail
-
-DEFI="${DEFI_CMD:-defi}"
-CHAIN="${1:-hyperevm}"
-
-echo "[exploit-scan] Scanning $CHAIN for oracle divergence, stablecoin depeg, exchange rate anomalies..." >&2
-"$DEFI" --json --chain "$CHAIN" scan --once --patterns oracle,stable,exchange_rate