@earnforge/skill 0.1.0

package/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: earnforge
+description: >
+  Discovers, compares, risk-scores, and builds unsigned deposit and withdrawal
+  quotes for 623+ DeFi yield vaults across 16 chains via the LI.FI Earn API.
+  Includes ERC-20 allowance checking, risk scoring (0-10), yield strategy
+  presets, portfolio allocation, and all 18 known API pitfalls handled.
+---
+
+# EarnForge Agent Skill
+
+## Commands
+
+All commands accept `--json` for machine-readable output.
+
+### Vault Discovery
+
+- `earnforge list [--asset USDC] [--chain 8453] [--min-tvl 1000000] [--strategy conservative] [--json]`
+  List vaults with optional filters. Supports pagination.
+
+- `earnforge top --asset USDC [--chain 8453] [--limit 10] [--strategy max-apy] [--json]`
+  Top vaults sorted by APY descending.
+
+- `earnforge vault <slug> [--json]`
+  Fetch a single vault by its slug.
+
+### Comparison & Analysis
+
+- `earnforge risk <slug> [--json]`
+  Full risk score breakdown (0-10 scale): TVL magnitude, APY stability,
+  protocol maturity, redeemability, asset type.
+
+- `earnforge apy-history <slug> [--json]`
+  30-day APY history from DeFiLlama yields API.
+
+### Portfolio & Suggestions
+
+- `earnforge suggest --amount 10000 --asset USDC [--max-chains 3] [--strategy diversified] [--json]`
+  Risk-adjusted portfolio allocation. Returns vault list with amounts and percentages.
+
+- `earnforge portfolio <wallet> [--json]`
+  Current positions for a wallet address.
+
+### Deposit & Withdraw
+
+- `earnforge quote --vault <slug> --amount 100 --wallet 0x... [--from-chain 1] [--optimize-gas] [--json]`
+  Build an unsigned deposit quote. Validates all pitfalls before quoting.
+  **Check allowance before executing** — the response includes `approvalAddress`.
+
+- `earnforge withdraw --vault <slug> --amount 100 --wallet 0x... [--to-token 0x...] [--json]`
+  Build an unsigned redeem/withdraw quote. Checks `isRedeemable` first.
+
+- `earnforge allowance --token 0x... --owner 0x... --spender 0x... --amount 1000000 --rpc-url <url> --chain-id 8453 [--json]`
+  Check ERC-20 token allowance. Returns whether approval is sufficient and
+  builds an unsigned approval tx if not. Use `approvalAddress` from the
+  deposit quote as the `--spender`.
+
+- `earnforge approve --token 0x... --spender 0x... --amount 1000000 --chain-id 8453 [--json]`
+  Build an unsigned ERC-20 approval transaction.
+
+### Safety & Monitoring
+
+- `earnforge preflight --vault <slug> --wallet 0x... [--amount 100] [--cross-chain] [--json]`
+  Run all preflight checks: isTransactional, chain match, gas balance,
+  token balance, redeemability.
+
+- `earnforge doctor --vault <slug> [--env] [--json]`
+  Run all 18 pitfall checks on a vault.
+
+- `earnforge watch --vault <slug> [--apy-drop 20] [--tvl-drop 30] [--json]`
+  Monitor a vault for APY/TVL drops. Streams events.
+
+- `earnforge simulate --vault <slug> --amount 100 --wallet 0x... [--json]`
+  Dry-run a deposit via eth_call. Runs preflight first.
+
+### Reference Data
+
+- `earnforge chains [--json]` — 16 supported chains with chainIds
+- `earnforge protocols [--json]` — 11 protocols with URLs
+- `earnforge init <name>` — Scaffold a new project with EarnForge wired up
+
+## Rules
+
+1. **Never submit transactions.** Only build unsigned quotes. The user signs.
+
+2. **Check ERC-20 allowance before depositing.** Use `earnforge allowance`
+   with the quote's `approvalAddress` as spender. If insufficient, have the
+   user sign the approval tx from `earnforge approve` first, then the deposit.
+
+3. **Always check `isTransactional` before quoting deposits.** Use `doctor`
+   or `preflight` to verify.
+
+4. **Check `isRedeemable` before quoting withdrawals.** Non-redeemable vaults
+   have locked liquidity.
+
+5. **Use `vault.address` as `toToken` for deposits, not the underlying.**
+   This is Pitfall #5. The SDK handles it automatically.
+
+6. **Filter stablecoins by the `stablecoin` tag, not by token symbol.**
+
+7. **Risk score thresholds:** >= 7 is low risk, 4-6.9 is medium, < 4 is
+   high risk. Always show score alongside APY.
+
+8. **APY values are already percentages** (3.84 = 3.84%). Do NOT multiply
+   by 100. `apy1d/apy7d/apy30d` can be null — use the fallback chain.
+
+9. **Cross-chain deposits require explicit `--from-token`.** The vault's
+   underlying token address is on the vault's chain, not the source chain.
+
+10. **Use chainId (number), not chain name, in all API paths.**
+
+## References
+
+- [references/pitfalls.md](references/pitfalls.md) — All 18 API pitfalls
+- [references/protocols.md](references/protocols.md) — 11 protocols with risk tiers
+- [references/chains.md](references/chains.md) — 16 chains with chainIds
+- [references/examples.md](references/examples.md) — Worked examples
+- [references/strategies.md](references/strategies.md) — 4 yield strategy presets

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@earnforge/skill",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Agent Skill for LI.FI Earn — vault discovery, risk scoring, and deposit quoting via CLI",
+  "files": ["SKILL.md", "references", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "echo 'Skill package has no tests — content only'"
+  }
+}

