@hypurrquant/defi-cli 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypurrquant/defi-cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Multi-chain DeFi CLI — lending, DEX, LP, bridge, vault, staking from your terminal",
   "type": "module",
   "license": "MIT",
@@ -10,6 +10,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "config",
     "mcp-config.example.json"
   ],

package/skills/defi-cli/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: defi-cli
+description: "Multi-chain DeFi operations CLI for HyperEVM (Hyperliquid) and Mantle. Use when user asks to: supply/withdraw from lending, swap tokens, add/remove LP, bridge assets, manage LP autopilot, claim rewards, compare APYs, check prices, track portfolio, or mentions defi-cli, HyperEVM, Hyperliquid EVM, Mantle, HypurrFi, HyperLend, Felix, KittenSwap, NEST, Ramses, Merchant Moe, KyberSwap, OpenOcean, LiquidSwap."
+allowed-tools: "Bash(defi:*), Bash(npx defi-cli:*), Bash(npx -y defi-cli:*)"
+license: MIT
+metadata:
+  author: hypurrquant
+  version: "0.4.0"
+---
+
+# defi-cli Agent Guide
+
+Multi-chain DeFi CLI — lending, DEX swaps, LP management, bridging, yield comparison — all from your terminal.
+
+2 chains: **HyperEVM** (Hyperliquid EVM, chain ID 999) and **Mantle** (chain ID 5000).
+21 protocols across lending, DEX, vault, CDP.
+
+## Rules
+
+1. **Always use `--json`** on every command.
+2. **Always use `--dry-run`** (default) before any mutating transaction. Only add `--broadcast` after user confirms.
+3. **Always use `--chain`** for transaction commands (`lending supply`, `swap`, `lp`, `token`, `price`, `wallet`, `bridge`). Query commands (`yield`, `status`) scan all chains by default.
+4. **NEVER broadcast without user confirmation.**
+5. **NEVER read private key files or `~/.` config files.**
+6. **Amounts are in wei** (18 decimals for most tokens, 6 for USDC/USDT). Use `BigInt(humanAmount * 10**decimals)` to convert.
+
+## Install
+
+```bash
+defi --version 2>/dev/null           # check if installed
+npm install -g @hypurrquant/defi-cli@latest 2>/dev/null || npx -y @hypurrquant/defi-cli@latest --json status
+```
+
+Use `defi` if global install works, otherwise `npx -y @hypurrquant/defi-cli@latest` as prefix.
+
+## Global Flags
+
+`--json` (required) | `--chain <chain>` (hyperevm or mantle, required for tx commands) | `--dry-run` (default, safe) | `--broadcast` (executes tx) | `--fields <f1,f2>` | `--ndjson`
+
+**Wallet**: set `DEFI_WALLET_ADDRESS` env for read queries. Set `DEFI_PRIVATE_KEY` for tx signing.
+
+## Environment
+
+```bash
+export DEFI_WALLET_ADDRESS=0xYourAddress
+export DEFI_PRIVATE_KEY=0xYourPrivateKey   # only needed for broadcasting
+```
+
+## Chains
+
+| Alias | Full Name | Chain ID |
+|-------|-----------|----------|
+| `hyperevm` | HyperEVM (Hyperliquid) | 999 |
+| `mantle` | Mantle | 5000 |
+
+## Protocol Slugs
+
+### HyperEVM Lending
+| Slug | Protocol | Interface |
+|------|----------|-----------|
+| `hyperlend` | HyperLend | aave_v3 |
+| `hypurrfi` | HypurrFi | aave_v3 |
+| `felix-morpho` | Felix Morpho | morpho_blue |
+
+### HyperEVM DEX
+| Slug | Protocol | Interface |
+|------|----------|-----------|
+| `kittenswap` | KittenSwap | algebra_v3 |
+| `nest-v1` | NEST V1 | algebra_v3 |
+| `ramses-cl` | Ramses CL | uniswap_v3 |
+| `ramses-hl` | Ramses HL | solidly_v2 |
+| `hybra` | Hybra | solidly_v2 |
+| `project-x` | Project X | uniswap_v2 |
+
+### HyperEVM Vaults / CDP
+| Slug | Protocol | Interface |
+|------|----------|-----------|
+| `felix` | Felix CDP | liquity_v2 |
+| `felix-vaults` | Felix Vaults | erc4626 |
+| `hyperbeat` | Hyperbeat | erc4626 |
+| `looping` | Looping | erc4626 |
+| `upshift` | Upshift | erc4626 |
+| `lazy-summer` | Lazy Summer | erc4626 |
+
+### Mantle Protocols
+| Slug | Protocol | Interface |
+|------|----------|-----------|
+| `aave-v3-mantle` | Aave V3 Mantle | aave_v3 |
+| `lendle-mantle` | Lendle | aave_v3 |
+| `uniswap-v3-mantle` | Uniswap V3 | uniswap_v3 |
+| `merchantmoe-mantle` | Merchant Moe | uniswap_v2 + lb |
+
+## Core Workflow: Lending
+
+```
+1. defi --json yield --asset USDC                                              # compare APYs (all chains)
+2. defi --json --chain hyperevm lending position --protocol hyperlend           # check position
+3. defi --json --chain hyperevm lending supply --protocol hyperlend --asset USDC --amount 1000000000  # dry-run
+4. [show result to user, get confirmation]
+5. defi --json --chain hyperevm lending supply --protocol hyperlend --asset USDC --amount 1000000000 --broadcast
+6. defi --json --chain hyperevm lending position --protocol hyperlend           # verify
+```
+
+## Core Workflow: Swap (DEX Aggregator)
+
+Aggregates KyberSwap, OpenOcean, LiquidSwap for best price automatically.
+
+```
+1. defi --json --chain hyperevm swap --from WHYPE --to USDC --amount 1000000000000000000   # dry-run
+2. [confirm with user]
+3. defi --json --chain hyperevm swap --from WHYPE --to USDC --amount 1000000000000000000 --broadcast
+```
+
+## Core Workflow: LP Autopilot
+
+```
+1. defi --json --chain hyperevm lp discover                                    # find pools with APR/TVL
+2. [user reviews, edits ~/.defi/pools.toml with chosen pools]
+3. defi --json --chain hyperevm lp autopilot --budget 1000000000               # dry-run allocation
+4. [confirm with user]
+5. defi --json --chain hyperevm lp autopilot --budget 1000000000 --broadcast   # execute
+```
+
+## Core Workflow: Yield Comparison
+
+```
+1. defi --json yield                                                  # all chains USDC rates
+2. defi --json --chain mantle yield --asset USDC                     # Mantle only
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| `Chain not found: X` | use `hyperevm` or `mantle` |
+| `Protocol not found: X` | run `defi --json status` to list valid slugs |
+| `No route found` | swap aggregator has no route — try smaller amount or different pair |
+| `No prices fetched` | asset not listed in registry — use token address directly |
+| `Multicall failed` | RPC issue — retry or check `status` |
+| `DEFI_WALLET_ADDRESS not set` | set env var or pass `--address` |
+
+## Examples
+
+**"What are the best USDC lending rates?"**
+```bash
+defi --json yield --asset USDC
+```
+
+**"Supply 1000 USDC to HyperLend"**
+```bash
+defi --json yield --asset USDC
+defi --json --chain hyperevm lending supply --protocol hyperlend --asset USDC --amount 1000000000
+# after user confirms:
+defi --json --chain hyperevm lending supply --protocol hyperlend --asset USDC --amount 1000000000 --broadcast
+```
+
+**"Swap 1 WHYPE to USDC"**
+```bash
+defi --json --chain hyperevm swap --from WHYPE --to USDC --amount 1000000000000000000
+defi --json --chain hyperevm swap --from WHYPE --to USDC --amount 1000000000000000000 --broadcast
+```
+
+**"Find Mantle LP pools with rewards"**
+```bash
+defi --json --chain mantle lp discover
+```
+
+**"Bridge 100 USDC from HyperEVM to Mantle"**
+```bash
+defi --json --chain hyperevm bridge --token USDC --amount 100000000 --to-chain mantle
+```
+
+**"Check my portfolio on HyperEVM"**
+```bash
+defi --json --chain hyperevm portfolio show --address 0xYourAddress
+```
+
+**"Claim LP rewards from KittenSwap"**
+```bash
+defi --json --chain hyperevm lp claim --protocol kittenswap --pool 0xYourPool --broadcast
+```

package/skills/defi-cli/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@hypurrquant/defi-cli-skill",
+  "version": "0.2.0",
+  "description": "AI agent skill for defi-cli — multi-chain DeFi operations via CLI",
+  "keywords": [
+    "ai-skill",
+    "claude",
+    "defi",
+    "lending",
+    "dex",
+    "swap",
+    "bridge",
+    "vault",
+    "staking",
+    "hyperevm",
+    "hyperliquid",
+    "mantle",
+    "aave",
+    "uniswap",
+    "yield"
+  ],
+  "author": "hypurrquant",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hypurrquant/defi-cli",
+    "directory": "ts/packages/defi-cli/skills/defi-cli"
+  },
+  "homepage": "https://github.com/hypurrquant/defi-cli#ai-agent-skill",
+  "files": [
+    "SKILL.md",
+    "references",
+    "scripts"
+  ],
+  "peerDependencies": {
+    "@hypurrquant/defi-cli": ">=0.2.0"
+  }
+}

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

@@ -0,0 +1,162 @@
+# defi-cli Command Reference
+
+All commands support `--json` for structured output. Always use `--json` when calling from an agent.
+All amounts are in **wei** unless noted. USDC/USDT use 6 decimals; native tokens and most ERC-20s use 18.
+
+## Dashboard (read-only, safe)
+
+```bash
+defi --json                                         # multicall balance dashboard
+defi --json --chain mantle                          # Mantle dashboard
+```
+
+## Status & Discovery (read-only, safe)
+
+```bash
+defi --json status                                  # list all protocols for current chain
+defi --json --chain mantle status                   # list Mantle protocols
+defi --json schema                                  # full CLI schema as JSON
+```
+
+## Yield (read-only, safe)
+
+```bash
+defi --json yield                                   # lending APY comparison (default: USDC, HyperEVM)
+defi --json yield --asset USDT                      # compare for a different asset
+defi --json --chain mantle yield --asset USDC        # Mantle lending rates
+```
+
+## Price (read-only, safe)
+
+```bash
+defi --json price --asset WHYPE                     # oracle + DEX prices for an asset
+defi --json price --asset USDC --source oracle      # oracle prices only
+defi --json price --asset WHYPE --source dex        # DEX spot prices only
+defi --json --chain mantle price --asset WMNT        # price on Mantle
+```
+
+## Lending (read-only queries, then mutating)
+
+```bash
+# Read-only
+defi --json lending rates --protocol <slug> --asset <token>
+defi --json lending position --protocol <slug>
+
+# Mutating (dry-run first, then --broadcast)
+defi --json lending supply --protocol <slug> --asset <token> --amount <wei>
+defi --json lending supply --protocol <slug> --asset <token> --amount <wei> --on-behalf-of <addr>
+defi --json lending withdraw --protocol <slug> --asset <token> --amount <wei> [--to <addr>]
+```
+
+Auto-approve: if token allowance is insufficient, the CLI checks, approves the exact amount, then supplies — all in one `--broadcast` call.
+
+## Swap (DEX aggregator — KyberSwap, OpenOcean, LiquidSwap)
+
+```bash
+defi --json swap --token-in <token> --token-out <token> --amount <wei> [--slippage <bps>]
+defi --json swap --token-in WHYPE --token-out USDC --amount 1000000000000000000 --slippage 50
+```
+
+Note: `swap` aggregates multiple DEX APIs for best route. Use `--broadcast` to execute.
+
+## LP Operations
+
+### Discover Pools
+
+```bash
+defi --json lp discover                             # all 134 emission pools
+defi --json lp discover --protocol kittenswap       # filter by protocol
+defi --json lp discover --min-apr 10                # filter by minimum APR
+```
+
+### Add Liquidity
+
+```bash
+defi --json lp add --protocol <slug> --pool-address <addr> --amount-a <wei> --amount-b <wei>
+```
+
+### Farm (Add + Auto-stake)
+
+```bash
+# Add liquidity and stake into gauge/farming for emissions
+defi --json lp farm --protocol <slug> --pool-address <addr> --amount-a <wei> --amount-b <wei>
+```
+
+### Claim Rewards
+
+```bash
+defi --json lp claim --protocol <slug> --pool-address <addr>
+```
+
+### Remove Liquidity
+
+```bash
+# Auto-unstake (if staked) then remove liquidity
+defi --json lp remove --protocol <slug> --pool-address <addr>
+```
+
+### LP Positions
+
+```bash
+defi --json lp positions                            # all LP positions across protocols
+```
+
+### LP Autopilot
+
+Reads `~/.defi/pools.toml` for whitelisted pools and allocates budget automatically.
+
+```bash
+defi --json lp autopilot --budget <wei>             # dry-run (default)
+defi --json lp autopilot --budget 1000000000 --broadcast  # execute
+```
+
+**pools.toml format:**
+```toml
+[[pools]]
+protocol = "kittenswap"
+pool_address = "0x..."
+weight = 50
+
+[[pools]]
+protocol = "nest-v1"
+pool_address = "0x..."
+weight = 50
+```
+
+## Portfolio
+
+```bash
+defi --json portfolio                               # aggregate positions across all protocols
+```
+
+## Token
+
+```bash
+# Read-only
+defi --json token balance --token <token> [--owner <addr>]
+defi --json token allowance --token <token> --spender <addr> [--owner <addr>]
+
+# Mutating
+defi --json token approve --token <token> --spender <addr> [--amount max|<wei>]
+defi --json token transfer --token <token> --to <addr> --amount <wei>
+```
+
+## Wallet
+
+```bash
+defi --json wallet address                          # show configured wallet address
+defi --json wallet balance [--address <addr>]       # native token balance
+```
+
+## Bridge (cross-chain)
+
+```bash
+# LI.FI (default, supports most token/chain combos)
+defi --json bridge --token USDC --amount 100000000 --to-chain mantle
+
+# deBridge DLN
+defi --json bridge --token USDC --amount 100000000 --to-chain arbitrum --provider debridge
+
+# Circle CCTP V2 (native USDC only: ethereum, avalanche, optimism, arbitrum, base, polygon)
+defi --json bridge --token USDC --amount 100000000 --to-chain arbitrum --provider cctp
+```

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

@@ -0,0 +1,115 @@
+# defi-cli Protocol Reference
+
+## HyperEVM (chain: `hyperevm`, Chain ID: 999)
+
+### Lending Protocols
+
+| Slug | Name | Interface | Notes |
+|------|------|-----------|-------|
+| `hyperlend` | HyperLend | aave_v3 | Main Aave V3 fork |
+| `hypurrfi` | HypurrFi | aave_v3 | HypurrQuant native lending |
+| `felix-morpho` | Felix Morpho | morpho_blue | Morpho Blue vaults |
+
+### DEX Protocols
+
+| Slug | Name | Interface | Notes |
+|------|------|-----------|-------|
+| `kittenswap` | KittenSwap | algebra_v3 | Algebra V3 (concentrated); 16 gauge pools |
+| `nest-v1` | NEST V1 | algebra_v3 | Algebra V3 fork; 13 gauge pools |
+| `ramses-cl` | Ramses CL | uniswap_v3 | Concentrated liquidity; 25 gauge pools |
+| `ramses-hl` | Ramses HL | solidly_v2 | Solidly V2 ve(3,3) |
+| `hybra` | Hybra | solidly_v2 | Solidly V2; 45 gauge pools |
+| `project-x` | Project X | uniswap_v2 | Uniswap V2 fork |
+
+### Vault Protocols (ERC-4626)
+
+| Slug | Name | Notes |
+|------|------|-------|
+| `felix-vaults` | Felix Vaults | CDP-backed vaults |
+| `hyperbeat` | Hyperbeat | Auto-compounding vault |
+| `looping` | Looping | Leverage looping |
+| `upshift` | Upshift | Yield optimization |
+| `lazy-summer` | Lazy Summer | Yield aggregator |
+
+### CDP Protocols
+
+| Slug | Name | Interface | Stablecoin |
+|------|------|-----------|------------|
+| `felix` | Felix CDP | liquity_v2 | feUSD |
+
+### Other
+
+| Slug | Name | Category |
+|------|------|----------|
+| `hypersurface` | Hypersurface | options |
+| `seaport-hyperevm` | Seaport | nft marketplace |
+
+---
+
+## Mantle (chain: `mantle`, Chain ID: 5000)
+
+### Lending Protocols
+
+| Slug | Name | Interface | Notes |
+|------|------|-----------|-------|
+| `aave-v3-mantle` | Aave V3 Mantle | aave_v3 | Official Aave V3 |
+| `lendle-mantle` | Lendle | aave_v3 | Mantle native lending |
+
+### DEX Protocols
+
+| Slug | Name | Interface | Notes |
+|------|------|-----------|-------|
+| `uniswap-v3-mantle` | Uniswap V3 | uniswap_v3 | Concentrated liquidity |
+| `merchantmoe-mantle` | Merchant Moe | uniswap_v2 + lb | V2 AMM + Liquidity Book; 35 LB pools |
+
+---
+
+## DEX Aggregator Providers (swap command)
+
+| Provider | Chains | Notes |
+|----------|--------|-------|
+| KyberSwap | HyperEVM, Mantle | Default for HyperEVM |
+| OpenOcean | HyperEVM, Mantle | Fallback aggregator |
+| LiquidSwap | HyperEVM | HyperEVM-native |
+
+---
+
+## Common Token Symbols
+
+### HyperEVM
+- `HYPE` — native token (use WHYPE for ERC-20 swaps)
+- `WHYPE` — wrapped HYPE (0x5555555555555555555555555555555555555555)
+- `USDC` — USD Coin
+- `USDT` — Tether
+- `WBTC` — Wrapped Bitcoin
+- `WETH` — Wrapped Ether
+
+### Mantle
+- `MNT` — native token
+- `WMNT` — wrapped MNT
+- `USDC` — USD Coin
+- `USDT` — Tether
+- `WETH` — Wrapped Ether
+
+---
+
+## Decimal Reference
+
+| Token | Decimals | 1 token in wei |
+|-------|----------|----------------|
+| HYPE/WHYPE/WETH/WBTC | 18 | `1000000000000000000` |
+| USDC | 6 | `1000000` |
+| USDT | 6 | `1000000` |
+| MNT/WMNT | 18 | `1000000000000000000` |
+
+---
+
+## Bridge Provider Support
+
+| Provider | Flag | Best For |
+|----------|------|----------|
+| LI.FI (default) | `--provider lifi` | Any token, any chain |
+| deBridge DLN | `--provider debridge` | Cross-chain arbitrary tokens |
+| Circle CCTP V2 | `--provider cctp` | Native USDC transfers |
+
+CCTP supported chains: `ethereum`, `avalanche`, `optimism`, `arbitrum`, `base`, `polygon`

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

@@ -0,0 +1,10 @@
+#!/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

package/skills/defi-cli/scripts/portfolio-snapshot.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# portfolio-snapshot.sh — take a portfolio snapshot and print PnL since last snapshot
+# Usage: WALLET=0xABC... bash portfolio-snapshot.sh [chain]
+set -euo pipefail
+
+DEFI="${DEFI_CMD:-defi}"
+WALLET="${DEFI_WALLET_ADDRESS:-${WALLET:-}}"
+CHAIN="${1:-hyperevm}"
+
+if [[ -z "$WALLET" ]]; then
+  echo '{"error":"Set DEFI_WALLET_ADDRESS or WALLET env var"}' >&2
+  exit 1
+fi
+
+echo "[portfolio] Taking snapshot for $WALLET on $CHAIN..." >&2
+"$DEFI" --json --chain "$CHAIN" portfolio snapshot --address "$WALLET"
+
+echo "[portfolio] Calculating PnL..." >&2
+"$DEFI" --json --chain "$CHAIN" portfolio pnl --address "$WALLET" || true

package/skills/defi-cli/scripts/preflight.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# preflight.sh — verify defi-cli is installed and wallet is configured
+set -euo pipefail
+
+DEFI="${DEFI_CMD:-defi}"
+
+# Check install
+if ! command -v "$DEFI" &>/dev/null; then
+  echo '{"ok":false,"error":"defi-cli not found. Install: npm install -g @hypurrquant/defi-cli@latest"}' >&2
+  exit 1
+fi
+
+VERSION=$("$DEFI" --version 2>/dev/null || echo "unknown")
+echo "{\"ok\":true,\"version\":\"$VERSION\",\"wallet\":\"${DEFI_WALLET_ADDRESS:-not_set}\"}"

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

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# yield-scan.sh — scan all chains for best yield on an asset
+# Usage: ASSET=USDC bash yield-scan.sh
+set -euo pipefail
+
+DEFI="${DEFI_CMD:-defi}"
+ASSET="${ASSET:-USDC}"
+
+echo "[yield-scan] Scanning all chains for $ASSET yield opportunities..." >&2
+"$DEFI" --json yield scan --asset "$ASSET"