ggonzalez94 · ggonzalez94 · Mar 20, 2026 · Mar 10, 2026 · Mar 10, 2026 · Mar 10, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -34,7 +34,7 @@ cmd/
 internal/
   app/runner.go                   # command wiring, provider routing, cache flow
   providers/                      # external adapters
-    aave/ morpho/                 # lending + yield (read + execution)
+    aave/ morpho/ moonwell/       # lending + yield (read + execution)
     defillama/                    # market/yield normalization + fallback + bridge analytics
     across/ lifi/                 # bridge quotes + lifi execution planning
     oneinch/ uniswap/ taikoswap/ tempo/ # swap quotes + execution planning providers
@@ -67,10 +67,10 @@ README.md                         # user-facing usage + caveats
 
 - Error output always returns a full envelope, even with `--results-only` or `--select`.
 - Config precedence is `flags > env > config file > defaults`.
-- `yield --providers` expects provider names (`aave,morpho,kamino`), not protocol categories.
-- Lending routes by `--provider` use direct protocol adapters (`aave`, `morpho`, `kamino`).
-- `lend positions` currently supports `--provider aave|morpho`; `kamino` does not expose positions yet.
-- `yield positions` currently supports `aave|morpho`; `kamino` does not expose positions yet.
+- `yield --providers` expects provider names (`aave,morpho,kamino,moonwell`), not protocol categories.
+- Lending routes by `--provider` use direct protocol adapters (`aave`, `morpho`, `kamino`, `moonwell`).
+- `lend positions` currently supports `--provider aave|morpho|moonwell`; `kamino` does not expose positions yet.
+- `yield positions` currently supports `aave|morpho|moonwell`; `kamino` does not expose positions yet.
 - `lend positions --type all` intentionally returns non-overlapping intents (`supply`, `borrow`, `collateral`) for automation-friendly filtering.
 - Most commands do not require provider API keys.
 - Key-gated routes: `swap quote --provider 1inch` (`DEFI_1INCH_API_KEY`), `swap quote --provider uniswap` (`DEFI_UNISWAP_API_KEY`), `chains assets`, and `bridge list` / `bridge details` via DefiLlama (`DEFI_DEFILLAMA_API_KEY`).
@@ -91,8 +91,8 @@ README.md                         # user-facing usage + caveats
   - `bridge plan|submit|status` (Across, LiFi)
   - `approvals plan|submit|status`
   - `transfer plan|submit|status`
-  - `lend supply|withdraw|borrow|repay plan|submit|status` (Aave, Morpho)
-  - `yield deposit|withdraw plan|submit|status` (Aave, Morpho)
+  - `lend supply|withdraw|borrow|repay plan|submit|status` (Aave, Morpho, Moonwell)
+  - `yield deposit|withdraw plan|submit|status` (Aave, Morpho, Moonwell)
   - `rewards claim|compound plan|submit|status` (Aave)
   - `actions list|show|estimate`
 - Execution builder architecture is intentionally split:
@@ -107,6 +107,9 @@ README.md                         # user-facing usage + caveats
 - Aave execution has default pool-address-provider coverage for chain IDs `1`, `10`, `137`, `8453`, `42161`, and `43114`; override with `--pool-address` / `--pool-address-provider` otherwise.
 - Morpho lend execution requires `--market-id` (Morpho market unique key bytes32).
 - Morpho yield execution requires `--vault-address` (Morpho vault contract address).
+- Moonwell lending/yield uses on-chain RPC reads (no API key required); supported on Base and Optimism.
+- Moonwell execution targets mToken contracts (Compound v2 style); use `--pool-address` to specify the mToken directly or let auto-resolution match by underlying asset via `Comptroller.getAllMarkets()`.
+- Moonwell's WETH mToken (mWETH) auto-unwraps to native ETH on borrow/withdraw and expects native ETH (not WETH) for supply/repay on some chains. Callers (UIs, automation) must wrap ETH → WETH before calling `repayBorrow` or handle the native ETH received from `borrow`/`redeemUnderlying`. The CLI planner currently uses the standard ERC-20 path (approve + call with value=0), so WETH wrapping is the caller's responsibility.
 - Key requirements are command + provider specific; `providers list` is metadata only and should remain callable without provider keys.
 - Prefer env vars for provider keys in docs/examples; keep config file usage optional and focused on non-secret defaults.
 - `--chain` supports CAIP-2, numeric chain IDs, and aliases; aliases include `tempo`/`tempo mainnet`/`presto`, `tempo testnet`/`moderato`, `tempo devnet`, `mantle`, `megaeth`/`mega eth`/`mega-eth`, `ink`, `scroll`, `berachain`, `gnosis`/`xdai`, `linea`, `sonic`, `blast`, `fraxtal`, `world-chain`, `celo`, `taiko`/`taiko alethia`, `taiko hoodi`/`hoodi`, `zksync`, `hyperevm`/`hyper evm`/`hyper-evm`, `monad`, and `citrea`.

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ Format:
 ## [Unreleased]
 
 ### Added
