feat: add protocols fees command

AGENTS.md

@@ -113,10 +113,11 @@ README.md                         # user-facing usage + caveats
 - Uniswap quote calls require a real `swapper` address via `swap quote --from-address` and default to provider auto slippage unless `swap quote --slippage-pct` is provided.
 - MegaETH bootstrap symbol parsing currently supports `MEGA`, `WETH`, and `USDT` (`USDT` maps to the chain's `USDT0` contract address on `eip155:4326`). Official Mega token list currently has no Ethereum L1 `MEGA` token entry.
 - Symbol parsing depends on the local bootstrap token registry; on chains without registry entries use token address or CAIP-19.
+- `chains gas` returns live EVM gas prices via RPC (EVM-only, no API key, bypasses cache); supports `--rpc-url` override and comma-separated `--chain` for parallel multi-chain queries (returns array; `--rpc-url` disallowed with multiple chains).
 - APY values are percentage points (`2.3` means `2.3%`), not ratios.
 - Morpho can emit extreme APYs in tiny markets; use `--min-tvl-usd` in ranking/filters.
 - Fresh cache hits (`age <= ttl`) skip provider calls; once TTL expires, the CLI re-fetches providers and only serves stale data within `max_stale` on temporary provider failures.
-- Metadata commands (`version`, `schema`, `providers list`) bypass cache initialization.
+- Metadata commands (`version`, `schema`, `providers list`, `chains list`, `chains gas`) bypass cache initialization.
 - Execution commands (`swap|bridge|approvals|transfer|lend|yield|rewards ... plan|submit|status`, `actions list|show|estimate`) bypass cache initialization.
 - For `lend`/`yield`, unresolved symbols are treated as symbol filters; on chains without bootstrap token entries, prefer token address or CAIP-19 for deterministic matching.
 - Amounts used for swaps/bridges are base units; keep both base and decimal forms consistent.

CHANGELOG.md

@@ -10,6 +10,11 @@ Format:
 ## [Unreleased]
 
 ### Added
+- Added `protocols fees` command to rank protocols by 24h fee revenue with 7d/30d totals and 1d/7d/1m percentage changes (no API key required, uses DefiLlama fees API). Supports `--category` filter and `--limit`.
+- Added `stablecoins chains` command to rank chains by total stablecoin market cap with dominant peg type and CAIP-2 chain IDs (no API key required, uses DefiLlama stablecoin chains API). Supports `--limit`.
+- Added `stablecoins top` command to list top stablecoins by circulating market cap with price, chain count, and day/week/month supply changes (no API key required, uses DefiLlama stablecoins API). Supports `--peg-type` filter (e.g. `peggedUSD`, `peggedEUR`) and `--limit`.
+- Added `chains gas` command to query current EVM gas prices (base fee, priority fee, gas price in gwei) with block number and EIP-1559 detection (no keys required, bypasses cache, supports `--rpc-url` override). Accepts comma-separated chains for multi-chain batch queries with parallel RPC fetching and partial-result support.
+- Added `chains list` command to enumerate all supported chains with slugs, CAIP-2 identifiers, namespaces, and accepted aliases (no keys required, bypasses cache).
 - Added TaikoSwap provider support for `swap quote` using on-chain quoter contract calls (no API key required).
 - Added swap execution workflow commands: `swap plan`, `swap submit`, and `swap status`.
 - Added bridge execution workflow commands: `bridge plan`, `bridge submit`, and `bridge status` (Across and LiFi providers).

README.md

@@ -15,7 +15,7 @@ Built for AI agents and scripts. Stable JSON output, canonical identifiers (CAIP
 - **Bridging** — get cross-chain quotes (Across, LiFi, Bungee), bridge analytics (volume, chain breakdown), and execute Across/LiFi bridge plans.
 - **Swapping** — get swap quotes (1inch, Uniswap, TaikoSwap) and execute TaikoSwap plans on-chain.
 - **Approvals, transfers & rewards** — create and execute ERC-20 approvals/transfers plus Aave rewards claim/compound flows.
-- **Chains & protocols** — browse top chains by TVL, inspect chain TVL by asset, discover protocols, resolve asset identifiers.
+- **Chains & protocols** — browse top chains by TVL, inspect chain TVL by asset, query live gas prices, discover protocols, track stablecoin market caps, resolve asset identifiers.
 - **Automation-friendly** — JSON-first output, field selection (`--select`), structured JSON/file input for mutation workflows, and a machine-readable schema export with required flags, enums, auth, and request/response metadata.
 
 ## Documentation Site (Mintlify)
@@ -86,8 +86,14 @@ defi version --long
 
 ```bash
 defi providers list --results-only
+defi chains list --results-only --select slug,caip2,namespace
+defi chains gas --chain 1 --results-only
+defi chains gas --chain 1,10,137,8453,42161 --results-only   # multi-chain batch
 defi chains top --limit 10 --results-only --select rank,chain,tvl_usd
 defi chains assets --chain 1 --asset USDC --results-only # Requires DEFI_DEFILLAMA_API_KEY
+defi protocols fees --limit 10 --results-only --select rank,protocol,fees_24h_usd,change_1d_pct
+defi stablecoins top --limit 10 --results-only --select rank,symbol,circulating_usd,price
+defi stablecoins chains --limit 10 --results-only --select rank,chain,circulating_usd
 defi assets resolve --chain base --symbol USDC --results-only
 defi lend markets --provider aave --chain 1 --asset USDC --results-only
 defi lend rates --provider morpho --chain 1 --asset USDC --results-only
@@ -288,12 +294,12 @@ providers:
 
 ## Cache Policy
 
-- Command TTLs are fixed in code (`chains/protocols/chains assets`: `5m`, `lend markets`: `60s`, `lend rates`: `30s`, `lend positions`: `30s`, `yield opportunities`: `60s`, `yield positions`: `30s`, `yield history`: `5m`, `bridge/swap quotes`: `15s`).
+- Command TTLs are fixed in code (`chains/protocols/stablecoins/chains assets`: `5m`, `lend markets`: `60s`, `lend rates`: `30s`, `lend positions`: `30s`, `yield opportunities`: `60s`, `yield positions`: `30s`, `yield history`: `5m`, `bridge/swap quotes`: `15s`).
 - Cache entries are served directly only while fresh (`age <= ttl`).
 - After TTL expiry, the CLI fetches provider data immediately.
 - `cache.max_stale` / `--max-stale` is only a temporary provider-failure fallback window (currently `unavailable` / `rate_limited`).
 - If fallback is disabled (`--no-stale` or `--max-stale 0s`) or stale data exceeds the budget, the CLI exits with code `14`.
-- Metadata commands (`version`, `schema`, `providers list`) bypass cache initialization.
+- Metadata commands (`version`, `schema`, `providers list`, `chains list`) bypass cache initialization.
 - Execution commands (`swap|bridge|approvals|transfer|lend|yield|rewards ... plan|submit|status`, `actions list|show|estimate`) bypass cache reads/writes.
 
 ## Caveats
@@ -310,6 +316,7 @@ providers:
 - `chains assets` requires `DEFI_DEFILLAMA_API_KEY` because DefiLlama chain asset TVL is key-gated.
 - `bridge list` and `bridge details` require `DEFI_DEFILLAMA_API_KEY`; quote providers (`across`, `lifi`) do not.
 - Category rankings from `protocols categories` are deterministic and sorted by `tvl_usd`, then protocol count, then name.
+- `protocols fees` rankings are sorted by 24h fees descending; protocols with null or zero 24h fees are excluded.
 - `--chain` normalization supports additional aliases/IDs including `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`.
 - Bungee Auto-mode quote coverage is chain+token dependent; unsupported pairs return provider errors even when chain normalization succeeds.
 - Bungee quote requests use deterministic placeholder sender/receiver addresses for quote-only resolution (`0x000...001`).
@@ -340,6 +347,7 @@ providers:
 - Bridge execution pre-sign checks validate settlement provider metadata and known settlement endpoint URLs for Across/LiFi; use `--unsafe-provider-tx` to bypass these guardrails.
 - All `submit` execution commands will broadcast signed transactions.
 - Rewards `--assets` expects comma-separated on-chain addresses used by Aave incentives contracts.
+- `chains gas` returns live EVM gas prices via RPC; it is EVM-only and bypasses cache. Use `--rpc-url` to override the default chain RPC. Pass comma-separated chains (e.g. `--chain 1,10,8453`) for parallel multi-chain queries; `--rpc-url` is only allowed with a single chain.
 - Selector choice is explicit for multi-provider flows; pass `--provider` (no implicit defaults).
 
 ## Exit Codes

docs/concepts/config-and-cache.mdx

@@ -45,7 +45,7 @@ cache:
 - Stale data is served only when providers fail temporarily (`unavailable` or `rate_limited`) and within `max_stale`.
 - Cache writes use SQLite WAL + busy timeout + lock/backoff retries to reduce lock contention in parallel runs.
 - If cache init fails (path/permissions), commands continue with cache disabled.
-- Metadata commands (`version`, `schema`, `providers list`) bypass cache initialization.
+- Metadata commands (`version`, `schema`, `providers list`, `chains list`) bypass cache initialization.
 
 ## Command TTLs
 

docs/guides/market-discovery.mdx

@@ -5,6 +5,17 @@ description: Discover chains, protocols, and assets before running strategy-spec
 
 Use market-discovery commands to scope chains/protocols and normalize assets first.
 
+## Supported chains
+
+Enumerate all chains the CLI recognizes, including slugs and CAIP-2 identifiers. No API keys required.
+
+```bash
+defi chains list --results-only
+defi chains list --results-only --select slug,caip2,namespace
+```
+
+Use this to discover valid `--chain` values before running other commands.
+
 ## Top chains by TVL
 
 ```bash
@@ -33,6 +44,15 @@ defi protocols categories --results-only
 
 Category ranking is deterministic: `tvl_usd`, then protocol count, then name.
 
+## Stablecoin market data
+
+```bash
+defi stablecoins top --limit 10 --results-only --select rank,symbol,circulating_usd,price
+defi stablecoins top --peg-type peggedUSD --limit 20 --results-only
+```
+
+Returns circulating market cap, current price, chain count, and day/week/month supply change deltas. Useful for stablecoin selection and depeg monitoring.
+
 ## Resolve assets to canonical IDs
 
 ```bash

docs/reference/market-commands.mdx

@@ -1,6 +1,6 @@
 ---
 title: Market Commands
-description: Reference for providers, chains, protocols, and assets commands.
+description: Reference for providers, chains, protocols, stablecoins, and assets commands.
 ---
 
 ## `providers list`
@@ -11,6 +11,15 @@ List supported providers and capability auth metadata.
 defi providers list --results-only
 ```
 
+## `chains list`
+
+List all supported chains with slugs, CAIP-2 identifiers, namespaces, and accepted aliases. No API keys required; bypasses cache.
+
+```bash
+defi chains list --results-only
+defi chains list --results-only --select slug,caip2,namespace
+```
+
 ## `chains top`
 
 Top chains by TVL.
@@ -62,6 +71,22 @@ List categories with protocol counts and TVL.
 defi protocols categories --results-only
 ```
 
+## `stablecoins top`
+
+Top stablecoins by circulating market cap. Includes price, chain count, and day/week/month supply change deltas.
+
+```bash
+defi stablecoins top --limit 10 --results-only
+defi stablecoins top --peg-type peggedUSD --limit 20 --results-only
+```
+
+Flags:
+
+- `--limit int` (default `20`)
+- `--peg-type string` (optional filter, e.g. `peggedUSD`, `peggedEUR`)
+
+No API key required; data sourced from DefiLlama stablecoins API.
+
 ## `assets resolve`
 
 Resolve symbol/address/CAIP-19 to canonical asset metadata.