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 | api.coingecko.com/api/v3/simple/price |
| 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 |
|---|---|
wallet-balances.js |
ETH + ERC-20 balances on OP + Base |
token-price.js |
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:
node scripts/yields.js # OP + Base, TVL >$1M, top 20
node scripts/yields.js --chain optimism # OP only
node scripts/yields.js --chain base # Base only
node scripts/yields.js --chain all --min-tvl 5000000 # both chains, TVL >$5M
node scripts/yields.js --top 5 # top 5 results only
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.jsreturns 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