+- Moonwell lending provider (Base, Optimism) — markets, rates, positions, yield opportunities/positions, and execution (supply, withdraw, borrow, repay).
 - Added `--chain` filter to `protocols fees` and `protocols revenue` to filter by chain presence (e.g. `protocols fees --chain Ethereum`). Supports combined `--category` and `--chain` filtering, consistent with `dexes volume --chain` behavior.
 - Added `--chain` filter to `protocols top` to rank protocols by chain-specific TVL (e.g. `protocols top --chain Ethereum`). When specified, TVL reflects the protocol's value locked on that chain rather than total TVL. Supports combined `--category` and `--chain` filtering. Output now includes `chains` count.
 - Added `protocols revenue` command to rank protocols by 24h revenue (protocol-retained fees) with 7d/30d totals and 1d/7d/1m percentage changes (no API key required, uses DefiLlama revenue API). Supports `--category` filter and `--limit`.
@@ -38,7 +39,7 @@ Format:
 - Tempo swap planning/quotes now validate TIP-20 currency metadata up front and return `unsupported` for non-USD assets or DEX reverts such as missing pairs, instead of reporting them as transient provider outages.
 
 ### Fixed
-- None yet.
+- Optimism USDC bootstrap address now points to native USDC (`0x0b2c...ff85`) instead of bridged USDC.e; added separate `USDC.e` entry for the bridged variant.
 
 ### Docs
 - Documented Tempo chain aliases, provider support, native DEX caveats, and execution examples across README, AGENTS, and Mintlify docs.