package/references/chains.md

@@ -0,0 +1,29 @@
+# Supported Chains
+
+16 chains currently supported by the LI.FI Earn API.
+
+| Chain | chainId | Network CAIP | Notes |
+|-------|---------|-------------|-------|
+| Ethereum | 1 | eip155:1 | Largest DeFi ecosystem; highest gas costs |
+| Optimism | 10 | eip155:10 | OP Stack L2; low gas |
+| BSC | 56 | eip155:56 | Binance Smart Chain |
+| Gnosis | 100 | eip155:100 | Formerly xDai; stable gas |
+| Unichain | 130 | eip155:130 | Uniswap's app-chain |
+| Polygon | 137 | eip155:137 | PoS chain; low gas |
+| Monad | 143 | eip155:143 | High-performance EVM chain |
+| Sonic | 146 | eip155:146 | Formerly Fantom rebranded |
+| Mantle | 5000 | eip155:5000 | L2 with MNT gas token |
+| Base | 8453 | eip155:8453 | Coinbase L2; fastest growing |
+| Arbitrum | 42161 | eip155:42161 | Largest L2 by TVL |
+| Celo | 42220 | eip155:42220 | Mobile-first chain |
+| Avalanche | 43114 | eip155:43114 | Subnet architecture |
+| Linea | 59144 | eip155:59144 | Consensys zkEVM L2 |
+| Berachain | 80094 | eip155:80094 | Proof of Liquidity chain |
+| Katana | 747474 | eip155:747474 | Ronin's DeFi chain |
+
+## Usage Notes
+
+- Always use `chainId` (number) in API calls, never the chain name string.
+- Chain name matching in CLI/bot is case-insensitive: `base`, `Base`, `BASE` all map to 8453.
+- Cross-chain deposits are supported via the Composer API (LI.FI routing).
+- Gas costs vary significantly: Ethereum (~$5-50) vs L2s (~$0.01-0.10).

package/references/examples.md

