DeFi Scout

On-chain financial intelligence across Optimism and Base. Most scripts require no API keys. Exception: cmc-sentiment.js requires CMC_API_KEY (free tier at coinmarketcap.com).

Data Sources

Source	What	Endpoint
CoinGecko	Token prices	INLINECODE2
DeFiLlama

Protocol TVL, yields | api.llama.fi | | Optimism RPC | Balances, gas | mainnet.optimism.io | | Base RPC | Balances, gas | mainnet.base.org | | Across API | Bridge quotes | app.across.to/api/suggested-fees |

Core Scripts

All scripts output JSON. Run with node scripts/<name>.js.

Script	Purpose
INLINECODE8	ETH + ERC-20 balances on OP + Base
INLINECODE9

CoinGecko price for any token |
| yields.js | Top yield pools on OP + Base from DeFiLlama |
| gas.js | Current gas on Optimism and Base |
| bridge-quote.js | Across Protocol bridge fee quote (no deps, 10s timeout) |
| aave-position.js | Aave V3 health factor + collateral/debt on OP + Base |
| swap-quote.js | Price-based swap estimate via CoinGecko (price math only — not a protocol-routed quote) |
| cmc-sentiment.js | BTC dominance, ETH dominance, Fear & Greed index (CoinMarketCap) |

Script Details

aave-position.js

node scripts/aave-position.js <0x-address>

Queries Aave V3 Pool getUserAccountData on both Optimism and Base via direct JSON-RPC eth_call. Returns collateral, debt, available borrows, liquidation threshold, LTV, and health factor. Adds a warning field if health factor < 1.2 (liquidation risk). 8-second timeout per RPC call.

swap-quote.js

node scripts/swap-quote.js <token_in> <token_out> <amount_in> [--chain optimism|base]
# Example: node scripts/swap-quote.js ETH USDC 1.5 --chain base

Fetches live prices from CoinGecko and computes estimated output = (priceIn / priceOut) * amountIn * 0.997 (0.3% fee estimate). Supported tokens: ETH, WETH, USDC, USDT, OP, VELO, AERO, cbETH. Not a real quote — use Aerodrome/Velodrome UI for execution.

Workflow

Wallet check: Run wallet-balances.js <address> → summarise balances + USD value.

Opportunity scan: Run yields.js → filter by chain, TVL >$1M, sort by APY. Flag stable pairs (no IL) and volatile pairs separately. Cross-reference gas cost vs position size before recommending entry.

Bridge quote: Run bridge-quote.js <amount_eth> [from_chain=10] [to_chain=8453] → returns fee, fill time, output amount.

Price check: Run token-price.js <coingecko_id> → price, 24h change.

Aave health check: Run aave-position.js <address> → health factor on both chains. Act immediately if < 1.2.

Swap estimate: Run swap-quote.js <tokenIn> <tokenOut> <amount> → rough output estimate for planning. Never use for execution.

Market sentiment: Run cmc-sentiment.js → BTC dom, ETH dom, Fear & Greed. Requires CMC_API_KEY env var. Caches results for 6h.

yields.js flags:
CODEBLOCK2

Error Handling

• - Bad address (wallet-balances.js, aave-position.js): returns { error: "invalid address" } — always validate 0x format before passing
• Unknown token (swap-quote.js): returns { error: "Unsupported token: XYZ" } — supported list is in script header
• RPC timeout: 8s timeout per call; on failure returns { error: "RPC timeout" } — retry once before surfacing to user
• DeFiLlama offline: yields.js returns empty array [] — surface as "yield data temporarily unavailable"

Key Addresses (verified)

See references/addresses.md for verified contract addresses on Optimism and Base.

Risk Rules

• - Never recommend pools with TVL < $1M
• Flag APY > 100% as high-risk / likely temporary incentive
• Always show gas cost as % of position before recommending entry
• Stable pairs (USDC-USDT, USDC-msUSD) = lower risk, note explicitly