diff --git a/README.md b/README.md
@@ -10,8 +10,8 @@ Built for AI agents and scripts. Stable JSON output, canonical identifiers (CAIP
 
 ## Features
 
-- **Lending** — query markets/rates from Aave/Morpho/Kamino, account positions from Aave/Morpho, and execute loan actions (`lend supply|withdraw|borrow|repay`).
-- **Yield** — compare opportunities, query positions, fetch historical series, and execute deposit/withdraw flows (Aave, Morpho).
+- **Lending** — query markets/rates from Aave/Morpho/Kamino/Moonwell, account positions from Aave/Morpho/Moonwell, and execute loan actions (`lend supply|withdraw|borrow|repay`).
+- **Yield** — compare opportunities, query positions, fetch historical series, and execute deposit/withdraw flows (Aave, Morpho, Moonwell).
 - **Bridging** — get cross-chain quotes (Across, LiFi, Bungee), bridge analytics, and execute bridge plans (Across, LiFi).
 - **Swapping** — get swap quotes (1inch, Uniswap, Jupiter, Tempo, TaikoSwap, Fibrous, Bungee) and execute swap plans (Tempo with native type 0x76 transactions and batched calls, TaikoSwap).
 - **Approvals, transfers & rewards** — ERC-20 approvals/transfers and Aave rewards claim/compound flows.
@@ -133,16 +133,16 @@ defi actions estimate --action-id <action_id> --results-only
 
 - `swap plan|submit|status` (Tempo, TaikoSwap)
 - `bridge plan|submit|status` (Across, LiFi)
-- `lend supply|withdraw|borrow|repay plan|submit|status` (Aave, Morpho)
-- `yield deposit|withdraw plan|submit|status` (Aave, Morpho)
+- `lend supply|withdraw|borrow|repay plan|submit|status` (Aave, Morpho, Moonwell)
+- `yield deposit|withdraw plan|submit|status` (Aave, Morpho, Moonwell)
 - `rewards claim|compound plan|submit|status` (Aave)
 - `approvals plan|submit|status`
 - `transfer plan|submit|status`
 - `actions list|show|estimate`
 
 All `plan` commands support `--rpc-url` to override chain default RPCs.
 `plan` and `submit` accept `--input-json` / `--input-file` for structured input; explicit flags override JSON values.
-`--providers` flags accept provider names from `defi providers list` (e.g. `aave,morpho,kamino`).
+`--providers` flags accept provider names from `defi providers list` (e.g. `aave,morpho,kamino,moonwell`).
 
 ### More quote examples
 
@@ -301,6 +301,7 @@ providers:
 - `yield` and `lend` are split by intent: `yield` for passive deposits/withdrawals, `lend` for loan lifecycle.
 - Morpho: `yield deposit|withdraw` targets vaults (`--vault-address`), `lend` targets markets (`--market-id`).
 - Aave execution auto-resolves pool addresses on Ethereum, Optimism, Polygon, Base, Arbitrum, and Avalanche; use `--pool-address` on other chains.
+- Moonwell execution targets mToken contracts (Compound v2 style) on Base and Optimism; use `--pool-address` to specify the mToken directly or let auto-resolution match by underlying asset.
 - Bridge execution waits for destination settlement; adjust `--step-timeout` for slower routes.
 - Pre-sign checks enforce bounded ERC-20 approvals by default; use `--allow-max-approval` to opt in to larger approvals.
 - Bridge pre-sign checks validate settlement endpoints; use `--unsafe-provider-tx` to bypass.
@@ -337,7 +338,7 @@ cmd/
 internal/
   app/runner.go                   # command wiring, routing, cache flow
   providers/                      # external adapters
-    aave/ morpho/                 # lending + yield (read + execution)
+    aave/ morpho/ moonwell/       # lending + yield (read + execution)
     defillama/                    # normalization + fallback + bridge analytics
     across/ lifi/                 # bridge quotes + lifi execution planning
     oneinch/ uniswap/ taikoswap/  # swap (quote + taikoswap execution planning)

diff --git a/docs/act-execution-design.md b/docs/act-execution-design.md
@@ -21,8 +21,8 @@ Execution is integrated inside existing domain commands (for example `swap`, `br
 | Swap | `swap plan|submit|status` | `--provider` required | `taikoswap` execution today |
 | Bridge | `bridge plan|submit|status` | `--provider` required | `across`, `lifi` execution |
 | Transfer | `transfer plan|submit|status` | no provider selector | native ERC-20 wallet transfer execution |
-| Lend | `lend (supply|withdraw|borrow|repay) plan|submit|status` | `--provider` required | `aave`, `morpho` execution (`morpho` requires `--market-id`) |
-| Yield | `yield (deposit|withdraw) plan|submit|status` | `--provider` required | `aave`, `morpho` execution (`morpho` requires `--vault-address`) |
+| Lend | `lend (supply|withdraw|borrow|repay) plan|submit|status` | `--provider` required | `aave`, `morpho`, `moonwell` execution (`morpho` requires `--market-id`) |
+| Yield | `yield (deposit|withdraw) plan|submit|status` | `--provider` required | `aave`, `morpho`, `moonwell` execution (`morpho` requires `--vault-address`) |
 | Rewards | `rewards (claim|compound) plan|submit|status` | `--provider` required | `aave` execution |
 | Approvals | `approvals plan|submit|status` | no provider selector | native ERC-20 approval execution |
 | Action inspection | `actions list|show|estimate` | optional `--status` / `--action-id` filters | persisted action inspection + gas/fee estimation |

diff --git a/docs/concepts/providers-and-auth.mdx b/docs/concepts/providers-and-auth.mdx
@@ -11,6 +11,7 @@ description: Provider coverage, key requirements, and routing behavior.
 | `aave` | lend (read + execution), yield (read + execution), rewards (execution) | No |
 | `morpho` | lend (read + execution), yield (read + execution) | No |
 | `kamino` | lend, yield (Solana mainnet, read only) | No |
+| `moonwell` | lend (read + execution), yield (read + execution) | No |
 | `across` | bridge quote + execution | No |
 | `lifi` | bridge quote + execution | No |
 | `bungee` | bridge quote, swap quote | No (default mode) |
@@ -39,10 +40,10 @@ If either is missing, bungee quotes use public backend.
 
 ## Routing and fallback
 
-- Lending routes by `--provider` (`aave`, `morpho`, `kamino`) using direct adapters only.
-- `lend positions` currently supports `--provider aave|morpho`.
-- `yield positions` currently supports `--providers aave,morpho`.
-- `yield opportunities` aggregates direct providers and accepts `--providers aave,morpho,kamino`.
+- Lending routes by `--provider` (`aave`, `morpho`, `kamino`, `moonwell`) using direct adapters only.
+- `lend positions` currently supports `--provider aave|morpho|moonwell`.
+- `yield positions` currently supports `--providers aave,morpho,moonwell`.
+- `yield opportunities` aggregates direct providers and accepts `--providers aave,morpho,kamino,moonwell`.
 - `yield history` uses the same direct providers and accepts `--providers aave,morpho,kamino`.
 - `bridge quote` and `swap quote` require explicit `--provider`; there are no implicit provider defaults.
 - Execution commands (`plan`, `run`, `submit`, `status`) require `--provider` for multi-provider surfaces.
@@ -62,3 +63,4 @@ If either is missing, bungee quotes use public backend.
 - Tempo DEX swap execution settles to the caller; `--recipient` must match `--from-address` (or be omitted).
 - `actions estimate` returns fee-token-denominated estimates for Tempo actions (includes `fee_unit` and `fee_token` fields).
 - `--signer tempo` enables agent wallet support via the Tempo CLI (`tempo wallet -j whoami`), with delegated access keys, spending limits, and expiry checks. Requires the Tempo CLI installed.
+- Moonwell uses on-chain RPC reads (no API key); supported on Base and Optimism. Execution targets mToken contracts (Compound v2 style); use `--pool-address` to specify the mToken directly or let auto-resolution match by underlying asset. Moonwell does not support `--on-behalf-of`.
diff --git a/docs/guides/lending.mdx b/docs/guides/lending.mdx
@@ -22,6 +22,7 @@ defi lend rates --provider kamino --chain solana --asset USDC --limit 10 --resul
 - `--provider aave` -> Aave adapter
 - `--provider morpho` -> Morpho adapter
 - `--provider kamino` -> Kamino adapter (Solana mainnet only)
+- `--provider moonwell` -> Moonwell adapter (Base, Optimism)
 
 ## Positions
 
@@ -31,7 +32,7 @@ defi lend positions --provider morpho --chain 1 --address 0xYourEOA --type borro
 ```
 
 `--type all` returns disjoint rows: `supply`, `collateral`, and `borrow`.
-Supported providers: `aave`, `morpho`.
+Supported providers: `aave`, `morpho`, `moonwell`.
 
 ## Execution (supply, withdraw, borrow, repay)
 
@@ -48,6 +49,14 @@ defi lend supply plan --provider morpho --chain 1 --asset USDC --market-id 0x...
 
 Aave auto-resolves pool addresses on Ethereum, Optimism, Polygon, Base, Arbitrum, and Avalanche. Use `--pool-address` on other chains.
 
+Moonwell execution targets mToken contracts (Compound v2 style) on Base and Optimism:
+
+```bash
+defi lend supply plan --provider moonwell --chain 8453 --asset USDC --amount 1000000 --from-address 0xYourEOA --results-only
+```
+
+Use `--pool-address` to specify the mToken directly, or omit it to auto-resolve by underlying asset. Moonwell does not support `--on-behalf-of`.
+
 ## Suggested filters and reliability defaults
 
 ```bash

diff --git a/docs/guides/yield.mdx b/docs/guides/yield.mdx
@@ -68,7 +68,7 @@ defi yield positions --chain 1 --address 0xYourEOA --providers aave,morpho --lim
 defi yield positions --chain 1 --address 0xYourEOA --providers morpho --asset USDC --results-only
 ```
 
-Supported providers: `aave`, `morpho`.
+Supported providers: `aave`, `morpho`, `moonwell`.
 
 ## Execution (deposit, withdraw)
 
@@ -90,6 +90,7 @@ defi yield deposit plan --provider morpho --chain 1 --asset USDC --vault-address
 - APY values are percentage points (`2.3` = `2.3%`).
 - Morpho may produce extreme APY for very small markets; use `--min-tvl-usd`.
 - Kamino yield routes currently support Solana mainnet only (read only, no execution).
+- Moonwell yield routes are supported on Base and Optimism; Moonwell does not support `--on-behalf-of`.
 - `yield opportunities` no longer includes subjective risk/score fields.
 - `yield history --metrics` supports `apy_total` and `tvl_usd`; Aave currently supports `apy_total` only.
 - Aave history is lookback-window based and effectively ends near current time.
diff --git a/docs/pr-description-plan-execution.md b/docs/pr-description-plan-execution.md
@@ -18,7 +18,7 @@ This lets agents and humans move from quote/data discovery to deterministic plan
 - Added local signer support for execution (`env`, `file`, `keystore`, plus one-off `--private-key`).
 - Added execution support for:
   - bridge: `across`, `lifi`
-  - lend: `aave`, `morpho`
+  - lend: `aave`, `morpho`, `moonwell`
   - rewards: `aave`
   - swap: `taikoswap` (same interface as Univ3)
   - approvals: native ERC-20 approvals
@@ -29,7 +29,7 @@ This is the initial execution-capable set; more providers will be added under th
 - `swap plan|submit|status`
 - `bridge plan|submit|status` (provider: `across|lifi`)
 - `approvals plan|submit|status`
-- `lend supply|withdraw|borrow|repay plan|submit|status` (provider: `aave|morpho`)
+- `lend supply|withdraw|borrow|repay plan|submit|status` (provider: `aave|morpho|moonwell`)
 - `rewards claim|compound plan|submit|status` (provider: `aave`)
 - `actions list|show`
 

diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
@@ -41,7 +41,7 @@ defi yield opportunities --chain 1 --asset USDC --providers aave,morpho --min-tv
 defi yield history --chain 1 --asset USDC --providers aave,morpho --metrics apy_total,tvl_usd --interval day --window 7d --limit 1 --results-only
 ```
 
-`--providers` expects provider names from `providers list` (`aave,morpho,kamino`), not protocol categories.
+`--providers` expects provider names from `providers list` (`aave,morpho,kamino,moonwell`), not protocol categories.
 
 ## 6. Get bridge and swap quotes