@@ -0,0 +1,172 @@
+# Worked Examples
+
+8 end-to-end examples demonstrating common EarnForge workflows.
+
+## 1. List Vaults by Asset
+
+Find all USDC vaults sorted by APY:
+
+```bash
+earnforge top --asset USDC --limit 5
+```
+
+```json
+[
+  {
+    "name": "STEAKUSDC",
+    "slug": "8453-0xbeef...",
+    "chain": "Base",
+    "apy": 3.85,
+    "tvl": "$33.8M",
+    "protocol": "morpho-v1",
+    "risk": { "score": 7.8, "label": "low" }
+  }
+]
+```
+
+## 2. Compare Two Vaults
+
+Side-by-side comparison of Morpho vs Aave USDC vaults:
+
+```bash
+earnforge compare 8453-0xbeef... 1-0xaave... --json
+```
+
+Output includes APY difference, TVL ratio, risk score delta, and protocol tier comparison.
+
+## 3. Build a Deposit Quote
+
+Quote depositing 1000 USDC into a Base vault:
+
+```bash
+earnforge quote 8453-0xbeef... 1000 0xYourWallet --json
+```
+
+The SDK automatically:
+- Sets `toToken = vault.address` (Pitfall #5)
+- Uses 6 decimals for USDC (Pitfall #9)
+- Validates `isTransactional` (Pitfall #13)
+- Checks `underlyingTokens` is non-empty (Pitfall #15)
+
+Returns an unsigned transaction for the user to sign.
+
+## 4. Portfolio Allocation
+
+Get a diversified allocation for $50,000 in USDC:
+
+```bash
+earnforge suggest 50000 USDC --max-vaults 5 --max-chains 3 --strategy diversified --json
+```
+
+```json
+{
+  "totalAmount": 50000,
+  "expectedApy": 4.52,
+  "allocations": [
+    { "vault": "STEAKUSDC", "amount": 20000, "percentage": 40.0, "apy": 3.85 },
+    { "vault": "Aave USDC", "amount": 15000, "percentage": 30.0, "apy": 5.20 },
+    { "vault": "Euler USDC", "amount": 10000, "percentage": 20.0, "apy": 4.10 },
+    { "vault": "Pendle USDC", "amount": 5000, "percentage": 10.0, "apy": 6.50 }
+  ]
+}
+```
+
+## 5. Withdraw from a Vault
+
+Build a redeem quote to exit a position:
+
+```bash
+earnforge withdraw 8453-0xbeef... 500 0xYourWallet --json
+```
+
+Checks `isRedeemable` and `redeemPacks` before building the quote. Warns if the vault is non-redeemable.
+
+## 6. Cross-Chain Deposit
+
+Deposit from Ethereum into a Base vault using LI.FI routing:
+
+```bash
+earnforge quote 8453-0xbeef... 1000 0xYourWallet --from-chain 1 --json
+```
+
+The Composer API handles the bridge + swap + deposit in a single quote. Use `gas-optimize` to compare costs across source chains:
+
+```bash
+earnforge gas-optimize 8453-0xbeef... 1000 0xYourWallet --from-chains 1,10,8453 --json
+```
+
+## 7. Risk Analysis
+
+Get a full risk breakdown for a vault:
+
+```bash
+earnforge risk 8453-0xbeef... --json
+```
+
+```json
+{
+  "score": 7.8,
+  "label": "low",
+  "breakdown": {
+    "tvl": 8,
+    "apyStability": 8,
+    "protocol": 9,
+    "redeemability": 10,
+    "assetType": 9
+  }
+}
+```
+
+Dimensions:
+- **TVL Magnitude** (25% weight): Higher TVL = lower risk. $100M+ = 10/10.
+- **APY Stability** (20% weight): Small divergence between apy1d/apy30d/total = more stable.
+- **Protocol Maturity** (25% weight): Known blue-chip protocols score higher.
+- **Redeemability** (15% weight): Non-redeemable = liquidity risk (3/10).
+- **Asset Type** (15% weight): Stablecoin tag = lower asset risk (9/10).
+
+## 8. Portfolio Suggestion with Strategy
+
+Use the conservative strategy for a safe allocation:
+
+```bash
+earnforge suggest 100000 USDC --strategy conservative --json
+```
+
+The conservative strategy applies these filters:
+- Only stablecoin-tagged vaults
+- TVL > $50M
+- Blue-chip protocols only (aave-v3, morpho-v1, euler-v2, pendle, maple)
+
+Other strategies: `max-apy` (no filters, pure APY sort), `diversified` (3+ chains, $1M+ TVL), `risk-adjusted` (risk score >= 7).
+
+## 9. Full Deposit Flow with Allowance Check
+
+The complete deposit flow has 3 steps: quote, approve, deposit.
+
+```bash
+# Step 1: Build deposit quote
+earnforge quote --vault 8453-0xbeef... --amount 100 --wallet 0xYour --json
+# Note the approvalAddress in the response
+
+# Step 2: Check if approval is needed
+earnforge allowance --token 0xUSDC --owner 0xYour --spender 0xApprovalAddr --amount 100000000 --rpc-url https://mainnet.base.org --chain-id 8453 --json
+# If sufficient: false, sign the approvalTx first
+
+# Step 3: Execute deposit (user signs the transactionRequest from step 1)
+```
+
+The SDK's `buildDepositQuote()` handles toToken, decimals, and pitfall validation automatically. The allowance check uses a raw JSON-RPC `eth_call` to read the ERC-20 contract.
+
+## 10. Withdraw from a Vault
+
+Withdrawal reverses the deposit — fromToken is the vault share token, toToken is the underlying.
+
+```bash
+# Check if vault is redeemable
+earnforge vault 8453-0xbeef... --json | jq '.isRedeemable'
+
+# Build withdrawal quote
+earnforge withdraw --vault 8453-0xbeef... --amount 50 --wallet 0xYour --json
+```
+
+The Composer uses the same `/v1/quote` endpoint with swapped tokens. Cross-chain withdrawals are supported — add `--to-chain` and `--to-token` for the destination.

package/references/pitfalls.md

@@ -0,0 +1,24 @@
+# LI.FI Earn API Pitfalls
+
+All 18 known pitfalls discovered during integration. The SDK handles each one by default.
+
+| # | Pitfall | Impact | Fix |
+|---|---------|--------|-----|
+| 1 | Earn Data API has no auth, Composer API requires API key | 401 on quote requests | Set `x-lifi-api-key` header only on Composer calls |
+| 2 | Earn Data base URL is `earn.li.fi`, not `li.quest` | 404 on vault/chain/protocol endpoints | Use `https://earn.li.fi` for data, `https://li.quest` for Composer |
+| 3 | API key goes in `x-lifi-api-key` header, not query param | 401 even with valid key | Pass key via header, never as URL parameter |
+| 4 | Composer quote endpoint is GET, not POST | 405 Method Not Allowed | Use `GET /v1/quote` with query parameters |
+| 5 | `toToken` must be vault address, not underlying token | Quote returns wrong asset or fails | Set `toToken = vault.address` for deposits |
+| 6 | Pagination uses cursor-based, not offset-based | Missing vaults after page 1 | Pass `nextCursor` to fetch subsequent pages |
+| 7 | `apy.total` can be 0 when only `apy30d` has data | Show 0% APY for active vaults | Use fallback chain: `apy.total` -> `apy30d` -> `apy7d` -> `apy1d` |
+| 8 | `tvl.usd` is a string, not a number | Numeric comparisons fail silently | Parse with `Number()` or `parseTvl()` before comparing |
+| 9 | Token amounts need correct decimals (USDC=6, ETH=18) | Deposit 1 USDC sends 0.000001 USDC | Read `underlyingTokens[0].decimals`, use `toSmallestUnit()` |
+| 10 | Vault list returns all chains mixed together | Cannot filter by chain in client | Pass `chainId` query parameter to filter server-side |
+| 11 | No gas token on destination chain | Transaction reverts | Check native balance before quoting; use LI.Fuel `fromAmountForGas` |
+| 12 | Wallet on wrong chain | Transaction sent to wrong network | Compare `wallet.chainId` with `vault.chainId` before deposit |
+| 13 | Non-transactional vaults exist | Cannot deposit programmatically | Check `vault.isTransactional === true` before any quote |
+| 14 | Some vaults have zero APY temporarily | Misleading display | Filter or flag vaults with `apy.total === 0` and no historical data |
+| 15 | `underlyingTokens` can be an empty array | Cannot determine `fromToken` | Check array length; require explicit `fromToken` if empty |
+| 16 | `description` field is optional (~14% of vaults) | `undefined` in display strings | Use optional chaining or fallback to vault name |
+| 17 | `apy.reward` is null for some protocols | NaN when summing base + reward | Normalize null to 0 (SDK Zod schema does this automatically) |
+| 18 | `apy1d`, `apy7d`, `apy30d` can all be null | Crash on `.toFixed()` or division | Null-check before arithmetic; use `getBestApy()` helper |

package/references/protocols.md

@@ -0,0 +1,26 @@
+# Supported Protocols
+
+11 protocols currently available through the LI.FI Earn API, with risk tier assignments used by the SDK's risk scorer.
+
+| Protocol | Risk Tier | Score | URL | Notes |
+|----------|-----------|-------|-----|-------|
+| aave-v3 | Blue-chip | 9/10 | https://app.aave.com | Largest DeFi lending protocol; battle-tested |
+| morpho-v1 | Blue-chip | 9/10 | https://app.morpho.org | Optimized lending layer on top of Aave/Compound |
+| euler-v2 | Established | 7/10 | https://app.euler.finance | Modular lending with custom vault support |
+| pendle | Established | 7/10 | https://app.pendle.finance | Yield tokenization and trading |
+| ethena-usde | Established | 7/10 | https://www.ethena.fi | Synthetic dollar protocol backed by staked ETH |
+| ether.fi-liquid | Established | 7/10 | https://app.ether.fi/liquid | Liquid restaking vaults |
+| ether.fi-stake | Established | 7/10 | https://ether.fi/app/weeth | Native ETH staking (weETH) |
+| maple | Moderate | 6/10 | https://app.maple.finance | Institutional lending with credit risk |
+| upshift | Emerging | 5/10 | https://app.upshift.finance | Newer yield aggregator |
+| neverland | Emerging | 4/10 | https://app.neverland.money | Emerging lending market |
+| yo-protocol | Emerging | 4/10 | https://app.yo.xyz | Newer yield protocol |
+
+## Risk Tier Definitions
+
+- **Blue-chip (9-10):** Multi-year track record, $1B+ TVL historically, multiple audits, battle-tested through market cycles.
+- **Established (7-8):** At least 1 year live, audited, significant TVL, active development.
+- **Moderate (5-6):** Audited but newer, or has had security incidents that were resolved.
+- **Emerging (3-4):** Less than 1 year live, limited audit history, lower TVL. Higher risk/reward.
+
+Protocols not in the list default to a score of 3/10 (unrated).

package/references/strategies.md

@@ -0,0 +1,84 @@
+# Yield Strategy Presets
+
+4 built-in strategy presets for portfolio allocation and vault filtering.
+
+## 1. Conservative
+
+**Description:** Stablecoin-tagged, TVL > $50M, APY 3-7%, blue-chip protocols only.
+
+| Filter | Value |
+|--------|-------|
+| Tags | `stablecoin` |
+| Min TVL | $50,000,000 |
+| Protocols | aave-v3, morpho-v1, euler-v2, pendle, maple |
+| Sort | APY descending |
+
+**Best for:** Capital preservation. Large allocations where safety is the priority. Institutional deposits.
+
+**Expected APY range:** 3-7%
+
+## 2. Max APY
+
+**Description:** Sort by APY descending, no TVL floor.
+
+| Filter | Value |
+|--------|-------|
+| Tags | (none) |
+| Min TVL | (none) |
+| Protocols | (all) |
+| Sort | APY descending |
+
+**Best for:** Yield maximizers willing to accept higher risk. Smaller allocations where loss is tolerable.
+
+**Expected APY range:** 5-50%+ (higher APY often correlates with higher risk)
+
+## 3. Diversified
+
+**Description:** Spread across 3+ chains, 3+ protocols, mix of stablecoin and LST.
+
+| Filter | Value |
+|--------|-------|
+| Tags | (none) |
+| Min TVL | $1,000,000 |
+| Protocols | (all) |
+| Sort | APY descending |
+
+**Best for:** Balanced risk through diversification. Medium-sized portfolios. Reducing single-chain or single-protocol exposure.
+
+**Expected APY range:** 4-15%
+
+## 4. Risk-Adjusted
+
+**Description:** Filter by risk score >= 7, then sort by APY.
+
+| Filter | Value |
+|--------|-------|
+| Tags | (none) |
+| Min TVL | (none) |
+| Min Risk Score | 7 (low risk only) |
+| Protocols | (all) |
+| Sort | APY descending |
+
+**Best for:** Optimizing the risk/return ratio. Getting the highest yield among safe vaults. Data-driven allocation.
+
+**Expected APY range:** 3-10%
+
+## Combining Strategies with Suggestions
+
+Pass `--strategy` to `earnforge suggest` to apply a preset:
+
+```bash
+# Conservative allocation for $100K USDC
+earnforge suggest 100000 USDC --strategy conservative
+
+# Max yield for $1K ETH
+earnforge suggest 1000 ETH --strategy max-apy
+
+# Diversified across chains
+earnforge suggest 50000 USDC --strategy diversified --max-chains 5
+
+# Only low-risk vaults
+earnforge suggest 25000 USDC --strategy risk-adjusted
+```
+
+Strategies can be combined with `--max-vaults` and `--max-chains` to further constrain the allocation.